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.



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.



 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.




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.



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, 

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 



 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 

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



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:





-- 
/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

=20



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:



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:



 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

 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