On 12/28/2014 7:57 AM, Ary Borenszweig wrote:
I think it would be much better to use Markdown for the documentation, as it is
so popular and easy to read (although not that easy to parse).
I don't want to use Markdown. The D wiki uses it, and once you step outside of
the trivial, you have to insert html that is crippled in various erratic ways.
Any non-trivial documentation winds up being one ugly mo-fo.
Then it would be awesome if the documentation could be smarter, providing
semi-automatic links. For example writing "#string.join" would create a link to
that function in that module (the $(XREF ...) is very noisy and verbose).
$(XREF string, join)
#string.join
Sorry, I don't see a big issue. Trouble with the latter, of course, is what
happens when you want '#' to appear in the display? Then you need some sort of
escape mechanism. And then special syntax for every markup element. Bleh, I
don't think there's a net improvement.
