Improving ddoc

[Andrei Alexandrescu via Digitalmars-d]

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