www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Worst Phobos documentation evar!

reply Walter Bright <newshound2 digitalmars.com> writes:
This is so bad there isn't even a direct link to it, it hides in shame. Just go 
here:



and scroll up one entry. Here it is:

    size_t encode(Tgt, Src, R)(in Src[] s, R range);

    Encodes c in units of type E and writes the result to the output range R.
    Returns the number of Es written.

Let me enumerate the awesomeness of its awfulness:

1. No 'Return:' block, though it obviously returns a value.
2. No 'Params:' block, though it obviously has parameters.
3. No 'Example:' block
4. No comparison with other 'encode' functions in the same module.
5. No description of what 'Tgt' is.
6. No description of what 'Src' is.
7. No clue where the variable 'c' comes from.
8. No clue where the type 'E' comes from.
9. 'R' is a type, not an instance.
10. I suspect it has something to do with UTF encodings, but there is no clue.

There's simply no way to figure out what is going on here without reading the 
source code.

Anyone want to take this on? There's a lot of stuff like this in Phobos. It's 
too much for one person to tackle, but if each of us just pick a function here 
and there, we can crowdsource and improve things greatly.

Some ones I've done, as examples of easy improvements:

https://github.com/D-Programming-Language/phobos/pull/2805
https://github.com/D-Programming-Language/phobos/pull/2812
https://github.com/D-Programming-Language/phobos/pull/2813
https://github.com/D-Programming-Language/phobos/pull/2814
Dec 27 2014
next sibling parent "eles" <eles215 gzk.dot> writes:
On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright wrote:

 Anyone want to take this on?
http://forum.dlang.org/post/mailman.3669.1419707884.9932.digitalmars-d puremagic.com Really sorry it has fallen on you.
Dec 27 2014
prev sibling next sibling parent reply "Xinok" <xinok live.com> writes:
On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright wrote:
 This is so bad there isn't even a direct link to it, it hides 
 in shame. Just go here:



 and scroll up one entry. Here it is:

    size_t encode(Tgt, Src, R)(in Src[] s, R range);

    Encodes c in units of type E and writes the result to the 
 output range R.
    Returns the number of Es written.

 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same 
 module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
 7. No clue where the variable 'c' comes from.
 8. No clue where the type 'E' comes from.
 9. 'R' is a type, not an instance.
 10. I suspect it has something to do with UTF encodings, but 
 there is no clue.

 There's simply no way to figure out what is going on here 
 without reading the source code.

 Anyone want to take this on? There's a lot of stuff like this 
 in Phobos. It's too much for one person to tackle, but if each 
 of us just pick a function here and there, we can crowdsource 
 and improve things greatly.

 Some ones I've done, as examples of easy improvements:

 https://github.com/D-Programming-Language/phobos/pull/2805
 https://github.com/D-Programming-Language/phobos/pull/2812
 https://github.com/D-Programming-Language/phobos/pull/2813
 https://github.com/D-Programming-Language/phobos/pull/2814
I'd like to contribute to the documentation (more within my skill level anyways), but I'd like to follow some solid guidelines if I'm to do so. If we don't have something like it already, perhaps we could create a page on the wiki with some tips and conventions for writing documentation for Phobos (and if we do, give me a link!). Then of course, we can incorporate some good and bad examples which you've provided for us already.
Dec 27 2014
next sibling parent "weaselcat" <weaselcat gmail.com> writes:
On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:

 I'd like to contribute to the documentation (more within my 
 skill level anyways), but I'd like to follow some solid 
 guidelines if I'm to do so. If we don't have something like it 
 already, perhaps we could create a page on the wiki with some 
 tips and conventions for writing documentation for Phobos (and 
 if we do, give me a link!). Then of course, we can incorporate 
 some good and bad examples which you've provided for us already.
+1 I'd like to contribute to D but the most I could probably do is help with documentation. It would be nice to have an article like this on the wiki.
Dec 28 2014
prev sibling next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 28/12/14 03:55, Xinok via Digitalmars-d wrote:
 I'd like to contribute to the documentation (more within my skill level
 anyways), but I'd like to follow some solid guidelines if I'm to do so. If we
 don't have something like it already, perhaps we could create a page on the
wiki
 with some tips and conventions for writing documentation for Phobos (and if we
 do, give me a link!). Then of course, we can incorporate some good and bad
 examples which you've provided for us already.
Yup, clear rules for how things should be documented are really necessary. Then it's trivial to find rulebreakers and fix them. A speculative thought, given the remarks by Manu and others on how templated signatures create hassle for comprehension. Is there any sane way that we could auto-generate a "quasi-signature" for functions with the template types specified? The idea would be that e.g. we could have the general signature, and then provide a trivial example of how that signature resolves to something saner if you know that (say) the input range is a built-in string, or built-in array, or whatever. So, say, you could have the general signature S doSomethingWithAString(S s, ...) if (isSomeString!S) and a note underneath providing the example with S == string: string doSomethingWithAString(string s, ...) Not sure if that's not too much work compared to just proper documentation, but thought I'd float it. BTW is it just me, or are the various isSomething methods of std.traits not having documentation generated properly? See: http://dlang.org/phobos/std_traits.html ... and try searching for, say, isBoolean, or isSomeString.
Dec 28 2014
parent reply Nick Treleaven <ntrel-pub mybtinternet.com> writes:
On 28/12/2014 14:22, Joseph Rushton Wakeling via Digitalmars-d wrote:
 BTW is it just me, or are the various isSomething methods of std.traits
 not having documentation generated properly?  See:
 http://dlang.org/phobos/std_traits.html

 ... and try searching for, say, isBoolean, or isSomeString.
Works with my newer dmd, I'm not sure why that link doesn't have them.
Dec 28 2014
parent Nick Treleaven <ntrel-pub mybtinternet.com> writes:
On 28/12/2014 17:09, Nick Treleaven wrote:
 On 28/12/2014 14:22, Joseph Rushton Wakeling via Digitalmars-d wrote:
 BTW is it just me, or are the various isSomething methods of std.traits
 not having documentation generated properly?  See:
 http://dlang.org/phobos/std_traits.html

 ... and try searching for, say, isBoolean, or isSomeString.
Works with my newer dmd, I'm not sure why that link doesn't have them.
Also the pre-release docs seem to have them: http://dlang.org/phobos-prerelease/std_traits.html#isSomeString
Dec 30 2014
prev sibling next sibling parent reply "bachmeier" <no spam.net> writes:
On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:
 On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright 
 wrote:
 This is so bad there isn't even a direct link to it, it hides 
 in shame. Just go here:



 and scroll up one entry. Here it is:

   size_t encode(Tgt, Src, R)(in Src[] s, R range);

   Encodes c in units of type E and writes the result to the 
 output range R.
   Returns the number of Es written.

 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same 
 module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
 7. No clue where the variable 'c' comes from.
 8. No clue where the type 'E' comes from.
 9. 'R' is a type, not an instance.
 10. I suspect it has something to do with UTF encodings, but 
 there is no clue.

 There's simply no way to figure out what is going on here 
 without reading the source code.

 Anyone want to take this on? There's a lot of stuff like this 
 in Phobos. It's too much for one person to tackle, but if each 
 of us just pick a function here and there, we can crowdsource 
 and improve things greatly.

 Some ones I've done, as examples of easy improvements:

 https://github.com/D-Programming-Language/phobos/pull/2805
 https://github.com/D-Programming-Language/phobos/pull/2812
 https://github.com/D-Programming-Language/phobos/pull/2813
 https://github.com/D-Programming-Language/phobos/pull/2814
I'd like to contribute to the documentation (more within my skill level anyways), but I'd like to follow some solid guidelines if I'm to do so. If we don't have something like it already, perhaps we could create a page on the wiki with some tips and conventions for writing documentation for Phobos (and if we do, give me a link!). Then of course, we can incorporate some good and bad examples which you've provided for us already.
will auto be allowed in any examples. The compiler should even reject files in which they appear. One of the most frustrating things is to read documentation with type T (completely uninformative) followed by an example with auto.
Dec 28 2014
next sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:

 will auto be allowed in any examples. The compiler should even 
 reject files in which they appear. One of the most frustrating 
 things is to read documentation with type T (completely 
 uninformative) followed by an example with auto.
Doesn't work with Voldemort types, stupid with LongClassName a = new LongClassName(long, parameter, list). Use your brain, not "under no circumstances" rules, when writing documentation. Same as Params:/Returns: - they may not be useful for trivial functions but are very useful with more complex ones. Again, use your brain - "Will someone reading this thing I'm writing here have any actual idea about how to use this function?"
Dec 28 2014
parent "bachmeier" <no spam.net> writes:
On Sunday, 28 December 2014 at 17:22:50 UTC, Kiith-Sa wrote:

 will auto be allowed in any examples. The compiler should even 
 reject files in which they appear. One of the most frustrating 
 things is to read documentation with type T (completely 
 uninformative) followed by an example with auto.
Doesn't work with Voldemort types, stupid with LongClassName a = new LongClassName(long, parameter, list). Use your brain, not "under no circumstances" rules, when writing documentation. Same as Params:/Returns: - they may not be useful for trivial functions but are very useful with more complex ones. Again, use your brain - "Will someone reading this thing I'm writing here have any actual idea about how to use this function?"
So you're arguing that the existing documentation was written by folks not using their brains? "Use your brain" doesn't work and that is the reason rules are necessary. Same thing for "Will someone reading this thing I'm writing here have any actual idea about how to use this function?" Everyone has their own definition of what can be understood. The person that wrote the documentation that started this thread evidently thought the explanation was sufficient. Without rules you have nothing.
Dec 28 2014
prev sibling parent reply "eles" <eles eles.com> writes:
On Sunday, 28 December 2014 at 17:10:21 UTC, bachmeier wrote:
 On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:
 On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright 
 wrote:

 will auto be allowed in any examples. The compiler should even 
 reject files in which they appear. One of the most frustrating 
 things is to read documentation with type T (completely 
 uninformative) followed by an example with auto.
Speaking of which: http://forum.dlang.org/post/dzuhxuoqmpzrumwcmtqj forum.dlang.org http://ddili.org/ders/d.en/destroy.html (Thanks, Ali)
Dec 28 2014
parent reply "bachmeier" <no spam.net> writes:
On Sunday, 28 December 2014 at 19:33:25 UTC, eles wrote:
 On Sunday, 28 December 2014 at 17:10:21 UTC, bachmeier wrote:
 On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:
 On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright 
 wrote:

 will auto be allowed in any examples. The compiler should even 
 reject files in which they appear. One of the most frustrating 
 things is to read documentation with type T (completely 
 uninformative) followed by an example with auto.
Speaking of which: http://forum.dlang.org/post/dzuhxuoqmpzrumwcmtqj forum.dlang.org http://ddili.org/ders/d.en/destroy.html (Thanks, Ali)
That's something that I was not aware of, but it's different from what I was referring to. Perhaps the rule should be that auto can only be used if it matters and if there is an explanation of why it matters.
Dec 28 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Sun, Dec 28, 2014 at 11:14:56PM +0000, bachmeier via Digitalmars-d wrote:
 On Sunday, 28 December 2014 at 19:33:25 UTC, eles wrote:
On Sunday, 28 December 2014 at 17:10:21 UTC, bachmeier wrote:
On Sunday, 28 December 2014 at 02:55:39 UTC, Xinok wrote:
On Sunday, 28 December 2014 at 01:00:49 UTC, Walter Bright wrote:

auto be allowed in any examples. The compiler should even reject
files in which they appear. One of the most frustrating things is to
read documentation with type T (completely uninformative) followed
by an example with auto.
Speaking of which: http://forum.dlang.org/post/dzuhxuoqmpzrumwcmtqj forum.dlang.org http://ddili.org/ders/d.en/destroy.html (Thanks, Ali)
That's something that I was not aware of, but it's different from what I was referring to. Perhaps the rule should be that auto can only be used if it matters and if there is an explanation of why it matters.
Most Phobos range functions return opaque types that the user should not depend on (even if the type is nameable), since the point of the range API is to have user code Just Work(tm) without needing to know the actual type of the returned object. What *is* very important in documentation, though, is to indicate what kind of range is returned. It's very frustrating, for example, if the function returns a forward range, but the documentation tells you nothing about what the return type can do! T -- MSDOS = MicroSoft's Denial Of Service
Dec 29 2014
parent reply "bachmeier" <no spam.com> writes:
On Monday, 29 December 2014 at 17:38:42 UTC, H. S. Teoh via 
Digitalmars-d wrote:
 Most Phobos range functions return opaque types that the user 
 should not
 depend on (even if the type is nameable), since the point of 
 the range
 API is to have user code Just Work(tm) without needing to know 
 the
 actual type of the returned object.
That's not something we should assume a new D user will know. Someone with a few years of C++ experience will probably be okay, but that's kind of my point - the documentation shouldn't require that background. I can imagine someone seeing examples that use auto with ranges and then asking "Now what?" Those are the frustrations that make users give up on the language.
Dec 29 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 21:10:15 +0000
bachmeier via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 That's not something we should assume a new D user will know.=20
 Someone with a few years of C++ experience will probably be okay,=20
 but that's kind of my point - the documentation shouldn't require=20
 that background. I can imagine someone seeing examples that use=20
 auto with ranges and then asking "Now what?" Those are the=20
 frustrations that make users give up on the language.
trying to use the language one didn't even bother to learn will inevitably lead to frustration. first time i tried to use Forth was... painful. but it was Z80 machine and i have no other sane choices, so now i love Forth.
Dec 29 2014
parent reply "bachmeier" <no spam.com> writes:
On Monday, 29 December 2014 at 21:23:07 UTC, ketmar via 
Digitalmars-d wrote:
 On Mon, 29 Dec 2014 21:10:15 +0000
 bachmeier via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 That's not something we should assume a new D user will know. 
 Someone with a few years of C++ experience will probably be 
 okay, but that's kind of my point - the documentation 
 shouldn't require that background. I can imagine someone 
 seeing examples that use auto with ranges and then asking "Now 
 what?" Those are the frustrations that make users give up on 
 the language.
trying to use the language one didn't even bother to learn will inevitably lead to frustration. first time i tried to use Forth was... painful. but it was Z80 machine and i have no other sane choices, so now i love Forth.
The only reason to read documentation is to learn the language. Based on the responses to my post, it's becoming clear why D has a reputation for terrible documentation...
Dec 29 2014
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 22:12:59 +0000
bachmeier via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 The only reason to read documentation is to learn the language.=20
O_O
Dec 29 2014
prev sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Mon, Dec 29, 2014 at 09:10:15PM +0000, bachmeier via Digitalmars-d wrote:
 On Monday, 29 December 2014 at 17:38:42 UTC, H. S. Teoh via Digitalmars-d
 wrote:
Most Phobos range functions return opaque types that the user should
not depend on (even if the type is nameable), since the point of the
range API is to have user code Just Work(tm) without needing to know
the actual type of the returned object.
That's not something we should assume a new D user will know. Someone with a few years of C++ experience will probably be okay, but that's kind of my point - the documentation shouldn't require that background. I can imagine someone seeing examples that use auto with ranges and then asking "Now what?" Those are the frustrations that make users give up on the language.
You're missing the point. The user *should not* know what the returned type is! (And cannot know, when it's a local struct inside the function that has no name outside.) The type is *intentionally* opaque, because the whole point of using such a construct is to prevent user code from having explicit dependencies on the actual type. Explicitly documenting the precise type defeats the purpose completely, and we might as well go back to C and use ExplicitIterator*, AnotherExplicitIterator*, YetAnotherExplicitIterator*, with 150 different structs defining 150 functionally-equivalent things that only just happen to be implemented differently. Of course, the flip side of that, is that probably all references to range return types (or any other Voldemort / opaque return types, for that matter) should to hyperlink to an explanation for what kind of operations the returned type supports. I don't think the issue you bring up will be a problem if the function documentation says something along the lines of: Returns: A [forward range] of integers. where [forward range] is a hyperlink to a definition of what a forward range is and what it does. In fact, here's another low-hanging fruit for wanna-be Phobos contributors: add said hyperlinks to all the range-based functions in Phobos. Or, better yet, since these things are so common in Phobos, add a macro that contains the hyperlink for each type of range, and just write $(INPUT_RANGE), $(FORWARD_RANGE), etc., instead in all places in the documentation where it occurs. T -- PNP = Plug 'N' Pray
Dec 29 2014
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/27/2014 6:55 PM, Xinok wrote:
 I'd like to contribute to the documentation (more within my skill level
 anyways), but I'd like to follow some solid guidelines if I'm to do so. If we
 don't have something like it already, perhaps we could create a page on the
wiki
 with some tips and conventions for writing documentation for Phobos (and if we
 do, give me a link!). Then of course, we can incorporate some good and bad
 examples which you've provided for us already.
A great first step would be to simply ensure that functions with return values have a [Returns:] block and functions with parameters have a [Params:] block.
Dec 28 2014
prev sibling next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 28/12/14 02:00, Walter Bright via Digitalmars-d wrote:
 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
'Params:' provides a special case for documenting input parameters, so you can write something like, /** * Params: * n = some description */ void foo(int n) { ... } and ddoc will generate a nice descriptive: <b>Params:</b><br> <table><tr><td>int <i>n</i></td> <td>some description</td></tr> </table> Is there an existing equivalent that can be used for template parameters? "Template Params:" or "TemplateParams:", for example, don't work. BTW it would be nice if, instead of generating "hardcoded" stylistic information like <b></b>, <i></i> and the use of <table>, the output could be more generic and semantically marked up for use with CSS. This is something that could contribute a lot towards making better-presented documentation.
Dec 28 2014
next sibling parent reply Nick Treleaven <ntrel-pub mybtinternet.com> writes:
On 28/12/2014 14:49, Joseph Rushton Wakeling via Digitalmars-d wrote:
 Is there an existing equivalent that can be used for template
 parameters? "Template Params:" or "TemplateParams:", for example, don't
 work.
You can just use Params: for them also. Perhaps separating them might be nice though.
 BTW it would be nice if, instead of generating "hardcoded" stylistic
 information like <b></b>, <i></i> and the use of <table>, the output
 could be more generic and semantically marked up for use with CSS.  This
 is something that could contribute a lot towards making better-presented
 documentation.
ddoc allows you to override its styling macros to output anything you like, here are some defaults: B = <b>$0</b> I = <i>$0</i> U = <u>$0</u> ... D_PSYMBOL = $(U $0) D_PARAM = $(I $0) ... DDOC_PSYMBOL = $(U $0) DDOC_KEYWORD = $(B $0) DDOC_PARAM = $(I $0) http://dlang.org/ddoc.html
Dec 28 2014
parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 28/12/14 19:04, Nick Treleaven via Digitalmars-d wrote:
 You can just use Params: for them also. Perhaps separating them might be nice
 though.
It seems a good idea to separate them, yes. I was slightly disappointed that "Template Params:" didn't Just Work.
 ddoc allows you to override its styling macros to output anything you like,
here
 are some defaults:
I recognize this is possible (I've done it for my own projects), I'd just like to see the defaults improved so as to better separate between semantic markup and formatting. We would be in a much better position if a redesign of the online druntime/phobos docs could be done 90% with changes to a style sheet.
Dec 28 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/28/2014 10:16 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 28/12/14 19:04, Nick Treleaven via Digitalmars-d wrote:
 You can just use Params: for them also. Perhaps separating them might be nice
 though.
It seems a good idea to separate them, yes. I was slightly disappointed that "Template Params:" didn't Just Work.
 ddoc allows you to override its styling macros to output anything you like,
here
 are some defaults:
I recognize this is possible (I've done it for my own projects), I'd just like to see the defaults improved so as to better separate between semantic markup and formatting. We would be in a much better position if a redesign of the online druntime/phobos docs could be done 90% with changes to a style sheet.
It's already possible. Change the macro definitions in the std.ddoc file.
Dec 28 2014
parent reply "Joseph Rushton Wakeling" <joseph.wakeling webdrake.net> writes:
On Monday, 29 December 2014 at 00:50:10 UTC, Walter Bright wrote:
 It's already possible. Change the macro definitions in the 
 std.ddoc file.
Sure. But I did think it might be a good idea to discuss things here first before jumping into changing anything. After all, you might have good reasons for the current defaults being as they are.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:24 AM, Joseph Rushton Wakeling wrote:
 On Monday, 29 December 2014 at 00:50:10 UTC, Walter Bright wrote:
 It's already possible. Change the macro definitions in the std.ddoc file.
Sure. But I did think it might be a good idea to discuss things here first before jumping into changing anything. After all, you might have good reasons for the current defaults being as they are.
The current defaults make it work without needing a style sheet. That's pretty much the reason why they are the way they are.
Dec 29 2014
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 29 December 2014 at 19:51:26 UTC, Walter Bright wrote:
 The current defaults make it work without needing a style 
 sheet. That's pretty much the reason why they are the way they 
 are.
You could also just bundle a stylesheet with it, which would be the best of both worlds. Have the semantic tags in the main macros and the style as an embedded <style> section in the DDOC macro header. The generated HTML would work just as well for what it does now, and be available for things much better at the same time.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 11:58 AM, Adam D. Ruppe wrote:
 On Monday, 29 December 2014 at 19:51:26 UTC, Walter Bright wrote:
 The current defaults make it work without needing a style sheet. That's pretty
 much the reason why they are the way they are.
You could also just bundle a stylesheet with it, which would be the best of both worlds. Have the semantic tags in the main macros and the style as an embedded <style> section in the DDOC macro header.
I'd rather not, as it's another thing to go wrong (i.e. where would that default stylesheet reside?).
Dec 29 2014
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 29 December 2014 at 22:32:59 UTC, Walter Bright wrote:
 I'd rather not, as it's another thing to go wrong (i.e. where 
 would that default stylesheet reside?).
Right there: https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L144 inline, immediately following the <title> tag.
Dec 29 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 2:42 PM, Adam D. Ruppe wrote:
 On Monday, 29 December 2014 at 22:32:59 UTC, Walter Bright wrote:
 I'd rather not, as it's another thing to go wrong (i.e. where would that
 default stylesheet reside?).
Right there: https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L144 inline, immediately following the <title> tag.
If you know how to do it, submit a PR!
Dec 29 2014
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 29 December 2014 at 23:13:32 UTC, Walter Bright wrote:
 If you know how to do it, submit a PR!
Eh, the other definitions need to be changed to add the correct data which is a bit tedious to ensure it is all covered... and I personally don't care that much, since I don't use it anyway.
Dec 29 2014
prev sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 29/12/14 23:42, Adam D. Ruppe via Digitalmars-d wrote:
 On Monday, 29 December 2014 at 22:32:59 UTC, Walter Bright wrote:
 I'd rather not, as it's another thing to go wrong (i.e. where would that
 default stylesheet reside?).
Right there: https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L144 inline, immediately following the <title> tag.
It's what I did for a project of mine: https://github.com/WebDrake/hap/blob/master/template.ddoc For something like the Phobos/druntime docs, or the dlang.org website, it's probably better to have a separate style.css file which is linked to from the template ddoc file, but that shouldn't complicate matters more than needing to include that file in the dlang.org "install" option.
Dec 29 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/28/2014 6:49 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 BTW it would be nice if, instead of generating "hardcoded" stylistic
information
 like <b></b>, <i></i> and the use of <table>, the output could be more generic
 and semantically marked up for use with CSS.  This is something that could
 contribute a lot towards making better-presented documentation.
Ddoc does not generate html markup. It generates macro calls, and the macro definitions default to expanding to html. You can override them to produce other effects.
Dec 28 2014
parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 29/12/14 01:48, Walter Bright via Digitalmars-d wrote:
 Ddoc does not generate html markup. It generates macro calls, and the macro
 definitions default to expanding to html. You can override them to produce
other
 effects.
Yes, understood, but I'm talking about the defaults here -- it would be nice if they were set in such a way as to offer better interaction with CSS+JavaScript. It's fine if you want to say "patches, please", but there might be practical reasons why the defaults are as they are, so I wanted to sound out the idea first.
Dec 29 2014
prev sibling next sibling parent reply "Suliman" <evermind live.ru> writes:
Walter, can be documentation moved to wiki? I think a lot of 
valanter will help with it's improving and adding more samples. 
The reading and understanding it's sometime is bug pain, 
especially with programmers, who come to D from Python and other 
simple languages.
Dec 28 2014
next sibling parent reply "Xinok" <xinok live.com> writes:
On Sunday, 28 December 2014 at 15:38:32 UTC, Suliman wrote:
 Walter, can be documentation moved to wiki? ....
The trouble with that is the documentation for Phobos is generated using DDoc [1]. There's a philosophy behind using Ddoc, such as the documentation is more likely to stay in sync with the code. Granted, using the wiki would make it easier for people to contribute to the documentation, but by continuing to use Ddoc, we advertise that feature of the D compiler and it will encourage us to continue to improve it. [1] http://dlang.org/ddoc.html
Dec 28 2014
parent reply Russel Winder via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Sun, 2014-12-28 at 16:41 +0000, Xinok via Digitalmars-d wrote:
 On Sunday, 28 December 2014 at 15:38:32 UTC, Suliman wrote:
 Walter, can be documentation moved to wiki? ....
The trouble with that is the documentation for Phobos is generated using DDoc [1]. There's a philosophy behind using Ddoc, such as the documentation is more likely to stay in sync with the
Given this thread, "more likely" seems to imply 0%, so something of a #fail. The problem is not DDoc per se (*), but the process that allowed the code into the repository without proper documentation. Trying to fix this problem seems to require people who want to contribute to have to clone Phobos and submit pull requests. I am not convinced this will actually happen. I agree a wiki isn't going to help, but maybe an email-based workflow could?
 code. Granted, using the wiki would make it easier for people to 
 contribute to the documentation, but by continuing to use Ddoc, we 
 advertise that feature of the D compiler and it will encourage us to 
 continue to improve it.
 
 
 [1] http://dlang.org/ddoc.html
(*) Every programming language seems to have to "do its own thing" thus requiring the language implementers to maintain a specialist tool. Couldn't D just use Doxygen or JavaDoc and thereby leave maintenance of the tool to someone else? -- Russel. ============================================================================= Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.winder ekiga.net 41 Buckmaster Road m: +44 7770 465 077 xmpp: russel winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder
Dec 28 2014
parent reply Nick Treleaven <ntrel-pub mybtinternet.com> writes:
On 28/12/2014 17:51, Russel Winder via Digitalmars-d wrote:
 Trying to fix
 this problem seems to require people who want to contribute to have to
 clone Phobos and submit pull requests.
You can do it all from your browser if you want, check the "Improve this page" link at the top right of each module.
Dec 28 2014
parent "Craig Dillabaugh" <craig.dillabaugh gmail.com> writes:
On Sunday, 28 December 2014 at 17:55:26 UTC, Nick Treleaven wrote:
 On 28/12/2014 17:51, Russel Winder via Digitalmars-d wrote:
 Trying to fix
 this problem seems to require people who want to contribute to 
 have to
 clone Phobos and submit pull requests.
You can do it all from your browser if you want, check the "Improve this page" link at the top right of each module.
In my own personal experience using the "Improve this page" doesn't really work very well. I tried submitting a simple documentation fix that way and somehow the GitHub online editor made a mess of what I had done. It was easier just to use regular old git from the command line.
Dec 28 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/28/2014 7:38 AM, Suliman wrote:
 Walter, can be documentation moved to wiki? I think a lot of valanter will help
 with it's improving and adding more samples. The reading and understanding it's
 sometime is bug pain, especially with programmers, who come to D from Python
and
 other simple languages.
I'm strongly in favor of a system where the top part of the page is the 'official' part and underneath that are user-contributed parts.
Dec 28 2014
parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 29 December 2014 at 10:40, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 12/28/2014 7:38 AM, Suliman wrote:
 Walter, can be documentation moved to wiki? I think a lot of valanter will
 help
 with it's improving and adding more samples. The reading and understanding
 it's
 sometime is bug pain, especially with programmers, who come to D from
 Python and
 other simple languages.
I'm strongly in favor of a system where the top part of the page is the 'official' part and underneath that are user-contributed parts.
Ah, like MSDN, very savvy :P
Dec 28 2014
prev sibling next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/27/14 10:00 PM, Walter Bright wrote:
 This is so bad there isn't even a direct link to it, it hides in shame.
 Just go here:



 and scroll up one entry. Here it is:

     size_t encode(Tgt, Src, R)(in Src[] s, R range);

     Encodes c in units of type E and writes the result to the output
 range R.
     Returns the number of Es written.

 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
 7. No clue where the variable 'c' comes from.
 8. No clue where the type 'E' comes from.
 9. 'R' is a type, not an instance.
 10. I suspect it has something to do with UTF encodings, but there is no
 clue.
After programming in Ruby for a long time (and I think in Python it's the same) I came to the conclusion that all the sections (Return, Params, Example) just make writing the documentation a harder task. For example: ~~~ /* * Returns a lowered-case version of a string. * * Params: * - x: the string to be lowered case * Return: the string in lower cases */ string lowercase(string x) ~~~ It's kind of redundant. True, there might be something more to say about the parameters or the return value, but if you are reading the documentation then you might as well read a whole paragraph explaining everything about it. For example, this is the documentation for the String#downcase method in Ruby: ~~~ def downcase(str) Returns a copy of `str` with all uppercase letters replaced with their lowercase counterparts. The operation is locale insensitive—only characters “A” to “Z” are affected. Note: case replacement is effective only in ASCII region. ~~~ Note how the documentation directly mentions the parameters. There's also an example snippet there, that is denoted by indenting code (similar to Markdown). I think it would be much better to use Markdown for the documentation, as it is so popular and easy to read (although not that easy to parse). Then it would be awesome if the documentation could be smarter, providing semi-automatic links. For example writing "#string.join" would create a link to that function in that module (the $(XREF ...) is very noisy and verbose).
Dec 28 2014
next sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Sunday, 28 December 2014 at 15:57:39 UTC, Ary Borenszweig 
wrote:
 On 12/27/14 10:00 PM, Walter Bright wrote:
 This is so bad there isn't even a direct link to it, it hides 
 in shame.
 Just go here:



 and scroll up one entry. Here it is:

    size_t encode(Tgt, Src, R)(in Src[] s, R range);

    Encodes c in units of type E and writes the result to the 
 output
 range R.
    Returns the number of Es written.

 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same 
 module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
 7. No clue where the variable 'c' comes from.
 8. No clue where the type 'E' comes from.
 9. 'R' is a type, not an instance.
 10. I suspect it has something to do with UTF encodings, but 
 there is no
 clue.
After programming in Ruby for a long time (and I think in Python it's the same) I came to the conclusion that all the sections (Return, Params, Example) just make writing the documentation a harder task. For example: ~~~ /* * Returns a lowered-case version of a string. * * Params: * - x: the string to be lowered case * Return: the string in lower cases */ string lowercase(string x) ~~~ It's kind of redundant. True, there might be something more to say about the parameters or the return value, but if you are reading the documentation then you might as well read a whole paragraph explaining everything about it. For example, this is the documentation for the String#downcase method in Ruby: ~~~ def downcase(str) Returns a copy of `str` with all uppercase letters replaced with their lowercase counterparts. The operation is locale insensitive—only characters “A” to “Z” are affected. Note: case replacement is effective only in ASCII region. ~~~ Note how the documentation directly mentions the parameters. There's also an example snippet there, that is denoted by indenting code (similar to Markdown). I think it would be much better to use Markdown for the documentation, as it is so popular and easy to read (although not that easy to parse). Then it would be awesome if the documentation could be smarter, providing semi-automatic links. For example writing "#string.join" would create a link to that function in that module (the $(XREF ...) is very noisy and verbose).
It depends on the function being documented. For 'downcase', such blocks are overkill; for more complex functions (and templates!) they're very helpful Params: is an excellent place to explain the *requirements* for the parameters. Even the current doc, which seems to be rewritten since Walter's post, does not make use of this: there's a paragraph "The input to this function MUST be validly encoded..." - this should not be a separate paragraph; it should be mentioned right in Params: for that parameter. Consistently documenting requirements/contract for each parameter in the Params: entry for that parameter makes it easy to find the requirement at glance. DDoc is powerful, but it is a very nasty case of "hard things are possible, easy things are hard" (e.g. tables, and very unreadable in source $(B bold) instead of **bold**, $(D code) instead of `code`, $(LINK2 ...), etc. . I'm working on generating documentation with both DDoc and Markdown in the same source, BTW, but not with the builtin DMD generator. Most of markdown can be used without conflicts, with notable exceptions of: --- // horizontal line (but - - - works) something els) -------- I think it'd be a good idea to add at least a subset of markdown to DMD DDoc, which could generate DDoc macros (e.g. **bold**, *italic*, `inline code` (DDoc already has nice syntax for code *blocks*), [link](www.link.com), and some table syntax (not in vanilla markdown, but e.g. GitHub markdown/PanDoc markdown have a common syntax) - I may be able to find some time to work on this for DMD DDoc in summer (not sooner unfortunately, I'd need some time to look around the code as I never touched it), but would it have a chance of being merged? (Walter?)
Dec 28 2014
next sibling parent "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Sunday, 28 December 2014 at 16:44:05 UTC, Kiith-Sa wrote:
 On Sunday, 28 December 2014 at 15:57:39 UTC, Ary Borenszweig 
 wrote:
 On 12/27/14 10:00 PM, Walter Bright wrote:
 This is so bad there isn't even a direct link to it, it hides 
 in shame.
 Just go here:



 and scroll up one entry. Here it is:

   size_t encode(Tgt, Src, R)(in Src[] s, R range);

   Encodes c in units of type E and writes the result to the 
 output
 range R.
   Returns the number of Es written.

 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same 
 module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
 7. No clue where the variable 'c' comes from.
 8. No clue where the type 'E' comes from.
 9. 'R' is a type, not an instance.
 10. I suspect it has something to do with UTF encodings, but 
 there is no
 clue.
After programming in Ruby for a long time (and I think in Python it's the same) I came to the conclusion that all the sections (Return, Params, Example) just make writing the documentation a harder task. For example: ~~~ /* * Returns a lowered-case version of a string. * * Params: * - x: the string to be lowered case * Return: the string in lower cases */ string lowercase(string x) ~~~ It's kind of redundant. True, there might be something more to say about the parameters or the return value, but if you are reading the documentation then you might as well read a whole paragraph explaining everything about it. For example, this is the documentation for the String#downcase method in Ruby: ~~~ def downcase(str) Returns a copy of `str` with all uppercase letters replaced with their lowercase counterparts. The operation is locale insensitive—only characters “A” to “Z” are affected. Note: case replacement is effective only in ASCII region. ~~~ Note how the documentation directly mentions the parameters. There's also an example snippet there, that is denoted by indenting code (similar to Markdown). I think it would be much better to use Markdown for the documentation, as it is so popular and easy to read (although not that easy to parse). Then it would be awesome if the documentation could be smarter, providing semi-automatic links. For example writing "#string.join" would create a link to that function in that module (the $(XREF ...) is very noisy and verbose).
It depends on the function being documented. For 'downcase', such blocks are overkill; for more complex functions (and templates!) they're very helpful Params: is an excellent place to explain the *requirements* for the parameters. Even the current doc, which seems to be rewritten since Walter's post, does not make use of this: there's a paragraph "The input to this function MUST be validly encoded..." - this should not be a separate paragraph; it should be mentioned right in Params: for that parameter. Consistently documenting requirements/contract for each parameter in the Params: entry for that parameter makes it easy to find the requirement at glance. DDoc is powerful, but it is a very nasty case of "hard things are possible, easy things are hard" (e.g. tables, and very unreadable in source $(B bold) instead of **bold**, $(D code) instead of `code`, $(LINK2 ...), etc. . I'm working on generating documentation with both DDoc and Markdown in the same source, BTW, but not with the builtin DMD generator. Most of markdown can be used without conflicts, with notable exceptions of: --- // horizontal line (but - - - works) something els) -------- I think it'd be a good idea to add at least a subset of markdown to DMD DDoc, which could generate DDoc macros (e.g. **bold**, *italic*, `inline code` (DDoc already has nice syntax for code *blocks*), [link](www.link.com), and some table syntax (not in vanilla markdown, but e.g. GitHub markdown/PanDoc markdown have a common syntax) - I may be able to find some time to work on this for DMD DDoc in summer (not sooner unfortunately, I'd need some time to look around the code as I never touched it), but would it have a chance of being merged? (Walter?)
argh, formatting, the heading2 thing should be: heading2 --------
Dec 28 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/28/2014 8:44 AM, Kiith-Sa wrote:
 It depends on the function being documented. For 'downcase', such blocks are
 overkill;
After doing it both ways for a while, I'm pretty convinced they are not overkill even for trivial functions: 1. they lend an air of consistency and comfort to the reader 2. they provide an anchor for automated tools which can extract the information 3. without such a block, I've found that I (and others, 'obvious' parameters which are actually not obvious at all. 4. a block can be styled in a custom manner
 DDoc is powerful, but it is a very nasty case of "hard things are possible,
easy
 things are hard" (e.g. tables, and very unreadable in source $(B bold) instead
 of **bold**, $(D code) instead of `code`, $(LINK2 ...), etc. .
Having used both Ddoc and Markdown, I seriously disagree with this. Take a look at the markdown source for DIP69. It's horrific.
 I think it'd be a good idea to add at least a subset of markdown to DMD DDoc,
 which could generate DDoc macros (e.g. **bold**, *italic*, `inline code` (DDoc
 already has nice syntax for code *blocks*), [link](www.link.com), and some
table
 syntax (not in vanilla markdown, but e.g. GitHub markdown/PanDoc markdown have
a
 common syntax)

 - I may be able to find some time to work on this for DMD DDoc in summer (not
 sooner unfortunately, I'd need some time to look around the code as I never
 touched it), but would it have a chance of being merged? (Walter?)
I'd rather not accept some Markdown dialect into Ddoc.
Dec 28 2014
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-29 06:39, Walter Bright wrote:

 Having used both Ddoc and Markdown, I seriously disagree with this. Take
 a look at the markdown source for DIP69. It's horrific.
Do you mean on the wiki? The wiki doesn't use Markdown. At least not anyone I've seen. -- /Jacob Carlborg
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:19 AM, Jacob Carlborg wrote:
 On 2014-12-29 06:39, Walter Bright wrote:

 Having used both Ddoc and Markdown, I seriously disagree with this. Take
 a look at the markdown source for DIP69. It's horrific.
Do you mean on the wiki? The wiki doesn't use Markdown. At least not anyone I've seen.
It uses something pretty similar. They all kinda mush together in my mind :-(
Dec 29 2014
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-29 20:47, Walter Bright wrote:

 It uses something pretty similar. They all kinda mush together in my
 mind :-(
Don't blame Markdown just because some other markup language you don't like looks similar to you. -- /Jacob Carlborg
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 12:02 PM, Jacob Carlborg wrote:
 On 2014-12-29 20:47, Walter Bright wrote:

 It uses something pretty similar. They all kinda mush together in my
 mind :-(
Don't blame Markdown just because some other markup language you don't like looks similar to you.
Why I don't like Markdown: "Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags." "For any markup that is not covered by Markdown’s syntax, you simply use HTML itself." http://daringfireball.net/projects/markdown/syntax#html Which is the same criticism for the markdown used in the D wiki. It's a frankensteinian hybrid.
Dec 29 2014
next sibling parent "Dicebot" <public dicebot.lv> writes:
On Monday, 29 December 2014 at 22:35:50 UTC, Walter Bright wrote:
 On 12/29/2014 12:02 PM, Jacob Carlborg wrote:
 On 2014-12-29 20:47, Walter Bright wrote:

 It uses something pretty similar. They all kinda mush 
 together in my
 mind :-(
Don't blame Markdown just because some other markup language you don't like looks similar to you.
Why I don't like Markdown: "Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags."
Which just the thing you need to make good simple documentation. DDOC suffers a lot from being generic macro language - it is simply not specialized enough to be convenient documentation markup language.
Dec 29 2014
prev sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 29 December 2014 at 22:35:50 UTC, Walter Bright wrote:
 "For any markup that is not covered by Markdown’s syntax, you 
 simply use HTML itself."
That's why I don't like DDoc. It has the "feature" if passing characters through it unencoded for embedding HTML, but that makes the output impossible to make correct and extremely tedious to approximate correctness when documenting something like xml. Ddoc isn't too bad, but trying to document examples in dom.d turned into a mess of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it. Since then, I just type plain text commands and don't use the macro processor in dmd. It is nice code, but just a flawed design for this use :(
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
 Ddoc isn't too bad, but trying to document examples in dom.d turned into a mess
 of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
I'd make a macro: XML=$(LT)$0/$(GT) I use custom macros all the time in Ddoc. If you aren't, you're not doing it right :-)
Dec 29 2014
next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/29/14 8:49 PM, Walter Bright wrote:
 On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
 Ddoc isn't too bad, but trying to document examples in dom.d turned
 into a mess
 of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
I'd make a macro: XML=$(LT)$0/$(GT) I use custom macros all the time in Ddoc. If you aren't, you're not doing it right :-)
Macros are for code, not for documentation. When wanting to contrirbute documentation you'll have to learn which macros the author defined and which ones to use. Again, this makes it harder to write docs, not easier.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 5:09 PM, Ary Borenszweig wrote:
 On 12/29/14 8:49 PM, Walter Bright wrote:
 On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
 Ddoc isn't too bad, but trying to document examples in dom.d turned
 into a mess
 of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
I'd make a macro: XML=$(LT)$0/$(GT) I use custom macros all the time in Ddoc. If you aren't, you're not doing it right :-)
Macros are for code, not for documentation.
?? Text processing using macros has a very long history.
 When wanting to contrirbute documentation you'll have to learn which macros the
 author defined and which ones to use. Again, this makes it harder to write
docs,
 not easier.
When I write markdown in github, wiki, reddit, man, troff, md, javadoc, doxygen, etc., I have to read the markup doc for that particular flavor and figure it out, too. If there was a standard markup language, you'd be right. But there isn't. Everyone invents their own system. I really do not understand this particular criticism of Ddoc (several others here have made the same criticism). (And actually, the Ddoc macro system very closely resembles the one used by make, as that is a simple and effective one, well known by programmers.)
Dec 29 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 17:51:14 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 (And actually, the Ddoc macro system very closely resembles the one used =
by=20
 make, as that is a simple and effective one, well known by programmers.)
i'm still not able to write anything more complex than three-line makefile, yet i'm doing programming for living for decades and actively using build systems. and none of my makefiles works with the first try, as i always forget that those idiotic tabs really MATTERS. my favorite editor can't even insert tab without tricks.
Dec 29 2014
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-30 02:51, Walter Bright wrote:

 (And actually, the Ddoc macro system very closely resembles the one used
 by make, as that is a simple and effective one, well known by programmers.)
"make" has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like "make" I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/ -- /Jacob Carlborg
Dec 31 2014
next sibling parent Dmitry Olshansky <dmitry.olsh gmail.com> writes:
31-Dec-2014 15:17, Jacob Carlborg пишет:
 On 2014-12-30 02:51, Walter Bright wrote:

 (And actually, the Ddoc macro system very closely resembles the one used
 by make, as that is a simple and effective one, well known by
 programmers.)
"simple, effective and well-known" ? I have to say all of 3 are wrong.
 "make" has to be the worst tool ever created. I not just me that has
 that opinion [1]. That you even consider this as a positive argument is
 baffling me.
+1
 Or rather not, if you like "make" I can see why you like Ddoc.

 [1] http://www.conifersystems.com/whitepapers/gnu-make/
-- Dmitry Olshansky
Dec 31 2014
prev sibling next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 9:17 AM, Jacob Carlborg wrote:
 On 2014-12-30 02:51, Walter Bright wrote:

 (And actually, the Ddoc macro system very closely resembles the one used
 by make, as that is a simple and effective one, well known by
 programmers.)
"make" has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like "make" I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/
Agreed. I try to avoid makefiles as much as I can. And it's no wonder why there are so many alternatives (rake, nake, etc.)
Dec 31 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 5:03 AM, Ary Borenszweig wrote:
 And it's no wonder why there are so many alternatives (rake, nake, etc.)
Which one has a better text macro system?
Dec 31 2014
parent Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 4:07 PM, Walter Bright wrote:
 On 12/31/2014 5:03 AM, Ary Borenszweig wrote:
 And it's no wonder why there are so many alternatives (rake, nake, etc.)
Which one has a better text macro system?
A real programming language without text macro systems.
Dec 31 2014
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdan.org> writes:
Ary Borenszweig <ary esperanto.org.ar> wrote:
 On 12/31/14 9:17 AM, Jacob Carlborg wrote:
 On 2014-12-30 02:51, Walter Bright wrote:
 
 (And actually, the Ddoc macro system very closely resembles the one used
 by make, as that is a simple and effective one, well known by
 programmers.)
"make" has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like "make" I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/
Agreed. I try to avoid makefiles as much as I can. And it's no wonder why there are so many alternatives (rake, nake, etc.)
... Neither of which successful :o)
Dec 31 2014
next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 09:23:58PM +0000, Andrei Alexandrescu via Digitalmars-d
wrote:
 Ary Borenszweig <ary esperanto.org.ar> wrote:
 On 12/31/14 9:17 AM, Jacob Carlborg wrote:
 On 2014-12-30 02:51, Walter Bright wrote:
 
 (And actually, the Ddoc macro system very closely resembles the
 one used by make, as that is a simple and effective one, well
 known by programmers.)
"make" has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like "make" I can see why you like Ddoc. [1] http://www.conifersystems.com/whitepapers/gnu-make/
Agreed. I try to avoid makefiles as much as I can. And it's no wonder why there are so many alternatives (rake, nake, etc.)
... Neither of which successful :o)
Yeah, just like D is still floundering in obscurity while inferior languages like C/C++ continue to flourish. *shrug* T -- There are four kinds of lies: lies, damn lies, and statistics.
Dec 31 2014
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote:
 And it's no wonder why there are so many alternatives (rake, nake, etc.)
... Neither of which successful :o)
I googled nake and couldn't find any references to it.
Dec 31 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 14:14:46 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote:
 And it's no wonder why there are so many alternatives (rake, nake, etc=
.)
 ... Neither of which successful :o)
=20 I googled nake and couldn't find any references to it.
"nake build system", first link from google: "Nake is a magic task runner tool for .NET. It's a hybrid of Shovel and Rake. The DSL for defining tasks is uniquely minimal and it's just
Dec 31 2014
prev sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 7:14 PM, Walter Bright wrote:
 On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote:
 And it's no wonder why there are so many alternatives (rake, nake, etc.)
... Neither of which successful :o)
I googled nake and couldn't find any references to it.
Oh, it's for Nimrod (Now Nim)
Dec 31 2014
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 7:43 PM, Ary Borenszweig wrote:
 On 12/31/14 7:14 PM, Walter Bright wrote:
 On 12/31/2014 1:23 PM, Andrei Alexandrescu wrote:
 And it's no wonder why there are so many alternatives (rake, nake,
 etc.)
... Neither of which successful :o)
I googled nake and couldn't find any references to it.
Oh, it's for Nimrod (Now Nim)
This one: https://github.com/fowlmouth/nake I'm not saying that it's popular, but people keep inventing things to avoid makefiles (and I think it's good to have this for a language).
Dec 31 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 2:47 PM, Ary Borenszweig wrote:
 I'm not saying that it's popular, but people keep inventing things to avoid
 makefiles (and I think it's good to have this for a language).
People keep inventing new markup formats, too. (The first one I used, runoff, dates from the 70's.) I think the unix .man markup is even older.
Dec 31 2014
prev sibling parent reply "Jacob Carlborg" <doob me.com> writes:
On Wednesday, 31 December 2014 at 21:23:58 UTC, Andrei 
Alexandrescu wrote:
 Ary Borenszweig <ary esperanto.org.ar> wrote:
 And it's no wonder why there are so many alternatives (rake, 
 nake, etc.)
... Neither of which successful :o)
What!! Rake is used by every Rails project out there. Thousands of more projects than D projects. -- /Jacob Carlborg
Dec 31 2014
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 22:37:08 +0000
Jacob Carlborg via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On Wednesday, 31 December 2014 at 21:23:58 UTC, Andrei=20
 Alexandrescu wrote:
 Ary Borenszweig <ary esperanto.org.ar> wrote:
=20
 And it's no wonder why there are so many alternatives (rake,=20
 nake, etc.)
... Neither of which successful :o)
=20 What!! Rake is used by every Rails project out there. Thousands=20 of more projects than D projects.
and not only rails. mkvtools_nix using rake too, but it's pure C++ project.
Dec 31 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 4:17 AM, Jacob Carlborg wrote:
 On 2014-12-30 02:51, Walter Bright wrote:

 (And actually, the Ddoc macro system very closely resembles the one used
 by make, as that is a simple and effective one, well known by programmers.)
"make" has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like "make" I can see why you like Ddoc.
You can not like a car's suspension but still like its engine.
Dec 31 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 10:59:32 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 4:17 AM, Jacob Carlborg wrote:
 On 2014-12-30 02:51, Walter Bright wrote:

 (And actually, the Ddoc macro system very closely resembles the one us=
ed
 by make, as that is a simple and effective one, well known by programm=
ers.)
 "make" has to be the worst tool ever created. I not just me that has th=
at
 opinion [1]. That you even consider this as a positive argument is baff=
ling me.
 Or rather not, if you like "make" I can see why you like Ddoc.
=20 You can not like a car's suspension but still like its engine.
but 'make' is a failure in every aspect, especially GNU make. bwah, build tool that can't do autoimatic dependency tracking? you must be joking.
Dec 31 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 10:17:26PM +0200, ketmar via Digitalmars-d wrote:
 On Wed, 31 Dec 2014 10:59:32 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 
 On 12/31/2014 4:17 AM, Jacob Carlborg wrote:
 On 2014-12-30 02:51, Walter Bright wrote:

 (And actually, the Ddoc macro system very closely resembles the
 one used by make, as that is a simple and effective one, well
 known by programmers.)
"make" has to be the worst tool ever created. I not just me that has that opinion [1]. That you even consider this as a positive argument is baffling me. Or rather not, if you like "make" I can see why you like Ddoc.
You can not like a car's suspension but still like its engine.
but 'make' is a failure in every aspect, especially GNU make. bwah, build tool that can't do autoimatic dependency tracking? you must be joking.
Yeah no kidding. How do I hate make? Let me count the ways: 1) Recursive make considered harmful. (Google it.) 2) Non-reproducible builds -- you have to make clean; make, just to be absolutely sure your build is correct (defeats the purpose of a build tool, really -- might as well use a shell script of compiler commands). 3) Changing compile flags in a makefile does not trigger rebuilding of all affected targets. You're on your own to kick make into rebuilding what's needed. Usually, this means yet another `make clean; make`. Which doesn't always work -- see (6). A great source of heisenbugs. 4) Unnecessary rebuilds -- if you edit a comment in a header file, it causes a waterfall effect in rebuilding everything that #include's it, and even though all of the .o files produced are identical to those from the previous run, make is oblivious to this fact, and wastes time linking them all and cascading even more rebuilds that depend on the link products, etc., etc.. 5) Timestamps are unreliable -- accidentally touching the timestamp of a header file included by everything (without changing its contents) will cause the entire tree to be rebuilt. Timestamps over NFS may be inconsistent, causing make to randomly rebuild files that don't need to be rebuilt and skip files that do. 6) Dependency scanning is O(n). Not scalable. 7) No built-in cleanup function -- everybody writes their own `make clean` rules, which are inevitably wrong (`rm -rf *.o *.so`, but what if you have an .so that isn't generated by the build?) or incomplete (oops, forgot to delete the .c file generated by bison). This, coupled with (2) and (3), leads to heisenbugs where stale libraries from previous builds get linked into the executable, causing runtime bugs that don't exist in the source code. The solution? `make clean; make` and have another coffee break. Very productive. (Except when your make clean rules failed to delete said stale library, then it's time to \rm -rf and git clone a new repo.) 8) Implicit dependencies between source files require external tooling support (gcc -MF, which leaves stray .dep files all over the place, which `make clean` inevitably forgets to clean up, and which cause mistakes in the dependency tree when dependencies change and the .dep files aren't updated before make reads them). 9) Build parameters (e.g. compiler flags) are not well-encapsulated -- the global CFLAGS has to be tweaked, or you have to invent your own convoluted set of macros that are combined into the final compiler flags, which leads to a maintenance nightmare. 10) No support for out-of-tree builds (which are increasingly becoming clear that it's the superior way to go -- littering generated files in the same directories as source files inevitably leads to a gigantic mess). 11) No support for simultaneous variant builds such as cross-compiling for multiple architectures in the same run (unless you manually write this, which is a royal pain and extremely error-prone for something the build system *should* have taken care of for you) -- because of (7): all build variables are global and there's no way to reuse the same build rules with different target parameters. 12) Many common build tasks are not supported by the core make system, and require the user to reinvent the wheel, which results in large, convoluted, and fragile makefiles that stop working as soon as you try to do something that wasn't anticipated by the makefile authors. 13) Anachronistic syntax requirements, like distinguishing between spaces and tabs. Make is like C... it offers you raw functionality to shoot yourself in the foot and drown in dependency bugs, just like C offers you countless ways to have buffer overruns and dangling pointers. Yet people glory in their scars acquired over decades of pain, and build entire ecosystems around it, such that mention of any alternatives is resisted at best, and ridiculed and summarily dismissed at worst. What's baffling is that such a reaction is observed even in the D community, which, ostensibly, exists exactly because people are finally fed up with the problems of C and want a less painful language. T -- It only takes one twig to burn down a forest.
Dec 31 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote:
 Yeah no kidding. How do I hate make? Let me count the ways:
Ironically, none of your points mention the macro system.
Dec 31 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 14:19:00 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote:
 Yeah no kidding. How do I hate make? Let me count the ways:
=20 Ironically, none of your points mention the macro system.
that's 'cause 'make' doesn't need any. it's either enough to have envvars for simple tool, or you need a scripting language for complex extensible tool.
Dec 31 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 01, 2015 at 12:26:04AM +0200, ketmar via Digitalmars-d wrote:
 On Wed, 31 Dec 2014 14:19:00 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 
 On 12/31/2014 1:15 PM, H. S. Teoh via Digitalmars-d wrote:
 Yeah no kidding. How do I hate make? Let me count the ways:
Ironically, none of your points mention the macro system.
that's 'cause 'make' doesn't need any. it's either enough to have envvars for simple tool, or you need a scripting language for complex extensible tool.
The macro system in make is so bad, it shouldn't need an explicit mention to be obvious that it's bad. Besides, macros are where the various flavors of make differ the most anyway, so anyone who wants anything resembling a cross-platform makefile should only use the most basic of macro functions and forego the actually-useful stuff. T -- Written on the window of a clothing store: No shirt, no shoes, no service.
Dec 31 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 2:47 PM, H. S. Teoh via Digitalmars-d wrote:
 The macro system in make is so bad, it shouldn't need an explicit
 mention to be obvious that it's bad.
It's so bad you didn't mention it in the thread about the only similarity between make and Ddoc? C'mon.
 Besides, macros are where the
 various flavors of make differ the most anyway,
Those are the various extensions people have added, and Ddoc copies none of those. That complaint about make macros is irrelevant to Ddoc.
Dec 31 2014
prev sibling parent "Daniel Murphy" <yebbliesnospam gmail.com> writes:
"H. S. Teoh via Digitalmars-d"  wrote in message 
news:mailman.3882.1420060673.9932.digitalmars-d puremagic.com...

 Yeah no kidding. How do I hate make? Let me count the ways:
 ...
Most of these are only problems with large projects, and large makefiles. For smaller projects make is vastly superior to a shell script, and almost always already installed.
Jan 02 2015
prev sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 15:49:10 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
 Ddoc isn't too bad, but trying to document examples in dom.d turned int=
o a mess
 of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
=20 I'd make a macro: =20 XML=3D$(LT)$0/$(GT) =20 I use custom macros all the time in Ddoc. If you aren't, you're not doing=
it=20
 right :-)
that's why ddoc is completely unusable either for reading "as is" or for generating separate documentation. i was very excited about built-in documentation generator in D, and now i'm not using it at all. i rarely generating stand-alone docs, they are just not handy for me. i prefer to read documentation right in the source (yet i still want to have an option to generate stand-alone files). did you tried to read Phobos documentation in Phobos sources? those macros are pure visual noise. i don't mind if D will understand one of the Markdown variants, or textile, or rss -- anything that is READABLE without preprocessing, yet can be easily processed to another format. i don't mind learning another markdown dialect if i can easily read it without preprocessing. that's why i'm not using doxygen too: it's noisy. seems that most document generator authors are sure that only generated documentation matters, so source documentation can be of any uglyness. yet if documentation is hard to read without preprocessor, it is hard to write it too! so people will tend to avoid writing it, and they will especially avoid polishing it, 'cause it's write-only, contaminated and hard to fix. D documentation WILL be bad until ddoc will start to understand some markdown-like mostly macro-free markup language.
Dec 29 2014
next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/29/14 10:49 PM, ketmar via Digitalmars-d wrote:
 On Mon, 29 Dec 2014 15:49:10 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 2:40 PM, Adam D. Ruppe wrote:
 Ddoc isn't too bad, but trying to document examples in dom.d turned into a mess
 of /// finds $(LT)foo/$(GT) quickly and I couldn't stand it.
I'd make a macro: XML=$(LT)$0/$(GT) I use custom macros all the time in Ddoc. If you aren't, you're not doing it right :-)
that's why ddoc is completely unusable either for reading "as is" or for generating separate documentation. i was very excited about built-in documentation generator in D, and now i'm not using it at all. i rarely generating stand-alone docs, they are just not handy for me. i prefer to read documentation right in the source (yet i still want to have an option to generate stand-alone files). did you tried to read Phobos documentation in Phobos sources? those macros are pure visual noise. i don't mind if D will understand one of the Markdown variants, or textile, or rss -- anything that is READABLE without preprocessing, yet can be easily processed to another format. i don't mind learning another markdown dialect if i can easily read it without preprocessing. that's why i'm not using doxygen too: it's noisy. seems that most document generator authors are sure that only generated documentation matters, so source documentation can be of any uglyness. yet if documentation is hard to read without preprocessor, it is hard to write it too! so people will tend to avoid writing it, and they will especially avoid polishing it, 'cause it's write-only, contaminated and hard to fix. D documentation WILL be bad until ddoc will start to understand some markdown-like mostly macro-free markup language.
Those are exactly my thoughts.
Dec 30 2014
parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
And here's that modified documentation generator with Markdown 
support (won't help anyone trying to contribute to Phobos, but 
maybe other projects):

http://forum.dlang.org/thread/itizuviesrhfaijyieex forum.dlang.org
Dec 30 2014
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 14:54:37 +0000
Kiith-Sa via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 And here's that modified documentation generator with Markdown=20
 support (won't help anyone trying to contribute to Phobos, but=20
 maybe other projects):
=20
 http://forum.dlang.org/thread/itizuviesrhfaijyieex forum.dlang.org
that's great, but it's not built-in. i can't tell about other people, but i for myself tend to ignore any external documentation generation tool. if it is not with compiler, it's nonexistent for me. but thanks for your work, it's much better to have separate tool than to have none. ;-)
Dec 30 2014
prev sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 01:50:01 UTC, ketmar via 
Digitalmars-d wrote:
 D documentation WILL be bad until ddoc will start to understand 
 some markdown-like mostly macro-free markup language.
I honestly don't think the macros are the biggest problem though. I think a bigger deal is the lack of overviews. Take a look here: http://dlang.org/phobos/std_algorithm.html There's some overview, and even a couple links. But the point about opaque types that are supposed to just work isn't easy to find. Contrast it to what Microsoft wrote up for Windows: http://msdn.microsoft.com/en-us/library/ms713499%28v=vs.85%29.aspx There's conceptual overviews, real-world examples, and the references (which link back to the relevant concepts and examples). std.algorithm could mention the concept of laziness, show examples of the opaque functions, have examples of the common (like seriously one of the most frequently asked questions I've seen) "how do I turn it into an array?", or show/explain how and why to avoid that. That's mostly plain text that could be written up in the module explanation or as a separate page. I think that's more important than what macros are used.
Dec 30 2014
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Tue, Dec 30, 2014 at 03:20:30PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Tuesday, 30 December 2014 at 01:50:01 UTC, ketmar via Digitalmars-d
 wrote:
D documentation WILL be bad until ddoc will start to understand some
markdown-like mostly macro-free markup language.
I honestly don't think the macros are the biggest problem though. I think a bigger deal is the lack of overviews.
Yeah, one of the most glaring defects of ddoc is the inability to generate tables of contents and/or indices. This forces you to manually maintain TOCs, navigation bars, etc., which is a royal pain and prone to quickly falling out-of-date as the code changes. There have already been a number of Phobos PR's that have slipped through without proper updating of the manually-maintained tables of links at the top of the module docs. Being able to automate this, or at least give a compiler warning when things don't match up, would be GREATLY appreciated.
 Take a look here:
 
 http://dlang.org/phobos/std_algorithm.html
 
 
 There's some overview, and even a couple links. But the point about
 opaque types that are supposed to just work isn't easy to find.
 
 Contrast it to what Microsoft wrote up for Windows:
 
 http://msdn.microsoft.com/en-us/library/ms713499%28v=vs.85%29.aspx
 
 There's conceptual overviews, real-world examples, and the references
 (which link back to the relevant concepts and examples).
 
 
 std.algorithm could mention the concept of laziness, show examples of
 the opaque functions, have examples of the common (like seriously one
 of the most frequently asked questions I've seen) "how do I turn it
 into an array?", or show/explain how and why to avoid that.
 
 
 That's mostly plain text that could be written up in the module
 explanation or as a separate page. I think that's more important than
 what macros are used.
PR, please. ;-) This is a lack in content, that no macro system can make up for, as you said. T -- People say I'm indecisive, but I'm not sure about that. -- YHL, CONLANG
Dec 30 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 10:35 AM, H. S. Teoh via Digitalmars-d wrote:
 PR, please.;-)  This is a lack in content, that no macro system can make
 up for, as you said.
I've been long hoping for this insight to occur in this thread. -- Andrei
Dec 30 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 11:42 AM, Andrei Alexandrescu wrote:
 On 12/30/14 10:35 AM, H. S. Teoh via Digitalmars-d wrote:
 PR, please.;-)  This is a lack in content, that no macro system can make
 up for, as you said.
I've been long hoping for this insight to occur in this thread. -- Andrei
Yup.
Dec 30 2014
prev sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 18:38:05 UTC, H. S. Teoh via 
Digitalmars-d wrote:
 Yeah, one of the most glaring defects of ddoc is the inability 
 to generate tables of contents and/or indices.
Absolutely, though I think this is more of a process thing than a ddoc thing - you could easily enough generate those files in a makefile as part of the build... I've written a program to do this before, but it was years ago and probably doesn't work anymore (i based it on the html output.)
 PR, please. ;-) This is a lack in content, that no macro system 
 can make up for, as you said.
I wrote a book, surely that gets me off the hook?! hey i found the time to write a rhyme, but those kind of conceptual things would take a lot of hours.... probably comparable to the book itself...
Dec 30 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 11:51 AM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 18:38:05 UTC, H. S. Teoh via
 Digitalmars-d wrote:
 Yeah, one of the most glaring defects of ddoc is the inability to
 generate tables of contents and/or indices.
Absolutely, though I think this is more of a process thing than a ddoc thing - you could easily enough generate those files in a makefile as part of the build... I've written a program to do this before, but it was years ago and probably doesn't work anymore (i based it on the html output.)
Exactly. And TOCs and indexes are generated wildly differently depending on the publishing platform. I don't think ddoc should do that.
 PR, please. ;-) This is a lack in content, that no macro system can
 make up for, as you said.
I wrote a book, surely that gets me off the hook?! hey i found the time to write a rhyme, but those kind of conceptual things would take a lot of hours.... probably comparable to the book itself...
You're soon to find out that paradoxically writing a book enlists you for more, not less, work. Andrei
Dec 30 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 11:54 AM, Andrei Alexandrescu wrote:
 You're soon to find out that paradoxically writing a book enlists you for more,
 not less, work.
Great examples are hard to come by. Would you, Adam and Ali be amenable to deriving examples from your books and putting them in the Phobos docs? I've already put one example from my slides into the Phobos docs :-)
Dec 30 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 12:24:13 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/30/2014 11:54 AM, Andrei Alexandrescu wrote:
 You're soon to find out that paradoxically writing a book enlists you f=
or more,
 not less, work.
=20 Great examples are hard to come by. Would you, Adam and Ali be amenable t=
o=20
 deriving examples from your books and putting them in the Phobos docs? I'=
ve=20
 already put one example from my slides into the Phobos docs :-)
this is a great idea, i think! maybe we can even add a links to Ali and Adam books, so people can find those boox just by reading the Phobos documentation?
Dec 30 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 1:02 PM, ketmar via Digitalmars-d wrote:
 On Tue, 30 Dec 2014 12:24:13 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/30/2014 11:54 AM, Andrei Alexandrescu wrote:
 You're soon to find out that paradoxically writing a book enlists you for more,
 not less, work.
Great examples are hard to come by. Would you, Adam and Ali be amenable to deriving examples from your books and putting them in the Phobos docs? I've already put one example from my slides into the Phobos docs :-)
this is a great idea, i think! maybe we can even add a links to Ali and Adam books, so people can find those boox just by reading the Phobos documentation?
Define "we" :o). More to come. -- Andrei
Dec 30 2014
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 15:26:57 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 this is a great idea, i think! maybe we can even add a links to Ali and
 Adam books, so people can find those boox just by reading the Phobos
 documentation?
=20 Define "we" :o). More to come. -- Andrei
i'm giving the ideas, you're doing it, we are working hard!
Dec 30 2014
prev sibling next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 15:20:30 +0000
"Adam D. Ruppe via Digitalmars-d" <digitalmars-d puremagic.com> wrote:

 On Tuesday, 30 December 2014 at 01:50:01 UTC, ketmar via=20
 Digitalmars-d wrote:
 D documentation WILL be bad until ddoc will start to understand=20
 some markdown-like mostly macro-free markup language.
=20 I honestly don't think the macros are the biggest problem though.=20 I think a bigger deal is the lack of overviews.
but the unnecessary noisy (and badly documented, that's it) documentation language surely doesn't add any joy for documentation writer. sure, markdown will not magically solve other problems, but at least it will remove one of the annoyances, which is good in itself.
Dec 30 2014
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via 
Digitalmars-d wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for 
 documentation writer.
Yeah, I see that too; I complain about ddoc as well (though I generally like it, I just wish it encoded the output correctly and had some nicer defaults, but I don't care enough to fight over it) but I don't think it is that big of a block because the hard part is writing the text rather than the formatting.
Dec 30 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 11:47 AM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via Digitalmars-d
 wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for documentation
 writer.
Yeah, I see that too; I complain about ddoc as well (though I generally like it, I just wish it encoded the output correctly and had some nicer defaults, but I don't care enough to fight over it) but I don't think it is that big of a block because the hard part is writing the text rather than the formatting.
Agreed! -- Andrei
Dec 30 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 11:49 AM, Andrei Alexandrescu wrote:
 On 12/30/14 11:47 AM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via Digitalmars-d
 wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for documentation
 writer.
Yeah, I see that too; I complain about ddoc as well (though I generally like it, I just wish it encoded the output correctly and had some nicer defaults, but I don't care enough to fight over it) but I don't think it is that big of a block because the hard part is writing the text rather than the formatting.
Agreed! -- Andrei
I agree so strongly that just email me the freakin' text and I'll mark it up and submit it. Ketmar, I expect my email inbox to fill up promptly! :-)
Dec 30 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 12:26:52 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/30/2014 11:49 AM, Andrei Alexandrescu wrote:
 On 12/30/14 11:47 AM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via Digitalmars-d
 wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for documentation
 writer.
Yeah, I see that too; I complain about ddoc as well (though I generally like it, I just wish it encoded the output correctly and had some nicer defaults, but I don't care enough to fight over it) but I don't think =
it
 is that big of a block because the hard part is writing the text rather
 than the formatting.
Agreed! -- Andrei
=20 I agree so strongly that just email me the freakin' text and I'll mark it=
up and=20
 submit it. Ketmar, I expect my email inbox to fill up promptly! :-)
i'm sux in writing documentation. i'm always explaining the things that are perfectly clear for everyone and failed to explain the things that are not so obvious ('cause they are obvious to me ;-). so i doubt that it even pass spamcheck. besides, if i start to do some real work, i will not have enough time to write my rants here!
Dec 30 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 1:00 PM, ketmar via Digitalmars-d wrote:
 On Tue, 30 Dec 2014 12:26:52 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/30/2014 11:49 AM, Andrei Alexandrescu wrote:
 On 12/30/14 11:47 AM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via Digitalmars-d
 wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for documentation
 writer.
Yeah, I see that too; I complain about ddoc as well (though I generally like it, I just wish it encoded the output correctly and had some nicer defaults, but I don't care enough to fight over it) but I don't think it is that big of a block because the hard part is writing the text rather than the formatting.
Agreed! -- Andrei
I agree so strongly that just email me the freakin' text and I'll mark it up and submit it. Ketmar, I expect my email inbox to fill up promptly! :-)
i'm sux in writing documentation. i'm always explaining the things that are perfectly clear for everyone and failed to explain the things that are not so obvious ('cause they are obvious to me ;-). so i doubt that it even pass spamcheck. besides, if i start to do some real work, i will not have enough time to write my rants here!
I'm choosing to reply to this because it is a perfect example of a pattern of cognitive dissonance that I've witnessed before in this forum. The irony is so astonishing, you were entirely right to frame it humorously - although it's not funny because it's entirely true: there's no time to get stuff done - it's all sucked by hand-wringing over it. You must be spending literally hours a week reading and composing messages on this forum, and my perception is that you are truly willing and able to help move D forward. Your posts are eloquent and well written. Yet when it comes to actually doing it, well, that's what doesn't quite happen. It seems to me that for some of us, contributing to D is like teenage sex: everybody talks about it, everybody knows how it should be done better than all others, but few are actually doing it. My question is how we can break this pattern? What steps can the D leadership take to convince folks like you to actually add, even with the simplest things? Andrei
Dec 30 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 15:39:18 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 I'm choosing to reply to this because it is a perfect example of a=20
 pattern of cognitive dissonance that I've witnessed before in this=20
 forum. The irony is so astonishing, you were entirely right to frame it=20
 humorously - although it's not funny because it's entirely true: there's=
=20
 no time to get stuff done - it's all sucked by hand-wringing over it.
it's not about time, it's about motivation. the real thing is that i have almost no motivation to make D better for others, and D is already good enough for me. i'm writing all my pet projects in D nowdays, and i'm ok both with the compiler (with some patches) and with the documentation. yet i have some thoughts that i mind to share, maybe in questionable form. i wish D to became world-wide success, and although i not motivated enough to write a code/documentation, i believe that expressing my opinions is good for those who may think the same way but didn't bother to write that. so they will see that they aren't alone. i'm trying to help people in D.learn too, as this is the thing i can do besides contributing the code/dox, so i'm not completely useless. ;-) ah, and it's fun to answer the questions, 'cause it helps me to find my weak points (and sometimes the questions themselves makes a nice riddles to solve).
 You must be spending literally hours a week reading and composing=20
 messages on this forum
this is the way i'm working, actually. when i designing the code in my head, i can do various other tasks. singing, writing to forum, playing Wasteland 2 and so on. i can even sing and play Wasteland simultaneously!
 and my perception is that you are truly willing=20
 and able to help move D forward.
yes, i love D. it has some things that i will never accept, and some things that annoys me, but it's the language that hooked me. i really with D to become widely-used mainstream language. but... see about motivation above.
 Your posts are eloquent and well written. Yet when it comes to actually
 doing it, well, that's what doesn't quite happen.
that's 'cause i often want questionable things. like allowing `auto` in or forbidding `new char[128]` syntax (or allowing `new char[128][32]` for that matter). small improvements here and there, which will hardly find their way to mainline. ah, and i HATE github. ;-) btw, you will hardly find me in DIP discussions too. i tried to design some languages in my life and found that i'm very bad in it. so if i don't see any obvious design flaws, i'm just lurking there.
 It seems to me that for some of us, contributing to D is like teenage=20
 sex: everybody talks about it, everybody knows how it should be done=20
 better than all others, but few are actually doing it.
this requires me being on github, and i don't want to be there. i understand that my hatred towards github is silly, and github is a great collaboration platform, but i just can't take it. and there is virtually no sense in posting patches to bugzilla.
 My question is how we can break this pattern? What steps can the D=20
 leadership take to convince folks like you to actually add, even with=20
 the simplest things?
i honestly don't know. this is complex issue that involves, besides other things, my lazyness and lack of motivation, which aren't directly connected to the way D is developing/managed. sure, i'm not expecting that i can direct D developement in the way i want it to go. yet seeing the great language which is contaminated with questionable legacy hurts my enthusiasm. i was there with C and C++: "we have alot of legacy code, so we can't change it to be better or do it in completely another way." i understand why not breaking people's code is so important, but... there are alot of things that dfix can do for us. and sometimes even not so intrusive changes, like deprecating prefix function attributes like `const`, aren't going to mainline. or enforcing property syntax, which will fix the long-standing bug with delegate properties (yes, i'm using that patches and i'm very happy with them). or introducing `virtual` keyword, which was banned, but desperately required to cancel `final` effect on some methods. i can go with that "cosmetic issues" for a long time. they seems to be small, but they are the source of everyday frustration. and knowning that even unintrusive fixes or fixes for which dfix will be able to upgrade source code automatically will likely not be accepted is decreasing motivation too. or take "magicport", for which i proposed to make a simplistic codegen that will produce C or C++ code (not a source translation, like magicport, but using C/C++ as "assembler" in codegen), so there will be no problems with bootstraping D compiler on the box where only C++ compiler is available. i was told that this is unlikely to be included in DMD, and immediately lost any interest in it -- as i don't need such codegen, and working on it without any hope that it will be used is just a wasted time. i don't know what you or any other person can do with this without turning D to "Ketmar's pet project". and i surely don't want to fork D, as it will not do any good for both projects. i don't know. i can stop ranting here in NGs, but this will force my overall interest in D to fade away. i'm writing here 'cause i really care. not enough to go to github and start contributing, but enough to highlight the things i consider not very good. i may be annoying, but then it's easy to just blacklist my posts in mail reader, or write simple userjs to hide my posts on the web. ;-) sorry for the long post which includes alot of homegrown phylosophy and only adds new questions instead of answering to yours.
Dec 30 2014
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Wednesday, 31 December 2014 at 00:51:24 UTC, ketmar via 
Digitalmars-d wrote:
 it's not about time, it's about motivation. the real thing is 
 that i
 have almost no motivation to make D better for others, and D is
 already good enough for me.
Yeah, that's kinda where I am too. I have time constraints as well (perhaps to get tighter soon as I'm in the process of maybe taking a second job), but can find some to do things from time to time... but then I prefer to spend it something that directly benefits me somehow, and docs just don't. I think the irony of the "people do what they need" is that the people knowledgeable enough to improve the docs are the very same who don't need the docs anymore....
Dec 30 2014
prev sibling next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31 December 2014 at 09:39, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 My question is how we can break this pattern? What steps can the D
 leadership take to convince folks like you to actually add, even with the
 simplest things?
I'll answer this, I suspect I'm one of the people you're talking about. Past what I already do, which I don't think is insignificant; I have hosted lectures to my local community, extensively promoted and advocated in my community and industry, report lots of bugs, and try and maintain a relevant voice for my industry in discussions - which is very time consuming these days! ... But I obviously don't commit code. There are practical reasons for this: - I have very little free time. - I don't want to be a contributor, I have so much other work that I want to get done, and I don't want to put that aside. Despite that, I have made attempts at contributing code on multiple occasions. They have gone like this: - Clone repo, doesn't build in Visual Studio... do something else instead. - Work on new phobos module, blocked by some other thing, can't continue... (std.simd is blocked by __forceinline) - Unit tests are really hard to write. (std.simd is hard to unittest, more time consuming than writing the module itself) - Documentation is hard to write. (std.simd has so many functions, it's a daunting task!) So I made a solid effort to contribute code, but those were the frictions that prevented me from getting it over the line (one remains a blocker). And further from that, and somewhat more fundamentally, when it comes to the sort of contribution that I'd *really* actually want to make, I'm convinced that my changes would never be pulled. My vision for the language is almost perpetually at odds with yours. Unless I can win an argument with you (even once!), then nothing could be more demotivating to me than realising that no matter what I do, my work would be rejected on principle. You devastated the substantial amount of motivation I had the day that you had a spaz about final-by-default, and insisted that the code be reverted (after was debated for months, unanimously agreed, approved, written, LGTM, and merged). I am still trying to recover from that, but that really killed it for me. That was a very hard fought battle, I won over everyone except Dejan (who was indifferent), and you. You casually played your veto, and devastated my enthusiasm. I feel eternally frustrated and somewhat passive-aggressive since that incident, and I know that's not doing me any favours. But it solidified my suspicion that I have nothing to add on that front. I tried to contribute to VisualD at some times, but that's kinda hard. I mean absolutely no disrespect to Rainer, who I think is one of the most important guys around here, but he wrote it in D (which I can understand - eating your own dogfood and all), and visual studio project's code. He's obviously struggled through the complicated integration (massive binding effort!), and he's comfortable with it now. I certainly wouldn't want to spawn a competing effort. And aside from that, I've said on countless occasions that I think the biggest blocker to really quality IDE integration at this point, is that there's still no libdmd. There are multiple duplicate projects attempting to parse D code for IDE integration, but I find it hard to imagine they'll ever really nail the job perfectly. The DMD front-end is the best piece of code for understanding D that there is, we need it's parser available to tooling. It's also a bit sad that some contributors are spending heaps of time on that effort, which really just seems like a distraction from what they actually set out to do, which was produce quality IDE integration. Considering the documentation problem, I feel like I can get amongst that, but I also feel the same as others have expressed when I go to make a move on it; that ddoc comment blocks are something of an unreadable wall of text. It just 'feels hard', and nobody loves documenting. It might be okay for those already invested, but to newbies, it's appears somewhat repelling. If it were my show, I would never have accepted a pull where a single function or symbol wasn't comprehensively documented by the author. I've experienced the documentation deficit commercially for decades; the only good solution is to enforce that the author documents their code to standards at the time of writing, otherwise it will never happen. Is that standard detailed anywhere? I feel a bit stuck recently, I am sufficiently married to D now, I use it for everything. When I started I was optimistic that the problems I had would be resolved in good time, but most of the big (controversial) issues I had since day one haven't even budged in the last 5-6 years. There is activity on the GC/ nogc front, which is excellent. RC, scope, and ref are remaining, fixing virtual was denied, and that's my entire list! I started full-time C/C++ work again recently, and it's torture! I'm having real trouble enjoying my work when I am eternally frustrated by language bullshit, but at the same time, I've it is evident that D's tooling is not sufficient for use professionally in my industry yet. So, sadly, my motivation is at an all time low. I am watching these current debates on issues that I've had _very_ significant investment in for years now, and I fear they're going to go in a direction that I can't get behind. I can't imagine what half a decade of wasted energy is going to feel like, so contrary to your request from the other thread (to be more restrained on debate), I'm finding myself somewhat more forceful on these topics... what else can I do? Sit back and watch it drift away? So I guess, in summary, I feel that nothing I can do will particularly influence direction. How can I be a contributor in any useful way past what I already do... which I do still feel is genuinely significant, despite being somewhat auxiliary. </walloftext>
Dec 30 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
Remember that UDAs and even Win64 are supported because of your influence. 
That's actually a pretty nice track record! You've also contributed about 6
pull 
requests, 5 of which have been merged.

I made a forceinline proposal at your request, but it sank under the weight of 
controversy over how to do it.
Dec 30 2014
next sibling parent "Daniel Murphy" <yebbliesnospam gmail.com> writes:
"Walter Bright"  wrote in message news:m8052b$2a84$1 digitalmars.com...

 I made a forceinline proposal at your request, but it sank under the 
 weight of controversy over how to do it.
It sank because it wasn't a forceinline proposal, it was a suggestinline proposal.
Dec 30 2014
prev sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31 December 2014 at 16:28, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 Remember that UDAs and even Win64 are supported because of your influence.
 That's actually a pretty nice track record! You've also contributed about 6
 pull requests, 5 of which have been merged.

 I made a forceinline proposal at your request, but it sank under the weight
 of controversy over how to do it.
I don't think I was trying to dismiss those things. They were 3-4 years ago and relatively uncontroversial, and already more or less intended or discussed in the past, I managed to give them a priority nudge. I hope they were all useful things; I know the win64 stuff in particular has made D available to a lot of my friends and colleagues to try out at least, and obviously, we were able to use it at Remedy on the back of those features. UDAs comes up as useful tools all over the place. There seems to be nothing left from me that's uncontroversial. Are you saying that if I worked on the stuff that I believe in, it would have a greater chance of being accepted, despite being outright opposed in conversation? We're talking about stimulating contribution, and I have no idea what I could contribute that would be accepted. And also detailing areas of friction I experience (or perceive) when getting involved in the past. The only thing that comes to mind is debugger related stuff, but I know absolutely nothing about it and it seems like a very large time investment to get up to speed on that stuff such that I could make any useful fixes. Both you and Rainer are more-or-less experts on CV8/PDB already. I would certainly like to resurrect forceinline discussion, but I feel like it's of lower priority than other topics that are receiving attention at the moment, so it's probably better not to distract attention from them for the time being. I wasn't excited about the pragma approach myself, I can't see any advantages... but I also wasn't particularly emotional about it, I'll take what I can get on that front. It just seems like that approach would lead to inconvenience, and possibly more edges to me. How can you do anything generic or meta with a pragma? Yay for text mixins! ;) There were others that felt more strongly about that one than me.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
What you can contribute that would be very valuable is what we've discussed 
before - your simd expertise. Your influence is what has shaped the current
simd 
support. I don't know anyone who knows even half of what you do about simd.
What 
you know could make D really fly with vector math.

You and I both know that auto vectorization, the approach used by everyone
else, 
is not the key to high performance simd. We have an opportunity here.
Dec 31 2014
next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31 December 2014 at 21:25, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 What you can contribute that would be very valuable is what we've discussed
 before - your simd expertise. Your influence is what has shaped the current
 simd support. I don't know anyone who knows even half of what you do about
 simd. What you know could make D really fly with vector math.

 You and I both know that auto vectorization, the approach used by everyone
 else, is not the key to high performance simd. We have an opportunity here.
Okay, well it's not really useful without a forceinline attribute. std.simd functions need to be pseudo-intrinsics, ie, the cost of a function call will definitely negate the work they perform. Yes, they will (probably) be inlined in release, but debug performance is also important, and I can't have maths code that runs much slower in debug builds because it makes a function call passing structs by value for every single maths opcode in the hottest loops. There were also troubles with GDC; I haven't been able to make it emit the opcode that I want. It reinterprets to emit something else depending on the SSE level argument passed to the compiler. There are attributes to set the 'target' per-function, but that didn't work for some reason, so I need to work out if that can be resolved, otherwise my whole approach (goal of being able to generate multiple SIMD version code paths for runtime selection) won't work (in GCC)... We need to get a quality low-level API out there, that is portable, and fills gaps in the various architectures, then we can focus on high-level wrappers and niceties. I really want to see your half-float module merged. Where did that go? I recall some people were saying it should be conflated with the custom-float stuff, so half-float was just a specialisation of custom float... I'm not so sure about that... but maybe? I have been needing a 3.7 (10bit) float too, maybe that fits in there? That stuff all needs forceinline too to be particularly useful.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 8:46 PM, Manu via Digitalmars-d wrote:
 Okay, well it's not really useful without a forceinline attribute.
 std.simd functions need to be pseudo-intrinsics, ie, the cost of a
 function call will definitely negate the work they perform.
 Yes, they will (probably) be inlined in release, but debug performance
 is also important, and I can't have maths code that runs much slower
 in debug builds because it makes a function call passing structs by
 value for every single maths opcode in the hottest loops.

 There were also troubles with GDC; I haven't been able to make it emit
 the opcode that I want. It reinterprets to emit something else
 depending on the SSE level argument passed to the compiler. There are
 attributes to set the 'target' per-function, but that didn't work for
 some reason, so I need to work out if that can be resolved, otherwise
 my whole approach (goal of being able to generate multiple SIMD
 version code paths for runtime selection) won't work (in GCC)...

 We need to get a quality low-level API out there, that is portable,
 and fills gaps in the various architectures, then we can focus on
 high-level wrappers and niceties.
Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along.
 I really want to see your half-float module merged. Where did that go?
 I recall some people were saying it should be conflated with the
 custom-float stuff, so half-float was just a specialisation of custom
 float...
Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-)
 I'm not so sure about that... but maybe? I have been needing a 3.7
 (10bit) float too, maybe that fits in there?
It would be trivial to use halffloat as a model for building other custom floating point types.
 That stuff all needs forceinline too to be particularly useful.
I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish. It also may be worthwhile to look through std.algorithm and see what can be specialized to use simd, such as string searching.
Jan 01 2015
next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 19:47, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 12/31/2014 8:46 PM, Manu via Digitalmars-d wrote:
 Okay, well it's not really useful without a forceinline attribute.
 std.simd functions need to be pseudo-intrinsics, ie, the cost of a
 function call will definitely negate the work they perform.
 Yes, they will (probably) be inlined in release, but debug performance
 is also important, and I can't have maths code that runs much slower
 in debug builds because it makes a function call passing structs by
 value for every single maths opcode in the hottest loops.

 There were also troubles with GDC; I haven't been able to make it emit
 the opcode that I want. It reinterprets to emit something else
 depending on the SSE level argument passed to the compiler. There are
 attributes to set the 'target' per-function, but that didn't work for
 some reason, so I need to work out if that can be resolved, otherwise
 my whole approach (goal of being able to generate multiple SIMD
 version code paths for runtime selection) won't work (in GCC)...

 We need to get a quality low-level API out there, that is portable,
 and fills gaps in the various architectures, then we can focus on
 high-level wrappers and niceties.
Make it work in dmd (with my help, of course) and prove the design. Then GDC will come along.
I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board.
 I really want to see your half-float module merged. Where did that go?
 I recall some people were saying it should be conflated with the
 custom-float stuff, so half-float was just a specialisation of custom
 float...
Half-float is here: http://digitalmars.com/sargon/halffloat.html in the Sargon component library :-)
That's probably not the best place for it ;) What was the controversy blocking it? I don't remember.
 I'm not so sure about that... but maybe? I have been needing a 3.7
 (10bit) float too, maybe that fits in there?
It would be trivial to use halffloat as a model for building other custom floating point types.
Isn't there a competing custom float implementation though? Should they be unified?
 That stuff all needs forceinline too to be particularly useful.
I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish.
I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation >_<
 It also may be worthwhile to look through std.algorithm and see what can be
 specialized to use simd, such as string searching.
SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD. So, where it sits is: DMD needs a commandline arg to request an SSE target level and made available to the code, I need to work out what to do about GDC, and I need to write the unittest's and docs... which is probably the biggest block tbh ;) Otherwise, it still rests in my fork where I left it. Some people have used it. When it's done I'll extend it to support matrices, and perhaps some higher-level linear algebra stuff. Oh yeah, and a massive one that I've discussed with Ethan and I think he's discussed with you; DMD likes to use the x87 in win64 builds... that's really no good. We can't be swapping between x87 and xmm regs. float/double args are passed in xmm according to the ABI, and then everywhere a float operation is performed, a swap from xmm -> x87 is emitted, and then back again. It's madness. You're gonna have to let the x87 go on x64 ;)
Jan 01 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 6:43 AM, Manu via Digitalmars-d wrote:
 Make it work in dmd (with my help, of course) and prove the design. Then GDC
 will come along.
I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board.
Have to start somewhere.
 Half-float is here:

 http://digitalmars.com/sargon/halffloat.html

 in the Sargon component library :-)
That's probably not the best place for it ;) What was the controversy blocking it? I don't remember.
I think the root issue was nobody thought it was useful other than you and I. There is a reasonable issue about "should this really be in the Standard Library, or an add-on?" I created Sargon as a place to put things I think would be generally useful, but have been unable to convince others of.
 It would be trivial to use halffloat as a model for building other custom
 floating point types.
Isn't there a competing custom float implementation though? Should they be unified?
I don't believe in the utility of a customizable float implementation. There is one, but it is pretty much useless. For example, halffloat cannot be implemented using it.
 That stuff all needs forceinline too to be particularly useful.
I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish.
I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation >_<
The last 10% of the work is always 90% of the work. Get it done!
 It also may be worthwhile to look through std.algorithm and see what can be
 specialized to use simd, such as string searching.
SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD.
std.algorithm is portable for the user. It is very accommodating for specializations, so most definitely it can be specialized for x86 with SIMD. Some platforms, such as OSX, have a reliable minimum standard. This is why we, for example, have abandoned 32 bit OSX. For others, a runtime switch based on CPUID is fine.
 So, where it sits is: DMD needs a commandline arg to request an SSE
 target level and made available to the code, I need to work out what
 to do about GDC, and I need to write the unittest's and docs... which
 is probably the biggest block tbh ;)
 Otherwise, it still rests in my fork where I left it. Some people have
 used it. When it's done I'll extend it to support matrices, and
 perhaps some higher-level linear algebra stuff.
The thing is, if you don't do the unittests and docs, you will be throwing away all the other work you've done. If you do them, there will be a large incentive to get forceinline working.
 Oh yeah, and a massive one that I've discussed with Ethan and I think
 he's discussed with you; DMD likes to use the x87 in win64 builds...
 that's really no good. We can't be swapping between x87 and xmm regs.
 float/double args are passed in xmm according to the ABI, and then
 everywhere a float operation is performed, a swap from xmm -> x87 is
 emitted, and then back again. It's madness. You're gonna have to let
 the x87 go on x64 ;)
That shouldn't affect vector code.
Jan 01 2015
parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 2 January 2015 at 08:26, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 1/1/2015 6:43 AM, Manu via Digitalmars-d wrote:
 Make it work in dmd (with my help, of course) and prove the design. Then
 GDC
 will come along.
I can't do anything that isn't supported by the GCC backend; that's the platform for almost all the cross-compilers, which I really care about. I also have a suspicion that anybody who uses SIMD seriously will probably be building with LDC or GCC because of improved codegen across the board.
Have to start somewhere.
Or, it might rather just be best to drop such ambitious goals for the API from the first revision :/
 Half-float is here:

 http://digitalmars.com/sargon/halffloat.html

 in the Sargon component library :-)
That's probably not the best place for it ;) What was the controversy blocking it? I don't remember.
I think the root issue was nobody thought it was useful other than you and I. There is a reasonable issue about "should this really be in the Standard Library, or an add-on?" I created Sargon as a place to put things I think would be generally useful, but have been unable to convince others of.
std.simd would ideally depend on it. half8 is a very useful SIMD primitive. It might be tricky to define a half8 type in std.simd alongside float4, short8, etc, that feels sufficiently related to the others and emits hardware opcodes.
 It would be trivial to use halffloat as a model for building other custom
 floating point types.
Isn't there a competing custom float implementation though? Should they be unified?
I don't believe in the utility of a customizable float implementation. There is one, but it is pretty much useless. For example, halffloat cannot be implemented using it.
Why? Well could custom float alternatively be implemented by generalising halffloat? But I agree that it's basically useless. Half float on the other hand is a standard type that appears in geometry and image data all the time these days.
 That stuff all needs forceinline too to be particularly useful.
I agree, but that does NOT block you from designing and writing the code. It only blocks the final polish.
I wrote the code years ago. I was at the point of polish where it got stuck on those issues... and unittest's, and documentation >_<
The last 10% of the work is always 90% of the work. Get it done!
 It also may be worthwhile to look through std.algorithm and see what can
 be
 specialized to use simd, such as string searching.
SSE provides some special opcodes for string processing that aren't really portable, so I don't expect those would be expressed in std.simd, but they could be used opportunistically in other places. The main trouble is that they are SSE4.2, which is still sufficiently new that we can't rely on it's presence on end-user machines. How will we tell the compiler it is okay to use those opcodes? GCC/LDC have args to say what SSE level to build for. We need a way to query the requested SSE level in the code, and we also need that concept added to DMD.
std.algorithm is portable for the user. It is very accommodating for specializations, so most definitely it can be specialized for x86 with SIMD. Some platforms, such as OSX, have a reliable minimum standard. This is why we, for example, have abandoned 32 bit OSX. For others, a runtime switch based on CPUID is fine.
I don't think a runtime switch is practical that far down the call-tree. We need to be able to supply a SIMD level to the compiler, and ideally, also change it locally with a pragma or an attribute (GCC and Clang use an attribute). Runtime SIMD branch selection needs to be positioned as high up the stack as possible.
 So, where it sits is: DMD needs a commandline arg to request an SSE
 target level and made available to the code, I need to work out what
 to do about GDC, and I need to write the unittest's and docs... which
 is probably the biggest block tbh ;)
 Otherwise, it still rests in my fork where I left it. Some people have
 used it. When it's done I'll extend it to support matrices, and
 perhaps some higher-level linear algebra stuff.
The thing is, if you don't do the unittests and docs, you will be throwing away all the other work you've done. If you do them, there will be a large incentive to get forceinline working.
I just recalled another problem actually. This: uda(Arg) void function(Arg)() { } I need to be able to supply a template arg to a UDA. The runtime cpuid branching tech depends on it, and thus the whole API design depends on it. So, yeah they're all coming back to me now slowly :) There were a number of things I was blocked on. If I can't prove that my API approach works, then it needs to completely change. These things were blocking me from proving the design actually works. Can this one be addressed?
 Oh yeah, and a massive one that I've discussed with Ethan and I think
 he's discussed with you; DMD likes to use the x87 in win64 builds...
 that's really no good. We can't be swapping between x87 and xmm regs.
 float/double args are passed in xmm according to the ABI, and then
 everywhere a float operation is performed, a swap from xmm -> x87 is
 emitted, and then back again. It's madness. You're gonna have to let
 the x87 go on x64 ;)
That shouldn't affect vector code.
Well, it kinda does. Swapping register types is one of the biggest performance hazards there is. Use of SIMD opcodes will generate use of xmm regs. As much as I preach best practise is to commit 100% to SIMD, people will inevitably find themselves moving float data into SIMD regs. x64 should actually be the most tolerant of that sort of code, because float data *should* already be in xmm regs, but I think in our case we're going to see some pretty ordinary simd benchmarks whenever floats appear. The register swapping will very probably result in code that is slower than just issuing sequential float ops.
Jan 02 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 2:05 AM, Manu via Digitalmars-d wrote:
 I don't believe in the utility of a customizable float implementation. There
 is one, but it is pretty much useless. For example, halffloat cannot be
 implemented using it.
Why?
The same reason I don't see a point to a 17 bit integer type.
 This:
     uda(Arg) void function(Arg)()
    {
    }

 I need to be able to supply a template arg to a UDA. The runtime cpuid
 branching tech depends on it, and thus the whole API design depends on
 it.

 So, yeah they're all coming back to me now slowly :)
 There were a number of things I was blocked on. If I can't prove that
 my API approach works, then it needs to completely change.
 These things were blocking me from proving the design actually works.

 Can this one be addressed?
template function(Arg) { uda(Arg) void function() { ... } }
 Well, it kinda does. Swapping register types is one of the biggest
 performance hazards there is.
 Use of SIMD opcodes will generate use of xmm regs. As much as I preach
 best practise is to commit 100% to SIMD, people will inevitably find
 themselves moving float data into SIMD regs. x64 should actually be
 the most tolerant of that sort of code, because float data *should*
 already be in xmm regs, but I think in our case we're going to see
 some pretty ordinary simd benchmarks whenever floats appear. The
 register swapping will very probably result in code that is slower
 than just issuing sequential float ops.
The best thing to do is make the library work, and then we go about making it faster. The thing is, M: Implement feature X and then I can deliver fantastic library A 2 years later. W: Ok, but I've got to first implement Y because it's blocking delivery of fantastic library B today. M: Implement feature X and then I can deliver fantastic library A tomorrow! W: Ok, it's at the top of the queue!
Jan 03 2015
parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 4 January 2015 at 13:48, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 1/2/2015 2:05 AM, Manu via Digitalmars-d wrote:
 This:
     uda(Arg) void function(Arg)()
    {
    }

 I need to be able to supply a template arg to a UDA. The runtime cpuid
 branching tech depends on it, and thus the whole API design depends on
 it.

 So, yeah they're all coming back to me now slowly :)
 There were a number of things I was blocked on. If I can't prove that
 my API approach works, then it needs to completely change.
 These things were blocking me from proving the design actually works.

 Can this one be addressed?
template function(Arg) { uda(Arg) void function() { ... } }
Ah, interesting. I've never written a template function like that. Hmmm, is that how code is rewritten when compiling? If so, why doesn't it just work already?
 Well, it kinda does. Swapping register types is one of the biggest
 performance hazards there is.
 Use of SIMD opcodes will generate use of xmm regs. As much as I preach
 best practise is to commit 100% to SIMD, people will inevitably find
 themselves moving float data into SIMD regs. x64 should actually be
 the most tolerant of that sort of code, because float data *should*
 already be in xmm regs, but I think in our case we're going to see
 some pretty ordinary simd benchmarks whenever floats appear. The
 register swapping will very probably result in code that is slower
 than just issuing sequential float ops.
The best thing to do is make the library work, and then we go about making it faster. The thing is, M: Implement feature X and then I can deliver fantastic library A 2 years later. W: Ok, but I've got to first implement Y because it's blocking delivery of fantastic library B today. M: Implement feature X and then I can deliver fantastic library A tomorrow! W: Ok, it's at the top of the queue!
Don't get me wrong, I'm not trying to rearrange priorities. The stuff going on at the moment is super important! I'm just saying where I'm at with it. It got stuck on problems I didn't-know-how/couldn't to resolve. I need to know my design is sound (ie, works), otherwise committing to the design is the wrong thing to do.
Jan 03 2015
next sibling parent "Daniel Murphy" <yebbliesnospam gmail.com> writes:
"Manu via Digitalmars-d"  wrote in message 
news:mailman.4110.1420345278.9932.digitalmars-d puremagic.com...

 template function(Arg)
 {
      uda(Arg) void function() { ... }
 }
Ah, interesting. I've never written a template function like that. Hmmm, is that how code is rewritten when compiling? If so, why doesn't it just work already?
I'm pretty sure you were told about this last time you asked about the same thing. Yes, this is how the compiler re-writes function templates internally, but if you have udas: uda(Arg) void function(Arg)() { ... } becomes uda(Arg) template function(Arg) { void function() { ... } } This makes more sense when you remember that uda(Arg) void function(Arg)() { ... } is identical to uda(Arg) { void function(Arg)() { ... } } so it doesn't make a lot of sense to pull the UDA inside the template. One weird thing is that it doesn't work with postfix udas either: void function(Arg)() uda(Arg) { ... } Would that be appropriate for your code if it worked? If so, it might be worth opening an enhancement.
Jan 03 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/3/2015 8:21 PM, Manu via Digitalmars-d wrote:
 template function(Arg)
 {
       uda(Arg) void function() { ... }
 }
Ah, interesting. I've never written a template function like that. Hmmm, is that how code is rewritten when compiling? If so, why doesn't it just work already?
The stuff outside of the function is not in scope with the function, that's why. I'm not sure it should be put in the scope.
 I'm just saying where I'm at with it. It got stuck on problems I
 didn't-know-how/couldn't to resolve.
 I need to know my design is sound (ie, works), otherwise committing to
 the design is the wrong thing to do.
You don't need forceinline to know if your design is sound.
Jan 04 2015
prev sibling next sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 15:43, Manu via Digitalmars-d wrote:
 Oh yeah, and a massive one that I've discussed with Ethan and I think
 he's discussed with you; DMD likes to use the x87 in win64 builds...
 that's really no good. We can't be swapping between x87 and xmm regs.
 float/double args are passed in xmm according to the ABI, and then
 everywhere a float operation is performed, a swap from xmm -> x87 is
 emitted, and then back again. It's madness. You're gonna have to let
 the x87 go on x64 ;)
Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work.
Jan 01 2015
prev sibling next sibling parent Iain Buclaw via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 22:40, Joseph Rushton Wakeling via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 01/01/15 15:43, Manu via Digitalmars-d wrote:
 Oh yeah, and a massive one that I've discussed with Ethan and I think
 he's discussed with you; DMD likes to use the x87 in win64 builds...
 that's really no good. We can't be swapping between x87 and xmm regs.
 float/double args are passed in xmm according to the ABI, and then
 everywhere a float operation is performed, a swap from xmm -> x87 is
 emitted, and then back again. It's madness. You're gonna have to let
 the x87 go on x64 ;)
Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work.
I've had the exact same talks as you. I would back any incentive to further push it further (I've only really made tidbit changes).
Jan 01 2015
prev sibling next sibling parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 2 January 2015 at 08:40, Joseph Rushton Wakeling via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 01/01/15 15:43, Manu via Digitalmars-d wrote:
 Oh yeah, and a massive one that I've discussed with Ethan and I think
 he's discussed with you; DMD likes to use the x87 in win64 builds...
 that's really no good. We can't be swapping between x87 and xmm regs.
 float/double args are passed in xmm according to the ABI, and then
 everywhere a float operation is performed, a swap from xmm -> x87 is
 emitted, and then back again. It's madness. You're gonna have to let
 the x87 go on x64 ;)
Don't know if it's entirely the same issue, but Don C. and I have been having occasional (admittedly fairly casual) chats about the need to do something about std.math and its use of real. I don't want to make any strong promises (far too much going on work-wise), but I could well be persuaded to look into that with some seriousness, if it could be helpfully related to std.simd work.
I'm sure it would. What do you mean 'do something about real'? You mean that x87 is deprecated for more than 10 years now, and will probably go away at some point.
Jan 02 2015
prev sibling next sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 10:59, Manu via Digitalmars-d wrote:
 Don't know if it's entirely the same issue, but Don C. and I have been
 having occasional (admittedly fairly casual) chats about the need to do
 something about std.math and its use of real.  I don't want to make any
 strong promises (far too much going on work-wise), but I could well be
 persuaded to look into that with some seriousness, if it could be helpfully
 related to std.simd work.
I'm sure it would. What do you mean 'do something about real'? You mean that x87 is deprecated for more than 10 years now, and will probably go away at some point.
I mean the fact that std.math functions on floating point are hardcoded to use real for their input and return types.
Jan 02 2015
prev sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 23:48, Iain Buclaw via Digitalmars-d wrote:
 I've had the exact same talks as you.  I would back any incentive to
 further push it further (I've only really made tidbit changes).
Sounds good, maybe the three of us can follow up on this together some time in the not-too-distant future.
Jan 02 2015
prev sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31/12/14 12:25, Walter Bright via Digitalmars-d wrote:
 What you can contribute that would be very valuable is what we've discussed
 before - your simd expertise. Your influence is what has shaped the current
simd
 support. I don't know anyone who knows even half of what you do about simd.
What
 you know could make D really fly with vector math.

 You and I both know that auto vectorization, the approach used by everyone
else,
 is not the key to high performance simd. We have an opportunity here.
FWIW Manu, I would be really excited to see what you could put together here. :-)
Jan 01 2015
prev sibling parent "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
 My question is how we can break this pattern? What steps can 
 the D leadership take to convince folks like you to actually 
 add, even with the simplest things?
Speaking as someone new who enjoys dmd (a lot) and considers contributing * It is really hard to understand what is going on by reading the forum and watching github. * The friction in the forum is just amazing. Very entertaining, but not leading to motivation or contributions. For me to be able to contribute in any meaningful way, clearer guidelines are needed. Both concerning the communication style in forums as well as technical directions such as what needs to be build and why. I feel the D leadership needs to set priorities and steer the whole effort in a coherent direction. Uli
Dec 31 2014
prev sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 19:47:53 +0000
"Adam D. Ruppe via Digitalmars-d" <digitalmars-d puremagic.com> wrote:

 On Tuesday, 30 December 2014 at 18:44:15 UTC, ketmar via=20
 Digitalmars-d wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for=20
 documentation writer.
=20 Yeah, I see that too; I complain about ddoc as well (though I=20 generally like it, I just wish it encoded the output correctly=20 and had some nicer defaults, but I don't care enough to fight=20 over it) but I don't think it is that big of a block because the=20 hard part is writing the text rather than the formatting.
sure, we need the actual text in the first place. ;-) but making it easier to create and format that text is good too.
Dec 30 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 10:44 AM, ketmar via Digitalmars-d wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for documentation
 writer. sure, markdown will not magically solve other problems, but at
 least it will remove one of the annoyances, which is good in itself.
Come on. An example, for example(!), is just inserting D code between ---, and better examples would be very helpful.
Dec 30 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 12:25:19 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/30/2014 10:44 AM, ketmar via Digitalmars-d wrote:
 but the unnecessary noisy (and badly documented, that's it)
 documentation language surely doesn't add any joy for documentation
 writer. sure, markdown will not magically solve other problems, but at
 least it will remove one of the annoyances, which is good in itself.
=20 Come on. An example, for example(!), is just inserting D code between ---=
, and=20
 better examples would be very helpful.
ah. it's incredibly hard to make a good example. yet i hope to gather some examples soon, as it is possible that i will train some mates in D. i will consider to look what parts of documentation are hard for 'em and what examples i will devise to explain the things, and then i will try to submit some ERs.
Dec 30 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 1:55 PM, ketmar via Digitalmars-d wrote:
 then i will try to submit some ERs.
Looking forward to it. PRs would be even better!
Dec 30 2014
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 7:20 AM, Adam D. Ruppe wrote:
 std.algorithm could mention the concept of laziness, show examples of the
opaque
 functions, have examples of the common (like seriously one of the most
 frequently asked questions I've seen) "how do I turn it into an array?", or
 show/explain how and why to avoid that.
Yes, better examples of solving real world issues would be better, and is exactly why I did these two documentation examples: https://github.com/D-Programming-Language/phobos/pull/2805 https://github.com/D-Programming-Language/phobos/pull/2806 If you've got ideas for better examples for other functions, please, don't hold back!
Dec 30 2014
prev sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Monday, 29 December 2014 at 19:47:50 UTC, Walter Bright wrote:
 On 12/29/2014 3:19 AM, Jacob Carlborg wrote:
 On 2014-12-29 06:39, Walter Bright wrote:

 Having used both Ddoc and Markdown, I seriously disagree with
 this. Take
 a look at the markdown source for DIP69. It's horrific.
Do you mean on the wiki? The wiki doesn't use Markdown. At least not anyone I've seen.
It uses something pretty similar. They all kinda mush together in my mind :-(
It's NOT SIMILAR at all. It's a completely different language. Also as mentioned above, DDoc macros are extremely ugly and hard to read (and to make sense of, with their lisp-ness). Not to mention, *almost everyone* coding today knows Markdown and can immediately begin contributing to the docs, without looking up DDoc documentation or a *freaking macro file in one of D's repositories*. Only a subset of D devs know DDoc macros, and a very small minority of those know DDoc macros used by Phobos. This is ugly, it is the *very definition* of ugly. (how the heck am I even supposed to read that?): DDoc: $(OL $(LI If $(D line) has type $(D string), $(D wstring), or $(D dstring), a new string of the respective type is allocated every read.) $(LI If $(D line) has type $(D char[]), $(D wchar[]), $(D dchar[]), the line's content will be reused (overwritten) across reads.) $(LI If $(D line) has type $(D immutable(ubyte)[]), the behavior is similar to case (1), except that no UTF checking is attempted upon input.) $(LI If $(D line) has type $(D ubyte[]), the behavior is similar to case (2), except that no UTF checking is attempted upon input.)) This is *much less ugly*: Markdown: 1. If `line` has type `string`, `wstring`, or `dstring`, a new string of the respective type is allocated every read. 2. If `line` has type `char[]`, `wchar[]`, `dchar[]`, the line's content will be reused (overwritten) across reads. 3. If `line` has type `immutable(ubyte)[]`, the behavior is similar to case (1), except that no UTF checking is attempted upon input. 4. If `line` has type `ubyte[]`, the behavior is similar to case (2), except that no UTF checking is attempted upon input. And my favorite, tables in DDoc. First 3 lines for brevity: DDoc: $(BOOKTABLE Cheat Sheet, $(TR $(TH Function Name) $(TH Description) ) $(LEADINGROW Searching ) $(TR $(TDNW $(LREF all)) $(TD $(D all!"a > 0"([1, 2, 3, 4])) returns $(D true) because all elements are positive) ) $(TR $(TDNW $(LREF any)) $(TD $(D any!"a > 0"([1, 2, -3, -4])) returns $(D true) because at least one element is positive) ) ... Markdown (assuming some kind of automatic crossreferencing, which *needs* to be in any decent documentation generator, and DDox, which renders your "preview new" documentation, already does it) | Function Name | Description | | ------------- |------------------------------------------------- | | #all | `all!"a > 0"([1, 2, 3, 4])` returns `true` ... | | #any | `any!"a > 0"([1, 2, -3, -4])` returns `true` ... | (shortened to fit mail, but you should be able to get the point) If you don't want so many pipes / aligning work, this works too: Function Name | Description - | - #all | `all!"a > 0"([1, 2, 3, 4])` returns `true` ... #any | `any!"a > 0"([1, 2, -3, -4])` returns `true` ... And yes, the above is limited, it can't do everything DDoc can do. Macros are useful when you need something way out of the ordinary. But using them for things like tables or lists or 5 different macros for links because you don't think cross-referencing is important is insane. I'd be happy if I could use *something that's not DDoc macros* 99% of the time. But if I want my docs to be anything better than bare text with Params:, Returns: and Examples:, I have to write that kind of gibberish (actually, not anymore, as I said I'm working on DDoc + markdown).
Dec 29 2014
next sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
Great, width limit messed up the (first version of) the table.


| Function Name | Description                                  |
| ------------- |--------------------------------------------- |
| #all          | `all!"a > 0"([1, 2, 3, 4])` returns `true`   |
| #any          | `any!"a > 0"([1, 2, -3, -4])` returns `true` |
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 1:50 PM, Kiith-Sa wrote:
 Great, width limit messed up the (first version of) the table.


 | Function Name | Description                                  |
 | ------------- |--------------------------------------------- |
 | #all          | `all!"a > 0"([1, 2, 3, 4])` returns `true`   |
 | #any          | `any!"a > 0"([1, 2, -3, -4])` returns `true` |
Yeah, now have a large table and have one line that's longer. BTW, you can line table entries up in Ddoc, too: $(TABLE $(THDR Function Name, Description ) $(TROW all , `all!"a > 0"([1, 2, 3, 4])` returns `true` ) $(TROW any , `any!"a > 0"([1, 2, -3, -4])` returns `true`) )
Dec 29 2014
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
 $(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns 
 `true`  )
Would that still work if the first column was something like (0,0) - including a comma? I've advocated nicer macros before, ddoc's recursive expansion makes for a lot of nice options, but the comma being a separator kinda worries me.
Dec 29 2014
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Mon, Dec 29, 2014 at 11:12:54PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
$(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns `true`  )
Would that still work if the first column was something like (0,0) - including a comma? I've advocated nicer macros before, ddoc's recursive expansion makes for a lot of nice options, but the comma being a separator kinda worries me.
We've already had to resort to $(COMMA) hacks to work around comma issues in Phobos docs. :-( Not to mention that as it stands, ddoc is only really convenient for HTML output; while it's certainly *possible* to target it for non-HTML output, it's a pain. Take LaTeX, for example. You have things like "Mr.\ So-and-so" (i.e., backslash followed by a single space) for inserting space of the appropriate width after a period (.) that doesn't end a sentence, where a normal "." would introduce end-of-sentence spacing. The only way to fully support this in ddoc is to use $(DOT) or some such hack instead of writing a literal ".". Or take the various dashes: "--" for ndash, "---" for mdash in LaTeX, but "&ndash;" or "&mdash;" for HTML, respectively. Again, the only way to correctly support this in ddoc is to define $(MDASH) and $(NDASH) macros. So instead of writing dashes in your ddocs, you now have to write the much more verbose and far uglier $(MDASH) and $(NDASH). But it gets worse. Certain character sequences in LaTeX need to be escaped; for example "$" needs to be written as "\$", whereas it can appear literally in HTML. Again, the only solution is $(DOLLAR). Ditto for opening/closing quotation marks, which are `` and '' in LaTeX, and &ldquo; and &rdquo; in HTML. And non-breaking space, which is ~ in LaTeX, and &nbsp; in HTML. So now, what was originally an easily-readable documentation comment: Returns: A range of dollar amounts -- if the input is $100 or more, as stated in Dr. Watson's "A One" specs; otherwise an empty range. becomes this monstrosity: Returns: A range of dollar amounts$(MDASH)if the input is $(DOLLAR)100 or more$(COMMA) as stated in Dr$(DOTSPACE)Watson's $(RDQUO)A$(NBSP)One$(LDQUO) specs; otherwise an empty range. Or, for that matter, the fact that LaTeX is sensitive to spaces in certain contexts, so Walter's formatting trick for Ddoc tables will fall flat on its face by introducing extraneous space where there shouldn't be spaces in the output. Or math symbols, which in LaTeX can be placed in-line by delimiting with $...$ pairs, with no HTML equivalent. Meaning that you'd need a $(MATH...) macro with every literal inside encoded as a separate macro, because LaTeX math mode interprets characters differently and a different set of escape characters are necessary, but since ddoc doesn't have contextual escaping of characters, the only way to do this properly is to write things like: Returns: $(MATH $(SQRT $(LPAREN)$(POW $(LIT_x), $(LIT_2))$(PLUS)$(LIT_1)$(RPAREN))). instead of: Returns: $\sqrt{(x^2 + 1)}$. In my own code, I avoid the macro capabilities of ddoc like the plague, and stick to just plain text. The only macro usage is for stylesheet configuration (i.e., setting up HTML containers with the right styles for the text). It's really hard to read code comments otherwise; the macro syntax *is* ugly (even if it's better than other markup languages). Where horizontal formatting is needed, I just use code blocks (that at least get fixed-width formatting so it's easy to manage without degrading into macro/tag soup). Macros are useful for overall styling and placement of elements on the page, but they are tedious and ugly for text-level elements, and underpowered. T -- For every argument for something, there is always an equal and opposite argument against it. Debates don't give answers, only wounded or inflated egos.
Dec 29 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
 We've already had to resort to $(COMMA) hacks to work around comma
 issues in Phobos docs. :-(
It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup.
 Not to mention that as it stands, ddoc is only really convenient for
 HTML output; while it's certainly *possible* to target it for non-HTML
 output, it's a pain.
More correctly, Ddoc works well for any markup that has a fundamentally nested structure. LaTeX does not. But at least you can make it work with LaTeX. Whatcha gonna do with Markdown? Ddoc has worked extremely well for being adaptible for different HTML output - like the online docs have undergone numerous facelifts while requiring zero changes to the Ddoc source code. It also has been able to generate ebooks from the documentation, again with zero source code changes, just a new set of macro definitions. CandyDoc has been done with it, also with zero source changes.
Dec 29 2014
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Mon, Dec 29, 2014 at 04:10:35PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
We've already had to resort to $(COMMA) hacks to work around comma
issues in Phobos docs. :-(
It's not a hack. The macro system is designed to work that way. All markup systems require some sort of escape mechanism. Including Markup.
I wasn't defending Markdown, btw. As you pointed out elsewhere, it does have its own set of limitations... but OTOH, it was never *designed* to be all-encompassing. It was just an attempt to reduce the tedium of HTML tag soup by using shorter, more visually-appealing syntax to represent some of the most common constructs. I'm not a big fan of Markdown, though. It's better than raw HTML, but only just so.
Not to mention that as it stands, ddoc is only really convenient for
HTML output; while it's certainly *possible* to target it for
non-HTML output, it's a pain.
More correctly, Ddoc works well for any markup that has a fundamentally nested structure. LaTeX does not.
That's not true; LaTeX supports nested structures quite well.
 But at least you can make it work with LaTeX. Whatcha gonna do with
 Markdown?
Again, I wasn't defending Markdown.
 Ddoc has worked extremely well for being adaptible for different HTML
 output
Yes, it works well with HTML, but not so well for other output formats.
 - like the online docs have undergone numerous facelifts while
 requiring zero changes to the Ddoc source code. It also has been able
 to generate ebooks from the documentation, again with zero source code
 changes, just a new set of macro definitions.
 
 CandyDoc has been done with it, also with zero source changes.
This is not really accurate... if all you care for is plain text copy-n-pasted from source code comments, with a smattering of tags added on top to eliminate the most egregious eyesores, then sure, you can just write straight text in the ddoc comments and it will Just Work(tm). But as soon as you try to do anything more with it -- output correctly-formed XHTML, for example, ddoc doesn't work. Try making it output paragraphs correctly encapsulated in <p>...</p> blocks sometime. It doesn't work, because ddoc doesn't understand what paragraphs are, it only knows what blank lines are, but blank lines are not a reliable indicator of paragraph breaks (e.g., what about the break between a section heading and a paragraph? Or between a quoted code block and a paragraph before/after the code?). The only way to get it right is to turn your ddoc comments into tag soup. Are you seriously suggesting that we have to write ddoc tag soup while coding? Or that we first write in plain text then go back afterwards and wrap every paragraph in $(P ...) macros? The only reason zero source code changes were required, was because the ddoc comments were already written with the requisite tag soup to begin with. Which is OK, if that's the "correct" way to use ddoc... but in that case, the page on dlang.org that describes ddoc should be revised to not give the false impression that you can just write documentation comments in plain text format and expect to get nice output from it. T -- Живёшь только однажды.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 4:45 PM, H. S. Teoh via Digitalmars-d wrote:
 Not to mention that as it stands, ddoc is only really convenient for
 HTML output; while it's certainly *possible* to target it for
 non-HTML output, it's a pain.
More correctly, Ddoc works well for any markup that has a fundamentally nested structure. LaTeX does not.
That's not true; LaTeX supports nested structures quite well.
'Supports' is not the same thing as 'is' a nested structure.
 But at least you can make it work with LaTeX. Whatcha gonna do with
 Markdown?
Again, I wasn't defending Markdown.
Then I'm a bit lost on what the point of complaining about Ddoc is. Are you arguing that Ddoc should implement LaTeX?
 The only way to get it right is to turn your ddoc comments into tag
 soup. Are you seriously suggesting that we have to write ddoc tag soup
 while coding? Or that we first write in plain text then go back
 afterwards and wrap every paragraph in $(P ...) macros? The only reason
 zero source code changes were required, was because the ddoc comments
 were already written with the requisite tag soup to begin with. Which is
 OK, if that's the "correct" way to use ddoc... but in that case, the
 page on dlang.org that describes ddoc should be revised to not give the
 false impression that you can just write documentation comments in plain
 text format and expect to get nice output from it.
I think this is an unfair critique. The blank lines separating paragraphs work fine. Ddoc is not intended to be LaTeX. That it can't do everything a professional typesetting language can is not remarkable, no other markup language can, either.
Dec 29 2014
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
So what's nice about ddoc is it understands the language. I think 
it should know scoping too.

Let's forget about the syntax for a moment and think of a feature 
I'd really like: automatic linkability to mentioned symbols.


module ddoc_test;
import module_with_baz;

void bar() {}

/// See also: $(DSYMBOL bar), $(DSYMBOL baz)
void foo() {}


I think it'd be great if it could recognize bar in there as a 
symbol and actually look it up in the current scope. Then you can 
define a macro to link it.

So it would translate it to $(DSYMBOL ddoc_test.bar bar) and 
$(DSYMBOL module_with_baz.baz baz) and the rest of the code is 
responsible for figuring out how to actually link to it.

The first argument it translates is the fully-qualified name 
determined by scope lookup rules. The second argument is what the 
user actually typed in there.


This would use the fact that ddoc is in the compiler to provide 
something compelling that is hard to do in an external program. 
Changing syntax is easy - dmd -D -X makes the json file which you 
can parse and make your own doc displayer. Getting scope names is 
hard though.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 5:33 PM, Adam D. Ruppe wrote:
 So what's nice about ddoc is it understands the language. I think it should
know
 scoping too.

 Let's forget about the syntax for a moment and think of a feature I'd really
 like: automatic linkability to mentioned symbols.


 module ddoc_test;
 import module_with_baz;

 void bar() {}

 /// See also: $(DSYMBOL bar), $(DSYMBOL baz)
 void foo() {}


 I think it'd be great if it could recognize bar in there as a symbol and
 actually look it up in the current scope. Then you can define a macro to link
it.

 So it would translate it to $(DSYMBOL ddoc_test.bar bar) and $(DSYMBOL
 module_with_baz.baz baz) and the rest of the code is responsible for figuring
 out how to actually link to it.

 The first argument it translates is the fully-qualified name determined by
scope
 lookup rules. The second argument is what the user actually typed in there.


 This would use the fact that ddoc is in the compiler to provide something
 compelling that is hard to do in an external program. Changing syntax is easy -
 dmd -D -X makes the json file which you can parse and make your own doc
 displayer. Getting scope names is hard though.
That's a good idea. How about turning this into an enhancement request in bugzilla?
Dec 29 2014
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 01:43:39 UTC, Walter Bright wrote:
 That's a good idea. How about turning this into an enhancement 
 request in bugzilla?
https://issues.dlang.org/show_bug.cgi?id=13914
Dec 29 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 6:13 PM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 01:43:39 UTC, Walter Bright wrote:
 That's a good idea. How about turning this into an enhancement request in
 bugzilla?
https://issues.dlang.org/show_bug.cgi?id=13914
Thanks!
Dec 29 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Mon, Dec 29, 2014 at 05:19:27PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/29/2014 4:45 PM, H. S. Teoh via Digitalmars-d wrote:
[...]
But at least you can make it work with LaTeX. Whatcha gonna do with
Markdown?
Again, I wasn't defending Markdown.
Then I'm a bit lost on what the point of complaining about Ddoc is. Are you arguing that Ddoc should implement LaTeX?
No, I'm saying that ddoc fails to be either (1) a human-readable source that can also be converted into a nicer format like HTML or LaTeX, or (2) a powerful-enough markup language that encompasses all necessary functionality that HTML/LaTeX/etc. encompass. Apparently point (2) fails by design, since you & Andrei repeatedly claim that ddoc should not be "too powerful". Point (1) fails because no matter what you do, you still have to insert markup *somewhere*. IOW, it's neither nice enough to be human-readable, nor powerful enough to justify the reduction in readability.
The only way to get it right is to turn your ddoc comments into tag
soup. Are you seriously suggesting that we have to write ddoc tag
soup while coding? Or that we first write in plain text then go back
afterwards and wrap every paragraph in $(P ...) macros? The only
reason zero source code changes were required, was because the ddoc
comments were already written with the requisite tag soup to begin
with. Which is OK, if that's the "correct" way to use ddoc... but in
that case, the page on dlang.org that describes ddoc should be
revised to not give the false impression that you can just write
documentation comments in plain text format and expect to get nice
output from it.
I think this is an unfair critique. The blank lines separating paragraphs work fine.
They certainly do not. Consider this: First section heading: Passing in a forward range that doesn't have .length may trigger some unexpected side effects. Some other description goes here. Second section heading: More descriptions follow here. The correct XHTML markup would be something like this: <h2>First section heading:</h2> <p>Passing in a forward range that doesn't have .length may trigger some unexpected side effects.</p> <p>Some other description goes here.</p> <h2>Second section heading</h2> <p>More descriptions follow here.</p> Now consider the structure of the input, as understood by ddoc: $(HEADING First section heading:) Passing in a forward range ... side effects. $(BLANKLINE) Some other description goes here. $(HEADING Second section heading:) More descriptions follow here. How do you get from this structure, to the structure of the XHTML markup above? You can't. You *can* hack it so that <p> is inserted by $(HEADING), and $(BLANKLINE) prepends </p>, and $(BLANKLINE) expands to </p><p>, but this will fail at the transition to the second heading: the second paragraph won't be closed. Unless you also prepend </p> in $(HEADING), but then the first heading will acquire an extraneous </p>, which breaks the markup. Things get worse if you now try to insert code blocks between paragraphs, or paragraphs within quoted blocks. Basically, the structure of $(BLANKLINE) does not perfectly align with tag boundaries, therefore no hack will cover all possible cases. The XHTML output will be malformed. Basically, $(BLANKLINE) only works if you use <br/> for paragraph breaks, but that screws up CSS styling when you actually want semantically-tagged paragraphs. Using blank lines to separate paragraphs would be fine, *if* ddoc processes them internally and wraps paragraphs in $(P...) automatically instead of inserting $(BLANKLINE). However, currently it doesn't. And I am loathe to change this because the PR will inevitably get rejected, since it will break every ddoc macro set that relies on $(BLANKLINE).
 Ddoc is not intended to be LaTeX. That it can't do everything a
 professional typesetting language can is not remarkable, no other
 markup language can, either.
The problem with this, is that ddoc is imposed upon all D users. It tries to be readable, but fails to be beyond the most trivial of cases. Things like embedded code blocks and section headings have special meaning, and have a nice human-readable input syntax, but other common constructs such as lists and tables require ugly macro syntax. I'd rather that macro syntax is either used *everywhere* (make it a full-fledged markup language) or nowhere (make it a fully human-readable language), but what we have now is a halfway job. And then, having included macros, which are deemed necessary, it doesn't go far enough either -- certain things (like autoindexing symbols in a module for making a table of contents, for example) aren't possible without lots of manual work and duplication. There are no capabilities for working with the text itself -- like capitalization so that you can use macros for extracting and placing text snippets in different places, inserting escape sequences for sensitive characters in the target format, extracting symbols to make a table of contents, etc.. This is apparently a deliberate design choice, which makes it feel like we're dangling the enticing capability to be a powerful documentation system, yet we withhold actual text-processing capabilities so that you either have to live with inferior output, or implement custom post-processing tools. Again, it feels like another halfway job, it's neither here nor there. I'm not saying that the macro system sucks -- it's actually quite elegantly designed as far as macro languages go -- but the problem is that the ddoc system as a whole shies away from what it is. It pretends to be human-readable when it is not, and on the other hand it tries to be a powerful text macro system yet shies away from actual text-processing capabilities. I wish we would stop trying to be all things to everyone, and settle one way or the other. Either we cater to the human-readable-input crowd and make it fully human readable with markdown-like syntax (or whatever other syntax you care to design), or we go all-out with the macro system and endow it with the full text-processing capabilities that it currently lacks. Right now we're stuck in between, and do neither very well. T -- MAS = Mana Ada Sistem?
Dec 30 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 10:10 AM, H. S. Teoh via Digitalmars-d wrote:
 Using blank lines to separate paragraphs would be fine,*if*  ddoc
 processes them internally and wraps paragraphs in $(P...) automatically
 instead of inserting $(BLANKLINE). However, currently it doesn't. And I
 am loathe to change this because the PR will inevitably get rejected,
 since it will break every ddoc macro set that relies on $(BLANKLINE).
I'd pull it, and I think it can work alongside BLANKLINE. -- Andrei
Dec 30 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Tue, Dec 30, 2014 at 11:36:16AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/30/14 10:10 AM, H. S. Teoh via Digitalmars-d wrote:
Using blank lines to separate paragraphs would be fine,*if*  ddoc
processes them internally and wraps paragraphs in $(P...)
automatically instead of inserting $(BLANKLINE). However, currently
it doesn't. And I am loathe to change this because the PR will
inevitably get rejected, since it will break every ddoc macro set
that relies on $(BLANKLINE).
I'd pull it, and I think it can work alongside BLANKLINE. -- Andrei
How would we make it work alongside BLANKLINE? Define $(P ...) as $(BLANKLINE)$0 ? I'm not sure it will actually be equivalent, though, and might cause some problems with existing ddoc macro sets. Or are you saying emit *both* BLANKLINE and P, and the user simply sets one of them to be a no-op? T -- Beware of bugs in the above code; I have only proved it correct, not tried it. -- Donald Knuth
Dec 30 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 12:31 PM, H. S. Teoh via Digitalmars-d wrote:
 On Tue, Dec 30, 2014 at 11:36:16AM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 On 12/30/14 10:10 AM, H. S. Teoh via Digitalmars-d wrote:
 Using blank lines to separate paragraphs would be fine,*if*  ddoc
 processes them internally and wraps paragraphs in $(P...)
 automatically instead of inserting $(BLANKLINE). However, currently
 it doesn't. And I am loathe to change this because the PR will
 inevitably get rejected, since it will break every ddoc macro set
 that relies on $(BLANKLINE).
I'd pull it, and I think it can work alongside BLANKLINE. -- Andrei
How would we make it work alongside BLANKLINE? Define $(P ...) as $(BLANKLINE)$0 ? I'm not sure it will actually be equivalent, though, and might cause some problems with existing ddoc macro sets. Or are you saying emit *both* BLANKLINE and P, and the user simply sets one of them to be a no-op?
The latter. Continue emitting BLANKLINE but set it to nothing. -- Andrei
Dec 30 2014
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Tue, Dec 30, 2014 at 12:42:11PM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/30/14 12:31 PM, H. S. Teoh via Digitalmars-d wrote:
On Tue, Dec 30, 2014 at 11:36:16AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
On 12/30/14 10:10 AM, H. S. Teoh via Digitalmars-d wrote:
Using blank lines to separate paragraphs would be fine,*if*  ddoc
processes them internally and wraps paragraphs in $(P...)
automatically instead of inserting $(BLANKLINE). However, currently
it doesn't. And I am loathe to change this because the PR will
inevitably get rejected, since it will break every ddoc macro set
that relies on $(BLANKLINE).
I'd pull it, and I think it can work alongside BLANKLINE. -- Andrei
How would we make it work alongside BLANKLINE? Define $(P ...) as $(BLANKLINE)$0 ? I'm not sure it will actually be equivalent, though, and might cause some problems with existing ddoc macro sets. Or are you saying emit *both* BLANKLINE and P, and the user simply sets one of them to be a no-op?
The latter. Continue emitting BLANKLINE but set it to nothing. -- Andrei
OK, I'll see if I can whip up a PR for this sometime this week or next week. In the meantime, for reference, here's the ER for this issue: https://issues.dlang.org/show_bug.cgi?id=9731 T -- Without outlines, life would be pointless.
Dec 30 2014
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 10:10 AM, H. S. Teoh via Digitalmars-d wrote:
 Using blank lines to separate paragraphs would be fine, *if* ddoc
 processes them internally and wraps paragraphs in $(P...) automatically
 instead of inserting $(BLANKLINE). However, currently it doesn't. And I
 am loathe to change this because the PR will inevitably get rejected,
 since it will break every ddoc macro set that relies on $(BLANKLINE).
Ddoc should do the $(P ) thing instead of $(BLANKLINE). The latter is a mistake on my part, as when I originally build Ddoc I had a lesser understanding of what the right output should be. It's a correctable mistake, and (as Andrei suggests) can coexist with BLANKLINE.
 The problem with this, is that ddoc is imposed upon all D users.  It
 tries to be readable, but fails to be beyond the most trivial of cases.
 Things like embedded code blocks and section headings have special
 meaning, and have a nice human-readable input syntax, but other common
 constructs such as lists and tables require ugly macro syntax. I'd
 rather that macro syntax is either used *everywhere* (make it a
 full-fledged markup language) or nowhere (make it a fully human-readable
 language), but what we have now is a halfway job.
Lists and tables are rarely used, and I don't find them unreadable.
 And then, having included macros, which are deemed necessary, it doesn't
 go far enough either -- certain things (like autoindexing symbols in a
 module for making a table of contents, for example) aren't possible
 without lots of manual work and duplication. There are no capabilities
 for working with the text itself -- like capitalization so that you can
 use macros for extracting and placing text snippets in different places,
 inserting escape sequences for sensitive characters in the target
 format, extracting symbols to make a table of contents, etc.. This is
 apparently a deliberate design choice, which makes it feel like we're
 dangling the enticing capability to be a powerful documentation system,
 yet we withhold actual text-processing capabilities so that you either
 have to live with inferior output, or implement custom post-processing
 tools. Again, it feels like another halfway job, it's neither here nor
 there.
Propose solutions. Your one about $(P ) is a good one.
Dec 30 2014
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-30 01:10, Walter Bright wrote:

 It's not a hack. The macro system is designed to work that way. All
 markup systems require some sort of escape mechanism. Including Markup.
You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected. Try for yourself in this online Markdown editor with live preview: http://dillinger.io/ -- /Jacob Carlborg
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 6:29 AM, Jacob Carlborg wrote:
 On 2014-12-30 01:10, Walter Bright wrote:

 It's not a hack. The macro system is designed to work that way. All
 markup systems require some sort of escape mechanism. Including Markup.
You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected.
I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things?
Dec 31 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 11:14:50 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 6:29 AM, Jacob Carlborg wrote:
 On 2014-12-30 01:10, Walter Bright wrote:

 It's not a hack. The macro system is designed to work that way. All
 markup systems require some sort of escape mechanism. Including Markup.
You don't need to escape all the special symbols used in Markdown, only=
in
 certain place. In Markdown, if you start a line with a star, '*', it wi=
ll be
 interpreted as the beginning of an unordered list. But if you write a s=
tar in
 the middle of text it will just output a star, as expected.
=20 I know that Markdown formatting is context sensitive. =20 And what happens if you want to have a * at the beginning of the line of =
output?=20
 And a | in a table entry? And so on for each of the context sensitive thi=
ngs? that still will be MUCH better than Ddoc.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 12:44 PM, ketmar via Digitalmars-d wrote:
 that still will be MUCH better than Ddoc.
After you refused my offer to add in the Ddoc for you, saying you weren't going to write documentation regardless, it's hard to put much weight on your opinion about it.
Dec 31 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 14:10:06 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 12:44 PM, ketmar via Digitalmars-d wrote:
 that still will be MUCH better than Ddoc.
=20 After you refused my offer to add in the Ddoc for you, saying you weren't=
going=20
 to write documentation regardless, it's hard to put much weight on your o=
pinion=20
 about it.
what use for me in such documentation? i can do Ddoc myself, i just can't read the result. what i want is readable documentation in .d files, without any preprocessing. Ddoc can't do that. so i can't see any sense in investing time to write documentation which then will be uglified by Ddoc.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 2:28 PM, ketmar via Digitalmars-d wrote:
 i can do Ddoc myself, i just can't read the result.
/**************************** This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***************************/
Dec 31 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 15:26:04 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 2:28 PM, ketmar via Digitalmars-d wrote:
 i can do Ddoc myself, i just can't read the result.
=20 =20 =20 /**************************** This function does blah, blah, blah. =20 Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. =20 Params: x =3D the awesome input value =20 Returns: insightful description of the return value =20 Example: --- int foo(int x) { ... stunning D code ... } --- ***************************/ =20
Implements the homonym function (also known as $(D accumulate), $(D compress), $(D inject), or $(D foldl)) present in various programming languages of functional flavor. The call $(D reduce!(fun)(seed, range)) first assigns $(D seed) to an internal variable $(D result), also called the accumulator. Then, for each element $(D x) in $(D range), $(D result =3D fun(result, x)) gets evaluated. Finally, $(D result) is returned. The one-argument version $(D reduce!(fun)(range)) works similarly, but it uses the first element of the range as the seed (the range must be non-empty). 'cmon, wtf all that $(XXX) crap is? and with capitals, which distracts from the actual text. ah, the following is even better: $(BOOKTABLE Cheat Sheet, $(TR $(TH Function Name) $(TH Description) ) $(LEADINGROW Searching ) $(TR $(TDNW $(LREF all)) $(TD $(D all!"a > 0"([1, 2, 3, 4])) returns $(D tr= ue) because all elements are positive) ) $(TR $(TDNW $(LREF any)) $(TD $(D any!"a > 0"([1, 2, -3, -4])) returns $(D = true) because at least one element is positive) ) $(TR $(TDNW $(LREF balancedParens)) $(TD $(D balancedParens("((1 + 1) / 2)")) returns $(D true) because the string has balanced parentheses.) ) $(TR $(TDNW $(LREF boyerMooreFinder)) $(TD $(D find("hello world", boyerMooreFinder("or"))) returns $(D "orld") using the $(LUCKY Boyer-Moore _algorithm).) ) $(TR $(TDNW $(LREF canFind)) $(TD $(D canFind("hello world", "or")) returns $(D true).) ) $(TR $(TDNW $(LREF count)) $(TD Counts elements that are equal to a specified value or satisfy a predicate. $(D count([1, 2, 1], 1)) returns $(D 2) and $(D count!"a < 0"([1, -3, 0])) returns $(D 1).) ) $(TR $(TDNW $(LREF countUntil)) $(TD $(D countUntil(a, b)) returns the number of steps taken in $(D a) to reach $(D b); for example, $(D countUntil("hello!", "o")) returns $(D 4).) ) $(TR $(TDNW $(LREF commonPrefix)) $(TD $(D commonPrefix("parakeet", "parachute")) returns $(D "para").) ) this goes on and on and on. this is just a line noise.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote:
 ah, the following is even better:
Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to.
Dec 31 2014
next sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Wednesday, 31 December 2014 at 23:53:48 UTC, Walter Bright 
wrote:
 On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote:
 ah, the following is even better:
Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to.
seriously, which part of: DDoc with Markdown do you fail to understand? This: http://defenestrate.eu/docs/tharsis-core/concepts/process.html is the kind of article I write in my documentation (one of the first few, there will be about 10 more). It's in ReStructuredText, which again, is pretty much a more feature-rich Markdown. I couldn't do that with DDoc without an extremely unreadable source; now, with DDoc+Markdown (https://github.com/kiith-sa/harbored-mod), I can do it with maybe one macro for the admonitions.
Dec 31 2014
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 00:05:10 UTC, Kiith-Sa wrote:
 DDoc with Markdown
This is the biggest deal: what people are talking about is actually not that different from what ddoc already does! If you write: /** Something here. Something else here. */ Ddoc ALREADY converts that into: $(DDOC_SUMMARY Something here.) $(DDOC_DESCRIPTION Something else here.) (Which tbh sometimes bugs me, I don't like how "Given: foo" alwas turns into a DDOC_SECTION) Anyway, the point is that ddoc is ALREADY a variant on the markdown style of languages! Those paragraphs are assumed to have semantic meaning and converted into macros for the output. What people really are proposing is to add a few more macro shorthands. Like `foo` being changed to $(D foo). None of the ddoc flexibility would be lost and you can still define your own macros. The only difference is there'd be a few more conversions done just the way DDOC_SUMMARY is done now.
Dec 31 2014
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 01, 2015 at 12:54:39AM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Thursday, 1 January 2015 at 00:05:10 UTC, Kiith-Sa wrote:
DDoc with Markdown
This is the biggest deal: what people are talking about is actually not that different from what ddoc already does! If you write: /** Something here. Something else here. */ Ddoc ALREADY converts that into: $(DDOC_SUMMARY Something here.) $(DDOC_DESCRIPTION Something else here.) (Which tbh sometimes bugs me, I don't like how "Given: foo" alwas turns into a DDOC_SECTION)
Ddoc has this ugly hack where if you want to suppress certain default behaviours, you stick _ in front of it. For example: _Given: x = ... will output "Given: x = ..." without a section heading, whereas removing the _ will make "Given" a section heading. There's also the (undocumented?) behaviour where multi-word headings are not recognized as such: My heading: blah blah blah does not produce a heading for "My heading". However, if you make it a single word by using _ instead of a space, then it will become a heading: My_heading: blah blah blah the _ gets replaced with a space in the output. Now I wonder what you'd have to do if you wanted a literal _ in the heading... or a word in the text... I'm guessing it's time for $(UNDERSCORE) all over again. T -- Shin: (n.) A device for finding furniture in the dark.
Dec 31 2014
prev sibling next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 15:52:45 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 The point is, you do not have to use the macros if Ddoc if you don't want=
to. the point is that i can't have documentation that both readable without preprocessing and generates good standalone files. i have to choose one of that. ah, and then i'll stick to my own documenting rules, 'cause i will not use Ddoc to generate anything anyway. it's not that hard to extend human-readable markup language to allow some D-specific features. i already wrote that this can be any language, not necessary markdown. like this, for example: =3D|Function Name|Description|=3D |`boyerMooreFinder` | `find("hello world", boyerMooreFinder("or"))` returns `"orld"` using the (Byer-Moore algorithm)[1]. |`count` | Counts elements that are equal to a specified value or satisfy a predicate. `count([1, 2, 1], 1))` returns `2` and `count!"a < 0"([1, -3, 0])` returns `1`. [1] https://some-long-link-with-alot-of-args now compare with this: $(TR $(TH Function Name) $(TH Description) ) $(TR $(TDNW $(LREF boyerMooreFinder)) $(TD $(D find("hello world", boyerMooreFinder("or"))) returns $(D "orld") using the $(LUCKY Boyer-Moore _algorithm).) ) $(TR $(TDNW $(LREF count)) $(TD Counts elements that are equal to a specified value or satisfy a predicate. $(D count([1, 2, 1], 1)) returns $(D 2) and $(D count!"a < 0"([1, -3, 0])) returns $(D 1).) ) it doesn't matter how much efforts you will put into latest, it will look like linenoise anyway. yes, documentation processor should be able to see that `boyerMooreFinder` and `count` are declared in the respective module and turn that to internal links. i can't see why i should do the work that computer can do for me. i devised this sample without deep design, of course, yet it's already human-readable and can be used to generate any kind of table.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 4:16 PM, ketmar via Digitalmars-d wrote:
 i devised this sample without deep design, of course, yet it's already
 human-readable and can be used to generate any kind of table.
You took care to carefully format your version and made no effort with the Ddoc version.
Dec 31 2014
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 16:39:10 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 4:16 PM, ketmar via Digitalmars-d wrote:
 i devised this sample without deep design, of course, yet it's already
 human-readable and can be used to generate any kind of table.
=20 You took care to carefully format your version and made no effort with th=
e Ddoc=20
 version.
didn't you read my post in a whole? maybe that wall of Ddoc text forces you to drop reading? i wrote that "it doesn't matter how much efforts you will put into latest, it will look like linenoise anyway." there are more macroformatting, and all that macros are still YELLING at me. it doesn't matter how good i'll format Ddoc version, it will not magically becomes human-readable due to all that macro crap.
Dec 31 2014
prev sibling next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Wednesday, 31 December 2014 at 23:53:48 UTC, Walter Bright 
wrote:
 Have fun with LUCKY in markdown.
LUCKY sucks anyway, it would be better to provide a regular link to something directly useful, even Wikipedia (which is usually the one I go straight to, and if I want more, I'll Bing it myself, thank you very much). Here's a counterpoint: make a Ddoc macro that links to the documentation of a given symbol. $(DOC std.array.array) It needs to somehow get here: The existing solution in Phobos' macros is something like this: $(XREF range,chain) But, how to you convert a name, say in a code example, to that macro without manual intervention? One of the things I like most about ddoc is the code example highlighting. Indeed, I decided to use it last night to start writing the draft of my DConf 2015 proposal: http://arsdnet.net/dcode/talk-2015.dd http://arsdnet.net/dcode/talk-2015.html Not bad, got some easy syntax highlighting and it wasn't painful to write at all. ...but when documenting code, it is nice to be able to click on names and see more information. To compile the ddoc, all imports need to resolve. Why not go ahead and make "import std.variant;" available for linking somehow? We could make it call a macro like $(XREF std.variant) .... but how do we get that to the link, phobos/std_variant.html? We can't do a call to replace(".", "_"). Well, I do have a solution for this: my dpldocs.info site. http://dpldocs.info/std.variant which for a while redirected to the Phobos site, then I found that useless since dlang.org couldn't link overloads and I just displayed the comment myself... but I think I'll go back to redirecting now that we can link to it. But the point is translating a module name to a Phobos link requires transformation code too complex for a ddoc macro... ironically needing something like LUCKY - an external search engine - to fix...
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 4:39 PM, Adam D. Ruppe wrote:
 But the point is translating a module name to a Phobos link requires
 transformation code too complex for a ddoc macro...
In my C++ compiler library documentation, I made a point in the code examples to hyperlink every call to a library function to the documentation for that library function. Yes, it would be nice to make this automatic.
 ironically needing something like LUCKY - an external search engine - to fix...
LUCKY isn't the only macro I use to make horrific url's palatable. I also use them for Amazon links, for example.
Jan 02 2015
parent "Mengu" <mengukagan gmail.com> writes:
On Friday, 2 January 2015 at 23:03:19 UTC, Walter Bright wrote:
 On 12/31/2014 4:39 PM, Adam D. Ruppe wrote:
 But the point is translating a module name to a Phobos link 
 requires
 transformation code too complex for a ddoc macro...
In my C++ compiler library documentation, I made a point in the code examples to hyperlink every call to a library function to the documentation for that library function. Yes, it would be nice to make this automatic.
 ironically needing something like LUCKY - an external search 
 engine - to fix...
LUCKY isn't the only macro I use to make horrific url's palatable. I also use them for Amazon links, for example.
by the way, how about a link in the docs to source for methods, types and everything?
Jan 03 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-01 00:52, Walter Bright wrote:
 On 12/31/2014 3:42 PM, ketmar via Digitalmars-d wrote:
 ah, the following is even better:
Now do it it markdown. Oh wait, markdown doesn't enable specification of different kinds of fonts and formatting. Markedown doesn't have local hyperlinks. Have fun with LUCKY in markdown. Of course, you can skip all that and just have generic tables, and generic formatting and fantastically ugly urls, but you can do that in Ddoc, too, and avoid using any pesky macros like LUCKY. I'll make it easy for you. Just show us $(LUCKY Boyer-Moore _algorithm) in markdown. The point is, you do not have to use the macros if Ddoc if you don't want to.
The point is to have consistent look and feel, not be able to customize every single thing. -- /Jacob Carlborg
Jan 02 2015
prev sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 4:14 PM, Walter Bright wrote:
 On 12/31/2014 6:29 AM, Jacob Carlborg wrote:
 On 2014-12-30 01:10, Walter Bright wrote:

 It's not a hack. The macro system is designed to work that way. All
 markup systems require some sort of escape mechanism. Including Markup.
You don't need to escape all the special symbols used in Markdown, only in certain place. In Markdown, if you start a line with a star, '*', it will be interpreted as the beginning of an unordered list. But if you write a star in the middle of text it will just output a star, as expected.
I know that Markdown formatting is context sensitive. And what happens if you want to have a * at the beginning of the line of output? And a | in a table entry? And so on for each of the context sensitive things?
You use a backslash character, like in almost every programming language, json, etc. http://daringfireball.net/projects/markdown/syntax#backslash Compare \* to $(STAR)
Dec 31 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 12:49 PM, Ary Borenszweig wrote:
 Compare \* to $(STAR)
I found two instances of $(COMMA) across the Phobos sources, and neither were necessary.
Dec 31 2014
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
 On Mon, Dec 29, 2014 at 11:12:54PM +0000, Adam D. Ruppe via Digitalmars-d
wrote:
 On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
 $(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns `true`  )
Would that still work if the first column was something like (0,0) - including a comma? I've advocated nicer macros before, ddoc's recursive expansion makes for a lot of nice options, but the comma being a separator kinda worries me.
We've already had to resort to $(COMMA) hacks to work around comma issues in Phobos docs. :-(
That's to be expected from any macro system.
 Not to mention that as it stands, ddoc is only really convenient for
 HTML output; while it's certainly *possible* to target it for non-HTML
 output, it's a pain. Take LaTeX, for example.
I have successfully generated LaTeX from dlang.org and phobos.
 You have things like
 "Mr.\ So-and-so" (i.e., backslash followed by a single space) for
 inserting space of the appropriate width after a period (.) that doesn't
 end a sentence, where a normal "." would introduce end-of-sentence
 spacing. The only way to fully support this in ddoc is to use $(DOT) or
 some such hack instead of writing a literal ".". Or take the various
 dashes: "--" for ndash, "---" for mdash in LaTeX, but "&ndash;" or
 "&mdash;" for HTML, respectively. Again, the only way to correctly
 support this in ddoc is to define $(MDASH) and $(NDASH) macros.
And what's the problem? This is exactly right, and fine. A macro system supports any formatter, present or future. One that's based on tricks needs to add a new trick for each formatter idiosyncrasy.
 So
 instead of writing dashes in your ddocs, you now have to write the much
 more verbose and far uglier $(MDASH) and $(NDASH). But it gets worse.
No it does not get worse. That's pretty much it.
 Certain character sequences in LaTeX need to be escaped; for example "$"
 needs to be written as "\$", whereas it can appear literally in HTML.
 Again, the only solution is $(DOLLAR).
Yah, as I said that's pretty much it. You need to encapsulate special stuff in macros, which is all uniform and simple.
 Ditto for opening/closing
 quotation marks, which are `` and '' in LaTeX, and &ldquo; and &rdquo;
 in HTML. And non-breaking space, which is ~ in LaTeX, and &nbsp; in
 HTML. So now, what was originally an easily-readable documentation
 comment:

 	Returns: A range of dollar amounts -- if the input is $100 or
 	more, as stated in Dr. Watson's "A One" specs; otherwise an
 	empty range.

 becomes this monstrosity:

 	Returns: A range of dollar amounts$(MDASH)if the input is
 	$(DOLLAR)100 or more$(COMMA) as stated in Dr$(DOTSPACE)Watson's
 	$(RDQUO)A$(NBSP)One$(LDQUO) specs; otherwise an empty range.
That's an extreme example. BTW it doesn't look much worse than TDPL's source. Andrei
Dec 29 2014
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 01:45:09 UTC, Andrei Alexandrescu 
wrote:
 Certain character sequences in LaTeX need to be escaped; for 
 example "$"
 needs to be written as "\$", whereas it can appear literally 
 in HTML.
 Again, the only solution is $(DOLLAR).
Yah, as I said that's pretty much it. You need to encapsulate special stuff in macros, which is all uniform and simple.
You know what drives me nuts about this? Ddoc's design has an elegant solution: https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L230 The ESCAPES thing. It is right there... been there for years... but not actually used. And now I think we're stuck with this nonsense since there's real world code that uses the html passthrough "feature".
Dec 29 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 5:49 PM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 01:45:09 UTC, Andrei Alexandrescu wrote:
 Certain character sequences in LaTeX need to be escaped; for example "$"
 needs to be written as "\$", whereas it can appear literally in HTML.
 Again, the only solution is $(DOLLAR).
Yah, as I said that's pretty much it. You need to encapsulate special stuff in macros, which is all uniform and simple.
You know what drives me nuts about this? Ddoc's design has an elegant solution: https://github.com/D-Programming-Language/dmd/blob/master/src/doc.c#L230 The ESCAPES thing. It is right there... been there for years... but not actually used. And now I think we're stuck with this nonsense since there's real world code that uses the html passthrough "feature".
Oh yah! https://github.com/D-Programming-Language/dlang.org/pull/271 (which I'm breaking into bite-sized pieces) uses it! -- Andrei
Dec 29 2014
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 02:00:57 UTC, Andrei Alexandrescu 
wrote:
 Oh yah! 
 https://github.com/D-Programming-Language/dlang.org/pull/271 
 (which I'm breaking into bite-sized pieces) uses it! -- Andrei
Yeah, I think it works for code embedded in the ---\ncode\n--- areas, but not the rest of it. If it worked on all text the user typed, there'd be no more need for nonsense like $(GT). (You might still need LPAREN, RPAREN, COMMA, and DOLLAR, since they are special to ddoc itself, but there'd be no more need for the nonsense of escaping every random character the target format might need.)
Dec 29 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 6:11 PM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 02:00:57 UTC, Andrei Alexandrescu wrote:
 Oh yah! https://github.com/D-Programming-Language/dlang.org/pull/271
 (which I'm breaking into bite-sized pieces) uses it! -- Andrei
Yeah, I think it works for code embedded in the ---\ncode\n--- areas, but not the rest of it. If it worked on all text the user typed, there'd be no more need for nonsense like $(GT). (You might still need LPAREN, RPAREN, COMMA, and DOLLAR, since they are special to ddoc itself, but there'd be no more need for the nonsense of escaping every random character the target format might need.)
That's not good either because then it works too much. -- Andrei
Dec 29 2014
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 30 December 2014 at 02:13:40 UTC, Andrei Alexandrescu 
wrote:
 That's not good either because then it works too much. -- Andrei
I'd make an exception for macro definitions themselves, which gives you a chance to put syntax for the target language, but ALL user text outside a macro definition should be encoded. That'd give consistently correct results and anything short of it is problematic - in web dev, failing to encode virtually anything is a likely cause of a cross-site scripting vulnerability and tends to make invalid output code. This is well enough known in the web development community that it is rare to find anything that doesn't auto-escape text anymore. Here's an example which has trouble right now: /// given "<b>bold text</b>", returns "bold text" string innerText(); In ddoc today, we wouldn't see the code it is given. You'd see bold text because the string isn't encoded properly for HTML output. If the escapes were run on the input, it would be quickly transformed and show the right thing. Now, suppose you actually *want* it to output the literal tag in HTML. Easy: /** Macros: B=<b>$0</b> */ /// given <b>$(B bold text)</b>, returns "bold text" That looks like what is seen by the end user - no mess of $(LT)b$(GT), nor any $(XML b) stuff making it harder to see what it is meant to be, and gives the flexibility to customize output code. The correct code from that in HTML would be: &lt;b&gt;<b>bold text</b>&lt;/b&gt; The correct code for that in RTF is <b>{\b bold text}</b> You can generate RTF from the source by just changing: Macros: B={\b $0} ESCAPES= (rtf does have a couple escapes, I think {} and \ need to be done there, but I'm pretty sure <>&" do not.) And changing nothing else.
Dec 29 2014
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 6:30 PM, Adam D. Ruppe wrote:
 On Tuesday, 30 December 2014 at 02:13:40 UTC, Andrei Alexandrescu wrote:
 That's not good either because then it works too much. -- Andrei
I'd make an exception for macro definitions themselves, which gives you a chance to put syntax for the target language, but ALL user text outside a macro definition should be encoded. That'd give consistently correct results
No. In LaTeX for example things need to be escaped differently (or not at all) depending on context. -- Andrei
Dec 29 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Mon, Dec 29, 2014 at 05:45:08PM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/29/14 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
On Mon, Dec 29, 2014 at 11:12:54PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
$(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns `true`  )
Would that still work if the first column was something like (0,0) - including a comma? I've advocated nicer macros before, ddoc's recursive expansion makes for a lot of nice options, but the comma being a separator kinda worries me.
We've already had to resort to $(COMMA) hacks to work around comma issues in Phobos docs. :-(
That's to be expected from any macro system.
Not to mention that as it stands, ddoc is only really convenient for
HTML output; while it's certainly *possible* to target it for non-HTML
output, it's a pain. Take LaTeX, for example.
I have successfully generated LaTeX from dlang.org and phobos.
Of what quality? Have you actually looked at the LaTeX output to see if it's actually correct? I doubt it's actually 100% correct. LaTeX is quite sensitive in some places to extra spaces, or special ways of writing certain text elements. If these details are not taken care of, sure it will still produce output, but there will be little niggling problems sprinkled throughout -- lines that don't line up properly, words that aren't spaced properly, etc..
You have things like "Mr.\ So-and-so" (i.e., backslash followed by a
single space) for inserting space of the appropriate width after a
period (.) that doesn't end a sentence, where a normal "." would
introduce end-of-sentence spacing. The only way to fully support this
in ddoc is to use $(DOT) or some such hack instead of writing a
literal ".". Or take the various dashes: "--" for ndash, "---" for
mdash in LaTeX, but "&ndash;" or "&mdash;" for HTML, respectively.
Again, the only way to correctly support this in ddoc is to define
$(MDASH) and $(NDASH) macros.
And what's the problem? This is exactly right, and fine. A macro system supports any formatter, present or future. One that's based on tricks needs to add a new trick for each formatter idiosyncrasy.
So we should stop the false advertisement that ddoc input is supposed to be "human readable", because it is not.
So instead of writing dashes in your ddocs, you now have to write the
much more verbose and far uglier $(MDASH) and $(NDASH). But it gets
worse.
No it does not get worse. That's pretty much it.
Certain character sequences in LaTeX need to be escaped; for example
"$" needs to be written as "\$", whereas it can appear literally in
HTML.  Again, the only solution is $(DOLLAR).
Yah, as I said that's pretty much it. You need to encapsulate special stuff in macros, which is all uniform and simple.
Yes, and the system degrades into something no better than writing raw HTML or LaTeX, when every other element in your text is "special stuff". Do you seriously believe that the ". " in "Mr. So-and-So" is "special stuff"? And what if another formatter requires special markup for "-" because it has special meaning? So now, a simple string like: Mr. So-and-So must be written as: Mr$(DOTSPACE)So$(HYPHEN)and$(HYPHEN)So Which is OK if that's the way things are intended to work, but we should seriously stop selling ddoc as "human readable" because at this point, it most certainly is not.
Ditto for opening/closing quotation marks, which are `` and '' in
LaTeX, and &ldquo; and &rdquo; in HTML. And non-breaking space, which
is ~ in LaTeX, and &nbsp; in HTML. So now, what was originally an
easily-readable documentation comment:

	Returns: A range of dollar amounts -- if the input is $100 or
	more, as stated in Dr. Watson's "A One" specs; otherwise an
	empty range.

becomes this monstrosity:

	Returns: A range of dollar amounts$(MDASH)if the input is
	$(DOLLAR)100 or more$(COMMA) as stated in Dr$(DOTSPACE)Watson's
	$(RDQUO)A$(NBSP)One$(LDQUO) specs; otherwise an empty range.
That's an extreme example. BTW it doesn't look much worse than TDPL's source.
[...] Yes, and therefore we should stop selling ddoc as a human-readable input format, since the above example is anything but. T -- Caffeine underflow. Brain dumped.
Dec 30 2014
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/30/14 10:19 AM, H. S. Teoh via Digitalmars-d wrote:
 On Mon, Dec 29, 2014 at 05:45:08PM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 On 12/29/14 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
 On Mon, Dec 29, 2014 at 11:12:54PM +0000, Adam D. Ruppe via Digitalmars-d
wrote:
 On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
 $(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns `true`  )
Would that still work if the first column was something like (0,0) - including a comma? I've advocated nicer macros before, ddoc's recursive expansion makes for a lot of nice options, but the comma being a separator kinda worries me.
We've already had to resort to $(COMMA) hacks to work around comma issues in Phobos docs. :-(
That's to be expected from any macro system.
 Not to mention that as it stands, ddoc is only really convenient for
 HTML output; while it's certainly *possible* to target it for non-HTML
 output, it's a pain. Take LaTeX, for example.
I have successfully generated LaTeX from dlang.org and phobos.
Of what quality?
Excellent.
 Have you actually looked at the LaTeX output to see if
 it's actually correct?
Of course.
 I doubt it's actually 100% correct.
It is. https://github.com/D-Programming-Language/dlang.org/pull/736. Destroyed? Andrei
Dec 30 2014
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/30/2014 10:19 AM, H. S. Teoh via Digitalmars-d wrote:
 Of what quality? Have you actually looked at the LaTeX output to see if
 it's actually correct? I doubt it's actually 100% correct. LaTeX is
 quite sensitive in some places to extra spaces, or special ways of
 writing certain text elements. If these details are not taken care of,
 sure it will still produce output, but there will be little niggling
 problems sprinkled throughout -- lines that don't line up properly,
 words that aren't spaced properly, etc..
Andrei has been using LaTeX for years, and writes his (successful) books with it. You've got a tough slog convincing him he doesn't know his way around it :-) He tried to teach me LaTeX once, but I was a poor student.
Dec 30 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote:
 	Returns: A range of dollar amounts -- if the input is $100 or
 	more, as stated in Dr. Watson's "A One" specs; otherwise an
 	empty range.

 becomes this monstrosity:

 	Returns: A range of dollar amounts$(MDASH)if the input is
 	$(DOLLAR)100 or more$(COMMA) as stated in Dr$(DOTSPACE)Watson's
 	$(RDQUO)A$(NBSP)One$(LDQUO) specs; otherwise an empty range.
I'd write it as: Returns: A range of dollar amounts $(MDASH) if the input is $(DOLLAR)100 or more, as stated in Dr. Watson's $(Q A One) specs; otherwise an empty range. In fact, you don't even need the $(MDASH) if you're willing to insert the Unicode character directly. Nor do you need the $(Q ) if you're willing to use " ", or the Unicode characters directly. The only markup actually needed is the $(DOLLAR). I have just finished doing the markup, 100% in ddoc, for this 650 page book: http://www.generalatomic.com/Historians/vol1.pdf and made it available here: http://www.amazon.com/exec/obidos/ASIN/B00REVL4BC/classicempire (yes, that's an affiliate link!) Sadly, the ebook format doesn't allow for all the formatting I'd like to have, but the html version is pretty nearly identical to the old book layout. It's full of strange formatting, weird characters, footnotes, superscripts, multiple fonts, tables, 4 languages, etc., and I was able to do it all. Even two different layouts, one for HTML and one for Ebook. I.e. I am a heavy user of Ddoc, and not just for the random Phobos function. (Doing these old books is a bit of a hobby of mine. Next up is my grandfather's book on crystallography.)
Dec 29 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 18:28:09 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 I.e. I am a heavy user of Ddoc, and not just for the random Phobos functi=
on.
=20
 (Doing these old books is a bit of a hobby of mine. Next up is my grandfa=
ther's=20
 book on crystallography.)
it's great that Ddoc is good for making books. but it's not so great that it's bad for documenting source code.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote:
 it's great that Ddoc is good for making books. but it's not so great
 that it's bad for documenting source code.
I also use it for all the documentation on the Digital Mars site, which include a lot of coding examples, the articles I wrote for Dr. Dobb's about code, all the documentation on walterbright.com, etc.
Dec 29 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 18:43:56 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote:
 it's great that Ddoc is good for making books. but it's not so great
 that it's bad for documenting source code.
=20 I also use it for all the documentation on the Digital Mars site, which i=
nclude=20
 a lot of coding examples, the articles I wrote for Dr. Dobb's about code,=
all=20
 the documentation on walterbright.com, etc.
yes, that's exactly why it's not so great for documenting source code. you basically invented your own TeX, which has alot of features to write stand-alone texts, but almost completely unreadable as a source code documentation without preprocessor. Ddoc is just too powerful.
Dec 29 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 6:49 PM, ketmar via Digitalmars-d wrote:
 On Mon, 29 Dec 2014 18:43:56 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote:
 it's great that Ddoc is good for making books. but it's not so great
 that it's bad for documenting source code.
I also use it for all the documentation on the Digital Mars site, which include a lot of coding examples, the articles I wrote for Dr. Dobb's about code, all the documentation on walterbright.com, etc.
yes, that's exactly why it's not so great for documenting source code. you basically invented your own TeX, which has alot of features to write stand-alone texts, but almost completely unreadable as a source code documentation without preprocessor. Ddoc is just too powerful.
I use (La)TeX macros all the time, and although necessary they're beyond awful. DDoc macros are a lot nicer and more consistent by comparison. They are not, however, as powerful. -- Andrei
Dec 29 2014
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 20:30:48 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 On 12/29/14 6:49 PM, ketmar via Digitalmars-d wrote:
 On Mon, 29 Dec 2014 18:43:56 -0800
 Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote:
 it's great that Ddoc is good for making books. but it's not so great
 that it's bad for documenting source code.
I also use it for all the documentation on the Digital Mars site, whic=
h include
 a lot of coding examples, the articles I wrote for Dr. Dobb's about co=
de, all
 the documentation on walterbright.com, etc.
yes, that's exactly why it's not so great for documenting source code. you basically invented your own TeX, which has alot of features to write stand-alone texts, but almost completely unreadable as a source code documentation without preprocessor. Ddoc is just too powerful.
=20 I use (La)TeX macros all the time, and although necessary they're beyond=
=20
 awful. DDoc macros are a lot nicer and more consistent by comparison.=20
 They are not, however, as powerful. -- Andrei
i don't want to say that Ddoc is better or worse than (La)TeX. the problem is that it unreadable due to visual noise. my point is that Ddoc documentation should be easily readable without preprocessing, right in the source code. markdown, textile, restructured... see the pattern? they all easily readable by humans without preprocessing. Ddoc is not. it is painful to read "rich" Ddoc comments AND it is painful to write 'em. that's why Ddoc is "too powerful": it has great macro system which gives Ddoc great power, but for the price. this price is "visual noise". most people don't need DTP package in documentation, they need simple, clean and human-readable syntax for WRITING that documentation in the first place. Ddos is perfectly usable, but it's uncomfortable to write nice documentation with it. Ddoc is for writing *reference* *documentation*, not complete documentation books. and it is simply too powerful for that. having Ddoc is great, but it's oftenly overkill to use it. i believe that Ddoc should be opt-in, and by default D should use one of the human-readable text formatting languages with some D-specific extensions (like easy cross-referencing, for example). most people will be OK with simple language for documenting API and will resort to "real Ddoc" only when they want to write something like wordy and detailed explanation of internal algorithms and such.
Dec 29 2014
prev sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 18:43:56 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 6:37 PM, ketmar via Digitalmars-d wrote:
 it's great that Ddoc is good for making books. but it's not so great
 that it's bad for documenting source code.
=20 I also use it for all the documentation on the Digital Mars site, which i=
nclude=20
 a lot of coding examples, the articles I wrote for Dr. Dobb's about code,=
all=20
 the documentation on walterbright.com, etc.
p.s. but i like "ditto" feature!
Dec 29 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:12 PM, Adam D. Ruppe wrote:
 On Monday, 29 December 2014 at 23:11:09 UTC, Walter Bright wrote:
 $(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns `true`  )
Would that still work if the first column was something like (0,0) - including a comma?
$(ARG 0,0) ARG = $0 (And I should ask, what if you wanted a | in the Markdown?)
 I've advocated nicer macros before, ddoc's recursive expansion makes for a lot
 of nice options, but the comma being a separator kinda worries me.
It's not a problem. And like I said, what about all the separators in Markdown? What are you going you'll never need them when documenting code.
Dec 29 2014
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Monday, 29 December 2014 at 23:53:01 UTC, Walter Bright wrote:
 (And I should ask, what if you wanted a | in the Markdown?)
I have no idea; I don't use it either, I just write plain text nowadays. It is easy to write and plenty legible in source code or extracted formats.
Dec 29 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:59 PM, Adam D. Ruppe wrote:
 On Monday, 29 December 2014 at 23:53:01 UTC, Walter Bright wrote:
 (And I should ask, what if you wanted a | in the Markdown?)
I have no idea; I don't use it either, I just write plain text nowadays. It is easy to write and plenty legible in source code or extracted formats.
And that works, too! What I do is type out a stream of consciousness, and get all the text right. I only add markup as a last pass.
Dec 29 2014
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-30 00:52, Walter Bright wrote:

 (And I should ask, what if you wanted a | in the Markdown?)
Just type a |. You don't need to escape most Markdown symbols in the middle of text.
 And like I said, what about all the separators in Markdown? What are you

 It's not like you'll never need them when documenting code.
Most of the time it's not a problem, see above. The only symbols that can cause a problem will most likely be used inside a code block anyway, where they are not interpreted as Markdown. -- /Jacob Carlborg
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 7:03 AM, Jacob Carlborg wrote:
 On 2014-12-30 00:52, Walter Bright wrote:

 (And I should ask, what if you wanted a | in the Markdown?)
Just type a |. You don't need to escape most Markdown symbols in the middle of text.
And when you want a | in a table entry?
 Most of the time it's not a problem, see above.
And when it is, how do you escape them?
Dec 31 2014
parent Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 4:09 PM, Walter Bright wrote:
 On 12/31/2014 7:03 AM, Jacob Carlborg wrote:
 On 2014-12-30 00:52, Walter Bright wrote:

 (And I should ask, what if you wanted a | in the Markdown?)
Just type a |. You don't need to escape most Markdown symbols in the middle of text.
And when you want a | in a table entry?
 Most of the time it's not a problem, see above.
And when it is, how do you escape them?
Backslash character.
Dec 31 2014
prev sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
 Yeah, now have a large table and have one line that's longer.
*Read* my post. The rows don' have to be aligned. And as I mentioned, IF you have a special case, THEN it's time for macros. But it shouln't happen for basic things like bold, code, links, references, 90% of tables or lists. I spend about half of my coding time writing documentation. DDoc is like I'm writing my documentation with LISP, or rather, Scheme. If I wanted to do that I wouldn't mind writing my code in Scheme either.
 BTW, you can line table entries up in Ddoc, too:

 $(TABLE
 $(THDR Function Name, Description
   )
 $(TROW all          , `all!"a > 0"([1, 2, 3, 4])` returns 
 `true`  )
 $(TROW any          , `any!"a > 0"([1, 2, -3, -4])` returns 
 `true`)
 )
No, it has to be at least:
 $(TABLE
 $(THDR Function Name, Description
   )
 $(TROW all          , $(D all!"a > 0"([1, 2, 3, 4])) returns 
 $(D true)  )
 $(TROW any          , $(D any!"a > 0"([1, 2, -3, -4])) returns 
 $(D true))
 )
because I need macros even for something as common as an inline code fragment. Not to mention, if I include the full table lines, not just ~70 chars this newsgroup will take, the difference in readability is much more massive.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 3:31 PM, Kiith-Sa wrote:
 because I need macros even for something as common as an inline code fragment.
Markup, macro, same thing.
 Not to mention, if I include the full table lines, not just ~70 chars this
 newsgroup will take, the difference in readability is much more massive.
Not really, because you can create your own custom macros to shorten things up. I use Ddoc all the time, and I create custom macros ALL THE TIME for semantic shortcuts, prettying things up, saving typing, etc. Any repetitive tasks are candidates for a custom macro. If you're not using custom macros, and you find Ddoc tedious and repetitive, you're using it wrong.
Dec 29 2014
parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Monday, 29 December 2014 at 23:56:47 UTC, Walter Bright wrote:
 On 12/29/2014 3:31 PM, Kiith-Sa wrote:
 because I need macros even for something as common as an 
 inline code fragment.
Markup, macro, same thing.
 Not to mention, if I include the full table lines, not just 
 ~70 chars this
 newsgroup will take, the difference in readability is much 
 more massive.
Not really, because you can create your own custom macros to shorten things up. I use Ddoc all the time, and I create custom macros ALL THE TIME for semantic shortcuts, prettying things up, saving typing, etc. Any repetitive tasks are candidates for a custom macro. If you're not using custom macros, and you find Ddoc tedious and repetitive, you're using it wrong.
I cannot use a custom macro to shorten $(D a == b). A well-written paragraph will have 20 such $(D XXX), $(B XXX), $(I XXX), not to mention $(SOMELINK xxx.com XXX). And there's no way to make lists or tables readable: *unless* their contents is homogenous, at best I will have rows full of $(XXX ). etc. is completely unreadable for anyone but people who have spent at least a year looking at the mess that is Phobos documentation comments. Javadoc is more readable in sources, as is Doxygen. Python's Sphinx is more readable in their sources. [Rust](http://doc.rust-lang.org/rustdoc.html) is using markdown for their documentation and they don't have any issues either. Yes, *you* use DDoc all the time. But *you* are also forcing it on everyone using the language, and on any average programmer who may potentially use D, most of whom don't share your love for macros and MANY of whom know much more common formats like Markdown. Most people don't write their docs in LaTeX either. Besides, no-one is proposing to *remove* the macros, the proposal it to add syntax for basic cases which frankly can *not* be made any less ugly with macros. And yeah, so you will need to escape I'm writing my *thesis* in ReStructuredText, which is basically Markdown on steroids with *way* more special characters than Markdown, and I almost never need to escape anything. Either way, I'm done with this argument, I expect it will take many more pissed-off users for this to change. As for the CSS thing, yes, you need that built in. It doesn't have to be amazing but it *has to be usable*. to be usable, documentation must be as simple to generate as: doxygen Doxyfile That's what a user coming from most different languages expects, if they don't get it, it seems *broken* and is extremely off-putting. When I was starting with D this almost made me give up. Bare HTML files, no cross-referencing, unreadable, no menu. No information on the site on how to get a usable documentation (not sure how it's now, it's been a few years), and coming from Doxygen, writing a bunch of .ddoc files I wasn't even told about wasn't what would come to my mind. The default does not need to look amazing, but there must be something usable to start with, without *any* work other than having documentation comments in your code. Any other common documentation generator will produce something that can at least be browsed.
Dec 29 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 4:37 PM, Kiith-Sa wrote:
 If you're not using custom macros, and you find Ddoc tedious and repetitive,
 you're using it wrong.
I cannot use a custom macro to shorten $(D a == b). A well-written paragraph will have 20 such $(D XXX), $(B XXX), $(I XXX), not to mention $(SOMELINK xxx.com XXX).
As opposed to some other markup language. You're always going to have 20 such markup instances, one way or another.
 And there's no way to make lists or tables readable:
Yes, there is. I just showed you.
 Yes, *you* use DDoc all the time. But *you* are also forcing it on everyone
 using the language, and on any average programmer who may potentially use D,
 most of whom don't share your love for macros and MANY of whom know much more
 common formats like Markdown. Most people don't write their docs in LaTeX
either.
No matter what form Ddoc takes, it will force some method upon users. However, you can use Doxygen on .d sources if you prefer.
 I'm writing my *thesis* in ReStructuredText, which is basically Markdown on
 steroids with *way* more special characters than Markdown, and I almost never
 need to escape anything.
The D language has a use for most every character, so escapes will be needed a lot.
 to be usable, documentation must be as simple to generate as:

    doxygen Doxyfile
dmd -D source.d (And you don't have to go find a doxygen that works on your system, is compatible with D source code, and is installed correctly.) BTW, you can use Doxygen with D if you want to. In fact, some people used Doxygen with D before D had Ddoc. If that actually worked out well, Ddoc would never have been created. But it did not work out well. It was a disaster. Few wanted to be bothered with installing Doxygen, so what happened was little to no documentation got written. The Phobos docs often bore no resemblance whatsoever to what the code did. Ddoc revolutionized all that. It's hard to understate how desirable it is to have it built in to the compiler, meaning everyone has it, and has the correct version of it. The only place anyone has to use Ddoc is in the Phobos documentation. If Doxygen is better, more convenient, etc., why aren't you using it? Ddoc must be doing something right :-)
Dec 29 2014
parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
 As opposed to some other markup language. You're always going 
 to have 20 such markup instances, one way or another.
There's a big difference between the amount of visual noise between different instances. I'm using D for 5 years and when I still find DDoc laced with $(LI $(B bold) $(D code)) hard to read.
 And there's no way to make lists or tables readable:
Yes, there is. I just showed you.
I don't consider that to be readable, especially, as I mentioned, if the items are long lines of non-plain text.
 No matter what form Ddoc takes, it will force some method upon 
 users. However, you can use Doxygen on .d sources if you prefer.
I don't use it because it doesn't *really* understand D. I'm not arguing for Doxygen's syntax / D support or lack thereof. I'm arguing for its user experience.
 The D language has a use for most every character, so escapes 
 will be needed a lot.
D blocks in DDoc are usually in: --- code here --- With a Markdown-like syntax, inline code could be in `inline code here` . I admit you would need to escape the backticks, which are very rare, especially in inline code fragments. I also admit *that* would force you to not reliably use *some* D code fragments *outside* backticks. And I find it unlikely that there are more than 3 fragments in entire Phobos doc this would break.
 to be usable, documentation must be as simple to generate as:

   doxygen Doxyfile
dmd -D source.d
The result takes a shitload of work to make it useful, especially if your project has more than 1 module (and no, passing more files won't help with that). THIS is useful (it's very close to what Doxygen spits out by default): http://irrlicht.sourceforge.net/docu/index.html D claims to have a builtin documentation generator, but you can either spend a week searching for nonexistent documentation about how to make decent documentation *or* you can get a third-party documentation generator, which is the same experience you get with C++ and Doxygen.
 The only place anyone has to use Ddoc is in the Phobos 
 documentation. If Doxygen is better, more convenient, etc., why 
 aren't you using it? Ddoc must be doing something right :-)
I'm modifying a third-party documentation generator to support Markdown and to get decent "Doxygen doxyfile" user experience right now.
Dec 29 2014
parent Jacob Carlborg <doob me.com> writes:
On 2014-12-30 04:13, Kiith-Sa wrote:

 D blocks in DDoc are usually in:

 ---
 code here
 ---

 With a Markdown-like syntax, inline code could  be in `inline code here` .
 I admit you would need to escape the backticks, which are very rare,
 especially in inline code fragments. I also admit *that* would force you
 to not reliably use *some* D code fragments *outside* backticks. And I
 find it unlikely that there are more than 3 fragments in entire Phobos doc
 this would break.
You only need to escape backticks in inline code, not code blocks, i.e. ``` auto a = `foo` ``` The above works perfectly fine. -- /Jacob Carlborg
Dec 31 2014
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 4:37 PM, Kiith-Sa wrote:
 Either way, I'm done with this argument, I expect it will take many more
 pissed-off users for this to change.
I've seen little else than emotion and appeal to such in making your argument. -- Andrei
Dec 29 2014
parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Tuesday, 30 December 2014 at 01:57:20 UTC, Andrei Alexandrescu 
wrote:
 On 12/29/14 4:37 PM, Kiith-Sa wrote:
 Either way, I'm done with this argument, I expect it will take 
 many more
 pissed-off users for this to change.
I've seen little else than emotion and appeal to such in making your argument. -- Andrei
I admit that. DDoc has been making me angry for years. And I do find the lack of readability of DDoc to be so much of an obvious issue, and I do thing it will hurt D (not so much as GC/noGC fanatcs, but it will, especially people who like writing documentation (yeah, such people exist, I'm one of them)). And now I have my monhly 'procastinate by actively posting on a forum' day.
Dec 29 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 7:20 PM, Kiith-Sa wrote:
 On Tuesday, 30 December 2014 at 01:57:20 UTC, Andrei Alexandrescu wrote:
 On 12/29/14 4:37 PM, Kiith-Sa wrote:
 Either way, I'm done with this argument, I expect it will take many more
 pissed-off users for this to change.
I've seen little else than emotion and appeal to such in making your argument. -- Andrei
I admit that. DDoc has been making me angry for years. And I do find the lack of readability of DDoc to be so much of an obvious issue, and I do thing it will hurt D (not so much as GC/noGC fanatcs, but it will, especially people who like writing documentation (yeah, such people exist, I'm one of them)). And now I have my monhly 'procastinate by actively posting on a forum' day.
The one way out is to propose something at least as useful and quite a bit more palatable. -- Andrei
Dec 29 2014
parent "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Tuesday, 30 December 2014 at 04:34:30 UTC, Andrei Alexandrescu 
wrote:
 On 12/29/14 7:20 PM, Kiith-Sa wrote:
 On Tuesday, 30 December 2014 at 01:57:20 UTC, Andrei 
 Alexandrescu wrote:
 On 12/29/14 4:37 PM, Kiith-Sa wrote:
 Either way, I'm done with this argument, I expect it will 
 take many more
 pissed-off users for this to change.
I've seen little else than emotion and appeal to such in making your argument. -- Andrei
I admit that. DDoc has been making me angry for years. And I do find the lack of readability of DDoc to be so much of an obvious issue, and I do thing it will hurt D (not so much as GC/noGC fanatcs, but it will, especially people who like writing documentation (yeah, such people exist, I'm one of them)). And now I have my monhly 'procastinate by actively posting on a forum' day.
The one way out is to propose something at least as useful and quite a bit more palatable. -- Andrei
See previous post. Useful? not 'at least as' in my mind. Palatable? probably, less escaping/special cases.
Dec 29 2014
prev sibling parent "Paolo Invernizzi" <paolo.invernizzi no.address> writes:
On Tuesday, 30 December 2014 at 00:37:26 UTC, Kiith-Sa wrote:
 On Monday, 29 December 2014 at 23:56:47 UTC, Walter Bright

 I'm writing my *thesis* in ReStructuredText, which is basically 
 Markdown on steroids with *way* more special characters than 
 Markdown, and I almost never need to escape anything.
Documentation here in SR Labs is allowed only in ReStructuredText: it's just a pleasure to use it. --- Paolo
Dec 30 2014
prev sibling parent reply "Dicebot" <public dicebot.lv> writes:
DDOC is probably one of D features with pretty idea and hardly 
usable design. I wish we had something like Markdown instead - 
can never remember Phobos macros to use and usually just resort 
to using plain text instead.
Dec 29 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 2:30 PM, Dicebot wrote:
 DDOC is probably one of D features with pretty idea and hardly usable design. I
 wish we had something like Markdown instead - can never remember Phobos macros
 to use and usually just resort to using plain text instead.
Yeah, well, whenever I use Markdown I have to go find the reference document for it, as every damn website uses a different syntax for it: * wiki * reddit * github * hackernews ::barf::
Dec 29 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Mon, 29 Dec 2014 14:38:46 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/29/2014 2:30 PM, Dicebot wrote:
 DDOC is probably one of D features with pretty idea and hardly usable d=
esign. I
 wish we had something like Markdown instead - can never remember Phobos=
macros
 to use and usually just resort to using plain text instead.
=20 Yeah, well, whenever I use Markdown I have to go find the reference docum=
ent for=20
 it, as every damn website uses a different syntax for it:
=20
 * wiki
 * reddit
 * github
 * hackernews
=20
 ::barf::
textile, anyone?
Dec 29 2014
prev sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote:
 * reddit
 * github
These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines.
 * wiki
 * hackernews
Hacker News and both the new D Wiki, and the old, do not use Markdown.
 ::barf::
This, too, is not Markdown.
Dec 31 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 7:20 AM, Vladimir Panteleev wrote:
 On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote:
 * reddit
 * github
These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines.
Yes, the same only different.
 * wiki
 * hackernews
Hacker News and both the new D Wiki, and the old, do not use Markdown.
It's just another variation of it - which is my point.
Dec 31 2014
next sibling parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright 
wrote:
 On 12/31/2014 7:20 AM, Vladimir Panteleev wrote:
 On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright 
 wrote:
 * reddit
 * github
These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines.
Yes, the same only different.
 * wiki
 * hackernews
Hacker News and both the new D Wiki, and the old, do not use Markdown.
It's just another variation of it - which is my point.
It's NOT a different variant. It's a different LANGUAGE. That's like saying D is a variant of Pascal.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 11:45 AM, Kiith-Sa wrote:
 It's NOT a different variant. It's a different LANGUAGE.
 That's like saying D is a variant of Pascal.
It's not illegitimate to consider all { } languages as variants of each other.
Dec 31 2014
next sibling parent "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Wednesday, 31 December 2014 at 20:05:43 UTC, Walter Bright 
wrote:
 On 12/31/2014 11:45 AM, Kiith-Sa wrote:
 It's NOT a different variant. It's a different LANGUAGE.
 That's like saying D is a variant of Pascal.
It's not illegitimate to consider all { } languages as variants of each other.
With that kind of thinking everyone would still be using COBOL and FORTRAN.
Dec 31 2014
prev sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 12:05:30 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 11:45 AM, Kiith-Sa wrote:
 It's NOT a different variant. It's a different LANGUAGE.
 That's like saying D is a variant of Pascal.
=20 It's not illegitimate to consider all { } languages as variants of each o=
ther. then D is doomed to vanish. nobody needs another C++, but with broken syntax and without libraries.
Dec 31 2014
prev sibling parent reply "Anon" <anon nope.avi> writes:
On Wednesday, 31 December 2014 at 19:11:27 UTC, Walter Bright 
wrote:
 On 12/31/2014 7:20 AM, Vladimir Panteleev wrote:
 On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright 
 wrote:
 * reddit
 * github
These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines.
Yes, the same only different.
Just like DDoc macros and Makefile macros. They're the same, but different. Also, the differences between Markdown implementations are trivial, and do not effect the readability of the source, which is the entire point of Markdown - making the "plain-text" readable, rather than polluting it with HTML (or DDoc) tag noise.
 * wiki
 * hackernews
Hacker News and both the new D Wiki, and the old, do not use Markdown.
It's just another variation of it - which is my point.
And your point is completely wrong. DDoc and Makefiles both use $(MACROS), does that mean that DDoc is a variation of Make? Yes, *lots* of things use common elements. Because that makes things more easily understood when *reading*, which is the single most important thing for documentation. The macros are fine for when they are needed, but you shouldn't have to use gotos and jumps when all you want is a gorram foreach loop. Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a list.
 I know that Markdown formatting is context sensitive.
 And what happens if you want to have a * at the beginning of 
 the line of
 output?
 And a | in a table entry? And so on for each of the context 
 sensitive things?
A backslash. Y'know, the unambiguous, familiar-to-all-programmers, really-hard-to-mistype thing that almost everything but HTML and DDoc use for escaping?
Dec 31 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 11:59 AM, Anon wrote:
 A backslash. Y'know, the unambiguous, familiar-to-all-programmers,
 really-hard-to-mistype thing that almost everything but HTML and DDoc use for
 escaping?
Yeah, the reason that people have added WYSIWYG string literals to languages :-)
Dec 31 2014
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 5:33 PM, Walter Bright wrote:
 On 12/31/2014 11:59 AM, Anon wrote:
 A backslash. Y'know, the unambiguous, familiar-to-all-programmers,
 really-hard-to-mistype thing that almost everything but HTML and DDoc
 use for
 escaping?
Yeah, the reason that people have added WYSIWYG string literals to languages :-)
Which still look readable (and the backslash is just one character of noise so it's also not that bad).
Dec 31 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 12:54 PM, Ary Borenszweig wrote:
 Which still look readable (and the backslash is just one character of noise so
 it's also not that bad).
(Then you've never tried to use regex string literals in C code.) C++ would not have added raw string literal syntax if this was not an issue. It was a welcome improvement from anyone I've heard comment on it.
Dec 31 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 11:59 AM, Anon wrote:
 Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C)) to get a
list.
You don't have to. You can write it as: $(LIST A, B, C) or: $(LIST A, B, C ) Yes, there currently isn't a LIST macro by default, but you can write one: LISTX=$(LI $1) $(LISTX $+) LIST=$(UL $(LISTX $1, $+)) I very often write custom macros for a particular job at hand. It's very, very handy. For example, suppose I want to switch between a definition list and a table? I write a higher level macro, then switch its definition. I can use the "X Macro" technique. I can "comment out" a block. I can create "variables". For example, when the D source moved from svn to github, the macro in each source code file that linked to the repository just needed its definition changed. With markdown, I'd have had to have edited every file (what, are there a thousand files?). And so on. http://en.wikipedia.org/wiki/X_Macro
Dec 31 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 12:54:14PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/31/2014 11:59 AM, Anon wrote:
Nor should you have to write (or read!) $(UL $(LI A) $(LI B) $(LI C))
to get a list.
You don't have to. You can write it as: $(LIST A, B, C) or: $(LIST A, B, C )
[...] And what if you need commas in the list items? Oh right, $(COMMA). Very readable. T -- Be in denial for long enough, and one day you'll deny yourself of things you wish you hadn't.
Dec 31 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote:
 And what if you need commas in the list items? Oh right, $(COMMA). Very
 readable.
And Markdown never needs escapes. Right. :-)
Dec 31 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 01:51:25PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote:
And what if you need commas in the list items? Oh right, $(COMMA).
Very readable.
And Markdown never needs escapes. Right. :-)
It needs escapes in far less places than ddoc does. When escapes are inescapable(!), you want the solution with less occurrences, not the solution with more. T -- In theory, software is implemented according to the design that has been carefully worked out beforehand. In practice, design documents are written after the fact to describe the sorry mess that has gone on before.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 2:05 PM, H. S. Teoh via Digitalmars-d wrote:
 On Wed, Dec 31, 2014 at 01:51:25PM -0800, Walter Bright via Digitalmars-d
wrote:
 On 12/31/2014 1:17 PM, H. S. Teoh via Digitalmars-d wrote:
 And what if you need commas in the list items? Oh right, $(COMMA).
 Very readable.
And Markdown never needs escapes. Right. :-)
It needs escapes in far less places than ddoc does. When escapes are inescapable(!), you want the solution with less occurrences, not the solution with more.
As I said, I grepped the Phobos sources for $(COMMA), and found 2 instances, neither of which were necessary.
Dec 31 2014
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-01 00:53, Walter Bright wrote:

 As I said, I grepped the Phobos sources for $(COMMA), and found 2
 instances, neither of which were necessary.
And how do you plan to find all commas that should actually be $(COMMA)? -- /Jacob Carlborg
Jan 02 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 1:17 PM, H. S. Teoh via Digitalmars-d wrote:
 And what if you need commas in the list items? Oh right, $(COMMA). Very
 readable.
Just write $(ARGS lots, of, commas). -- Andrei
Jan 01 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 7:20 AM, Vladimir Panteleev wrote:
 On Monday, 29 December 2014 at 22:39:02 UTC, Walter Bright wrote:
 * reddit
 * github
These both use Markdown. The syntax is the same, except for minor things, such as the handling of newlines.
I agree that Markdown, especially Github's, has become a de facto standard. That's nice because tools and expertise are easy to find. It's a good argument. -- Andrei
Dec 31 2014
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 2:30 PM, Dicebot wrote:
 DDOC is probably one of D features with pretty idea and hardly usable
 design. I wish we had something like Markdown instead - can never
 remember Phobos macros to use and usually just resort to using plain
 text instead.
I'm with Walter here - I find Markdown and its ilk inferior to macro systems. -- Andrei
Dec 29 2014
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-30 02:38, Andrei Alexandrescu wrote:

 I'm with Walter here - I find Markdown and its ilk inferior to macro
 systems. -- Andrei
I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing documentation for code. Not web sites, not books, but documentation for code. -- /Jacob Carlborg
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 7:13 AM, Jacob Carlborg wrote:
 I don't agree, I feel the opposite. Markdown is superior to Ddoc in writing
 documentation for code. Not web sites, not books, but documentation for code.
Documentation for code winds up on a web site. I find it very handy that the Ddoc embedded in D code, and the Ddoc used for the rest of the web site, all use the same style sheets, the same macro files, etc. And an ebook and pdf can all be generated from the same.
Dec 31 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 12:40:20 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 7:13 AM, Jacob Carlborg wrote:
 I don't agree, I feel the opposite. Markdown is superior to Ddoc in wri=
ting
 documentation for code. Not web sites, not books, but documentation for=
code.
=20
 Documentation for code winds up on a web site.
finally, i got your point. D is *your* *personal* *project*. not more, not less. it something is handy for you, it will be in D, and it doesn't matter how much other people arguing about changing it. if something is of no use for you, it would be a miracle to see it in D, even when the code is ready and almost anyone who cares about the thing anough wrote "yes, do it!" and i'm not talking about Ddoc here. and about Ddoc/markdown issue: the quoted sentense says it all. you want Ddoc to be able to produce websites. and you don't care if some other people think that Ddoc was invented for documenting the source code. you know, documenting sources implies easy reading by human without preprocesing. and easy human-readable format is easy to write. but yes, it can't create a cool website for you. nor it is good for DTP. you keep inventing artificial samples to show that one still has to use escaping in markdown. you know, looking at Ddoc, which consists mostly of visual noise, i can tell you that markdown is god-given immortal purity. yet i got the idea: Ddoc is for websites, not for API documentation. it happens to understand some D, but the primary goal is to create website. ok. we just misunderstood why Ddoc is here. i appreciate all your hard work on D (and on C/C++ compilers too, which i was used from time to time). but do you really want D to be a widely used language? seems that you are thinking about some "future users", who will surely need to write a complex documents right in the D source code, so Ddoc must resemble DTP languages. that they ("future users") will write alot of code and so we can't break that unwritten code by changing the language now. and so on. what you seem to miss here is that it's the current D users who spreading a word. make D better for current passionate users, and you may get those "future users" in the future. make D great, but frustrating for current passionate users, and you will get no "future users" at all, 'cause there will be nobody to spread a word about D. i, for myself, can't see why i have to endure annoyance in the name of "future users". those "future users" did nothing for me, except making D frustrating. the thing is that "future users" will have to take what we giving 'em, not we have to take something that *might* please those "future users". do you think that vibe.d is a valuable project? S=C3=B6nke wants property enforcement syntax, for example. just ask him! and patch for that syntax is already here. that patch works, my DMD build using it. yet S=C3=B6nke will not come here to argue for this feature for month (or years?), he is busy developing vibe.d (and other things). S=C3=B6nke is a real user with a real project. he can live without property enforcement, but... besides, enforcing property syntax will solve the bug with delegate properties, where they need `()()` to really call the delegate. and we have dfix which can be extended to automatically fix user code. and what about tuple syntax? two years passed since PR was submitted. isn't it enough to stop thinking about how accepting that PR will close the opportunity to invent better syntax in the future and just accept it? two years of stagnation is enough to see that this feature is not at the top of priority list and you and Andrei will *always* have more important tasks to do. so just merge it and forget! (yes, i know that it can't be merged right now without rebasing; seems that we simply lost it) sorry. i hate new years.
Dec 31 2014
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2014-12-31 21:40, Walter Bright wrote:

 Documentation for code winds up on a web site.

 I find it very handy that the Ddoc embedded in D code, and the Ddoc used
 for the rest of the web site, all use the same style sheets, the same
 macro files, etc. And an ebook and pdf can all be generated from the same.
If, hypothetically, Ddoc was removed and replaced with something completely different, that doesn't mean you need to stop using it. You could even continue to ship it with DMD was a separate tool. -- /Jacob Carlborg
Jan 02 2015
prev sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/29/14 10:38 PM, Andrei Alexandrescu wrote:
 On 12/29/14 2:30 PM, Dicebot wrote:
 DDOC is probably one of D features with pretty idea and hardly usable
 design. I wish we had something like Markdown instead - can never
 remember Phobos macros to use and usually just resort to using plain
 text instead.
I'm with Walter here - I find Markdown and its ilk inferior to macro systems. -- Andrei
Definitely, because Markdown is not a macro system, it's a documentation tool.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 12:55 PM, Ary Borenszweig wrote:
 Definitely, because Markdown is not a macro system, it's a documentation tool.
I write a lot of documentation. A macro system has saved enormous amounts of effort. Night and day, really. Not having a macro system is like using a programming language that does not have functions. Ketmar, for example, complained mightily about Ddoc markup. I suggested he simply email me the Phobos documentation he wants to write, and I'd mark it up for him and submit the PRs. He admitted he is not interested in actually writing any documentation. Ddoc is not the real issue, at least for him. I'll extend the same offer to you. Email me the fixed Phobos docs. I'll mark them up and submit PRs. The thing is, with Ddoc you don't actually have to write any markup. You can write: /**************************** This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***************************/
Dec 31 2014
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 6:46 PM, Walter Bright wrote:
 On 12/31/2014 12:55 PM, Ary Borenszweig wrote:
 Definitely, because Markdown is not a macro system, it's a
 documentation tool.
I write a lot of documentation. A macro system has saved enormous amounts of effort. Night and day, really. Not having a macro system is like using a programming language that does not have functions. Ketmar, for example, complained mightily about Ddoc markup. I suggested he simply email me the Phobos documentation he wants to write, and I'd mark it up for him and submit the PRs. He admitted he is not interested in actually writing any documentation. Ddoc is not the real issue, at least for him. I'll extend the same offer to you. Email me the fixed Phobos docs. I'll mark them up and submit PRs. The thing is, with Ddoc you don't actually have to write any markup. You can write: /**************************** This function does blah, blah, blah. Blah, blah, blah is an amazing algorithm invented by I. M. Nerdly. Params: x = the awesome input value Returns: insightful description of the return value Example: --- int foo(int x) { ... stunning D code ... } --- ***************************/
You are right. I browsed some phobo's code and saw the documentation, it looks clean and nice. The only exception is std.algorithm which is full of macros and barely readable. So where is that other macro code? The one that has $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed?
Dec 31 2014
parent reply "Dicebot" <public dicebot.lv> writes:
On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig 
wrote:
 You are right. I browsed some phobo's code and saw the 
 documentation, it looks clean and nice. The only exception is 
 std.algorithm which is full of macros and barely readable.

 So where is that other macro code? The one that has 
 $(BLANKLINE) or $(COMMA) or $(DASH) and why is it needed?
IMHO biggest issue is not inline documentation for functions but more higher level stuff like http://dlang.org/arrays.html - it was all in DDOC too last time I checked and changing anything about it is hardly a pleasure. Inline documentations only suffers when more pretty stuff like tables gets added. One more fundamental issue with inline docs is not markup language but lack of any simple way to inherit / refer existing documentation entries. There is "ditto" but no "same as in base method" or "same as for symbol X".
Dec 31 2014
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 7:46 PM, Dicebot wrote:
 On Wednesday, 31 December 2014 at 22:41:41 UTC, Ary Borenszweig wrote:
 You are right. I browsed some phobo's code and saw the documentation,
 it looks clean and nice. The only exception is std.algorithm which is
 full of macros and barely readable.

 So where is that other macro code? The one that has $(BLANKLINE) or
 $(COMMA) or $(DASH) and why is it needed?
IMHO biggest issue is not inline documentation for functions but more higher level stuff like http://dlang.org/arrays.html - it was all in DDOC too last time I checked and changing anything about it is hardly a pleasure. Inline documentations only suffers when more pretty stuff like tables gets added.
It looks quite clean to me: https://github.com/D-Programming-Language/dlang.org/blob/master/arrays.dd Except for the fact that instead of the familiar HTML tags there are macros. I see macros for: Paragraphs: $(P) Lists: $(UL), $(LI) Links: $(HTTP) These are very, very, veeeery common in documentation and sites. Couldn't DDoc provide nice, readable ways for dealing with these?
Dec 31 2014
parent reply "Dicebot" <public dicebot.lv> writes:
On Wednesday, 31 December 2014 at 22:53:14 UTC, Ary Borenszweig 
wrote:
 It looks quite clean to me:

 https://github.com/D-Programming-Language/dlang.org/blob/master/arrays.dd
One of the very first lines: $(TABLE2 Kinds of Arrays, $(THEAD Syntax, Description) $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, Pointers to data))) $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2 static-arrays, Static arrays))) $(TROW $(ARGS $(I type)[]), $(ARGS $(RELATIVE_LINK2 dynamic-arrays, Dynamic arrays))) $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map, Associative Arrays, Associative arrays))) ) I had no idea of what it is and how it will look like after doc generation until started checking each macro one by one. Similar stuff in md: | Kinds of Arrays | |--------------------------| | Syntax | Description | |------------------------------| |`type*` | [Pointers to data](/arrays.html#pointers) | |`type[integer]` | [Static arrays](/arrays.html#static-arrays) | // etc. it is just so much easier to work with : resembles actual generated layout, less noise from service symbols, no special macros for basic things. It may be somewhat less maintainable because everything is hard-coded but it is not something that changes casually.
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 3:03 PM, Dicebot wrote:
 One of the very first lines:

      $(TABLE2 Kinds of Arrays,
          $(THEAD Syntax, Description)
          $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, Pointers
 to data)))
          $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2
 static-arrays, Static arrays)))
          $(TROW $(ARGS $(I type)[]),  $(ARGS $(RELATIVE_LINK2 dynamic-arrays,
 Dynamic arrays)))
          $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map,
 Associative Arrays, Associative arrays)))
      )

 I had no idea of what it is and how it will look like after doc generation
until
 started checking each macro one by one. Similar stuff in md:

      |       Kinds of Arrays    |
      |--------------------------|
      | Syntax         | Description |
      |------------------------------|
      |`type*`         | [Pointers to data](/arrays.html#pointers)  |
      |`type[integer]` | [Static arrays](/arrays.html#static-arrays) |

      // etc.
It's quite unfair to not bother with whitespace formatting in one but not the other. It's like the "before" and "after" advertisements for cosmetics where the "before" has uncombed hair, poor lighting, is frowning, didn't brush their teeth, frumpy clothes, etc., and you know what they did with the "after" picture. Furthermore, the person who wrote the Ddoc macros not only did not bother to format, he also used unnecessary markup - the $(ARGS) is redundant. Making some effort myself: $(TABLE2 Kinds of Arrays, $(THEAD Syntax , Description ) $(TROW $(I type*) , $(LINK2 #pointers, Pointers to data) ) $(TROW $(I type[integer]), $(LINK2 #static-arrays, Static arrays)) ) versus: |Kinds of Arrays| |---| |Syntax|Description| |-| |`type*`|[Pointers to data](/arrays.html#pointers)| |`type[integer]`|[Static arrays](/arrays.html#static-arrays)|
Dec 31 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 16:21:26 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 12/31/2014 3:03 PM, Dicebot wrote:
 One of the very first lines:

      $(TABLE2 Kinds of Arrays,
          $(THEAD Syntax, Description)
          $(TROW $(ARGS $(I type)*), $(ARGS $(RELATIVE_LINK2 pointers, P=
ointers
 to data)))
          $(TROW $(ARGS $(I type)[$(I integer)]), $(ARGS $(RELATIVE_LINK2
 static-arrays, Static arrays)))
          $(TROW $(ARGS $(I type)[]),  $(ARGS $(RELATIVE_LINK2 dynamic-a=
rrays,
 Dynamic arrays)))
          $(TROW $(ARGS $(I type)[$(I type)]), $(ARGS $(DDLINK hash-map,
 Associative Arrays, Associative arrays)))
      )
 Making some effort myself:
=20
 $(TABLE2 Kinds of Arrays,
    $(THEAD Syntax            , Description                           )
    $(TROW  $(I type*)        , $(LINK2 #pointers, Pointers to data)  )
    $(TROW  $(I type[integer]), $(LINK2 #static-arrays, Static arrays))
 )
not really better. it's still noisy and it's still YELLING AT ME, disctracting me from the actual text.
Dec 31 2014
prev sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Thursday, 1 January 2015 at 00:21:42 UTC, Walter Bright wrote:
 It's quite unfair to not bother with whitespace formatting in 
 one but not the other. It's like the "before" and "after" 
 advertisements for cosmetics where the "before" has uncombed 
 hair, poor lighting, is frowning, didn't brush their teeth, 
 frumpy clothes, etc., and you know what they did with the 
 "after" picture.
It is the way original author has formatted. There is indentation so must be not accidental.
 Furthermore, the person who wrote the Ddoc macros not only did 
 not bother to format, he also used unnecessary markup - the 
 $(ARGS) is redundant.
Probably because it is so hard to understand what is necessary and what isn't?
 Making some effort myself:

 $(TABLE2 Kinds of Arrays,
   $(THEAD Syntax            , Description
     )
   $(TROW  $(I type*)        , $(LINK2 #pointers, Pointers to 
 data)  )
   $(TROW  $(I type[integer]), $(LINK2 #static-arrays, Static 
 arrays))
 )

 versus:

  |Kinds of Arrays|
  |---|
  |Syntax|Description|
  |-|
  |`type*`|[Pointers to data](/arrays.html#pointers)|
  |`type[integer]`|[Static arrays](/arrays.html#static-arrays)|
Second version still looks much more clear to me, despite intentionally screwed formatting. It is a problem of noise-to-content ratio and it is hard to compete with ASCII art in terms of readability.
Dec 31 2014
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 5:00 PM, Dicebot wrote:
 It is the way original author has formatted. There is indentation so must be
not
 accidental.
If you saw a piece of crummy code in language X, that means language X is a bad programming language?
Dec 31 2014
prev sibling next sibling parent reply "jklp" <jklp nowhere.fr> writes:
On Monday, 29 December 2014 at 05:39:16 UTC, Walter Bright wrote:
 On 12/28/2014 8:44 AM, Kiith-Sa wrote:
 It depends on the function being documented. For 'downcase', 
 such blocks are
 overkill;
After doing it both ways for a while, I'm pretty convinced they are not overkill even for trivial functions: 1. they lend an air of consistency and comfort to the reader 2. they provide an anchor for automated tools which can extract the information 3. without such a block, I've found that I (and others, descriptions of 'obvious' parameters which are actually not obvious at all. 4. a block can be styled in a custom manner
 DDoc is powerful, but it is a very nasty case of "hard things 
 are possible, easy
 things are hard" (e.g. tables, and very unreadable in source 
 $(B bold) instead
 of **bold**, $(D code) instead of `code`, $(LINK2 ...), etc. .
Having used both Ddoc and Markdown, I seriously disagree with this. Take a look at the markdown source for DIP69. It's horrific.
 I think it'd be a good idea to add at least a subset of 
 markdown to DMD DDoc,
 which could generate DDoc macros (e.g. **bold**, *italic*, 
 `inline code` (DDoc
 already has nice syntax for code *blocks*), 
 [link](www.link.com), and some table
 syntax (not in vanilla markdown, but e.g. GitHub 
 markdown/PanDoc markdown have a
 common syntax)

 - I may be able to find some time to work on this for DMD DDoc 
 in summer (not
 sooner unfortunately, I'd need some time to look around the 
 code as I never
 touched it), but would it have a chance of being merged? 
 (Walter?)
I'd rather not accept some Markdown dialect into Ddoc.
I like your sense of the compromise. DDoc is mostly usefull to generate the doc as html but inside the sources, it's often **unreadable**. I think that you know that documentation comments as markdow would be good but maybe you're scared because of the consequences implied when rendering dlang.org std reference and such things. And if both could live together ? If I had the power to do this, DDoc would be primilarly 'markdown' with optionally html and macros things allowed.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 10:34 AM, jklp wrote:
 I like your sense of the compromise. DDoc is mostly usefull to generate the doc
 as html but inside the sources, it's often **unreadable**. I think that you
know
 that documentation comments as markdow would be good but maybe you're scared
 because of the consequences implied when rendering dlang.org std reference and
 such things.
 And if both could live together ?

 If I had the power to do this, DDoc would be primilarly 'markdown' with
 optionally html and macros things allowed.
I don't care much for hybrids, they are confusing and ugly.
Dec 29 2014
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-29 20:48, Walter Bright wrote:

 I don't care much for hybrids, they are confusing and ugly.
Markdown already support raw HTML. We could use Markdown but with Ddoc macros instead of raw HTML. BTW, Ddoc macros are really ugly. -- /Jacob Carlborg
Dec 29 2014
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 12:04 PM, Jacob Carlborg wrote:
 On 2014-12-29 20:48, Walter Bright wrote:

 I don't care much for hybrids, they are confusing and ugly.
Markdown already support raw HTML.
I know. That's what's wrong with it. It is severely underpowered, and so uses a wretched hybrid approach like C uses a preprocessor because it is underpowered.
 We could use Markdown but with Ddoc macros
 instead of raw HTML.

 BTW, Ddoc macros are really ugly.
In reddit, is it [link](description) or [description](link) or (link)[description] or (description)[link]? I have to read the dam help file every time. No, I can't remember what it is for which Markdown flavor, either. BTW, using macros have cut my web page writing time by about 75%. It's also a joy to just change the macro definitions and voila! the whole web site fixes itself.
Dec 29 2014
parent Jacob Carlborg <doob me.com> writes:
On 2014-12-29 23:44, Walter Bright wrote:

 I know. That's what's wrong with it. It is severely underpowered, and so
 uses a wretched hybrid approach like C uses a preprocessor because it is
 underpowered.
That's what's making it better than ddoc. 90% of the time that power is not needed. Ddoc is instead making that 90% of the documentation a lot harder to write
 In reddit, is it [link](description) or [description](link) or
 (link)[description] or (description)[link]? I have to read the dam help
 file every time. No, I can't remember what it is for which Markdown
 flavor, either.
If it's uses anything other than [text](url) it's not Markdown, period.
 BTW, using macros have cut my web page writing time by about 75%. It's
 also a joy to just change the macro definitions and voila! the whole web
 site fixes itself.
Using Ruby and Haml has improved the time it takes for me to write a web site. I can just change a Ruby function or a template the whole site changes. That doesn't mean I just Ruby and Haml to document my code. Pick the write tool for the job. Markdown is not the right tool to use for writing a book or a complete web site. Ddoc is not the right tool for documenting code. -- /Jacob Carlborg
Dec 31 2014
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 12:04 PM, Jacob Carlborg wrote:
 On 2014-12-29 20:48, Walter Bright wrote:

 I don't care much for hybrids, they are confusing and ugly.
Markdown already support raw HTML. We could use Markdown but with Ddoc macros instead of raw HTML. BTW, Ddoc macros are really ugly.
Ideas for a better syntax? I like the idea of a uniform syntax for all macros instead of learning one syntax for each artfact. -- Andrei
Dec 29 2014
parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Tuesday, 30 December 2014 at 01:35:57 UTC, Andrei Alexandrescu 
wrote:
 On 12/29/14 12:04 PM, Jacob Carlborg wrote:
 On 2014-12-29 20:48, Walter Bright wrote:

 I don't care much for hybrids, they are confusing and ugly.
Markdown already support raw HTML. We could use Markdown but with Ddoc macros instead of raw HTML. BTW, Ddoc macros are really ugly.
Ideas for a better syntax? I like the idea of a uniform syntax for all macros instead of learning one syntax for each artfact. -- Andrei
Current syntax: $(B bolded) OO O O * 4 characters of overhead * The characters are 'big' and seem like text (especially $), taking attention away from the actual content. Different from e.g. **bold** or `italic` * To type, needs 6 keypresses - 2 shifts + 4 keys (shift held for one key) - as a person with RSI, this is relevant to me * Need parens even for 1-argument version, increasing lisp-ness with nested macros ----------------------------- Idea: short 1-argument syntax ----------------------------- I think one way to improve this would be to add an equivalent of the short template instantiation syntax: someFunction(to!(ReturnType!T)) is less lispy and more readable than someFunction(to!(ReturnType!(T))) (especially with longer lines, more args, deeper nestings) similarly e.g. (not proposing this exact syntax - just an example) $(LI B$bold D$true) is more readable than $(LI $(B bold) $(D true)) And requires only 2 keypresses (including shift) for the 1-parameter macros. Of course, this only helps with 1-parameter macros, but that's very often the worst source of visual noise in DDoc, especially with things like list items and tables (nesting), especially if the lines are long. -------------------------------------- Idea: 2(3 with space) character syntax -------------------------------------- I'm not sure if this is viable without causing more damage than benefit (too much escaping). Idea: use 2 delimiting characters, preferably 'small' characters that don't distract. E.g (again, these are not actual proposals, just to illustrate the point): `B bold` (very little visual noise but perhaps a bit too little/easy to miss, 3 keypresses including space) ;B bold; (slightly more visual noise but not too distracting, but ';' is probably too common character so there could be too much escaping, 3 keypresses) .. etc.
Dec 29 2014
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
Some not bad ideas!
Dec 29 2014
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 6:50 PM, Kiith-Sa wrote:
 .. etc.
You seem to not like your own proposals! -- Andrei
Dec 29 2014
parent reply "Kiith-Sa" <kiithsacmp gmail.com> writes:
On Tuesday, 30 December 2014 at 04:33:10 UTC, Andrei Alexandrescu 
wrote:
 On 12/29/14 6:50 PM, Kiith-Sa wrote:
 .. etc.
You seem to not like your own proposals! -- Andrei
I like them less than a markdown-DDoc combo. They (at least the first one) are still a way to make DDoc more readable even without markdown. As escaping seems to be considered to be the major issue here the second proposal may result in a lot of extra escaping depending on character/s used (and I personally would hate $MACRO arg1 arg2$ which would reuse $ to minimize escaping). The first idea I don't find anything to dislike about, but it will only help for 1-param macros. That's not a 'bad', just 'good to a lesser degree'.
Dec 29 2014
parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 30/12/2014 5:46 p.m., Kiith-Sa wrote:
 On Tuesday, 30 December 2014 at 04:33:10 UTC, Andrei Alexandrescu wrote:
 On 12/29/14 6:50 PM, Kiith-Sa wrote:
 .. etc.
You seem to not like your own proposals! -- Andrei
I like them less than a markdown-DDoc combo. They (at least the first one) are still a way to make DDoc more readable even without markdown. As escaping seems to be considered to be the major issue here the second proposal may result in a lot of extra escaping depending on character/s used (and I personally would hate $MACRO arg1 arg2$ which would reuse $ to minimize escaping). The first idea I don't find anything to dislike about, but it will only help for 1-param macros. That's not a 'bad', just 'good to a lesser degree'.
Hmm I have an idea. I wonder if I can get ddoc to generate json files. If I can, theoretically with some client side clever tricks I could make this rather nice. Integration into dub and might even have a central documentation source on dub repo. Also means all the ddoc macros like styles would be going away.
Dec 29 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/29/14 9:13 PM, Rikki Cattermole wrote:
 I wonder if I can get ddoc to generate json files.
That should be possible (probably after a few improvements). I'm working on a few templates for alternate formats including LaTeX, plain text, and well, now json. -- Andrei
Dec 29 2014
next sibling parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 30/12/2014 6:36 p.m., Andrei Alexandrescu wrote:
 On 12/29/14 9:13 PM, Rikki Cattermole wrote:
 I wonder if I can get ddoc to generate json files.
That should be possible (probably after a few improvements). I'm working on a few templates for alternate formats including LaTeX, plain text, and well, now json. -- Andrei
I've had a go, its mostly already possible for json. Although escaping is a major issue. For things like a double quote. This is what I have: Ddoc _=General macros for HTML generation. Even predefined macros are present here for completeness. Macros defer wherever possible to style classes. _=Simple tags, ordered alphabetically A = $+ ADEF = $0 AHTTP = http://$1 $+ AHTTPS = https://$1 $+ B = $0 $+ BIG = $0 BR = DD = $0 DIV = $1 $+ DIVC = $1 $+ DIVCID = $1 $2 $3 DIVID = $1 $+ DL = $0 DOUBLEQUOTE = $(LDQUO)$0$(RDQUO) DT = $0 ENUMERATE = [$(ITEMS_HELPER $1, $+)] GREATER = &gt; ITEMIZE = [$(ITEMS_HELPER $1, $+)] ITEMS_HELPER = "$1", $(ITEMS_HELPER $+) FONT = $1 $+ H1 = $0 H2 = $0 H3 = $0 H4 = $0 H5 = $0 HR = I = $0 LI = $0 LESS = &lt; OL = [$0] P = $0 PRE = $0 SCRIPT = $0 SINGLEQUOTE = $(LSQUO)$0$(RSQUO) SMALL = $0 SPAN = $1 $+ SPANC = $1 $+ SUBSCRIPT = $0 SUPERSCRIPT = $0 TABLE = $0 TABLEC = $1 $+ TD = $0 TD_HELPER = $(TD $1)$(TD_HELPER $+) TH_HELPER = $(TH $1)$(TH_HELPER $+) TR = $0 TT = $0 U = $0 UL = [$0] _=Defining anchors and linking LINK = $(A $0, $0) LINK2 = $(A $1, $+) HTTP = $(LINK2 http://$1,$2) HTTPS = $(LINK2 https://$1,$2) WEB = $(HTTP $1,$2) _=Colors COLOR = $(FONT color=$1, $+) RED = $0 GREEN = $0 BLUE = $0 YELLOW = $0 BLACK = $0 WHITE = $0 _=Explanatory stuff of the kind "Throws: blah" or "Returns: blah". Note that if you want to make a SPAN-like (brief) explanation, you can do it with the DIV block using "display: inline-block;", see e.g. http://stackoverflow.com/questions/1611065/span-vs-div-inline-block DDOC_EXPLANATORY=$(DIVC explanatory, $(SPANC explanation_item, $1:) $(DIVC $1, $+)) _=Predefined D-related stuff D_CODE = $0 D_COMMENT = $(SPANC d_comment, $0) D_STRING = $(SPANC d_string, $0) D_KEYWORD = $(SPANC d_keyword, $0) D_PSYMBOL = $(SPANC d_psymbol, $0) D_PARAM = $(SPANC d_param, $0) _=Main entry point DDOC = { "Project": "$(TITLE)", $(BODY) } JSONVALUES = "$1", $(JSONVALUES $+) _=DDoc-related stuff DDOC_COMMENT = DDOC_DECL = $(DT $(BIG $0)) DDOC_DECL_DD = $(DD $0) DDOC_DITTO = $(BR)$0 DDOC_SECTIONS = $0 DDOC_SUMMARY = "Summary": "$0", DDOC_DESCRIPTION = "Description:": "$0", DDOC_AUTHORS = "Authors:": [$(JSONVALUES $0)], DDOC_BUGS = "Bugs: "$0", DDOC_COPYRIGHT = "Copyright": "$0", DDOC_DATE = "Date": $0", DDOC_DEPRECATED = "Deprecated": "$0", DDOC_EXAMPLES = "Examples": "$0", DDOC_HISTORY = "History": "$0", DDOC_LICENSE = "License": "$0", DDOC_RETURNS = "Returns": [$0], DDOC_SEE_ALSO = "See Also": [$0], DDOC_STANDARDS = "Standards": "$0", DDOC_THROWS = "Throws": "$0", DDOC_VERSION = "Version": "$0", DDOC_SECTION_H = $0 DDOC_SECTION = $0 DDOC_MEMBERS = $0 DDOC_MODULE_MEMBERS = $(DDOC_MEMBERS $0) DDOC_CLASS_MEMBERS = $(DDOC_MEMBERS $0) DDOC_STRUCT_MEMBERS = $(DDOC_MEMBERS $0) DDOC_ENUM_MEMBERS = $(DDOC_MEMBERS $0) DDOC_TEMPLATE_MEMBERS = $(DDOC_MEMBERS $0) DDOC_PARAMS = "Params": $0 DDOC_PARAM_ROW = $(TR $0) DDOC_PARAM_ID = $(TD $0) DDOC_PARAM_DESC = $(TD $0) DDOC_BLANKLINE = $(BR)$(BR) DDOC_ANCHOR = $1 DDOC_PSYMBOL = $(U $0) DDOC_KEYWORD = $(B $0) DDOC_PARAM = $(I $0) _=HTML named entities, ordered approximately as in http://dlang.org/entity.html QUOT = &quot; AMP = &amp; OELIG_CAP = &OElig; OELIG = &oelig; SCARON_CAP = &Scaron; SCARON = &scaron; YUML = &Yuml; CIRC = &circ; TILDE = &tilde; ENSP = &ensp; EMSP = &emsp; THINSP = &thinsp; ZWNJ = &zwnj; ZWJ = &zwj; LRM = &lrm; RLM = &rlm; NDASH = &ndash; MDASH = &mdash; LSQUO = &lsquo; RSQUO = &rsquo; SBQUO = &sbquo; LDQUO = &ldquo; RDQUO = &rdquo; BDQUO = &bdquo; DAGGER = &dagger; DAGGER_CAP = &Dagger; PERMIL = &permil; LSAQUO = &lsaquo; RSAQUO = &rsaquo; EURO = &euro; NBSP = &nbsp; IEXCL = &iexcl; CENT = &cent; POUND = &pound; CURREN = &curren; YEN = &yen; BRVBAR = &brvbar; SECT = &sect; UML = &uml; COPY = &copy; REG = &reg; ORDF = &ordf; LAQUO = &laquo; NOT = &not; SHY = &shy; REG = &reg; MACR = &macr; DEG = &deg; PLUSMN = &plusmn; SUP2 = &sup2; SUP3 = &sup3; ACUTE = &acute; MICRO = &micro; PARA = &para; MIDDOT = &middot; CEDIL = &cedil; SUP1 = &sup1; ORDM = &ordm; RAQUO = &raquo; FRAC14 = &frac14; FRAC12 = &frac12; FRAC34 = &frac34; IQUEST = &iquest; AGRAVE_CAP = &Agrave; AACUTE_CAP = &Aacute; ACIRC_CAP = &Acirc; ATILDE_CAP = &Atilde; AUML_CAP = &Auml; ARING_CAP = &Aring; AELIG_CAP = &AElig; CCEDIL_CAP = &Ccedil; EGRAVE_CAP = &Egrave; EACUTE_CAP = &Eacute; ECIRC_CAP = &Ecirc; EUML_CAP = &Euml; IGRAVE_CAP = &Igrave; IACUTE_CAP = &Iacute; ICIRC_CAP = &Icirc; IUML_CAP = &Iuml; ETH_CAP = &ETH; NTILDE_CAP = &Ntilde; OGRAVE_CAP = &Ograve; OACUTE_CAP = &Oacute; OCIRC_CAP = &Ocirc; OTILDE_CAP = &Otilde; OUML_CAP = &Ouml; TIMES = &times; OSLASH_CAP = &Oslash; UGRAVE_CAP = &Ugrave; UACUTE_CAP = &Uacute; UCIRC_CAP = &Ucirc; UUML_CAP = &Uuml; YACUTE_CAP = &Yacute; THORN_CAP = &THORN; SZLIG = &szlig; AGRAVE = &agrave; AACUTE = &aacute; ACIRC = &acirc; ATILDE = &atilde; AUML = &auml; ARING = &aring; AELIG = &aelig; CCEDIL = &ccedil; EGRAVE = &egrave; EACUTE = &eacute; ECIRC = &ecirc; EUML = &euml; IGRAVE = &igrave; IACUTE = &iacute; ICIRC = &icirc; IUML = &iuml; ETH = &eth; NTILDE = &ntilde; OGRAVE = &ograve; OACUTE = &oacute; OCIRC = &ocirc; OTILDE = &otilde; OUML = &ouml; DIVIDE = &divide; OSLASH = &oslash; UGRAVE = &ugrave; UACUTE = &uacute; UCIRC = &ucirc; UUML = &uuml; YACUTE = &yacute; THORN = &thorn; YUML = &yuml; FNOF = &fnof; ALPHA_CAP = &Alpha; BETA_CAP = &Beta; GAMMA_CAP = &Gamma; DELTA_CAP = &Delta; EPSILON_CAP = &Epsilon; ZETA_CAP = &Zeta; ETA_CAP = &Eta; THETA_CAP = &Theta; IOTA_CAP = &Iota; KAPPA_CAP = &Kappa; LAMBDA_CAP = &Lambda; MU_CAP = &Mu; NU_CAP = &Nu; XI_CAP = &Xi; OMICRON_CAP = &Omicron; PI_CAP = &Pi; RHO_CAP = &Rho; SIGMA_CAP = &Sigma; TAU_CAP = &Tau; UPSILON_CAP = &Upsilon; PHI_CAP = &Phi; CHI_CAP = &Chi; PSI_CAP = &Psi; OMEGA_CAP = &Omega; ALPHA = &alpha; BETA = &beta; GAMMA = &gamma; DELTA = &delta; EPSILON = &epsilon; ZETA = &zeta; ETA = &eta; THETA = &theta; IOTA = &iota; KAPPA = &kappa; LAMBDA = &lambda; MU = &mu; NU = &nu; XI = &xi; OMICRON = &omicron; PI = &pi; RHO = &rho; SIGMAF = &sigmaf; SIGMA = &sigma; TAU = &tau; UPSILON = &upsilon; PHI = &phi; CHI = &chi; PSI = &psi; OMEGA = &omega; THETASYM = &thetasym; UPSIH = &upsih; PIV = &piv; BULL = &bull; HELLIP = &hellip; PRIME = &prime; PRIME = &Prime; OLINE = &oline; FRASL = &frasl; WEIERP = &weierp; IMAGE = &image; REAL = &real; TRADE = &trade; ALEFSYM = &alefsym; LARR = &larr; UARR = &uarr; RARR = &rarr; DARR = &darr; HARR = &harr; CRARR = &crarr; LARR_CAP = &lArr; UARR_CAP = &uArr; RARR_CAP = &rArr; DARR_CAP = &dArr; HARR_CAP = &hArr; FORALL = &forall; PART = &part; EXIST = &exist; EMPTY = &empty; NABLA = &nabla; ISIN = &isin; NOTIN = &notin; NI = &ni; PROD = &prod; SUM = &sum; MINUS = &minus; LOWAST = &lowast; RADIC = &radic; PROP = &prop; INFIN = &infin; ANG = &ang; AND = &and; OR = &or; CAP = &cap; CUP = &cup; INT = &int; THERE4 = &there4; SIM = &sim; CONG = &cong; ASYMP = &asymp; NE = &ne; EQUIV = &equiv; LE = &le; GE = &ge; SUB = &sub; SUP = &sup; NSUB = &nsub; SUBE = &sube; SUPE = &supe; OPLUS = &oplus; OTIMES = &otimes; PERP = &perp; SDOT = &sdot; LCEIL = &lceil; RCEIL = &rceil; LFLOOR = &lfloor; RFLOOR = &rfloor; LOZ = &loz; SPADES = &spades; CLUBS = &clubs; HEARTS = &hearts; DIAMS = &diams; LANG = &lang; RANG = &rang; Produces: { "Project": "devisualization.window.interfaces.window", "Summary": "Declared the majority of the interfaces for Devisualization.Window ", "Authors:": ["Richard Andrew Cattermole ", ], "License": "The MIT License (MIT) Copyright (c) 2014 Devisualization (Richard Andrew Cattermole) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ", "Examples": " To create a window without an OpenGL context: Windowable d_psymbol window = d_keyword new Window(800, 600, d_string "My window!"w, 100, 100); d_psymbol window.show(); Window.messageLoop(); This runs the message loop after showing the window. Does nothing with events. Or show any content.", WindowConfigstruct WindowConfig; "Summary": "Arguments to create a window. Some may be optional. ", "Description:": "A minimum width and height should be supplied. ", "See Also": [Windowable], WindowConfig.widthuint width; "Summary": "Width of the window to create. Must be atleast 0 (px).", WindowConfig.heightuint height; "Summary": "Height of the window to create. Must be atleast 0 (px).", WindowConfig.titlewstring title; "Summary": "The title of the window to create. Commonly a UTF-8 support should be available. However if not ASCII will be used. Which is effectively a string. Assume ASCII values are safe as a value. ", Default: "A DWC window" WindowConfig.xint x; "Summary": "The x position of the window to be created. It is possible that this is ignored by the implementation. ", Default: 0 (px) WindowConfig.yint y; "Summary": "The y position of the window to be created. It is possible that this is ignored by the implementation. ", Default: 0 (px) WindowConfig.contextTypeWindowContextType contextType; "Summary": "Specifies the type of context to create. Validated by the window implementation. ", Default: None Windowableinterface Windowable; "Summary": "A generic window interface. ", "Description:": " Should be supportive of majority of windowing toolkits in existance. Is unaware of screens. Implementation should support two constructors: d_keyword this(T...)(T config) { d_keyword this(WindowConfig(config)); } d_keyword this(WindowConfig config); ", Events Mechanism: A window support a set number of events. From those the event offer set functionality to manipulate them. Adds a listener on an event d_keyword void addEventName(d_keyword void d_keyword delegate(T)); d_keyword void addEventName(d_keyword bool d_keyword delegate(T)); Removes the provided listener d_keyword void removeEventName(d_keyword bool d_keyword delegate(T)); d_keyword void removeEventName(d_keyword void d_keyword delegate(T)); Counts how many listeners for an event size_t countEventName(); Runs the event for all listeners with the given arguments d_keyword void eventName(T); Clears all listeners for an event d_keyword void clearEventName(); Optionally will also support: d_keyword void eventName(T[1 .. $]); Where T[0] is Windowable. This will run the event and pass in as first argument this (Windowable). Events: Upon the message loop drawing period this is called.<br/> onDraw = Windowable When the message loop is informed the window has moved, this is called.<br/> onMove = Windowable, int x, int y When the message loop is informed the window has resized, this is called.<br/> onResize = Windowable, uint newWidth, uint newHeight When the window has been requested to be closed from the user, this is called.<br/> On this event Windowable.close must be called manually.<br/> onClose = Windowable Windowable.messageLoopstatic void messageLoop(); "Summary": "Continues iteration of the message loop. ", "Description:": "This is expected functionality provided from the implementation.", Windowable.messageLoopIterationstatic void messageLoopIteration(); "Summary": "A single iteration of the message loop. ", "Description:": "This is expected functionality provided from the implementation.", Windowable.showabstract void show(); "Summary": "Hides the window. ", "See Also": [hide], Windowable.hideabstract void hide(); "Summary": "Shows the window. ", "See Also": [close], Windowable.titleabstract property void title(string text); "Summary": "Sets the title text. ", "Params": string text The text to set the title of the window to Windowable.titleabstract property void title(dstring text); "Summary": "Sets the title text. ", "Params": dstring text The text to set the title of the window to Windowable.titleabstract property void title(wstring text); "Summary": "Sets the title text. ", "Params": wstring text The text to set the title of the window to Windowable.sizeabstract property void size(uint width, uint height); "Summary": "Resize the window. ", "Description:": "Does not animate. ", "Params": uint width The width to set to uint height The height to set to Windowable.moveabstract property void move(int x, int y); "Summary": "Move the window to coordinate. ", "Description:": "Coordinate system based upon Top left corner of screen. Does not support screens (could be moved outside main screen). Coordinates can be negative, but is dependent upon the OS. ", "Params": int x The x coordinate to move to int y The y coordinate to move to Windowable.canResizeabstract property void canResize(bool can = true); "Summary": "Enable / disable resizing of the window. ", "Params": bool can Is it possible to resize the window (default yes) Windowable.fullscreenabstract property void fullscreen(bool isFullscreen = true); "Summary": "Go into/out fullscreen ", "Params": bool isFullscreen Should be fullscreen (default yes) Windowable.closeabstract property void close(); "Summary": "Closes the window. The window cannot reopened once closed. ", "See Also": [hide], Windowable.hasBeenClosedabstract property bool hasBeenClosed(); "Summary": "Has the window been closed? ", "Returns": [True if close has been called ], "See Also": [close], Windowable.contextabstract property IContext context(); "Summary": "Gets the current context that the window has open or null for none. ", "Returns": [A context that has a buffer that can be swapped and activated once created], Windowable.iconabstract void icon(Image image); "Summary": "Sets the icon for the window. Supports transparency. ", "Params": Image image The image (from Devisualization.Image). Windowable.icondeprecated abstract void icon(ushort width, ushort height, ubyte[3][] data, ubyte[3]* transparent = null); "Summary": "Sets the icon for the window. Supports transparency. ", "Params": ushort width The width of the icon ushort height The height of the icon ubyte[3][] data rgb data 0 .. 255, 3 bytes per pixel ubyte[3]* transparent The given pixel (3 bytes like data) color to use as transparency "Deprecated": "Superseded by using Devisualization.Image's Image, as argument instead.", } Pretty yucky in terms of whitespace.
Dec 29 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/29/2014 10:04 PM, Rikki Cattermole wrote:
 On 30/12/2014 6:36 p.m., Andrei Alexandrescu wrote:
 On 12/29/14 9:13 PM, Rikki Cattermole wrote:
 I wonder if I can get ddoc to generate json files.
That should be possible (probably after a few improvements). I'm working on a few templates for alternate formats including LaTeX, plain text, and well, now json. -- Andrei
I've had a go, its mostly already possible for json. Although escaping is a major issue. For things like a double quote. This is what I have:
Thank you for doing this!
 "License": "The MIT License (MIT)
Can you please consider the Boost license? It's what everything else in D uses. Having multiple licenses interleaved makes things much more complicated for corporate lawyers to adopt.
Dec 29 2014
parent Rikki Cattermole <alphaglosined gmail.com> writes:
On 30/12/2014 8:57 p.m., Walter Bright wrote:
 On 12/29/2014 10:04 PM, Rikki Cattermole wrote:
 On 30/12/2014 6:36 p.m., Andrei Alexandrescu wrote:
 On 12/29/14 9:13 PM, Rikki Cattermole wrote:
 I wonder if I can get ddoc to generate json files.
That should be possible (probably after a few improvements). I'm working on a few templates for alternate formats including LaTeX, plain text, and well, now json. -- Andrei
I've had a go, its mostly already possible for json. Although escaping is a major issue. For things like a double quote. This is what I have:
Thank you for doing this!
Unfortunately I can't take it any further as there will need to be compiler support. Things like white space and quote escaping is just nasty right now.
 "License": "The MIT License (MIT)
Can you please consider the Boost license? It's what everything else in D uses. Having multiple licenses interleaved makes things much more complicated for corporate lawyers to adopt.
That was example output based upon Devisualization.Window:interfaces. Don't worry about it. I posted just so e.g. Andrei could take it further since I can't.
Dec 30 2014
prev sibling parent reply "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Tuesday, 30 December 2014 at 05:36:47 UTC, Andrei Alexandrescu 
wrote:
 That should be possible (probably after a few improvements). 
 I'm working on a few templates for alternate formats including 
 LaTeX, plain text, and well, now json. -- Andrei
Would it not be easier to just do a raw convert to XML and use XSLT to transform into other formats?
Dec 30 2014
next sibling parent reply Russel Winder via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 2014-12-30 at 13:08 +0000, via Digitalmars-d wrote:
 On Tuesday, 30 December 2014 at 05:36:47 UTC, Andrei Alexandrescu 
 wrote:
 That should be possible (probably after a few improvements).
 I'm working on a few templates for alternate formats including 
 LaTeX, plain text, and well, now json. -- Andrei
Would it not be easier to just do a raw convert to XML and use XSLT to transform into other formats?
And, of course, ASCIIDoc was invented to be a human usable input to such a tool chain. Though now with ASCIIDoctor there is a direct to PDF without using FOP or LaTeX. Markdown is inadequate for more than single page HTML, XeLaTeX is incorrectly disliked by far too many people, ReStructured Text is perceived to be Python specific,… ASCIIDoc wins. -- Russel. ============================================================================= Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel.winder ekiga.net 41 Buckmaster Road m: +44 7770 465 077 xmpp: russel winder.org.uk London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder
Dec 30 2014
next sibling parent reply "Mengu" <mengukagan gmail.com> writes:
On Tuesday, 30 December 2014 at 13:18:46 UTC, Russel Winder via 
Digitalmars-d wrote:
 On Tue, 2014-12-30 at 13:08 +0000, via Digitalmars-d wrote:
 On Tuesday, 30 December 2014 at 05:36:47 UTC, Andrei 
 Alexandrescu wrote:
 That should be possible (probably after a few improvements).
 I'm working on a few templates for alternate formats 
 including LaTeX, plain text, and well, now json. -- Andrei
Would it not be easier to just do a raw convert to XML and use XSLT to transform into other formats?
And, of course, ASCIIDoc was invented to be a human usable input to such a tool chain. Though now with ASCIIDoctor there is a direct to PDF without using FOP or LaTeX. Markdown is inadequate for more than single page HTML, XeLaTeX is incorrectly disliked by far too many people, ReStructured Text is perceived to be Python specific,… ASCIIDoc wins.
coming from Python, i'm in favour of rST, markdown and asciidoc.
Dec 30 2014
parent "Kiith-Sa" <kiithsacmp gmail.com> writes:
About that user experience:

http://forum.dlang.org/post/nyclgpfzpkzemgitfyza forum.dlang.org
Dec 30 2014
prev sibling parent "Joseph Rushton Wakeling" <joseph.wakeling webdrake.net> writes:
On Tuesday, 30 December 2014 at 13:18:46 UTC, Russel Winder via 
Digitalmars-d wrote:
 XeLaTeX is incorrectly disliked by far too many people
Remind me what makes XeLaTex distinct. I recall using it as a convenient way to allow (i) utf8 input and (ii) graphics of any kind (PNG, JPEG, PDF, EPS all mixed in one document), but I'm not sure I see its relevance here.
Dec 30 2014
prev sibling next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 13:08:28 +0000
via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On Tuesday, 30 December 2014 at 05:36:47 UTC, Andrei Alexandrescu=20
 wrote:
 That should be possible (probably after a few improvements).=20
 I'm working on a few templates for alternate formats including=20
 LaTeX, plain text, and well, now json. -- Andrei
=20 Would it not be easier to just do a raw convert to XML and use=20 XSLT to transform into other formats?
and drop Ddoc completely, as if it is required an external tool to get something readable, the whole point of built-in documentation generator is lost.
Dec 30 2014
prev sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Tue, 30 Dec 2014 13:18:05 +0000
Russel Winder via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 Markdown is inadequate for more than single page HTML
which is exactly what API reference documentation is! a list of functions with explanations, some samples and a brief overview. this is why markdown-like language is a good choice. stop writing Charles Dickens' novels in source code, please! ;-)
Dec 30 2014
parent Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/30/14 3:57 PM, ketmar via Digitalmars-d wrote:
 On Tue, 30 Dec 2014 13:18:05 +0000
 Russel Winder via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 Markdown is inadequate for more than single page HTML
which is exactly what API reference documentation is! a list of functions with explanations, some samples and a brief overview. this is why markdown-like language is a good choice. stop writing Charles Dickens' novels in source code, please! ;-)
Yes, exactly. If you need to add special HTML beyond what Markdown offers you, then you are doing it wrong. My question is: why D docs need more that the basics?
Dec 30 2014
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-30 06:13, Rikki Cattermole wrote:

 Hmm I have an idea.
 I wonder if I can get ddoc to generate json files.
You would still need to write the documentation in Ddoc, which is what we're complaining about. -- /Jacob Carlborg
Dec 31 2014
parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 4:23 a.m., Jacob Carlborg wrote:
 On 2014-12-30 06:13, Rikki Cattermole wrote:

 Hmm I have an idea.
 I wonder if I can get ddoc to generate json files.
You would still need to write the documentation in Ddoc, which is what we're complaining about.
I know. And btw currently ddoc cannot output json. I was considering some form of external tool that used e.g. DScanner to grab all the AST/comments and then parse them a little similar to DDoc just without the macros.
Dec 31 2014
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdan.org> writes:
Rikki Cattermole <alphaglosined gmail.com> wrote:
 On 1/01/2015 4:23 a.m., Jacob Carlborg wrote:
 On 2014-12-30 06:13, Rikki Cattermole wrote:
 
 Hmm I have an idea.
 I wonder if I can get ddoc to generate json files.
You would still need to write the documentation in Ddoc, which is what we're complaining about.
I know. And btw currently ddoc cannot output json.
If ddoc cannot generate json that's a bug in ddoc. -- Andrei
Dec 31 2014
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 3:51 PM, Rikki Cattermole wrote:
 On 1/01/2015 4:23 a.m., Jacob Carlborg wrote:
 On 2014-12-30 06:13, Rikki Cattermole wrote:

 Hmm I have an idea.
 I wonder if I can get ddoc to generate json files.
You would still need to write the documentation in Ddoc, which is what we're complaining about.
I know. And btw currently ddoc cannot output json.
Json generation should follow this mold: https://github.com/D-Programming-Language/dlang.org/pull/737 -- Andrei
Jan 01 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-01 00:51, Rikki Cattermole wrote:

 I know.
 And btw currently ddoc cannot output json.
 I was considering some form of external tool that used e.g. DScanner to
 grab all the AST/comments and then parse them a little similar to DDoc
 just without the macros.
You can already get the documentation when generating the JSON using the -X flag. That's how Ddox works, if I recall correctly. -- /Jacob Carlborg
Jan 02 2015
prev sibling parent "jklp" <jklp nowhere.fr> writes:
On Monday, 29 December 2014 at 19:49:11 UTC, Walter Bright wrote:
 On 12/29/2014 10:34 AM, jklp wrote:
 I like your sense of the compromise. DDoc is mostly usefull to 
 generate the doc
 as html but inside the sources, it's often **unreadable**. I 
 think that you know
 that documentation comments as markdow would be good but maybe 
 you're scared
 because of the consequences implied when rendering dlang.org 
 std reference and
 such things.
 And if both could live together ?

 If I had the power to do this, DDoc would be primilarly 
 'markdown' with
 optionally html and macros things allowed.
I don't care much for hybrids, they are confusing and ugly.
):
Dec 29 2014
prev sibling parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 29 December 2014 at 15:39, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 12/28/2014 8:44 AM, Kiith-Sa wrote:
 It depends on the function being documented. For 'downcase', such blocks
 are
 overkill;
After doing it both ways for a while, I'm pretty convinced they are not overkill even for trivial functions: 1. they lend an air of consistency and comfort to the reader 2. they provide an anchor for automated tools which can extract the information 3. without such a block, I've found that I (and others, of 'obvious' parameters which are actually not obvious at all. 4. a block can be styled in a custom manner
I'm super happy to hear this :)
Dec 29 2014
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2014-12-28 16:57, Ary Borenszweig wrote:

 After programming in Ruby for a long time (and I think in Python it's
 the same) I came to the conclusion that all the sections (Return,
 Params, Example) just make writing the documentation a harder task. For
 example:

 ~~~
 /*
   * Returns a lowered-case version of a string.
   *
   * Params:
   *   - x: the string to be lowered case
   * Return: the string in lower cases
   */
 string lowercase(string x)
 ~~~

 It's kind of redundant. True, there might be something more to say about
 the parameters or the return value, but if you are reading the
 documentation then you might as well read a whole paragraph explaining
 everything about it.

 For example, this is the documentation for the String#downcase method in
 Ruby:

 ~~~
 def downcase(str)

 Returns a copy of `str` with all uppercase letters replaced with their
 lowercase counterparts. The operation is locale insensitive—only
 characters “A” to “Z” are affected. Note: case replacement is effective
 only in ASCII region.


 ~~~

 Note how the documentation directly mentions the parameters. There's
 also an example snippet there, that is denoted by indenting code
 (similar to Markdown).
I've never liked that. I usual write my documentation in Yardoc [1]. It's quite similar to JavaDoc, with special tags like return and param. It's a lot more expressive, like automatically creates links (like you're suggesting below), supports adding types to parameters and return values. Yardoc is also used for all (most) gems on rubygems.org.
 I think it would be much better to use Markdown for the documentation,
 as it is so popular and easy to read (although not that easy to parse).
Agree.
 Then it would be awesome if the documentation could be smarter,
 providing semi-automatic links. For example writing "#string.join" would
 create a link to that function in that module (the $(XREF ...) is very
 noisy and verbose).
I completely agree. I've complained about this several times. Also, if I recall correctly, XREF only works with one package, not with nested packages. [1] http://yardoc.org/ -- /Jacob Carlborg
Dec 28 2014
prev sibling next sibling parent "uri" <uri.grill gmail.com> writes:
On Sunday, 28 December 2014 at 15:57:39 UTC, Ary Borenszweig 
wrote:
 After programming in Ruby for a long time (and I think in 
 Python it's the same) I came to the conclusion that all the 
 sections (Return, Params, Example) just make writing the 
 documentation a harder task. For example:

 ~~~
 /*
  * Returns a lowered-case version of a string.
  *
  * Params:
  *   - x: the string to be lowered case
  * Return: the string in lower cases
  */
 string lowercase(string x)
 ~~~

 It's kind of redundant. True, there might be something more to 
 say about the parameters or the return value, but if you are 
 reading the documentation then you might as well read a whole 
 paragraph explaining everything about it.
-1 Most of the time I know what the function does but I need the docs for the parameters and types.
 For example, this is the documentation for the String#downcase 
 method in Ruby:

 ~~~
 def downcase(str)

 Returns a copy of `str` with all uppercase letters replaced 
 with their lowercase counterparts. The operation is locale 
 insensitive—only characters “A” to “Z” are affected. Note: case 
 replacement is effective only in ASCII region.


 ~~~

 Note how the documentation directly mentions the parameters. 
 There's also an example snippet there, that is denoted by 
 indenting code (similar to Markdown).
Again, I don't want to wade through a wall of text just to get the parameter types or what a function returns. The signature itself is too noise IMO so explicit Return & Param sections are preferable IMO. I'd also like to see TemplateParms: or TemplateTraits:, as others have already mentioned.
 I think it would be much better to use Markdown for the 
 documentation, as it is so popular and easy to read (although 
 not that easy to parse).
DDoc is not hard to read or write so Markdown would be wasted effort. If DDoc generated Markdown that might be useful for the WIKI.
 Then it would be awesome if the documentation could be smarter, 
 providing semi-automatic links. For example writing 
 "#string.join" would create a link to that function in that 
 module (the $(XREF ...) is very noisy and verbose).
+1 I agree links to functions would be much simpler with a #tag. Cheers, uri
Dec 28 2014
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/28/2014 7:57 AM, Ary Borenszweig wrote:
 I think it would be much better to use Markdown for the documentation, as it is
 so popular and easy to read (although not that easy to parse).
I don't want to use Markdown. The D wiki uses it, and once you step outside of the trivial, you have to insert html that is crippled in various erratic ways. Any non-trivial documentation winds up being one ugly mo-fo.
 Then it would be awesome if the documentation could be smarter, providing
 semi-automatic links. For example writing "#string.join" would create a link to
 that function in that module (the $(XREF ...) is very noisy and verbose).
$(XREF string, join) #string.join Sorry, I don't see a big issue. Trouble with the latter, of course, is what escape mechanism. And then special syntax for every markup element. Bleh, I don't think there's a net improvement.
Dec 28 2014
parent Jacob Carlborg <doob me.com> writes:
On 2014-12-29 01:45, Walter Bright wrote:

 I don't want to use Markdown. The D wiki uses it, and once you step
 outside of the trivial, you have to insert html that is crippled in
 various erratic ways. Any non-trivial documentation winds up being one
 ugly mo-fo.
I does not use Markdown.
 $(XREF string, join)
 #string.join

 Sorry, I don't see a big issue. Trouble with the latter, of course, is

 some sort of escape mechanism. And then special syntax for every markup
 element. Bleh, I don't think there's a net improvement.
XREF only work for one level of package. -- /Jacob Carlborg
Dec 29 2014
prev sibling next sibling parent reply Nick Treleaven <ntrel-pub mybtinternet.com> writes:
On 28/12/2014 01:00, Walter Bright wrote:
 This is so bad there isn't even a direct link to it
With newer dmd, there should be - I get ".encode.4" as the anchor name. Thanks for merging that pull BTW. But for some reason codePoints and codeUnits are in between .encode.3 and .encode.4!
Dec 28 2014
parent Nick Treleaven <ntrel-pub mybtinternet.com> writes:
On 28/12/2014 17:11, Nick Treleaven wrote:
 But for some reason codePoints and codeUnits are in between .encode.3
 and .encode.4!
I made a start on fixing Walter's points, and fixed the above: https://github.com/D-Programming-Language/phobos/pull/2825
Dec 30 2014
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Sat, Dec 27, 2014 at 05:00:00PM -0800, Walter Bright via Digitalmars-d wrote:
 This is so bad there isn't even a direct link to it, it hides in
 shame. Just go here:
 

 
 and scroll up one entry. Here it is:
 
    size_t encode(Tgt, Src, R)(in Src[] s, R range);
 
    Encodes c in units of type E and writes the result to the output
    range R.  Returns the number of Es written.
 
 Let me enumerate the awesomeness of its awfulness:
 
 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
There's a related bug that limits the usefulness of Params blocks: https://issues.dlang.org/show_bug.cgi?id=13270 On another note, the wall-of-text-function-signature complaint that people have voiced can be solved with: https://issues.dlang.org/show_bug.cgi?id=13676 I'll take a stab at this sometime in the near future, but before putting too much time into it, I'd like to know, is this the right direction to go? Will it be approved? There's also a minor cosmetic issue with template ddocs: https://issues.dlang.org/show_bug.cgi?id=13272 T -- Why waste time learning, when ignorance is instantaneous? -- Hobbes, from Calvin & Hobbes
Dec 29 2014
prev sibling next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 28/12/14 02:00, Walter Bright via Digitalmars-d wrote:
 Anyone want to take this on? There's a lot of stuff like this in Phobos. It's
 too much for one person to tackle, but if each of us just pick a function here
 and there, we can crowdsource and improve things greatly.
Just been having a play with documenting Params/Returns for the free functions in std.random. A number of issues encountered. First, it looks like the build system has changed since I last tried building docs. If I go with 'make html' in my local phobos branch, the various html files generated are all empty -- with their content seemingly intended to be filled by javascript which doesn't work. What gives? :-( Second and more importantly, I ran into some tricky cases implementing Params: lists for functions that have multiple overloads with different parameter lists. As things are, it's convenient -- in terms of reading the code -- to have different functions ordered from simple to complex signatures, with one documentation block for the first, and everything else sharing the same documentation using /// ditto. However, this won't work with a Params: list because ddoc attempts to match listed parameters to those of the immediately following function signature. Trivial example: /** * Params: * rng = (optional) random number generator to use; * if not specified, defaults to $(D rndGen) * * Returns: * Floating-point random variate of type $(D T) drawn from the uniform * distribution across the half-open interval [0, 1$(RPAREN). */ T uniform01(T = double)() if (isFloatingPoint!T) { return uniform01!T(rndGen); } /// ditto T uniform01(T = double, UniformRNG)(ref UniformRNG rng) if (isFloatingPoint!T && isUniformRNG!UniformRNG) out (result) { assert(0 <= result); assert(result < 1); } body { ... } The above will generate a warning because, of course, the first function signature doesn't have a parameter 'rng'. Since docs are compiled with -w, I believe this will result in an error ... ? In the above case, of course, it's trivial just to swap the order of the functions, but in general this is not the case, and it's rather irritating to have to tweak everything so that functions are listed in order of complex-to-simple signatures rather than simple-to-complex. It's also not clear to me that one can in general avoid cases where there is a group of functions, all doing the same thing, where nevertheless there is no single function signature accepting all the possible parameters; and yet, it's still very convenient to group together the documentation of those function signatures.
Dec 31 2014
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 The above will generate a warning because, of course, the first function
 signature doesn't have a parameter 'rng'.  Since docs are compiled with -w, I
 believe this will result in an error ... ?
I know, I don't care for that warning, which was added fairly recently.
Dec 31 2014
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 First, it looks like the build system has changed since I last tried
 building docs.  If I go with 'make html' in my local phobos branch, the
 various html files generated are all empty -- with their content
 seemingly intended to be filled by javascript which doesn't work.  What
 gives? :-(
Not sure. That should work, no js no nothing. -- Andrei
Dec 31 2014
next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 03:57:32PM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/31/14 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
First, it looks like the build system has changed since I last tried
building docs.  If I go with 'make html' in my local phobos branch,
the various html files generated are all empty -- with their content
seemingly intended to be filled by javascript which doesn't work.
What gives? :-(
Not sure. That should work, no js no nothing. -- Andrei
I'm seeing this problem as well, after updating to the latest dlang.org and phobos repos. Now I can't work on any ddoc PR's, 'cos I can't see the results anymore. :-( T -- I've been around long enough to have seen an endless parade of magic new techniques du jour, most of which purport to remove the necessity of thought about your programming problem. In the end they wind up contributing one or two pieces to the collective wisdom, and fade away in the rearview mirror. -- Walter Bright
Dec 31 2014
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 04:01:14PM -0800, H. S. Teoh via Digitalmars-d wrote:
 On Wed, Dec 31, 2014 at 03:57:32PM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 On 12/31/14 5:50 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
First, it looks like the build system has changed since I last tried
building docs.  If I go with 'make html' in my local phobos branch,
the various html files generated are all empty -- with their content
seemingly intended to be filled by javascript which doesn't work.
What gives? :-(
Not sure. That should work, no js no nothing. -- Andrei
I'm seeing this problem as well, after updating to the latest dlang.org and phobos repos. Now I can't work on any ddoc PR's, 'cos I can't see the results anymore. :-(
git bisect on dlang.org revealed that the problem is caused by commit 8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84. jump-to anchors I *did* say that this change would be problematic, but was summarily ignored. >:-( T -- One Word to write them all, One Access to find them, One Excel to count them all, And thus to Windows bind them. -- Mike Champion
Dec 31 2014
prev sibling next sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 01:42, H. S. Teoh via Digitalmars-d wrote:
 git bisect on dlang.org revealed that the problem is caused by commit
 8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84.


jump-to anchors

 I *did* say that this change would be problematic, but was summarily
 ignored. >:-(
Ouch, nasty. :-( Any chance this could be reverted short-term until it's resolved properly?
Dec 31 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 01, 2015 at 01:56:43AM +0100, Joseph Rushton Wakeling via
Digitalmars-d wrote:
 On 01/01/15 01:42, H. S. Teoh via Digitalmars-d wrote:
git bisect on dlang.org revealed that the problem is caused by commit
8d74f3292d5cdb2c6dc14dfea679c1017c0c6b84.


jump-to anchors

I *did* say that this change would be problematic, but was summarily
ignored. >:-(
Ouch, nasty. :-( Any chance this could be reverted short-term until it's resolved properly?
I tried reverting on github but it failed because it conflicts with later commits. :-( You *could* just `git checkout fbc73d2d78e6b51ebb92aac1a602fbfc48888dde` to get an older version of dlang.org that doesn't have that change; that should temporarily make things work again until we figure out how to clean up this mess. (And btw, while troubleshooting this, I ran into a totally nasty dependency problem in phobos/posix.mak where somehow it gets into a bad state where it stops rebuilding .html files, and attempting to clean those files will cause make to start aborting with "No rule to build index.html needed by rule `html`" for no discernible reason. Talk about non-reproducible builds... I hate make soooooo much right now. :-/ I've yet to locate the cause of this problem, it's an unpleasant task trying to wade through the layers of make macro hacks in posix.mak to figure out what went wrong.) T -- "You are a very disagreeable person." "NO."
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 5:07 PM, H. S. Teoh via Digitalmars-d wrote:
 I've yet to locate the cause of this problem, it's an unpleasant task trying
 to wade through the layers of make macro hacks in posix.mak to figure
 out what went wrong.)
I'm not sympathetic because everyone hated my straightforward (but voluminous) makefiles and changed them to what you see now.
Jan 04 2015
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Sun, Jan 04, 2015 at 08:56:28PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/31/2014 5:07 PM, H. S. Teoh via Digitalmars-d wrote:
I've yet to locate the cause of this problem, it's an unpleasant task
trying to wade through the layers of make macro hacks in posix.mak to
figure out what went wrong.)
I'm not sympathetic because everyone hated my straightforward (but voluminous) makefiles and changed them to what you see now.
Yet another nail in the long-overdue coffin of make. T -- Winners never quit, quitters never win. But those who never quit AND never win are idiots.
Jan 04 2015
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 02:50:34PM +0100, Joseph Rushton Wakeling via
Digitalmars-d wrote:
[...]
 Second and more importantly, I ran into some tricky cases implementing
 Params: lists for functions that have multiple overloads with
 different parameter lists.  As things are, it's convenient -- in terms
 of reading the code -- to have different functions ordered from simple
 to complex signatures, with one documentation block for the first, and
 everything else sharing the same documentation using /// ditto.
 However, this won't work with a Params: list because ddoc attempts to
 match listed parameters to those of the immediately following function
 signature.
This is a known issue: https://issues.dlang.org/show_bug.cgi?id=13270 T -- Some ideas are so stupid that only intellectuals could believe them. -- George Orwell
Dec 31 2014
prev sibling next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote:
 This is a known issue:

 	https://issues.dlang.org/show_bug.cgi?id=13270
Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now?
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote:
 This is a known issue:

     https://issues.dlang.org/show_bug.cgi?id=13270
Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now?
Just ignore the warning.
Dec 31 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote:
This is a known issue:

    https://issues.dlang.org/show_bug.cgi?id=13270
Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now?
Just ignore the warning.
Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name). T -- If it breaks, you get to keep both pieces. -- Software disclaimer notice
Dec 31 2014
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 1:19 PM, H. S. Teoh via Digitalmars-d wrote:
 On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d
wrote:
 On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote:
 This is a known issue:

     https://issues.dlang.org/show_bug.cgi?id=13270
Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now?
Just ignore the warning.
Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name).
You can, of course, occasionally look at the warnings :-)
Dec 31 2014
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 01:26:50PM -0800, Walter Bright via Digitalmars-d wrote:
 On 12/31/2014 1:19 PM, H. S. Teoh via Digitalmars-d wrote:
On Wed, Dec 31, 2014 at 12:57:36PM -0800, Walter Bright via Digitalmars-d wrote:
On 12/31/2014 7:36 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
On 31/12/14 16:00, H. S. Teoh via Digitalmars-d wrote:
This is a known issue:

    https://issues.dlang.org/show_bug.cgi?id=13270
Good to know. Any preferences for proceeding with this? Put in place the params even allowing for the bug, or just avoid the problem params for now?
Just ignore the warning.
Which causes non-existent parameters to slip through (e.g., if you mistyped a parameter name).
You can, of course, occasionally look at the warnings :-)
Of course. But it would be nice if this wasn't necessary in the first place. :-) Yes, yes, I know, where's the PR... I'll get to it! This week just isn't a good time for that, too many things going on IRL. I'm planning to submit some ddoc-related PRs in the near future; it would be a good time to fold this one in too. T -- Famous last words: I *think* this will work...
Dec 31 2014
prev sibling next sibling parent Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/27/14 10:00 PM, Walter Bright wrote:
 This is so bad there isn't even a direct link to it, it hides in shame.
 Just go here:



 and scroll up one entry. Here it is:

     size_t encode(Tgt, Src, R)(in Src[] s, R range);

     Encodes c in units of type E and writes the result to the output
 range R.
     Returns the number of Es written.

 Let me enumerate the awesomeness of its awfulness:

 1. No 'Return:' block, though it obviously returns a value.
 2. No 'Params:' block, though it obviously has parameters.
 3. No 'Example:' block
 4. No comparison with other 'encode' functions in the same module.
 5. No description of what 'Tgt' is.
 6. No description of what 'Src' is.
 7. No clue where the variable 'c' comes from.
 8. No clue where the type 'E' comes from.
 9. 'R' is a type, not an instance.
 10. I suspect it has something to do with UTF encodings, but there is no
 clue.
This one is missing some docs too: http://dlang.org/phobos/std_math.html#abs
Dec 31 2014
prev sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31/12/14 14:50, Joseph Rushton Wakeling via Digitalmars-d wrote:
 Second and more importantly, I ran into some tricky cases implementing Params:
 lists for functions that have multiple overloads with different parameter
lists.
Slightly more subtle variant of same: if the first, documented code is a struct or class definition, and the /// ditto'd code blocks are factory functions to generate instances of that code, you get the same warnings, and it means that _none_ of the parameters will have type info attached. (Encountered with e.g. randomCover and randomSample.) On the bright side, PR is in :-) https://github.com/D-Programming-Language/phobos/pull/2831
Jan 01 2015