On 1/7/15 1:14 AM, Jacob Carlborg wrote:
On 2015-01-06 23:43, Andrei Alexandrescu wrote:
Let's crowdsource the review. Please check the entries linked from here:
http://dlang.org/library/index.html.
What about all those suggestions in the thread "Improving ddoc" [1]?
Some of those suggestions might require to redesign the documentation.
Is it still worth updating to the new layout?
[1] http://forum.dlang.org/thread/[email protected]
My summary of that discussion follows. There were quite a few radical
suggestions, some of which were interesting but that seemed to entail a
lot of work compared to the reaped benefits. (I have to say it was quite
fun to re-read the whole thread and see Walter calmly dismantling some
of the less valid arguments.)
The suggestions I think are actionable:
* Detect `xyz` and replace it with $(BACKQUOTED xyz), pull request in
progress at https://github.com/D-Programming-Language/dmd/pull/4228.
Maybe detect some __underscored__ or **bolded** words similarly.
* Better whitespace control
* Macros that expand without $() - possibly an extension of ESCAPES.
* Add a subset of markdown on top of ddoc (details unclear).
* Make [text](url) denote a link.
* Hashtags for headings
* Generate cross-references automatically.
* Clever automatic linking or embedding of overridden functions docs.
* Automatic links to source code.
* Simplified signatures (__FILE__ etc, template constraints)
* Replace some of the parens with indent nesting.
* Not in that thread, but it was somewhere proposed that we use
recursive macros for nice $(LIST item one, two, three).
What did I miss? Among the more radical proposals:
* Use markdown
* Use doxygen
Again, it seems to me these would yield little benefit for the effort
even assuming perfect execution.
Andrei
