www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Improving ddoc

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Hello,


In wake of the recent discussions on improving ddoc syntax we're looking 
at doing something about it. Please discuss any ideas you might have 
here. Thanks!

One simple starter would be to allow one escape character, e.g. the 
backtick (`), as a simple way to expand macros: instead of $(MACRO arg1, 
arg2) one can write `MACRO arg1, arg2`.


Andrei
Dec 31 2014
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 Hello,
 
 In wake of the recent discussions on improving ddoc syntax we're
 looking at doing something about it. Please discuss any ideas you
 might have here.  Thanks!
 
 One simple starter would be to allow one escape character, e.g. the
 backtick (`), as a simple way to expand macros: instead of $(MACRO
 arg1, arg2) one can write `MACRO arg1, arg2`.
[...] The problem with using only a single escape character is that it's ambiguous when nested. If you write `X`Y`Z`, should it be interpreted as $(X $(Y)) or $(X)Y$(Z)? Also, the people complaining about $(MACRO ...)) syntax aren't complaining about the $(...) part specifically, but about the MACRO part. No matter how you try to prettify it, $(MACRO x y z) is still `MACRO x y z`. As long as you have a single syntax for all macros, the syntax people won't be happy. What they are clamoring for is dedicated syntax for the most common macros, so that they don't have to keep repeating the MACRO part of the invocation. Besides, ddoc syntax is really the least of our problems right now, what with functionality issues like: https://issues.dlang.org/show_bug.cgi?id=9731 https://issues.dlang.org/show_bug.cgi?id=13270 https://issues.dlang.org/show_bug.cgi?id=13272 https://issues.dlang.org/show_bug.cgi?id=13676 just to name a few. Everyone wants a new coffee machine but nobody cares about nuclear reactor usability issues. T -- Music critic: "That's an imitation fugue!"
Dec 31 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 12:30 PM, H. S. Teoh via Digitalmars-d wrote:
 On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 The problem with using only a single escape character is that it's
 ambiguous when nested. If you write `X`Y`Z`, should it be interpreted as
 $(X $(Y)) or $(X)Y$(Z)?
That issue is fairly obvious, as is its solution - backticks (or whichever escape) don't nest; for nesting use the full syntax. Just like bash/zsh.
 Also, the people complaining about $(MACRO ...)) syntax aren't
 complaining about the $(...) part specifically, but about the MACRO
 part. No matter how you try to prettify it, $(MACRO x y z) is still
 `MACRO x y z`. As long as you have a single syntax for all macros, the
 syntax people won't be happy. What they are clamoring for is dedicated
 syntax for the most common macros, so that they don't have to keep
 repeating the MACRO part of the invocation.
That's a bit of a bummer because that seems a slippery slope to me. But I guess we could standardize on markdown syntax.
 Besides, ddoc syntax is really the least of our problems right now, what
 with functionality issues like:

 	https://issues.dlang.org/show_bug.cgi?id=9731
 	https://issues.dlang.org/show_bug.cgi?id=13270
 	https://issues.dlang.org/show_bug.cgi?id=13272
 	https://issues.dlang.org/show_bug.cgi?id=13676

 just to name a few. Everyone wants a new coffee machine but nobody cares
 about nuclear reactor usability issues.
That's a very good point. Andrei
Dec 31 2014
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Dec 31, 2014 at 06:27:30PM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/31/14 12:30 PM, H. S. Teoh via Digitalmars-d wrote:
On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
The problem with using only a single escape character is that it's
ambiguous when nested. If you write `X`Y`Z`, should it be interpreted
as $(X $(Y)) or $(X)Y$(Z)?
That issue is fairly obvious, as is its solution - backticks (or whichever escape) don't nest; for nesting use the full syntax. Just like bash/zsh.
So there will be two syntaxes for the same thing in the non-nested case then?
Also, the people complaining about $(MACRO ...)) syntax aren't
complaining about the $(...) part specifically, but about the MACRO
part. No matter how you try to prettify it, $(MACRO x y z) is still
`MACRO x y z`. As long as you have a single syntax for all macros,
the syntax people won't be happy. What they are clamoring for is
dedicated syntax for the most common macros, so that they don't have
to keep repeating the MACRO part of the invocation.
That's a bit of a bummer because that seems a slippery slope to me. But I guess we could standardize on markdown syntax.
Unfortunately it seems Walter is against it. But on a deeper note, perhaps the issue isn't really ddoc syntax per se, but the fact that doc comments can *only* be processed by ddoc. If there was a way to get the raw text out, the people who dislike ddoc can pipe it to the formatter of their own choice, and they would be happy. People who are indifferent will get ddoc by default, which, despite its flaws, isn't really *that* horrible. T -- Why is it that all of the instruments seeking intelligent life in the universe are pointed away from Earth? -- Michael Beibl
Dec 31 2014
next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 02:43:39 UTC, H. S. Teoh via 
Digitalmars-d wrote:
 But on a deeper note, perhaps the issue isn't really ddoc 
 syntax per se, but the fact that doc comments can *only* be
 processed by ddoc. If there was a way to get the raw text out
There is a way: dmd -D -X gets the raw text into the .json file. That's what my dpldocs.info scans: http://dpldocs.info/std.algorithm (which is, sadly, pretty illegible for the Phobos docs, but it works for my files e.g. http://dpldocs.info/search/search2?searchTerm=arsd.dom.Element.getElementsBySelector
Dec 31 2014
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdan.org> writes:
"H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> wrote:
 On Wed, Dec 31, 2014 at 06:27:30PM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 On 12/31/14 12:30 PM, H. S. Teoh via Digitalmars-d wrote:
 On Wed, Dec 31, 2014 at 11:50:51AM -0800, Andrei Alexandrescu via
Digitalmars-d wrote:
 The problem with using only a single escape character is that it's
 ambiguous when nested. If you write `X`Y`Z`, should it be interpreted
 as $(X $(Y)) or $(X)Y$(Z)?
That issue is fairly obvious, as is its solution - backticks (or whichever escape) don't nest; for nesting use the full syntax. Just like bash/zsh.
So there will be two syntaxes for the same thing in the non-nested case then?
 Also, the people complaining about $(MACRO ...)) syntax aren't
 complaining about the $(...) part specifically, but about the MACRO
 part. No matter how you try to prettify it, $(MACRO x y z) is still
 `MACRO x y z`. As long as you have a single syntax for all macros,
 the syntax people won't be happy. What they are clamoring for is
 dedicated syntax for the most common macros, so that they don't have
 to keep repeating the MACRO part of the invocation.
That's a bit of a bummer because that seems a slippery slope to me. But I guess we could standardize on markdown syntax.
Unfortunately it seems Walter is against it.
One at a time :)
 But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
 but the fact that doc comments can *only* be processed by ddoc. If there
 was a way to get the raw text out, the people who dislike ddoc can pipe
 it to the formatter of their own choice, and they would be happy. People
 who are indifferent will get ddoc by default, which, despite its flaws,
 isn't really *that* horrible.
That's pretty much the very charter of ddoc- most misunderstood tool ever. Luckily I'll send some pull requests that simplify generation - some time next year :o)
Dec 31 2014
parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote:
 But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
 but the fact that doc comments can *only* be processed by ddoc. If there
 was a way to get the raw text out, the people who dislike ddoc can pipe
 it to the formatter of their own choice, and they would be happy. People
 who are indifferent will get ddoc by default, which, despite its flaws,
 isn't really *that* horrible.
That's pretty much the very charter of ddoc- most misunderstood tool ever. Luckily I'll send some pull requests that simplify generation - some time next year :o)
My problem is very much the opposite: it's not that only ddoc can process ddoc syntax, it's that raw ddoc syntax is, often, not very human-readable. For me it's very important that the documentation should be trivially comprehensible _when browsing source code_, and too often Ddoc markup prevents that.
Jan 01 2015
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 2:10 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 01/01/15 05:48, Andrei Alexandrescu via Digitalmars-d wrote:
 But on a deeper note, perhaps the issue isn't really ddoc syntax per se,
 but the fact that doc comments can *only* be processed by ddoc. If there
 was a way to get the raw text out, the people who dislike ddoc can pipe
 it to the formatter of their own choice, and they would be happy. People
 who are indifferent will get ddoc by default, which, despite its flaws,
 isn't really *that* horrible.
That's pretty much the very charter of ddoc- most misunderstood tool ever. Luckily I'll send some pull requests that simplify generation - some time next year :o)
My problem is very much the opposite: it's not that only ddoc can process ddoc syntax, it's that raw ddoc syntax is, often, not very human-readable. For me it's very important that the documentation should be trivially comprehensible _when browsing source code_, and too often Ddoc markup prevents that.
Got it. I think auto-macroizing would help with that. -- Andrei
Jan 01 2015
prev sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
 My problem is very much the opposite: it's not that only ddoc 
 can process ddoc syntax, it's that raw ddoc syntax is, often, 
 not very human-readable.
Yeah. The enormous irony is the #1 ddoc justification - and one of the big reasons doxygen or xml wasn't used IIRC - is 1. It looks good as embedded documentation, not just after it is extracted and processed. 2. It's easy and natural to write, i.e. minimal reliance on <tags> and other clumsy forms one would never see in a finished document. http://dlang.org/ddoc.html blargh :(
Jan 01 2015
parent reply "ponce" <contact gam3sfrommars.fr> writes:
On Thursday, 1 January 2015 at 14:16:05 UTC, Adam D. Ruppe wrote:
 On Thursday, 1 January 2015 at 10:10:53 UTC, Joseph Rushton 
 Wakeling via Digitalmars-d wrote:
 My problem is very much the opposite: it's not that only ddoc 
 can process ddoc syntax, it's that raw ddoc syntax is, often, 
 not very human-readable.
Yeah. The enormous irony is the #1 ddoc justification - and one of the big reasons doxygen or xml wasn't used IIRC - is 1. It looks good as embedded documentation, not just after it is extracted and processed. 2. It's easy and natural to write, i.e. minimal reliance on <tags> and other clumsy forms one would never see in a finished document. http://dlang.org/ddoc.html blargh :(
I actually like DDoc as it is, and finds it readable. Markdown is readable and all but the specifications are just insane. http://commonmark.org/
Jan 01 2015
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote:
 I actually like DDoc as it is, and finds it readable.
You know, if $(D_CODE) escaped the code properly and `code` was a shortcut to it... that'd actually solve my big complaints with the ddoc language itself and make it convenient. Really, those are the two things I want, I don't really care about the rest of the argument. Maybe it is PR time.
Jan 01 2015
parent "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 14:37:31 UTC, Adam D. Ruppe wrote:
 On Thursday, 1 January 2015 at 14:22:19 UTC, ponce wrote:
 I actually like DDoc as it is, and finds it readable.
You know, if $(D_CODE) escaped the code properly and `code` was a shortcut to it... that'd actually solve my big complaints with the ddoc language itself and make it convenient.
For a preview how this might look like: perl -p -e 's/\$\(D ([^\$()]*+(\((?:[^\$()]*+|(?1))*\))*[^\$()]*)\)/`$1`/g' std/algorithm.d | less
Jan 01 2015
prev sibling next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Wednesday, 31 December 2014 at 19:50:49 UTC, Andrei 
Alexandrescu wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax 
 we're looking at doing something about it. Please discuss any 
 ideas you might have here. Thanks!

 One simple starter would be to allow one escape character, e.g. 
 the backtick (`), as a simple way to expand macros: instead of 
 $(MACRO arg1, arg2) one can write `MACRO arg1, arg2`.


 Andrei
My biggest issue with DDOC compared to popular stuff like Markdown / ReStructured Text : it doesn't look nice as a source. Markdown is so cute because it mimics the style of ASCII-based text file formatting. DDOC is naturally very verbose because of all $(MACRO stuff) and lack of basic primitives for most common needs. I don't feel like any small change in DDOC will make me like/use it.
Dec 31 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 1:12 PM, Dicebot wrote:
 I don't feel like any small change in DDOC will make me like/use it.
I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: `hello world` --> $(BACKQUOTED hello world) "hello world" --> $(QUOTED hello world) 'hello world' --> $(SQUOTED hello world) _hello world_ --> $(UNDERLINED hello world) *hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately. Andrei
Jan 01 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:
 On 12/31/14 1:12 PM, Dicebot wrote:
 I don't feel like any small change in DDOC will make me like/use it.
I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: `hello world` --> $(BACKQUOTED hello world) "hello world" --> $(QUOTED hello world) 'hello world' --> $(SQUOTED hello world) _hello world_ --> $(UNDERLINED hello world) *hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately.
" and ` naturally come in pairs, but *, _ and ' do not.
Jan 01 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 1:39 AM, Walter Bright wrote:
 On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:
 On 12/31/14 1:12 PM, Dicebot wrote:
 I don't feel like any small change in DDOC will make me like/use it.
I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: `hello world` --> $(BACKQUOTED hello world) "hello world" --> $(QUOTED hello world) 'hello world' --> $(SQUOTED hello world) _hello world_ --> $(UNDERLINED hello world) *hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately.
" and ` naturally come in pairs, but *, _ and ' do not.
Stars and underlines are popular due to markdown. There'd be limitations, e.g. pairs occurring across a ddoc parent won't be considered for expansion etc. Also the defaults can be written to be idempotent. (Below I am removing the single quote because indeed it's not fitting): BACKQUOTED=`$0` QUOTED="$0" UNDERLINED=_$0_ STARRED=*$0* So essentially we get to start 100% backward compatible and figure out under what circumstances the macros expand. I think we can get this working. Andrei
Jan 01 2015
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 01:47:27 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 Stars and underlines are popular due to markdown.
we were using that long before markdown was invented. FIDOnet, newsgroups with UUCP, you name it.
Jan 01 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote:
 Stars and underlines are popular due to markdown. There'd be limitations, e.g.
 pairs occurring across a ddoc parent won't be considered for expansion etc.
Also
 the defaults can be written to be idempotent. (Below I am removing the single
 quote because indeed it's not fitting):

 BACKQUOTED=`$0`
 QUOTED="$0"
 UNDERLINED=_$0_
 STARRED=*$0*

 So essentially we get to start 100% backward compatible and figure out under
 what circumstances the macros expand. I think we can get this working.
Ddoc assumes ( ) nests. But this would require that these characters nest, too: *abc_def * _i for example, which is stretching things a bit because they do not naturally nest.
Jan 01 2015
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 11:33:25 UTC, Walter Bright wrote:
 Ddoc assumes ( ) nests. But this would require that these 
 characters nest, too:

    *abc_def * _i

 for example, which is stretching things a bit because they do 
 not naturally nest.
I think someone who writes *long bold text like this* is in error anyway; I lose track of what those stars are supposed to me. (BTW the gmail html to text converter does this, making emails unreadable to me!) I would say the pattern to match would be \w\*[a-zA-Z0-9]+\*\w. Honestly, I think _foo_ and /foo/ are both not worth supporting in this context. *bold* is the only one we really need - the most common, and the least ambiguous. We do NOT want it to think *a = *b; is supposed to be bolding. We do NOT want it to think _object._method is supposed to be underlined. We do NOT want it to think /bin/bash is supposed to be italic. (Granted, those might be in code blocks anyway, but still, no point making this harder than it has to be.) But when would you write *a* = foo in code? Never, I don't think that's ever valid. So making that a $(STARRED) macro should just work in pretty much all circumstances. And we can always fall back on $(B bold) and $(I italic) when we do need them. I just think shooting for an 80% solution is more reasonable than a 99 or 100% solution - just do the easiest, least ambiguous shortcuts and use macros for the rest of them. It'll probably go a LONG way. Again those are: *bold* and `code`.
Jan 01 2015
next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
 Again those are: *bold* and `code`.
I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`;
Jan 01 2015
next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
 I would be inclined to prefer ``code`` or ```code```, simply 
 because it's valid D syntax to have,

     auto someString = `Some great big string`;
Eh, that breaks my habit from stack overflow. How often do you write an inline `raw string` anyway? It'd still just work inside ---\ncode\n--- blocks, and you could still do $(D_CODE auto s = `code`;) if you wanted to.
Jan 01 2015
prev sibling parent reply "ponce" <contact gam3sfrommars.fr> writes:
On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
 On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
 Again those are: *bold* and `code`.
I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`;
Github, Stack Overflow, trac and others use one single escape quote.
Jan 01 2015
parent "Dicebot" <public dicebot.lv> writes:
On Thursday, 1 January 2015 at 15:21:40 UTC, ponce wrote:
 On Thursday, 1 January 2015 at 14:41:00 UTC, Joseph Rushton 
 Wakeling via Digitalmars-d wrote:
 On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
 Again those are: *bold* and `code`.
I would be inclined to prefer ``code`` or ```code```, simply because it's valid D syntax to have, auto someString = `Some great big string`;
Github, Stack Overflow, trac and others use one single escape quote.
And such snippet is much more likely to go into dedicated code block: ``` auto someString = `Some great big string`; ``` than as an inline snippet.
Jan 01 2015
prev sibling next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 15:40:30 +0100
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 On 01/01/15 15:26, Adam D. Ruppe via Digitalmars-d wrote:
 Again those are: *bold* and `code`.
=20 I would be inclined to prefer ``code`` or ```code```, simply because it's=
valid=20
 D syntax to have,
=20
      auto someString =3D `Some great big string`;
=20
i think that in most cases you can use `r"..."` instead. and if you really want backticks, you can use dedicated code block for that.
Jan 01 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-02 02:31, ketmar via Digitalmars-d wrote:

 i think that in most cases you can use `r"..."` instead. and if you
 really want backticks, you can use dedicated code block for that.
One really good use case for backticks is when the string contains double quotes. -- /Jacob Carlborg
Jan 02 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 6:26 AM, Adam D. Ruppe wrote:
 Honestly, I think _foo_ and /foo/ are both not worth supporting in this
 context. *bold* is the only one we really need - the most common, and
 the least ambiguous.
Maybe not even *bold*. Good documentation uses bold sparingly, and most uses of bold in dlang.org should actually be code. -- Andrei
Jan 02 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:06 AM, Andrei Alexandrescu wrote:
 Maybe not even *bold*. Good documentation uses bold sparingly, and most uses of
 bold in dlang.org should actually be code. -- Andrei
I agree. Excessive use of bold is like shouting at people - it's wearying to read. Pull any programming book off the shelf and flip through it. There's very little use of bold.
Jan 02 2015
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote:
 I agree. Excessive use of bold is like shouting at people - 
 it's wearying to read. Pull any programming book off the shelf 
 and flip through it. There's very little use of bold.
Aye, my opinion now is that `code` is the only really important one. I can live without the others. List, table, and link might be nice, but totally non-essential in my eyes; plain ASCII or recursive macros look good enough to me.
Jan 02 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:42 PM, Adam D. Ruppe wrote:
 On Friday, 2 January 2015 at 21:36:52 UTC, Walter Bright wrote:
 I agree. Excessive use of bold is like shouting at people - it's wearying to
 read. Pull any programming book off the shelf and flip through it. There's
 very little use of bold.
Aye, my opinion now is that `code` is the only really important one. I can live without the others. List, table, and link might be nice, but totally non-essential in my eyes; plain ASCII or recursive macros look good enough to me.
I agree. I was telling Andrei last night what a good idea you'd had.
Jan 02 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 3:32 AM, Walter Bright wrote:
 On 1/1/2015 1:47 AM, Andrei Alexandrescu wrote:
 Stars and underlines are popular due to markdown. There'd be
 limitations, e.g.
 pairs occurring across a ddoc parent won't be considered for expansion
 etc. Also
 the defaults can be written to be idempotent. (Below I am removing the
 single
 quote because indeed it's not fitting):

 BACKQUOTED=`$0`
 QUOTED="$0"
 UNDERLINED=_$0_
 STARRED=*$0*

 So essentially we get to start 100% backward compatible and figure out
 under
 what circumstances the macros expand. I think we can get this working.
Ddoc assumes ( ) nests. But this would require that these characters nest, too: *abc_def * _i for example, which is stretching things a bit because they do not naturally nest.
No nesting. Again I'm talking simple rules. They should get us a ton of mileage. -- Andrei
Jan 01 2015
prev sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/1/15 4:39 AM, Walter Bright wrote:
 On 1/1/2015 1:19 AM, Andrei Alexandrescu wrote:
 On 12/31/14 1:12 PM, Dicebot wrote:
 I don't feel like any small change in DDOC will make me like/use it.
I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: `hello world` --> $(BACKQUOTED hello world) "hello world" --> $(QUOTED hello world) 'hello world' --> $(SQUOTED hello world) _hello world_ --> $(UNDERLINED hello world) *hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately.
" and ` naturally come in pairs, but *, _ and ' do not.
What about #[{( anything inside here can use markdown )}]# I'm half joking about the brackets, but some method of saying "in here, I permit markdown" would make this both backwards compatible, and not inflict too much damage to readability of ddoc. In fact, if you did something like: /**[[ ... comments with markdown ]]*/ or something like this at the beginning of each ddoc comment, it would be almost unnoticeable. I'd also suggest giving a toggling mechanism, something like: /** $(MARKDOWN true/false) **/ Which allows one to set the default for the enclosed ddocs. That's my contribution to the project :) I wish I could actually code it... -Steve
Jan 02 2015
prev sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Thu, Jan 01, 2015 at 01:19:06AM -0800, Andrei Alexandrescu via Digitalmars-d
wrote:
 On 12/31/14 1:12 PM, Dicebot wrote:
I don't feel like any small change in DDOC will make me like/use it.
I'm envisioning quite an interesting possibility in which certain constructs are automatically converted to macros: `hello world` --> $(BACKQUOTED hello world) "hello world" --> $(QUOTED hello world) 'hello world' --> $(SQUOTED hello world) _hello world_ --> $(UNDERLINED hello world) *hello world* --> $(STARRED hello world) ... and such. Then generating nice formatting for each of these constructs is achieved by simply defining these macros appropriately.
[...] Nice idea, but I think _..._ will have to be left out, due to the prevalence of special meanings of _ currently in use. For example, _abc currently means "abc" without any automatic highlighting (e.g., if abc were a parameter or function name); _abc: at the beginning of a line means a literal word "abc" where otherwise abc: would mean a section heading "abc"; and abc_def: means a section heading with two words "abc def". I anticipate that overloading _ to do even more than this will only lead to a nasty mess where it's impossible for the non-expert to figure out what it actually means. T -- The early bird gets the worm. Moral: ewww...
Jan 01 2015
prev sibling next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 11:50:51 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 In wake of the recent discussions on improving ddoc syntax we're looking=
=20
 at doing something about it. Please discuss any ideas you might have=20
 here. Thanks!
ahem... kill it and use markdown instead.
Dec 31 2014
parent reply "Freddy" <Hexagonalstar64 gmail.com> writes:
On Wednesday, 31 December 2014 at 21:51:32 UTC, ketmar via 
Digitalmars-d wrote:
 On Wed, 31 Dec 2014 11:50:51 -0800
 Andrei Alexandrescu via Digitalmars-d 
 <digitalmars-d puremagic.com>
 wrote:

 In wake of the recent discussions on improving ddoc syntax 
 we're looking at doing something about it. Please discuss any 
 ideas you might have here. Thanks!
ahem... kill it and use markdown instead.
http://commonmark.org/
Dec 31 2014
next sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Wed, 31 Dec 2014 22:58:46 +0000
Freddy via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On Wednesday, 31 December 2014 at 21:51:32 UTC, ketmar via=20
 Digitalmars-d wrote:
 On Wed, 31 Dec 2014 11:50:51 -0800
 Andrei Alexandrescu via Digitalmars-d=20
 <digitalmars-d puremagic.com>
 wrote:

 In wake of the recent discussions on improving ddoc syntax=20
 we're looking at doing something about it. Please discuss any=20
 ideas you might have here. Thanks!
ahem... kill it and use markdown instead.
=20 http://commonmark.org/
ah, "markdown" here means "anything human-readable", be it markdown, textile, restructured, or something completely different. i don't really care, as long as it's not littered by visual noise.
Dec 31 2014
prev sibling next sibling parent reply Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 ah, "markdown" here means "anything human-readable", be it markdown,
 textile, restructured, or something completely different. i don't
 really care, as long as it's not littered by visual noise.
I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org, with the same (or close to) the generated output as the ddoc one, and then we can clearly see how the two compare and whether it's worth considering looking into. I personally agree the ddoc macro's can introduce a lot of visual noise.
Dec 31 2014
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Wednesday, 31 December 2014 at 23:14:33 UTC, Andrej Mitrovic 
via Digitalmars-d wrote:
 I think the best way to show the benefits of any of these 
 formatting syntax flavors is to actually write a sample 
 documentation page based on an existing one from 
 phobos/dlang.org
You might be able to do an automatic conversion even... either ddoc macros (LOL) or a html to text converter.
Dec 31 2014
prev sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 1 Jan 2015 00:14:23 +0100
Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 ah, "markdown" here means "anything human-readable", be it markdown,
 textile, restructured, or something completely different. i don't
 really care, as long as it's not littered by visual noise.
=20 I think the best way to show the benefits of any of these formatting syntax flavors is to actually write a sample documentation page based on an existing one from phobos/dlang.org, with the same (or close to) the generated output as the ddoc one, and then we can clearly see how the two compare and whether it's worth considering looking into. =20 I personally agree the ddoc macro's can introduce a lot of visual noise.
there is no sense in demonstrating anything, as Walter and Andrei seems to be sure that Ddoc is human-readable, and there's no much sense in changing it, as people should always generate html/TeX/other output, not trying to read the documentation right in .d files. anything less powerful than Ddoc will be rejected with arbitrary reason (see Walter posts about escaping in markdown, for example).
Dec 31 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdan.org> writes:
ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 On Thu, 1 Jan 2015 00:14:23 +0100 Andrej Mitrovic via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 
 On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 ah, "markdown" here means "anything human-readable", be it markdown,
 textile, restructured, or something completely different. i don't really
 care, as long as it's not littered by visual noise.
 
 I think the best way to show the benefits of any of these formatting
 syntax flavors is to actually write a sample documentation page based on
 an existing one from phobos/dlang.org, with the same (or close to) the
 generated output as the ddoc one, and then we can clearly see how the two
 compare and whether it's worth considering looking into.
 
 I personally agree the ddoc macro's can introduce a lot of visual noise.
 
 there is no sense in demonstrating anything, as Walter and Andrei seems
 to be sure that Ddoc is human-readable, and there's no much sense in
 changing it, as people should always generate html/TeX/other output, not
 trying to read the documentation right in .d files. anything less
 powerful than Ddoc will be rejected with arbitrary reason (see Walter
 posts about escaping in markdown, for example).
That's unfair. You wouldn't us to give in to emotional arguments that lack reason. Make good points and they'll be minded. -- Andrei
Dec 31 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 1 Jan 2015 05:50:18 +0000 (UTC)
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 That's unfair. You wouldn't us to give in to emotional arguments that lack
 reason. Make good points and they'll be minded. -- Andrei
"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 Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 10:00 PM, ketmar via Digitalmars-d wrote:
 On Thu, 1 Jan 2015 05:50:18 +0000 (UTC)
 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
 wrote:

 That's unfair. You wouldn't us to give in to emotional arguments that lack
 reason. Make good points and they'll be minded. -- Andrei
"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."
Sadly indeed that muffles any point you're trying to make around here. Time for a New Year Resolution? :o) -- Andrei
Jan 01 2015
prev sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 1 Jan 2015 05:50:18 +0000 (UTC)
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 On Thu, 1 Jan 2015 00:14:23 +0100 Andrej Mitrovic via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
=20
 On 1/1/15, ketmar via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 ah, "markdown" here means "anything human-readable", be it markdown,
 textile, restructured, or something completely different. i don't really
 care, as long as it's not littered by visual noise.
=20
 I think the best way to show the benefits of any of these formatting
 syntax flavors is to actually write a sample documentation page based on
 an existing one from phobos/dlang.org, with the same (or close to) the
 generated output as the ddoc one, and then we can clearly see how the t=
wo
 compare and whether it's worth considering looking into.
=20
 I personally agree the ddoc macro's can introduce a lot of visual noise.
=20
 there is no sense in demonstrating anything, as Walter and Andrei seems
 to be sure that Ddoc is human-readable, and there's no much sense in
 changing it, as people should always generate html/TeX/other output, not
 trying to read the documentation right in .d files. anything less
 powerful than Ddoc will be rejected with arbitrary reason (see Walter
 posts about escaping in markdown, for example).
=20 That's unfair. You wouldn't us to give in to emotional arguments that lack reason. Make good points and they'll be minded. -- Andrei
p.s. i already demonstrated excerpt from std.algorithm in that other topic. Walter says that i didn't bother to format Ddoc noise, not even reading my post about it till the end, where i told that there is no much sense in formatting Ddoc, as it will still be noise. so i will not even to try to do it again and again just to read the same answers again and again. about "that needs escaping too", about "we can't specify different fonts there" and so on. i wrote several times that Ddoc is reminding DTP, and it is not human-readable. i even shown the sample. seems that Walter is clearly missing the point of human-readable documentation (i think that he just don't care, as from his POV documentation must be preprocessed to standalone files, there's no reason to read it inside .d source; and he wants powerful preprocessor with DTP features). sorry about you, though, as you didn't seem to tell anything like that except some messages that (it seems) just trying to stop the flamefest. mea culpa.
Dec 31 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote:
 sorry about you, though, as you didn't seem to tell anything like that
 except some messages that (it seems) just trying to stop the flamefest.
 mea culpa.
It would be awesome indeed if the civil atmosphere in this forum would be restored. I very much hope in your help with this. -- Andrei
Jan 01 2015
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 01:30:58 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote:
 sorry about you, though, as you didn't seem to tell anything like that
 except some messages that (it seems) just trying to stop the flamefest.
 mea culpa.
=20 It would be awesome indeed if the civil atmosphere in this forum would=20 be restored. I very much hope in your help with this. -- Andrei
i'm trying to do my best. honestly! ;-) i'm deleting first two or three variants of many replies. so my answers looks perfectly calm for me... until i see them posted. yet i'll try to improve than situation in this year. maybe deleting first ten variants, i don't know... ;-)
Jan 01 2015
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 1/1/15 4:46 AM, ketmar via Digitalmars-d wrote:
 On Thu, 01 Jan 2015 01:30:58 -0800
 Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
 wrote:

 On 12/31/14 10:10 PM, ketmar via Digitalmars-d wrote:
 sorry about you, though, as you didn't seem to tell anything like that
 except some messages that (it seems) just trying to stop the flamefest.
 mea culpa.
It would be awesome indeed if the civil atmosphere in this forum would be restored. I very much hope in your help with this. -- Andrei
i'm trying to do my best. honestly! ;-) i'm deleting first two or three variants of many replies. so my answers looks perfectly calm for me... until i see them posted. yet i'll try to improve than situation in this year. maybe deleting first ten variants, i don't know... ;-)
This is a frequent habit of mine, I always re-read my posts until I feel comfortable that I wouldn't mind reading it (most of the time, it takes at least 2 reviews). Anything especially antagonistic usually gets extra scrutiny :) If NNTP posted replies as I typed them, I would be banned for sure... -Steve
Jan 02 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 3:19 PM, ketmar via Digitalmars-d wrote:
 Walter and Andrei seems to be sure that Ddoc is human-readable,
It doesn't help matters when the examples posted to show how "unreadable" Ddoc is are both misuse of Ddoc and extremely poor whitespace formatting, comparing it with carefully formatted Markdown. I've seen this repeatedly in that thread, by multiple authors, including you. It is not compelling any more than if I tried to show D was better than C++ by showing sloppy and incompetently written C++ code.
  anything less
 powerful than Ddoc will be rejected with arbitrary reason (see Walter
 posts about escaping in markdown, for example).
The complaint was made about needing escaping in Ddoc, and then it is arbitrary when I point out that all markup languages need escaping, including Markdown? And lastly, the general problem users have with documentation in Phobos is not that it is written in Ddoc. That has NOTHING to do with it, it's an excuse. Nobody has yet taken me up on my offer to take their text documentation and add markup for them. Few people being willing to write good content is the problem. No documentation tool can fix that. Non-existent documentation can be not written using any tool. Some have been recently stepping up to create PRs to fix documentation in Phobos. That's what we need, and I thank the people doing it: aldacron, AndrejMitrovic, JakobOvrum, quickfur, ntrel, andralex, klickverbot, kiith-sa, Dicebot, schveiguy to name some.
Jan 01 2015
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 01:07:37 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 And lastly, the general problem users have with documentation in Phobos i=
s not=20
 that it is written in Ddoc. That has NOTHING to do with it, it's an excus=
e.=20
 Nobody has yet taken me up on my offer to take their text documentation a=
nd add=20
 markup for them. Few people being willing to write good content is the pr=
oblem.=20
 No documentation tool can fix that. Non-existent documentation can be not=
=20
 written using any tool.
Adam already told that people who can write good documentation is rarely need it. so they just DON'T HAVE that documentation written in the way it can be useful for others. so the only way to make such people write something is to make documentation formatting unintrusive. Ddoc IS intrusive. i can fix something if i can read it, and i can't read that Ddoc mess. so i'm going to dlang.org to look at the dox instead of looking it right in the Phobos sources. and if i see something that can/should be fixed on dlang.org... ah, well, i have to drop the thing i was doing, open another terminal, go to Phobos source directory, find the file with the dox, then find the place to fix... screw it, i was looking at documentation for doing completely different things! but see, if Phobos documentation is human-readable without preprocessing, it's WAY EASIER for me to just open Phobos source file and look there. and guess what i'll do if i'll see that something needs fixing there? yep, i'll fix that, 'cause i'm already at the place that needs fixing. the process is not distractive. and then i can do 'git diff' and send a patch. the whole point is that Ddoc is *not* *human* *readable*. so why i should look to Phobos sources and try to decipher it? and i don't want to drop whatever i was doing to go from the site to Phobos. and when i done with my task, i already forgot what requires fixing (or exhausted and don't want to do it). i understand that D is your child, and you are working on it with passion. but for me D is the tool to solve my tasks. i'm ready to help improving that tool, but only if that's as easy as possible for me. when i done with my task, i already know what i wanted to know, so there is little sense in fixing that. i'm done with it, now i remember it. or at least remember in which of my source files i should look when i need to refresh my memory (yep, i'm looking for usage samples and patterns in my sources if i can, 'cause it's way easier to open another source file for me than to go to some webpage, even local one). that's why i'm advocating human-readable markup. it's easier to read. it's easier to write. it's easier to fix. it can be used without preprocessor. any decent IDE (and even my patched mcedit) can open source file with function definition in one or two clicks. i can't fix it inplace -- i will not fix it. i can't do 'git diff' with it -- i will not fix it. i can't read it -- i will not fix it. and all this is solvable, even without sacrificing your beloved Ddoc: we can have BOTH markdown-like and Ddoc simultaneously. do that and see what language people will prefer to use.
Jan 01 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote:
 i can fix something if i can read it, and i can't read that Ddoc mess.
 so i'm going to dlang.org to look at the dox instead of looking it
 right in the Phobos sources. and if i see something that can/should be
 fixed on dlang.org... ah, well, i have to drop the thing i was doing,
 open another terminal, go to Phobos source directory, find the file
 with the dox, then find the place to fix... screw it, i was looking at
 documentation for doing completely different things!

 but see, if Phobos documentation is human-readable without
 preprocessing, it's WAY EASIER for me to just open Phobos source file
 and look there. and guess what i'll do if i'll see that something needs
 fixing there? yep, i'll fix that, 'cause i'm already at the place that
 needs fixing. the process is not distractive. and then i can do 'git
 diff' and send a patch.
All you need is a mail client seeing as Walter offered you twice to email him any fixes you have and he'll integrate them for you. (Not to mention you refuse to use github etc.) Honestly if someone would pass similarly constructed arguments by you, would you put any weight on their opinion? I find your posts oddly awesome. Such cognitive dissonance is the stuff of legends. -- Andrei
Jan 01 2015
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 01:43:13 -0800
Andrei Alexandrescu via Digitalmars-d <digitalmars-d puremagic.com>
wrote:

 On 1/1/15 1:34 AM, ketmar via Digitalmars-d wrote:
 i can fix something if i can read it, and i can't read that Ddoc mess.
 so i'm going to dlang.org to look at the dox instead of looking it
 right in the Phobos sources. and if i see something that can/should be
 fixed on dlang.org... ah, well, i have to drop the thing i was doing,
 open another terminal, go to Phobos source directory, find the file
 with the dox, then find the place to fix... screw it, i was looking at
 documentation for doing completely different things!

 but see, if Phobos documentation is human-readable without
 preprocessing, it's WAY EASIER for me to just open Phobos source file
 and look there. and guess what i'll do if i'll see that something needs
 fixing there? yep, i'll fix that, 'cause i'm already at the place that
 needs fixing. the process is not distractive. and then i can do 'git
 diff' and send a patch.
=20 All you need is a mail client seeing as Walter offered you twice to=20 email him any fixes you have and he'll integrate them for you. (Not to=20 mention you refuse to use github etc.) Honestly if someone would pass=20 similarly constructed arguments by you, would you put any weight on=20 their opinion? I find your posts oddly awesome. Such cognitive=20 dissonance is the stuff of legends. -- Andrei
you seem to miss my point completely. i'm *not* doing any fixes at all. if Phobos documentation will be human-readable, i will not go to dlang.org ever, i will use Phobos sources instead. i.e. i will look for documentation right in the Phobos sources, not on some website. and surely, it's easy to fix something if the file where it must be fixed is already open in your editor, and exatly on the place which needs fixing. but going from website all way down to Phobos src, and then struggling with Ddoc... no, thanks. i'm not reading that dox for fun and enjoyment. if i'm reading dox it means that i got some problem that i need to solve, and distracting me for too long from that problem is destructive for my workflow. fixing something that is already before my eyes and ready to be edited is ok. dropping my work to fix something that is both far away and requires to grasp non-readable formatting is no-no. having human-readable formatting for documentation solves that problem. it's still possible to generate standalone dox with it, but it's now possible to read dox without generating anything, just in place where that dox was created. and most existing dox can be magically converted to human-readable format too.
Jan 01 2015
prev sibling next sibling parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 8:50 a.m., Andrei Alexandrescu wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax we're looking
 at doing something about it. Please discuss any ideas you might have
 here. Thanks!

 One simple starter would be to allow one escape character, e.g. the
 backtick (`), as a simple way to expand macros: instead of $(MACRO arg1,
 arg2) one can write `MACRO arg1, arg2`.


 Andrei
1. We need to control whitespace This includes indentation of output elements and new lines added Use case: JSON, YAML 2. Allow usage of CTFE as a macro. Seriously, let actual D code act as a macro. Also a trait to use a macro. Maybe even extend allMembers for it too. Use case: Any advanced macros such as find and replace. 3. It should be possible to not use DDOC macros inside e.g. function comment to make it readable when exported. I'm not sure how this would work, but most likely some form of catch all would be needed. Use case: Markdown as format but still outputs clean and nice text. But also outputting e.g. JSON with clean structure.
Dec 31 2014
parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 12:49:06 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 2. Allow usage of CTFE as a macro.
this what Ddoc is really should be. no need in anything other: let all documentation be processed by CTFE. not by per-function basis though: compiler must collect *all* documentation and then call one CTFE entry point to process it. if we gave multiple source files in the command line, it should collect documentation from all that source files. this is to allow keeping some state when processing docs. and then everything Ddoc macros does now can be written in D. and if someone wants markdown... he will just write a markdown processor in D, and BLAM! there is markdown processor, without patching the compiler. ah, and compiler source can be made simplier, as Ddoc can be removed altogether. it's perfect. it will solve ALL problems. it will allow people to use anything they like. and we already has the D interpreter to power it.
Dec 31 2014
parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 12:59 p.m., ketmar via Digitalmars-d wrote:
 On Thu, 01 Jan 2015 12:49:06 +1300
 Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 2. Allow usage of CTFE as a macro.
this what Ddoc is really should be. no need in anything other: let all documentation be processed by CTFE. not by per-function basis though: compiler must collect *all* documentation and then call one CTFE entry point to process it. if we gave multiple source files in the command line, it should collect documentation from all that source files. this is to allow keeping some state when processing docs. and then everything Ddoc macros does now can be written in D. and if someone wants markdown... he will just write a markdown processor in D, and BLAM! there is markdown processor, without patching the compiler. ah, and compiler source can be made simplier, as Ddoc can be removed altogether. it's perfect. it will solve ALL problems. it will allow people to use anything they like. and we already has the D interpreter to power it.
Following this, we could extend this one altogether. AST entry points. Read only (later maybe not) full access to dmd-fe AST. e.g. __ast(__ASTTree tree) { string output = "<modules>"; foreach(string name, __ASTModule theModule; tree.modules) { string theOutput; output ~= "<module name=\"" ~ name ~ "\">"; output ~= "<doc>"; output ~= preprocessor(theModule.comment); output ~= "</doc>"; output ~= "</module>"; output ~= theOutput; // __DDOC ~= theOutput; } __DDOC/*[0]*/ = output ~ "</modules>"; } Multiple __ast functions is not invalid. But one per module. One caveat of this however is that if you have these modules they would be required to be almost 100% standalone. Example usage with dub, is you have an independent package that supplies a YAML output with markdown format. To do so you will want you package as well as possibly all predecessor and successor packages to use that format. To do so, dub could rebuild all dependencies and pass in those extra files. And any successor packages will have it added as a dependency and not -I'd. This could really kill so many birds. We could even get rid of traits and prefer __ast(Type/Symbol) to get the AST for it. And remember how we don't know about all modules? That's the thing, with this approach its designed to not assume it has all. But it can see them at some point thanks to e.g. dub. Although this is a little extreme compared to my original post...
Dec 31 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 13:21:16 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 Although this is a little extreme compared to my original post...
a little. ;-) yes, processing ASTs with CTFE will be great, but this is huge task. replacing Ddoc with CTFE which receives an array (tuple? ;-) of functions with documentation text (preprocessed a little, see below) is a lighter task. then we can use compile-time introspection to get function args and so, and format the output as we like. "small preprocessing" converts the following: /** text0 * text1 * text2 */ to: text0 text1 text2 i.e. just removing that indentation with corresponding '*'. it's easy and must be done for any formatting, so it can be done before invoking CTFE. just make sure that the following will not be processed: /** text0 * text1 heh * text2 */ there is no vertical line of '*', so no need to remove leading '*' here.
Dec 31 2014
parent reply Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 1:35 p.m., ketmar via Digitalmars-d wrote:
 On Thu, 01 Jan 2015 13:21:16 +1300
 Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 Although this is a little extreme compared to my original post...
a little. ;-) yes, processing ASTs with CTFE will be great, but this is huge task. replacing Ddoc with CTFE which receives an array (tuple? ;-) of functions with documentation text (preprocessed a little, see below) is a lighter task. then we can use compile-time introspection to get function args and so, and format the output as we like. "small preprocessing" converts the following: /** text0 * text1 * text2 */ to: text0 text1 text2 i.e. just removing that indentation with corresponding '*'. it's easy and must be done for any formatting, so it can be done before invoking CTFE. just make sure that the following will not be processed: /** text0 * text1 heh * text2 */ there is no vertical line of '*', so no need to remove leading '*' here.
I was thinking one simpler. $(D myfunction, $0) This will be enough of a big task, but enough of a pay off to make it worth while. The AST stuff would guaranteed be a DIP (second to last CTFE implementation type, well as I define it anyway).
Dec 31 2014
next sibling parent reply ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 13:44:23 +1300
Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 I was thinking one simpler.
 $(D myfunction, $0)
it's not really better than current Ddoc. sure, you can use it to write custom doc processor, but you can't store state with it, and you still have to escape alot. this actually making Ddoc *worse*, as it adds complexity.
Dec 31 2014
parent Rikki Cattermole <alphaglosined gmail.com> writes:
On 1/01/2015 1:54 p.m., ketmar via Digitalmars-d wrote:
 On Thu, 01 Jan 2015 13:44:23 +1300
 Rikki Cattermole via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 I was thinking one simpler.
 $(D myfunction, $0)
it's not really better than current Ddoc. sure, you can use it to write custom doc processor, but you can't store state with it, and you still have to escape alot. this actually making Ddoc *worse*, as it adds complexity.
At the very least, atleast the compiler wouldn't need changes per each different doc processor. I can understand state being an issue. But this atleast will use CTFE to extend DDOC just enough to make it more useful. For full AST access which basically has state local to the function, its too much code on the compiler side to make it worth while right now. But this is a nice compromise IMO.
Dec 31 2014
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-01 01:44, Rikki Cattermole wrote:

 The AST stuff would guaranteed be a DIP (second to last CTFE
 implementation type, well as I define it anyway).
http://wiki.dlang.org/DIP50 ;) -- /Jacob Carlborg
Jan 01 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-01 01:21, Rikki Cattermole wrote:

 Following this, we could extend this one altogether.
 AST entry points. Read only (later maybe not) full access to dmd-fe AST.
So we're back at AST macros :). I don't mind but I don't think it's the right solution in this case. -- /Jacob Carlborg
Jan 01 2015
prev sibling next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
I'd actually prefer to focus more on ddoc's unique strengths - 
that it understands the compiler's scoping rules.

My #1 ddoc wish is not change to macro syntax (i prefer plain 
text anyway)... my #1 wish is for all D symbols to be made 
available to the output somehow, with their fully-qualified names 
and or mangles.

Imagine how cool it would be if you could write

import std.stdio;
/**
    ---
       import std.path;
       File f = open(path.whatever());
    ---
*/
File open(string name);


And have it come out as:


/**
    ---
       $(D_CODE_KEYWORD import) ($D_CODE_IDENT std.path, std.path);
       $(D_CODE_IDENT std.stdio.File, File) f = 
open(path.whatever());
    ---
*/
$(D_CODE_IDENT std.stdio.File, File) open(string name);


and so on and so forth.


then we could implement a macro or a "I feel lucky" style search 
that links all those D_CODE_IDENT to the right places, 
automatically.


I think that'd be pretty boss.
Dec 31 2014
parent "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 00:44:33 UTC, Adam D. Ruppe wrote:
 I'd actually prefer to focus more on ddoc's unique strengths - 
 that it understands the compiler's scoping rules.
If I understand this correctly, it seems very compelling to me. Would it be an option to 1. Work on ddoc (as it is now) to be even closer to the compiler (e.g. scoping rules) 2. Add a carefully selected markdown on top of proper ddoc (e.g. use ddoc instead of html as fallback) 3. Provide ddoc macro definitions to generate all kinds of output This would help in several ways 1. The fully functional ddoc system that can do books remains available. There is use for it. 2. The code documentation could be much more lightweight (but still have the full ddoc macros available if needed) 3. Generating to pandoc or the like. There are converters out there. If any of this is of any value, I am happy to help to make it happen.
Jan 01 2015
prev sibling next sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax we're looking at
 doing something about it. Please discuss any ideas you might have here.
 Thanks!

 One simple starter would be to allow one escape character, e.g. the backtick
 (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one
 can write `MACRO arg1, arg2`.
I don't really have any particular opinions on this topic, but the only feeling I've really had in the past is, "why is it so different from doxygen?" Most people are already familiar with doxygen. Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start?
Dec 31 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote:
 On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d
 <digitalmars-d puremagic.com> wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax we're looking at
 doing something about it. Please discuss any ideas you might have here.
 Thanks!

 One simple starter would be to allow one escape character, e.g. the backtick
 (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one
 can write `MACRO arg1, arg2`.
I don't really have any particular opinions on this topic, but the only feeling I've really had in the past is, "why is it so different from doxygen?" Most people are already familiar with doxygen. Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start?
No particular system was clearly dominant when Walter invented ddoc. Also I might be frequenting the wrong circles; most people I know and myself aren't fluent at all with doxygen. -- Andrei
Jan 01 2015
next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
 No particular system was clearly dominant when Walter invented ddoc. Also I
 might be frequenting the wrong circles; most people I know and myself aren't
 fluent at all with doxygen. -- Andrei
It is really trivial to learn and quite effective. I used it years ago for a C/C++ project; when I encountered Ddoc my reaction was, "OK, it's basically a custom and slightly weirder-looking variant of Doxygen..." It has some _very_ nice features such as the easy inclusion of LaTeX formulas into documentation, and in my experience Doxygen markup is much more readable-in-source than Ddoc. Three things I'm not sure about: (i) does it allow definitions of custom macros as with Ddoc (although I'm not sure how necessary that is in practice); (ii) I have a nasty feeling its keyword markup syntax (e.g. return param etc.) might not play nice with D code examples; (iii) I suspect we'd have to do some integration work getting D support into Doxygen in order to enjoy the best of all its features.
Jan 01 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
 No particular system was clearly dominant when Walter invented ddoc.
 Also I
 might be frequenting the wrong circles; most people I know and myself
 aren't
 fluent at all with doxygen. -- Andrei
It is really trivial to learn and quite effective.
Totally. I did use it briefly a few years ago and I'm sure I can relearn it. My point here was to give context for ddoc's history. FWIW switching dlang and phobos now to doxygen would be a major effort and I'm not sure we'd be in a better place even after assuming perfect execution. Andrei
Jan 01 2015
next sibling parent reply "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 10:16:01 UTC, Andrei Alexandrescu 
wrote:
 My point here was to give context for ddoc's history. FWIW 
 switching dlang and phobos now to doxygen would be a major 
 effort and I'm not sure we'd be in a better place even after 
 assuming perfect execution.
I don't think the current documentation of phobos is affecting (professional) D adoption much, although it can improve a lot. Adoption is a language/compiler/runtime/tooling issue. On the other hand, if converting phobos' Ddoc into Doxygen cannot be automated, then that suggests that there is a fundamental problem with how Ddoc is used as a markup tool. Adopting Doxygen would give you some benefits: - it makes D look less weird - it makes it easier to use existing formatting/presentation solutions - it is more motivating to learn Doxygen than figuring out Ddoc since you can use it for non-D projects The Doxygen front page advertises the following: «it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.» D would look better without the "to some extend" and you might get the Doxygen community to help out with Doxygen relevant tooling issues if it is the default D documentation tool. Basically an opportunity for synergy.
Jan 01 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 3:09 AM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
<ola.fosheim.grostad+dlang gmail.com>" wrote:
 Adopting Doxygen would give you some benefits:
"Doxygen is developed under Mac OS X and Linux, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available." -- http://www.stack.nl/~dimitri/doxygen/ There are no packages for FreeBSD, for example. Doxygen is GPL, but appears to be supported by only one person. There is also nothing stopping anyone from using Doxygen if they prefer it.
Jan 01 2015
parent "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 12:05:03 UTC, Walter Bright wrote:
 There is also nothing stopping anyone from using Doxygen if 
 they prefer it.
Sure, but there is a big advantage in having a the same tech doc format for all libraries for the same language/group of languages. I've spent way too much time learning new essential languages, so learning a new one for a fringe activity like writing tech docs is not going to happen. Picking a common subset of an existing markup language will reduce resistance to learning the one D is using. Doxygen syntax is a good candidate if you want people to write uniform docs for D libraries. Especially if D is going to continue to focus on C++ integration.
Jan 01 2015
prev sibling next sibling parent reply Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1/1/15, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 Totally. I did use it briefly a few years ago and I'm sure I can relearn
 it.
The wxWidgets developers maintain a hand-written set of doxygen interface files because doxygen actually crashes when trying to parse the C++ code directly. As a result the documentation is frequently out of date. I remember filing numerous patches to fix their docs (over 100 of them), it was blatantly out of date[1]. We would have the same problem with D. Any time there were syntax changes in D we would have to fix doxygen to be able to parse D code again. Anyway, maybe we can do something about ddoc and make it easier to use. I'm just saying the grass isn't necessarily greener on the other side. [1]: http://trac.wxwidgets.org/search?ticket=on&q=drey&page=13&noquickjump=1
Jan 01 2015
next sibling parent "Piotrek" <none nowhere.pl> writes:
On Thursday, 1 January 2015 at 13:28:39 UTC, Andrej Mitrovic via 
Digitalmars-d wrote:
 Anyway, maybe we can do something about ddoc and make it easier 
 to use. I'm just saying the grass isn't necessarily greener
 on the other side.
+1. Every documentation tool has its problems. IMO, changing documentation system from the dedicated one would be a step backwards. Piotrek
Jan 01 2015
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-01 14:28, Andrej Mitrovic via Digitalmars-d wrote:

 The wxWidgets developers maintain a hand-written set of doxygen
 interface files because doxygen actually crashes when trying to parse
 the C++ code directly.

 As a result the documentation is frequently out of date. I remember
 filing numerous patches to fix their docs (over 100 of them), it was
 blatantly out of date[1].

 We would have the same problem with D. Any time there were syntax
 changes in D we would have to fix doxygen to be able to parse D code
 again.
I'm pretty sure I read on the Clang mailing list that someone wants to use Clang to extract doxygen comments. -- /Jacob Carlborg
Jan 01 2015
prev sibling parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 20:16, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 1/1/15 2:02 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
 No particular system was clearly dominant when Walter invented ddoc.
 Also I
 might be frequenting the wrong circles; most people I know and myself
 aren't
 fluent at all with doxygen. -- Andrei
It is really trivial to learn and quite effective.
Totally. I did use it briefly a few years ago and I'm sure I can relearn it. My point here was to give context for ddoc's history. FWIW switching dlang and phobos now to doxygen would be a major effort and I'm not sure we'd be in a better place even after assuming perfect execution.
I was thinking more along the lines of letting doxygen inspire enhancements to ddoc, since as far as I can see, it's pretty much the standard these days, and people already know it.
Jan 01 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
 I was thinking more along the lines of letting doxygen inspire
 enhancements to ddoc, since as far as I can see, it's pretty much the
 standard these days, and people already know it.
And others are saying "Markdown is the standard." BTW, Boost doesn't seem to use Doxygen, apparently because it crashes reading Boost C++ files: http://stackoverflow.com/questions/3349783/boost-doxygen-documentation
Jan 01 2015
next sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 20:42, Walter Bright via Digitalmars-d wrote:
 On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
 I was thinking more along the lines of letting doxygen inspire
 enhancements to ddoc, since as far as I can see, it's pretty much the
 standard these days, and people already know it.
And others are saying "Markdown is the standard."
I think the two are not in contradiction, because as Manu noted earlier in the thread, Doxygen now permits Markdown to be used in its documentation.
Jan 01 2015
prev sibling next sibling parent reply Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1/1/15, Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:
 On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
 I was thinking more along the lines of letting doxygen inspire
 enhancements to ddoc, since as far as I can see, it's pretty much the
 standard these days, and people already know it.
And others are saying "Markdown is the standard."
Well the actual truth is that doxygen is pretty much the C++ standard, while Markdown is a standard for everything else. :)
Jan 01 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 12:02 PM, Andrej Mitrovic via Digitalmars-d wrote:
 Well the actual truth is that doxygen is pretty much the C++ standard,
 while Markdown is a standard for everything else. :)
My experience with C/C++ is that no documentation is the standard :-)
Jan 01 2015
prev sibling parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 2 January 2015 at 05:42, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 1/1/2015 8:19 AM, Manu via Digitalmars-d wrote:
 I was thinking more along the lines of letting doxygen inspire
 enhancements to ddoc, since as far as I can see, it's pretty much the
 standard these days, and people already know it.
And others are saying "Markdown is the standard."
It is, doxygen supports markdown. Doxygen users are generally familiar with markdown in docs.
 BTW, Boost doesn't seem to use Doxygen, apparently because it crashes
 reading Boost C++ files:

 http://stackoverflow.com/questions/3349783/boost-doxygen-documentation
Hah. C++ is such a pig, I'm amazed it's actually POSSIBLE to parse it anymore! ;)
Jan 01 2015
prev sibling parent =?UTF-8?Q?Tobias=20M=C3=BCller?= <troplin bluewin.ch> writes:
Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com>
wrote: 
 Three things I'm not sure about: (i) does it allow definitions of custom
 macros as with Ddoc (although I'm not sure how necessary that is in
 practice); (ii) I have a nasty feeling its  keyword markup syntax (e.g.
  return  param etc.) might not play nice with D code examples; (iii) I
 suspect we'd have to do some integration work getting D support into
 Doxygen in order to enjoy the best of all its features.
AFAIK keyword is javadoc style (but supported by doxygen) and original doxygen style uses \keyword.
Jan 02 2015
prev sibling next sibling parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 19:33, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 12/31/14 10:17 PM, Manu via Digitalmars-d wrote:
 On 1 January 2015 at 05:50, Andrei Alexandrescu via Digitalmars-d

 <digitalmars-d puremagic.com> wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax we're looking
 at
 doing something about it. Please discuss any ideas you might have here.
 Thanks!

 One simple starter would be to allow one escape character, e.g. the
 backtick
 (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one
 can write `MACRO arg1, arg2`.
I don't really have any particular opinions on this topic, but the only feeling I've really had in the past is, "why is it so different from doxygen?" Most people are already familiar with doxygen. Why is doxygen insufficient? Is there a reason ddoc was invented rather than supporting the practically-industry-standard doxygen format from the start?
No particular system was clearly dominant when Walter invented ddoc.
Okay.
 Also I might be frequenting the wrong circles; most people I know and myself
aren't
 fluent at all with doxygen. -- Andrei
What do you tend to use instead? I miss doxygen's '\' tags. For instance, '\a argName' to refer to a function argument argName, which will be formatted appropriately and all that. I find it a lot less visually distracting. It might also be interesting to note that doxygen implemented markdown support quite some time back, so I think there's precedent for people expecting that markdown be available for use in their documentation.
Jan 01 2015
prev sibling next sibling parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 20:02, Joseph Rushton Wakeling via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 01/01/15 10:33, Andrei Alexandrescu via Digitalmars-d wrote:
 No particular system was clearly dominant when Walter invented ddoc. Also
 I
 might be frequenting the wrong circles; most people I know and myself
 aren't
 fluent at all with doxygen. -- Andrei
It is really trivial to learn and quite effective. I used it years ago for a C/C++ project; when I encountered Ddoc my reaction was, "OK, it's basically a custom and slightly weirder-looking variant of Doxygen..." It has some _very_ nice features such as the easy inclusion of LaTeX formulas into documentation, and in my experience Doxygen markup is much more readable-in-source than Ddoc. Three things I'm not sure about: (i) does it allow definitions of custom macros as with Ddoc (although I'm not sure how necessary that is in practice); (ii) I have a nasty feeling its keyword markup syntax (e.g. return param etc.) might not play nice with D code examples; (iii) I suspect we'd have to do some integration work getting D support into Doxygen in order to enjoy the best of all its features.
Doxygen supports both param and \param. It would be really good if doxygen supported D comprehensively. I often port C code to D which already has doxygen commentary. I never port the doxygen docs to ddoc though.
Jan 01 2015
prev sibling next sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 17:16, Manu via Digitalmars-d wrote:
 Doxygen supports both  param and \param.
Ah yes, I'd forgotten that. It's been a while :-\
 It would be really good if doxygen supported D comprehensively. I
 often port C code to D which already has doxygen commentary. I never
 port the doxygen docs to ddoc though.
Did you ever try preserving the docs and continuing to use doxygen to generate them? If so, how did it go? Or is that an outright impossibility?
Jan 01 2015
prev sibling parent Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 2 January 2015 at 03:06, Joseph Rushton Wakeling via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 01/01/15 17:16, Manu via Digitalmars-d wrote:
 Doxygen supports both  param and \param.
Ah yes, I'd forgotten that. It's been a while :-\
 It would be really good if doxygen supported D comprehensively. I
 often port C code to D which already has doxygen commentary. I never
 port the doxygen docs to ddoc though.
Did you ever try preserving the docs and continuing to use doxygen to generate them? If so, how did it go? Or is that an outright impossibility?
Doxygen doesn't know about most D-specific concepts stuff. Other language concepts are usually a subset of C/C++, but C++ is really a subset of D. Doxygen needs some new concepts as far as I can tell.
Jan 01 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote:
 Why is doxygen insufficient? Is there a reason ddoc was invented
 rather than supporting the practically-industry-standard doxygen
 format from the start?
There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 or 3 people used it. The problem was Doxygen was some add on tool. It was not part of the downloadable D package. It couldn't be. Anyone wanting to use Doxygen was going to have to: 1. pray a version exists on the platform they have that D is installed on. 2. pray that version was the one the D docs were expecting. 3. buy Doxygen. 4. download and install Doxygen successfully. 5. Doxygen is a large and complex tool - lots of work to understand it. 6. expect the D community to provide tech support with "Doxygen is not working on my D documents." The end result was, essentially nobody used Doxygen. In fact, nobody used any sort of documentation system, and we know what the result looked like - your typical out-of-date, totally wrong, or non-existent normally found with C and C++ projects. Ddoc, being: 1. always there 2. always the correct version 3. Ddoc is trivial to learn and use revolutionized the D documentation. And that's an understatement.
Jan 01 2015
parent reply Manu via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1 January 2015 at 21:51, Walter Bright via Digitalmars-d
<digitalmars-d puremagic.com> wrote:
 On 12/31/2014 10:17 PM, Manu via Digitalmars-d wrote:
 Why is doxygen insufficient? Is there a reason ddoc was invented
 rather than supporting the practically-industry-standard doxygen
 format from the start?
There was a time when D did not have Ddoc. Doxygen was available. Perhaps 2 or 3 people used it. The problem was Doxygen was some add on tool. It was not part of the downloadable D package. It couldn't be. Anyone wanting to use Doxygen was going to have to: 1. pray a version exists on the platform they have that D is installed on. 2. pray that version was the one the D docs were expecting. 3. buy Doxygen. 4. download and install Doxygen successfully. 5. Doxygen is a large and complex tool - lots of work to understand it. 6. expect the D community to provide tech support with "Doxygen is not working on my D documents." The end result was, essentially nobody used Doxygen. In fact, nobody used any sort of documentation system, and we know what the result looked like - your typical out-of-date, totally wrong, or non-existent normally found with C and C++ projects. Ddoc, being: 1. always there 2. always the correct version 3. Ddoc is trivial to learn and use revolutionized the D documentation. And that's an understatement.
I'm not arguing that it wasn't an excellent decision to include a doc parser in DMD, but I don't think any of those advantages are attributed to the ddoc syntax specifically so much as just including it in the compiler. I'm sure the ddoc syntax is fine. It's just noisy and hard to read, as I think we've established to be the popular opinion. I'm just suggesting that DMD could also parse some useful subset of doxygen as ddoc shorthand. I don't think parsing doxygen would be particularly difficult. Basically all the suggestions here so far, like the markdown bits are valid doxygen.
Jan 01 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 8:39 AM, Manu via Digitalmars-d wrote:
 It's just noisy and hard to read, as
 I think we've established to be the popular opinion.
I'm sure we can also agree that: #include\ <stdio.h\

#include\
  <stdlib.h>
int main\
(){print\
f("hello\
  world\n\
");retur\
n EXIT_S\
UCCESS;}

Is also hard to read. Yes, I'm being facetious, but take a look at those 
examples posted here about how ugly Ddoc is - they're of that category.

Consider also this Ddoc code:

/****************************
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 ... }
---
***************************/


And lastly, people initially hated the D template syntax:

    foo!(args)
    foo!arg

but today it elicits nary a ripple - it's liked now. It's simply familiar now.
Jan 01 2015
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote:
 Is also hard to read. Yes, I'm being facetious, but take a look 
 at those examples posted here about how ugly Ddoc is - they're 
 of that category.
The difference is the ddoc code posted here is copied verbatim from a real world project, Phobos, even the standard library. Why the hell were they written that way in the first place? Beats the crap out of me, but they ARE written that way...
Jan 01 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 12:04 PM, Adam D. Ruppe wrote:
 On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote:
 Is also hard to read. Yes, I'm being facetious, but take a look at those
 examples posted here about how ugly Ddoc is - they're of that category.
The difference is the ddoc code posted here is copied verbatim from a real world project, Phobos, even the standard library.
I know. But have you ever seen badly formatted C code? Do you conclude from that that C code is inherently ugly? Or do you say "hey, fix the formatting!"
 Why the hell were they written that way in the first place? Beats the crap out
 of me, but they ARE written that way...
Yep, and I've seen a lot of crappily formatted D code, too. That's pretty much died down in the Phobos submissions, because the reviewers won't allow it in. Little comparable attention, however, has been paid to the Ddoc style. I did put to rights one of the posted examples: https://github.com/D-Programming-Language/phobos/pull/2828
Jan 01 2015
prev sibling next sibling parent "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 19:57:56 UTC, Walter Bright wrote:
 On 1/1/2015 8:39 AM, Manu via Digitalmars-d wrote:
 It's just noisy and hard to read, as
 I think we've established to be the popular opinion.
Is also hard to read. Yes, I'm being facetious, but take a look at those examples posted here about how ugly Ddoc is - they're of that category.
At this point it might be helpful to point out that Ddoc does its jobs very well. It deserves praise on its merits. For properly documented code, however, it requires more visual noise than desirable. Take std/algorithm.d as an example. In my opinion replacing $(D ...) with `...` boosts the file considerably. The beauty of markdown is that it requires significantly less visual noise. It is not clean what markdown actually is, so voting for it might be nonsensical. On the other hand, I believe in reading source code and some documentation in phobos is unreadable to me. This is why I think Ddoc should be improved.
Jan 01 2015
prev sibling parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 11:57:37 -0800
Walter Bright via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 Is also hard to read. Yes, I'm being facetious, but take a look at those=
=20
 examples posted here about how ugly Ddoc is - they're of that category.
and you know why? 'cause nobody cares to make 'em human readable, as it's almost impossible with Ddoc. so why someone should waste his time on that? on contrary, human-readable markup tend to be formatted to be actually human-readable. yet i will not argue anymore, as you seem to ignore the fact that most people don't want to do DTP in API documentation. this is very easy to judge: just preapprove markdown-like parser for documentation (without throwing off Ddoc) and then see what people will use most of the time. i bet you know the answer.
Jan 01 2015
prev sibling next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote:
 One simple starter would be to allow one escape character, e.g. the backtick
 (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2) one can
 write `MACRO arg1, arg2`.
Would that be accompanied by deprecation and removal of the $(MACRO arg1, arg2) syntax? I ask because for me, one of the biggest annoyances of Ddoc (in terms of source readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc accidentally seeing a macro where there is none.
Jan 01 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 31/12/14 20:50, Andrei Alexandrescu via Digitalmars-d wrote:
 One simple starter would be to allow one escape character, e.g. the
 backtick
 (`), as a simple way to expand macros: instead of $(MACRO arg1, arg2)
 one can
 write `MACRO arg1, arg2`.
Would that be accompanied by deprecation and removal of the $(MACRO arg1, arg2) syntax?
No.
 I ask because for me, one of the biggest annoyances of Ddoc (in terms of
 source readability of the docs) is having to use $(RPAREN) in order to
 avoid Ddoc accidentally seeing a macro where there is none.
cd code/d/phobos git grep RPAREN | wc -l 28 RPAREN is indeed more frequent in dlang.org: cd code/d/phobos git grep RPAREN | wc -l 589 Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The majority are in changelog.dd; I guess a couple of macros might help there. Andrei
Jan 01 2015
next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 11:21, Andrei Alexandrescu via Digitalmars-d wrote:
 cd code/d/phobos
 git grep RPAREN | wc -l
        28
It's a bugbear for std.random because I find myself writing things like: /** $(D uniform01) offers a faster generation of random variates than the equivalent $(D uniform!"[$(RPAREN)"(0.0, 1.0)) and so may be preferred for some applications. Returns: Floating-point random variate of type $(D T) drawn from the uniform distribution across the half-open interval [0, 1$(RPAREN). */ With respect to my other remarks in this thread, the example above is one of the single most annoying human-unreadable things I encounter: I would really, really like mathematics and inline code examples in the docs to not need "escaping" in this manner, so that it's as easy as possible to compare and contrast docs and code in the source file. I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-(
Jan 01 2015
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I'm hoping that I'm just missing a Ddoc trick here, but I don't think so :-(
Other than the: $(INTERVAL 0, 1) macro, you can use: &rparen; or the unicode &rbbrk; which looks like a right ) : [0, 1❳ You can also use: [0, 1[ which is actually an international standard notation: http://en.wikipedia.org/wiki/ISO_31-11#Sets
Jan 01 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 3:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I'm hoping that I'm just missing a Ddoc trick here, but I don't think so
 :-(
You're not but that's really rare. uniform01 is a rare case of unpaired paren in code. -- Andrei
Jan 01 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 2:21 AM, Andrei Alexandrescu wrote:
 Yet that's out of 25479 lines of ddoc source, so one every 43 lines. The
 majority are in changelog.dd; I guess a couple of macros might help there.
There are also things in the language spec documentation like: $(B $(LPAREN) $(RPAREN)) which are simply unnecessary. Instead: $(B ( ))
Jan 01 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 2:04 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I ask because for me, one of the biggest annoyances of Ddoc (in terms of source
 readability of the docs) is having to use $(RPAREN) in order to avoid Ddoc
 accidentally seeing a macro where there is none.
Please show some context where that frequently happens for you. I see some instances in Phobos, but they are all of the form: [x .. y$(RPAREN) which would be better coded as: $(INTERVAL x .. y) INTERVAL=[$0$(RPAREN)
Jan 01 2015
parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote:
 Please show some context where that frequently happens for you.

 I see some instances in Phobos, but they are all of the form:

    [x .. y$(RPAREN)

 which would be better coded as:

    $(INTERVAL x .. y)

    INTERVAL=[$0$(RPAREN)
See, this is my point. $(INTERVAL x .. y) is, to my mind, less clear to read _in the source_ than [x, y). If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-)
Jan 01 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 See, this is my point.  $(INTERVAL x .. y) is, to my mind, less clear to read
 _in the source_ than [x, y).
My point is there's ALWAYS going to be some sort of escaping mechanism, and it is ALWAYS going to interfere with the look of anyone who wants to use the full character set on the keyboard, which IS going to happen whenever you write math text.
 If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x
 and y.  But is it the closed interval [x, y], one of the half-open intervals
(x,
 y] or [x, y) or the open one (x, y) ... ?
You don't have to call it INTERVAL. You can write your own macro to name it whatever works for you. I do it all the time. You can even then change the definition of the macro and, for example, have it styled differently (like use a different font, different font weight, different color, etc.) I find that very handy. A lot of the complaints about Ddoc clearly stem from people not realizing they can create their own macros. It's like not realizing that C code can contain custom written functions. Here's one example that was brought up in the discussion: https://github.com/D-Programming-Language/phobos/pull/2828 A custom macro made all the difference. Not only that, it is now easy to switch it from a table to a definition list, or have custom styling for it, all without messing anything else up. This cannot be done with Markdown. You might ask "why would we want custom styling"? Turns out that that example is a nice one for why not use it.
 I need that kind of precision to document the kind of code I'm writing
 (including phobos contributions), and I would like to be able to read and write
 with that precision explicitly in the source.
 If I need to use a macro
 definition, then the reader has to look up that definition, and you just _know_
 that people are going to use those macros incorrectly, e.g. if we suppose that
 INTERVAL is [x, y), then people will use it in circumstances where they mean
[x,
 y] or (x, y) or whatever.

 Yes, I could use a right-bracket UTF8 character, but that's finnicky and
 annoying (and potentially runs into other problems for readers, e.g. what if
 someone copy-pastes my ddoc source into a non-UTF8 email?).
Math notation uses a ton of special characters, it's one of the reasons why Unicode was invented. Limiting yourself to non-Markdown ascii is extremely limiting. Heck, look at this: https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ
 And yes, I could
 use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely
 to be confusing to readers.

 I'm sorry, but I can't see it as anything other than a serious flaw of ddoc
that
 a super-common character in both code and mathematics has problems being used,
 as itself, inside the documentation markup :-)
Isn't * a super common math character? and |? and +? All of which are markdown characters. The only time the stray paren issue comes up is in the interval notation.
Jan 01 2015
next sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 01/01/15 21:15, Walter Bright via Digitalmars-d wrote:
 My point is there's ALWAYS going to be some sort of escaping mechanism, and it
 is ALWAYS going to interfere with the look of anyone who wants to use the full
 character set on the keyboard, which IS going to happen whenever you write math
 text.
Yes, I accept that. I'm just pointing out what I find problematic with this particular escaping mechanism, given the documentation needs of the code I'm involved with. I do however still think that using $( ) to delineate start and end of macro blocks is a bad choice given the prevalence of ( ) in code. Before I reply to the rest of your email, I think I should point out two things: * I understand that ddoc is a macro system, I understand what that means and how flexible and powerful it can be (I've used LaTeX for years, and I have created my own custom ddoc macros). I'm not trying to persuade you to give that up. * I'm not trying to advocate for you to start supporting markdown, although I do understand why some people are. * LaTeX maths notation on the other hand ... ;-) - actually I'm mostly raising this last point to tease you, but there is a serious side; I'll explain later in the email. Anyway, to some details ...
 You don't have to call it INTERVAL. You can write your own macro to name it
 whatever works for you. I do it all the time. You can even then change the
 definition of the macro and, for example, have it styled differently (like use
a
 different font, different font weight, different color, etc.) I find that very
 handy.
Yes, I understand that I can write different macros to mean different things. But surely you can understand my point from the previous email, that having 4 different macros to indicate the different types of intervals, is much less nice from a reading/writing point of view than just being able to write, in ASCII, [x, y], (x, y], [x, y) and (x, y). It's not just maths notation either -- this will trigger the 'Stray )' warning too: Example: -------- auto u = uniform!"[)"(0.0, 1.0); -------- I think we can achieve that simplicity of reading, not just for these two examples, but for potentially quite a bit more maths and code, without sacrificing any of the things you're interested in keeping.
 A lot of the complaints about Ddoc clearly stem from people not realizing they
 can create their own macros. It's like not realizing that C code can contain
 custom written functions.

 Here's one example that was brought up in the discussion:

     https://github.com/D-Programming-Language/phobos/pull/2828

 A custom macro made all the difference. Not only that, it is now easy to switch
 it from a table to a definition list, or have custom styling for it, all
without
 messing anything else up. This cannot be done with Markdown.

 You might ask "why would we want custom styling"? Turns out that that example
is
 a nice one for why not use it.
Yes, and nothing I say here should be taken as denying the usefulness or desirability of being able to do that. BTW talking of custom macros and custom styling, that file has something I consider to be a horrendous violation of good styling design in it: MYREF = <font face='Consolas, "Bitstream Vera Sans Mono", "Andale Mono", Monaco, "DejaVu Sans Mono", "Lucida Console", monospace'><a href="#.$1">$1</a>&nbsp;</font>
 Math notation uses a ton of special characters, it's one of the reasons why
 Unicode was invented. Limiting yourself to non-Markdown ascii is extremely
 limiting. Heck, look at this:

 https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ
Sure, but even with unicode, there's a limit to how sanely you can represent a complex formula in plain-text. Personally, this is the point where I'd rather be able to use inline LaTeX formulas, because I think most people interested in complex formulas will be able to understand that. Please don't dismiss this idea out of hand: I think there are some handy tools we could use to integrate this very well into our documentation system. Using the MathJax javascript makes it pretty easy to embed LaTeX formulas into an HTML document: http://www.mathjax.org/ ... and obviously when outputting to LaTeX, it becomes much easier to just hand on LaTeX formulas as they are. If we could do something like, $(MATH F(x) = \int_{0}^{10} f(x) dx ) then it would be very nice. Obviously this won't work notationally quite as-is, but I don't see why it shouldn't be possible to find something similar that is workable. (N.B. this is a definite "Dream Wishlist" item, so please don't see it as the main concern of my email; if it isn't workable, just tell me that and move on to the end of the email, where there is the point I really would like your feedback on.)
 Isn't * a super common math character? and |? and +? All of which are markdown
 characters.
Well, as I'm not arguing for markdown, this may be a moot point. But I don't recall encountering those issues with markdown, because IIRC most markdown use of those special characters is quite context dependent: i.e. *this produces bold or emphasized text* but x * y * z does not :-) ... so it doesn't complicate maths notation as you might think. (The above works at least with GitHub markdown:-)
 The only time the stray paren issue comes up is in the interval notation.
I get that my example is an edge case that may not be the best motivation for you to change how things work. But here's the other idea I'd like to suggest that might help resolve this. Others have suggested `this` as a shorthand for $(D_CODE ) or whatever. I'd like to suggest that instead `this` be used as a way to indicate to Ddoc: "There are no Ddoc macros inside this bit of text, nor will a macro end." So, for example, I could rewrite my earlier documentation example as: /** $(D uniform01) offers a faster generation of random variates than the equivalent $(D `uniform!"[)"(0.0, 1.0)`) and so may be preferred for some applications. Returns: Floating-point random variate of type $(D T) drawn from the uniform distribution across the half-open interval `[0, 1)`. */ ... and the "Stray ')'" concerns need not arise, because the `...` blocks guarantee that any ')' character they contain is not stray. Does this sound at all feasible?
Jan 01 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I do however still think that using $( ) to delineate start and end of
 macro blocks is a bad choice given the prevalence of ( ) in code.
s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei
Jan 02 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote:
 On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I do however still think that using $( ) to delineate start and end of
 macro blocks is a bad choice given the prevalence of ( ) in code.
s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei
The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it). Grep the Phobos sources, the only stray paren issue in it is the use of [..) in a few places in the documentation. I know it's irritating for you, but it simply is not prevalent.
Jan 02 2015
next sibling parent "John Colvin" <john.loughran.colvin gmail.com> writes:
On Friday, 2 January 2015 at 21:03:44 UTC, Walter Bright wrote:
 On 1/2/2015 1:34 AM, Andrei Alexandrescu wrote:
 On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d 
 wrote:
 I do however still think that using $( ) to delineate start 
 and end of
 macro blocks is a bad choice given the prevalence of ( ) in 
 code.
s/think/believe/ seeing as you bring awfully little evidence to back that up. -- Andrei
The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it).
Not that I know of. [ and ] are for function application/calls in mathematica and ( ) have their normal order-of-evaluation meaning.
Jan 02 2015
prev sibling parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 22:03, Walter Bright via Digitalmars-d wrote:
 The thing is, ( ) naturally pair in code, and naturally paired ( ) are not an
 issue in Ddoc. One never sees [..) in code (maybe Mathematica supports it).
Er, I believe I posted an example of just that :-) I'm entirely open to the possibility of reworking the 'uniform' function so that its bounds are indicated in a different way, but it _is_ something that currently occurs in D code (albeit not frequently).
 Grep the Phobos sources, the only stray paren issue in it is the use of [..) in
 a few places in the documentation. I know it's irritating for you, but it
simply
 is not prevalent.
I can live with you not addressing my irritation :-) But since we're discussing how to improve Ddoc, I thought it best to make sure that my issues with it were well described and understood.
Jan 02 2015
next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton 
Wakeling via Digitalmars-d wrote:
 Er, I believe I posted an example of just that :-)
error stray paren :) Uh oh, another one! It actually is kinda a pity to me that it is such a common character. In my macro expander I wrote for css uses this weird character: ¤ to start a macro. That way, I could be reasonably sure it would never show up anywhere else, simplifying the code a bit. By mapping it to F7 in my editor, it is easily available despite not being on the keyboard, and it is even in the 8-bit character set my old fonts use, so it would show up there too. Imagine if macros were: ¤“name ‗ argument ‗ arg2”! But I don't suppose we can ask people to map hotkeys to conveniently write the docs either :(
Jan 02 2015
parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 22:40, Adam D. Ruppe via Digitalmars-d wrote:
 On Friday, 2 January 2015 at 21:23:52 UTC, Joseph Rushton Wakeling via
 Digitalmars-d wrote:
 Er, I believe I posted an example of just that :-)
error stray paren :) Uh oh, another one! It actually is kinda a pity to me that it is such a common character.
/** You know the worst thing? I can't use emoticons in my ddoc ;-) This makes me very sad, and I can't even express my sadness without generating another warning. :-( Although I can, speaking tongue in cheek, see how some people might consider that a bonus. :-P */
 Imagine if macros were: ¤“name ‗ argument ‗ arg2”!


 But I don't suppose we can ask people to map hotkeys to conveniently write the
 docs either :(
Seriously: how feasible could it be to address the issue by delineating the start and end of macros by a _pair_ of characters, reducing the chance of ambiguity? $(NEW_MACRO this would be the new macro system)$
Jan 02 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 1:23 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I can live with you not addressing my irritation :-)  But since we're
discussing
 how to improve Ddoc, I thought it best to make sure that my issues with it were
 well described and understood.
I like to think I do understand the issue :-) even if I don't agree with many conclusions. An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of a rather simple piece of code.
Jan 02 2015
parent reply Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 03/01/15 01:11, Walter Bright via Digitalmars-d wrote:
 An interesting thing about Ddoc is we've gotten a heluva lot of mileage out of
a
 rather simple piece of code.
Very much so, and your point elsewhere in this thread about how valuable it is to have a built-in documentation tool is absolutely spot-on. A story to illustrate this ... A few days ago I had a go at building and installing the rust compiler (no, I'm not jumping ship, I just decided it was about time I started getting some proper hands-on understanding of some of the alternative design approaches out there:-). This uses pandoc to generate documentation, which in turn evokes pdflatex, xelatex or lualatex, with the last of these being the preferred option. One ./configure && make later, and after quite a bit of compilation, the compiler itself was built -- at which point, the makefile tried to go on and build the documentation, and failed, for reasons I still don't understand (it was the lualatex command that was failing, but the error message was not very clear in conveying what the actual problem was). OK, well, the compiler is built, right? So let's try 'make install' ... oh no, the first thing it tries to do is to complete the 'make all' target and build the docs, and of course that fails, so it doesn't install anything. :-\ Now, full credit to the rust community: they were immediately friendly and helpful in advising me how to deal with this (you can pass a flag to the ./configure command to request not to build the docs). And of course you can see this as primarily a fault in how the build system defines its targets and their dependencies. But the simple fact is, had documentation generation been built in rather than relying on 3rd-party tools, it would never have been an issue, _and_ I'd have ended up having the documentation as well as just the compiler executable and libraries.
Jan 02 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 1/2/2015 4:29 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 Now, full credit to the rust community: they were immediately friendly and
 helpful in advising me how to deal with this (you can pass a flag to the
 ./configure command to request not to build the docs).  And of course you can
 see this as primarily a fault in how the build system defines its targets and
 their dependencies.  But the simple fact is, had documentation generation been
 built in rather than relying on 3rd-party tools, it would never have been an
 issue, _and_ I'd have ended up having the documentation as well as just the
 compiler executable and libraries.
Note that Doxygen is a third party tool, it also requires a bunch more third party tools. A friend of mine bemoaned using a piece of software on Linux that required not one but multiple different and specific versions of Perl be installed in order to even build the software. Back in the early days of my compiler business, Microsoft shipped a linker on the DOS disks. So all my users had a linker. Unfortunately, the linker versions changed constantly. Eventually MS left the linker off of the DOS disks, but would include it on the disks of all sorts of other software they sold. The result was I couldn't rely on users having a linker, or any particular linker. There was a blizzard of MS linkers in the wild, each with their own features and bugs. It was a support nightmare, consuming more and more of my time. I had disks filled with my "linker collection" to test against. Finally, I got my own linker (written by Bjorn Freeman-Benson). It wasn't the greatest linker evar, but it worked, it was consistent, I knew what users had, and I could fix bugs in it rather than find workarounds. I learned over and over that controlling the full stack of what the user needed was very practical.
Jan 03 2015
prev sibling parent Joseph Rushton Wakeling via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 02/01/15 10:34, Andrei Alexandrescu via Digitalmars-d wrote:
 On 1/1/15 1:59 PM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 I do however still think that using $( ) to delineate start and end of
 macro blocks is a bad choice given the prevalence of ( ) in code.
s/think/believe/ seeing as you bring awfully little evidence to back that up.
I don't think that's fair. AFAICS the only reason there's a "Stray ')'" issue to be concerned about is because the ) character is used to mark the end of a Ddoc macro. OK, I accept that it's rare that you get a ) without it being preceded by an opening ). But there are surely much rarer (in code) characters that could have been used, or the end-of-macro marker could have been chosen to be something completely unambiguous like $) or )$.
Jan 02 2015
prev sibling parent "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 20:15:55 UTC, Walter Bright wrote:
 A lot of the complaints about Ddoc clearly stem from people not 
 realizing they can create their own macros. It's like not
On the contrary, the complaint is that you can create your own macros and loose the semantics of the markup. I looked at the possibility to create a high quality javascript based front end to phobos documentation last year and the messy macro-markup/generated html killed the project before it got started.
 Math notation uses a ton of special characters, it's one of the 
 reasons why Unicode was invented. Limiting yourself to 
 non-Markdown ascii is extremely limiting. Heck, look at this:

 https://www.google.com/search?q=latex+math+symbols&biw=1282&bih=897&tbm=isch&tbo=u&source=univ&sa=X&ei=pqqlVLbcM5TkoATv9oGABg&sqi=2&ved=0CDQQsAQ
LaTeX is not a standard. It is a quick'n'dirty macro-hack over TeX. If you want to mark up math, use HTML5's MathML and use MathJax for browsers that don't fully support it. http://www.w3.org/Math/ http://www.mathjax.org/sponsors/
Jan 02 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 6:00 AM, Joseph Rushton Wakeling via Digitalmars-d wrote:
 On 01/01/15 13:11, Walter Bright via Digitalmars-d wrote:
 Please show some context where that frequently happens for you.

 I see some instances in Phobos, but they are all of the form:

    [x .. y$(RPAREN)

 which would be better coded as:

    $(INTERVAL x .. y)

    INTERVAL=[$0$(RPAREN)
See, this is my point. $(INTERVAL x .. y) is, to my mind, less clear to read _in the source_ than [x, y). If I read $(INTERVAL x .. y) then, OK, I will grasp it's an interval between x and y. But is it the closed interval [x, y], one of the half-open intervals (x, y] or [x, y) or the open one (x, y) ... ? I need that kind of precision to document the kind of code I'm writing (including phobos contributions), and I would like to be able to read and write with that precision explicitly in the source. If I need to use a macro definition, then the reader has to look up that definition, and you just _know_ that people are going to use those macros incorrectly, e.g. if we suppose that INTERVAL is [x, y), then people will use it in circumstances where they mean [x, y] or (x, y) or whatever. Yes, I could use a right-bracket UTF8 character, but that's finnicky and annoying (and potentially runs into other problems for readers, e.g. what if someone copy-pastes my ddoc source into a non-UTF8 email?). And yes, I could use [x, y[ or ]x, y] or ]x, y[, but that notation is more specialist and likely to be confusing to readers. I'm sorry, but I can't see it as anything other than a serious flaw of ddoc that a super-common character in both code and mathematics has problems being used, as itself, inside the documentation markup :-)
"Serious flaw" sounds like a serious exaggeration. The notation "[x, y)" has unpaired parens. Any tool relying on pairing parens is going to have difficulty with it. This is exactly the kind of argument that diminishes the value of an otherwise great notion - that ddoc needs improvements addressing pain points with it. Andrei
Jan 02 2015
prev sibling next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 12/31/14 4:50 PM, Andrei Alexandrescu wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax we're looking
 at doing something about it. Please discuss any ideas you might have
 here. Thanks!

 One simple starter would be to allow one escape character, e.g. the
 backtick (`), as a simple way to expand macros: instead of $(MACRO arg1,
 arg2) one can write `MACRO arg1, arg2`.


 Andrei
1. Add "* foo" syntax for lists 2. Add **bold** and __bold__ 3. Add *italic* and _italic_ 4. Make `some text` automatically link to other D code. For example `std.algorithm.any` would automatically link to http://dlang.org/phobos/std_algorithm.html#.any . This must work for types, functions, etc. If it doesn't resolve to a symbol, just put it inside <code>...</code> 5. Make [text](url) denote a link. 6. Remove macros. Walter said: "Oh, Markdown can't be used to change the typography, generate TOCs, etc.?". Well, you don't need to do those things. Changing the typography will make it look ugly. You need a TOC? That's the job of the documentation tool (the binary), not the documentation syntax. Basically, use Markdown :-) Keep DDoc as it is now. Use it for your website if you want, to write books or whatever. But for documentation don't use it as it is. There's no need for macros. There's no need to generate JSON, XML, YAML, PDF or anything other than HTML, which is quite universal and accessible now. I repeat: keep DDoc, enhance it, use it as dog food for your websites, books, etc. Use something simpler and less powerful for documenting types and functions.
Jan 01 2015
next sibling parent reply "Dicebot" <public dicebot.lv> writes:
My top list of md shortcuts for "casual" documentation:

1. `code`

2. * lists

    headers
3. =======

    ----------------------
4. | tables | that are  |
    ----------------------
    | pretty | in source |
    ----------------------
Jan 01 2015
next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 15:09:22 UTC, Dicebot wrote:
 My top list of md shortcuts for "casual" documentation:

 1. `code`
https://github.com/D-Programming-Language/dmd/pull/4228 That's by far my #1 syntax-wise, and since my implementation uses the existing code, it will be relevant semantically too at some point - when the code examples get cross-referencing, inline bits will too, so we can link with that too (probably*). The others aren't even really important to me at all; $(HEADER foo) or Foo: both look good enough for me. Tables might be nice, but overall aren't that big of a deal to me. * A potential problem running it through that D highlighter is not all `code` is necessarily D code. But most of it is and the rest still seems to work well enough - my xml tag test passed - so I think it is the biggest win for ddoc.
Jan 01 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-01 16:09, Dicebot wrote:
 My top list of md shortcuts for "casual" documentation:

 1. `code`

 2. * lists

     headers
 3. =======
I prefer the hashtag syntax: # header ## header -- /Jacob Carlborg
Jan 01 2015
parent ketmar via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, 01 Jan 2015 21:51:06 +0100
Jacob Carlborg via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 On 2015-01-01 16:09, Dicebot wrote:
 My top list of md shortcuts for "casual" documentation:

 1. `code`

 2. * lists

     headers
 3. =3D=3D=3D=3D=3D=3D=3D
=20 I prefer the hashtag syntax: =20 # header =20 ## header
there is nothing wrong in supporting both. ;-)
Jan 01 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 1/1/2015 7:09 AM, Dicebot wrote:
     headers
 3. =======
headers:
Jan 01 2015
parent reply "Dicebot" <public dicebot.lv> writes:
On Thursday, 1 January 2015 at 21:52:59 UTC, Walter Bright wrote:
 On 1/1/2015 7:09 AM, Dicebot wrote:
    headers
 3. =======
headers:
Wait what? It isn't formatted as <hX> as far as I can see. How exactly this is supposed to work?
Jan 06 2015
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 6 January 2015 at 15:00:06 UTC, Dicebot wrote:
 Wait what? It isn't formatted as <hX> as far as I can see. How 
 exactly this is supposed to work?
That makes a DDOC_SECTION. The default macro is DDOC_SECTION_H = $(B $0)$(BR) DDOC_SECTION = $0$(BR)$(BR) But if these macros were better, it could be a <header><hx>$0</hx></header> where the x is the right level. I might spend a day revamping these macros eventually, the default ones are so bad, they make poor html and hide some of ddoc's own features.
Jan 06 2015
parent reply "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Tuesday, 6 January 2015 at 15:13:00 UTC, Adam D. Ruppe wrote:
 But if these macros were better, it could be a 
 <header><hx>$0</hx></header> where the x is the right level.
The "header" element belongs in a sectioning element and the first heading in each section should be "h1": <section><h1>...</h1> <section><h1>...</h1> </section> </section>
Jan 06 2015
parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Tuesday, 6 January 2015 at 15:17:32 UTC, Ola Fosheim Grøstad 
wrote:
 The "header" element belongs in a sectioning element
Right, DDOC_SECTION is a <section> and the first element of it that ddoc outputs is is a DDOC_SECTION_H - a section header. We could debate the specific contents of it, h1 works for me but i kinda think h1 should be the outer aggregate name and then h2 if it is a nested member... but regardless, ddoc doesn't let you change the macros based on nesting anyway, but it does have the concept of grouped sections with headers.
Jan 06 2015
parent "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Tuesday, 6 January 2015 at 15:31:52 UTC, Adam D. Ruppe wrote:
 could debate the specific contents of it, h1 works for me but i 
 kinda think h1 should be the outer aggregate name and then h2 
 if it is a nested member... but regardless, ddoc doesn't let 
 you change the macros based on nesting anyway, but it does have 
 the concept of grouped sections with headers.
Well, either way, if ddoc is worth fixing it would be a good idea to stick to HTML5 spec since they eventually managed to clean up the header mess of HTML4 (somewhat). http://www.w3.org/TR/html5/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements
Jan 06 2015
prev sibling next sibling parent reply "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig 
wrote:
 it is. There's no need for macros. There's no need to generate 
 JSON, XML, YAML, PDF or anything other than HTML, which is 
 quite universal and accessible now.
You only need to generate XML with high quality semantic markup for programming languages. From XML to other formats there are more options than this thread can handle... The semantics of HTML is too weak to build high quality cross-library-indexing and precise search rankings.
Jan 01 2015
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 1/1/15 1:23 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
<ola.fosheim.grostad+dlang gmail.com>" wrote:
 On Thursday, 1 January 2015 at 15:01:13 UTC, Ary Borenszweig wrote:
 it is. There's no need for macros. There's no need to generate JSON,
 XML, YAML, PDF or anything other than HTML, which is quite universal
 and accessible now.
You only need to generate XML with high quality semantic markup for programming languages. From XML to other formats there are more options than this thread can handle... The semantics of HTML is too weak to build high quality cross-library-indexing and precise search rankings.
What's cross-library-indexing? You mean show documentation for many libraries at once?
Jan 01 2015
parent reply "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig 
wrote:
 What's cross-library-indexing? You mean show documentation for 
 many libraries at once?
Yes, many libraries, source code with builtin links, links to github with line numbers, docs for other languages when D wrappers are provided. The ideal is to propagate as much useful information as possible to a normalized universal format that makes it easy to build intelligent information systems using some kind of deduction. You should generate a database, not a document. HTML is underpowered and assumes that domain specific semantical information is encoded in a different layer like RDF, but that leads to solutions that are overly complicated compared to a domain specific XML format.
Jan 01 2015
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
On 1/1/15 2:35 PM, "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= 
<ola.fosheim.grostad+dlang gmail.com>" wrote:
 On Thursday, 1 January 2015 at 17:19:09 UTC, Ary Borenszweig wrote:
 What's cross-library-indexing? You mean show documentation for many
 libraries at once?
Yes, many libraries, source code with builtin links, links to github with line numbers, docs for other languages when D wrappers are provided. The ideal is to propagate as much useful information as possible to a normalized universal format that makes it easy to build intelligent information systems using some kind of deduction. You should generate a database, not a document. HTML is underpowered and assumes that domain specific semantical information is encoded in a different layer like RDF, but that leads to solutions that are overly complicated compared to a domain specific XML format.
I really don't understand why you say that. I just started writing a documentation generator for the Crystal programming language. http://crystal-lang.org/api/ You can read about its features here: http://crystal-lang.org/2014/12/31/crystal-0.5.6-release.html Now, I go here http://dlang.org/phobos/std_file.html and I can't believe that after 10+ years of development, D documentation still doesn't have a basic feature like inter-linking between types (I even once submitted a PR but it wasn't accepted because other code was written on top of it and then the merge was hard to do). For example: http://dlang.org/phobos/std_file.html#.timeLastModified I should be able to click SysTime and go to that type definition. But, DDoc can generate Latex. Then, take a look at Rust. Guess what they use for their documentation? Markdown! Here's a web framework called Iron: http://ironframework.io/ Here are the API docs: http://ironframework.io/doc/iron/ Let's take a look at enum.Method: http://ironframework.io/doc/iron/method/enum.Method.html See that red "String" text? Click it and it takes you here: http://doc.rust-lang.org/nightly/collections/string/struct.String.html Wow! It took you to the String definition in an entirely different host! Back to Crystal's docs, below every method there's a "View Source" link that takes you to that code in GitHub. No such thing in D. Note that all of this was done with just Markdown (HTML) and by making the documentation generator understand and use the language as much as possible, something with DDoc doesn't do. I once submitted a PR to fix that, but it was ignored. I would suggest D to use a simple language to write the documentation, and then a powerful tool that understands the semantics of the language and allows you to generate good looking, easily browsable documentation. Neither JSON, XML, YAML or macros are needed for that.
Jan 01 2015
next sibling parent reply "JN" <666total wp.pl> writes:
On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig 
wrote:
 and I can't believe that after 10+ years of development, D 
 documentation still doesn't have a basic feature like 
 inter-linking between types (I even once submitted a PR but it 
 wasn't accepted because other code was written on top of it and 
 then the merge was hard to do). For example:

 http://dlang.org/phobos/std_file.html#.timeLastModified

 I should be able to click SysTime and go to that type 
 definition.
Don't know why it's not working for Phobos, but vibe.d documentation seems to have clickable types (http://vibed.org/api/)
Jan 01 2015
parent "Dicebot" <public dicebot.lv> writes:
On Thursday, 1 January 2015 at 18:24:47 UTC, JN wrote:
 I should be able to click SysTime and go to that type 
 definition.
Don't know why it's not working for Phobos, but vibe.d documentation seems to have clickable types (http://vibed.org/api/)
vibe.d docs are generated using custom tool by Sonke, ddox, not the stock DDOC. Among other things it does automatically search for cross-references when generating the docs, no additional markup required afair.
Jan 01 2015
prev sibling parent reply "Ola Fosheim =?UTF-8?B?R3LDuHN0YWQi?= writes:
On Thursday, 1 January 2015 at 18:15:10 UTC, Ary Borenszweig 
wrote:
 I really don't understand why you say that.
Because it is true? :-) Documents are old fashion, what you want is an interactive frontend to an information database.
 I would suggest D to use a simple language to write the 
 documentation, and then a powerful tool that understands the
You sometimes need to add annotations to enhance what can be deduced. That is obvious for dynamic languages (so you have JSDoc, which is kinda like JavaDoc/Doxygen), but it also holds for languages with static typing.
Jan 01 2015
parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Thursday, 1 January 2015 at 20:00:12 UTC, Ola Fosheim Grøstad 
wrote:
 Because it is true? :-) Documents are old fashion, what you 
 want is an interactive frontend to an information database.
One thing I would like to do is add $(TAGS sorting, searching) etc to functions where applicable which can be linked to auto-generated lists and it can do categorization tables, etc. I did a proof of concept of this years ago but there wasn't much interest at the time. (Arguably, now we could just group tagged functions into a submodule instead...)
Jan 01 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 7:01 AM, Ary Borenszweig wrote:
 1. Add "* foo" syntax for lists
Currently ddoc ignores leading * so we'd need another character if at all.
 2. Add **bold** and __bold__
How necessary are these?
 3. Add *italic* and _italic_
Maybe these would be more often useful.
 4. Make `some text` automatically link to other D code. For example
 `std.algorithm.any` would automatically link to
 http://dlang.org/phobos/std_algorithm.html#.any . This must work for
 types, functions, etc. If it doesn't resolve to a symbol, just put it
 inside <code>...</code>
Nice.
 5. Make [text](url) denote a link.
Nice.
 6. Remove macros.
We probably can't do that. Thanks! Andrei
Jan 02 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-02 10:10, Andrei Alexandrescu wrote:
 On 1/1/15 7:01 AM, Ary Borenszweig wrote:
 1. Add "* foo" syntax for lists
Currently ddoc ignores leading * so we'd need another character if at all.
A dash. -- /Jacob Carlborg
Jan 02 2015
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2014-12-31 20:50, Andrei Alexandrescu wrote:

 One simple starter would be to allow one escape character, e.g. the
 backtick (`), as a simple way to expand macros: instead of $(MACRO arg1,
 arg2) one can write `MACRO arg1, arg2`.
I don't see how that would improve anything, at all. -- /Jacob Carlborg
Jan 01 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2014-12-31 20:50, Andrei Alexandrescu wrote:

 In wake of the recent discussions on improving ddoc syntax we're looking
 at doing something about it. Please discuss any ideas you might have
 here. Thanks!
I think there are two big issues with Ddoc: its syntax and its lack of functionality. I think the major reason for these issues is that Ddoc is a general text macro tool. Personally I would just throw out Ddoc and start completely fresh, I know that is too extreme so I'm not suggesting that. I think the solution is to use Ddoc as it is today, with full support for Github flavored Markdown added and a couple of other enhancements. The reason is listed below: I'm not going to argue so much about the syntax since many others have already done so. The functionality that I feel is missing: * Automatically generating cross-references * Inhering documentation. Methods that override some other method should automatically inherit the documentation of the overridden method, unless there's already documentation present for that method or explicitly disable the inheritance with a command. * A list of summary with all symbols should be automatically generated for a module * Documentation for private symbols should be generated but hidden by default in the output with a button to show them * A nice tree view with all packages and modules with filter for all symbols * Automatically create links to the source code for each symbol. This could either be to syntax highlighted source code Ddoc generates or to Github. There could be a flag (or some other way) to specify which Github project to link to * Simplified signatures. Template constraints and default values which are special symbols like __FILE__ or __LINE__ should be hidden by default The following should automatically be generated for a given class: * Links to all base classes and interfaces of a class * Links to all symbols from all base classes and interfaces * Links to all known subclasses That are just a couple of suggestions. Just take a look at some existing documentation for other language and see what's missing [1], [2]. [1] http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable -- /Jacob Carlborg
Jan 01 2015
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/1/15 2:38 PM, Jacob Carlborg wrote:
 On 2014-12-31 20:50, Andrei Alexandrescu wrote:

 In wake of the recent discussions on improving ddoc syntax we're looking
 at doing something about it. Please discuss any ideas you might have
 here. Thanks!
I think there are two big issues with Ddoc: its syntax and its lack of functionality. I think the major reason for these issues is that Ddoc is a general text macro tool. Personally I would just throw out Ddoc and start completely fresh, I know that is too extreme so I'm not suggesting that.
Sounds great, thanks.
 I think the solution is to use Ddoc as it is today, with full support
 for Github flavored Markdown added and a couple of other enhancements.
Full support would probably break a lot of extant documentation.
 The reason is listed below:

 I'm not going to argue so much about the syntax since many others have
 already done so.

 The functionality that I feel is missing:

 * Automatically generating cross-references
Nice.
 * Inhering documentation. Methods that override some other method should
 automatically inherit the documentation of the overridden method, unless
 there's already documentation present for that method or explicitly
 disable the inheritance with a command.
Nice!
 * A list of summary with all symbols should be automatically generated
 for a module
Shouldn't we leave that to postprocessing?
 * Documentation for private symbols should be generated but hidden by
 default in the output with a button to show them
Nice.
 * A nice tree view with all packages and modules with filter for all
 symbols
This seems like a matter of styling, not functionality.
 * Automatically create links to the source code for each symbol. This
 could either be to syntax highlighted source code Ddoc generates or to
 Github. There could be a flag (or some other way) to specify which
 Github project to link to
Nice.
 * Simplified signatures. Template constraints and default values which
 are special symbols like __FILE__ or __LINE__ should be hidden by default
Nice.
 The following should automatically be generated for a given class:

 * Links to all base classes and interfaces of a class
 * Links to all symbols from all base classes and interfaces
 * Links to all known subclasses

 That are just a couple of suggestions. Just take a look at some existing
 documentation for other language and see what's missing [1], [2].

 [1]
 http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html


 [2] http://www.scala-lang.org/api/current/#scala.collection.Iterable
Looks like a great list, thanks. Andrei
Jan 02 2015
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-01-02 10:40, Andrei Alexandrescu wrote:

 * A list of summary with all symbols should be automatically generated
 for a module
Shouldn't we leave that to postprocessing?
No, why would we do that? I want be able to easily generate good documentation. If something requires an extra step to make it better it will not be as easy. I also think it will be easier for Ddoc to do this than doing it in a postprocess step: * Ddoc will already have all the information available * The postprocessing tool will need to parse the output to get this information * If Ddoc is supposed to be designed for multiple output formats the postprocessing tool need to be able to handle that as well. Also, it should be possible to disable this if it's not desired.
 * A nice tree view with all packages and modules with filter for all
 symbols
This seems like a matter of styling, not functionality.
I don't see how this can be a matter of styling if it should support filtering. I'm thinking of something like the Scala documentation I linked to [1]. It has something more like a flat list with different sections. It doesn't matter if you call it styling of functionality ;) I still would like to see it in the default output. [1] http://www.scala-lang.org/api/current/#scala.collection.Iterable -- /Jacob Carlborg
Jan 02 2015
prev sibling parent reply "Mathias LANG" <geod24 gmail.com> writes:
On Friday, 2 January 2015 at 09:40:45 UTC, Andrei Alexandrescu 
wrote:
 * Automatically generating cross-references
Nice.
https://github.com/rejectedsoftware/ddox/blob/master/README.md#ddox-documentation-engine I'm still wondering why it's not shipped with DMD.
 * A list of summary with all symbols should be automatically 
 generated
 for a module
Shouldn't we leave that to postprocessing?
Agree. It would break one of the goal of Ddoc (It does not repeat information that the compiler already knows from parsing the code.) Note that ddox also do that http://vibed.org/api/vibe.core.concurrency/ . It's not perfect, but you're sure it's always up to date, and is way more readable than what Phobos is currently doing with BOOKTABLE.
 * Documentation for private symbols should be generated but 
 hidden by
 default in the output with a button to show them
Nice.
I don't see it being useful for Phobos, or any other library. Have one doc with the public API available, optionally another one for the framework/lib devs (but those often prefers the code).
 * Simplified signatures. Template constraints and default 
 values which
 are special symbols like __FILE__ or __LINE__ should be hidden 
 by default
Nice.
Strongly agree for the constraints. For __FILE__ & __LINE__, what would it affects ? I can think of exception-related stuff, anything else ? Also, I was very puzzled with $(D) when I was looking for the right way to use it. I think the answer is relevent to this dicussion: https://github.com/rejectedsoftware/vibe.d/pull/875 Most of the issues, IMO, are stylistic. We should firstly work on improving the output, rather than introduce new syntax. Also, documentation is much more subjective than code (just like success and adult content :o) ). We could introduce control flags to ensure some minima are met, examples that come to mind are: --ddoc-werror (build failure on doc warning), --ddoc-require=params,returns (require Params and Returns sections to be defined, those can be empty for trivial functions), --ddoc-document=public (require every public symbols to be documented).
Jan 02 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-01-02 15:12, Mathias LANG wrote:

 I don't see it being useful for Phobos, or any other library. Have one
 doc with the public API available, optionally another one for the
 framework/lib devs (but those often prefers the code).
I see that being useful for any open source library. I don't mind having an option to enable/disable generating documentation for private symbols.
 Strongly agree for the constraints. For __FILE__ & __LINE__, what would
 it affects ? I can think of exception-related stuff, anything else ?
A perfect example where this is a big issue is the upcoming std.logger [1]. It looks absolutely horrible. Every logging functions has five of these arguments and in 99.99% of the cases you do not need to pass these arguments manually. [1] http://burner.github.io/phobos/phobos-prerelease/std_logger_core.html -- /Jacob Carlborg
Jan 03 2015
prev sibling parent "Ulrich =?UTF-8?B?S8O8dHRsZXIi?= <kuettler gmail.com> writes:
On Thursday, 1 January 2015 at 22:38:05 UTC, Jacob Carlborg wrote:
 That are just a couple of suggestions. Just take a look at some 
 existing documentation for other language and see what's 
 missing [1], [2].

 [1] 
 http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.jdt.doc.isv%2Freference%2Fapi%2Foverview-summary.html

 [2] 
 http://www.scala-lang.org/api/current/#scala.collection.Iterable
To me Ddoc documentation is different from javadoc-flavored documentation and rightfully so. Ddoc is module centered with some nice introduction at the top and includes helpful unittest examples, too. Where OO-centered reference documentation puts comments to all classes and methods, Ddoc allows (and encourages) documentation that can be read to learn about the module. You know, I am your average troll, spending my time reading documentation. Pure reference documents are no fun to read.
Jan 02 2015
prev sibling parent "Martin Nowak" <code dawg.eu> writes:
On Wednesday, 31 December 2014 at 19:50:49 UTC, Andrei 
Alexandrescu wrote:
 Hello,


 In wake of the recent discussions on improving ddoc syntax 
 we're looking at doing something about it. Please discuss any 
 ideas you might have here. Thanks!
Quite often pull requests for the changelog [0] contain unbalanced parens. Maybe we can replace some of the parens with indent level nesting? Example: $(BUGSTITLE Language Changes, $(LI $(RELATIVE_LINK2 asm-attributes, Asm statements can now be used in pure nothrow nogc trusted code.)) ) $BUGSTITLE Language Changes $LI $RELATIVE_LINK2 asm-attributes, Asm statements can now be used in pure nothrow nogc trusted code. An indented block is the last argument to a macro (BUGSTITLE). A macro without parens has all of it's arguments on the same line. Commas belong to the innermost macro (RELATIVE_LINK2). Parens can still be used. [0]: https://github.com/D-Programming-Language/dlang.org/blob/master/changelog.dd
Jan 02 2015