Improving ddoc

[Ary Borenszweig via Digitalmars-d]

On 12/31/14 4:50 PM, Andrei Alexandrescu wrote:
> Hello,
>
>
> In wake of the recent discussions on improving ddoc syntax we're looking
> at doing something about it. Please discuss any ideas you might have
> here. Thanks!
>
> One simple starter would be to allow one escape character, e.g. the
> backtick (`), as a simple way to expand macros: instead of $(MACRO arg1,
> arg2) one can write `MACRO arg1, arg2`.
>
>
> Andrei

1. Add "* foo" syntax for lists
2. Add **bold** and __bold__
3. Add *italic* and _italic_
4. Make `some text` automatically link to other D code. For example 
`std.algorithm.any` would automatically link to 
http://dlang.org/phobos/std_algorithm.html#.any . This must work for 
types, functions, etc. If it doesn't resolve to a symbol, just put it 
inside <code>...</code>
5. Make [text](url) denote a link.
6. Remove macros. Walter said: "Oh, Markdown can't be used to change the 
typography, generate TOCs, etc.?". Well, you don't need to do those 
things. Changing the typography will make it look ugly. You need a TOC? 
That's the job of the documentation tool (the binary), not the 
documentation syntax.

Basically, use Markdown :-)

Keep DDoc as it is now. Use it for your website if you want, to write 
books or whatever. But for documentation don't use it as it is. There's 
no need for macros. There's no need to generate JSON, XML, YAML, PDF or 
anything other than HTML, which is quite universal and accessible now.

I repeat: keep DDoc, enhance it, use it as dog food for your websites, 
books, etc. Use something simpler and less powerful for documenting 
types and functions.