Ready to make page-per-item ddocs the default?

[Andrei Alexandrescu via Digitalmars-d]

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/m81k2p$k47$1@digitalmars.com

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