[Dlang-internal] Potential changes to DDoc

[Walter Bright]

On 1/22/2018 10:14 AM, David Gileadi wrote:
> Regarding multiple ways of doing headings, thematic breaks, unordered lists, 
> etc. I'd really like to support as much standard Markdown as possible. My 
> rationale is:

Thanks for the reasonable approach, but I disagree and will try to explain.

Markdown supports multiple ways of doing things because (I presume) it's trying 
to accommodate multiple diverse existing markdown schemes. We do not have that 
issue. When there are multiple ways to do X, then inevitably the arguments come 
as to which is the "approved" method. I do not wish to expend any time debating 
potayto-potahto. I've had plenty enough of them in my career :-)

Having multiple equivalent ways to do something increases the size of the 
documentation, the size of the test suite, the potential for bugs, and the 
cognitive load on the user.

Just pick the most reasonable method, and do that.

(For example, using --- or ``` or ~~~ or 4 space indent for code blocks. Gahhh. 
Just use ---, because it works and looks fine, and we already do it.)


 > 1. It's easier for people who already know Markdown to use when the list of
 > unsupported features is small.

Markdown is so trivial I can't believe this is an issue. (I myself use different 
markdowns on different systems. The differences are simply not a problem.)


 > 2. There is already harboured-mod which melds Ddoc and Markdown, and I've been
 > trying to match its list of differences from vanilla Markdown [1] so that it's
 > straightforward to switch between DDoc generators.

What is proposed here shouldn't make life difficult for Habored-mod.


 > 3. The additional code for implementing the same feature with different
 > triggering characters is small.

Features should not be added because of "why not" or "they're easy to 
implement". They need to be justified. Ideally, a language should be a very 
small set of orthogonal building blocks from which anything can be constructed, 
not a panoply of marginally different overlapping features.