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.
