[Dlang-internal] Potential changes to DDoc

[John Gabriele]

On Tuesday, 23 January 2018 at 03:23:37 UTC, Walter Bright wrote:
> 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.)

The prime directive of markdown is to be easy to *read* --- not 
necessarily easy to write. That is: to look good/natural, without 
looking hardly at all like markup. For example, you go through 
the extra trouble to indent subsequent lines in list items:

   * Some multi-line list item
     with subsequent lines indented
     to look good.

   * Second item. Lorem ipsum dolor
     sit amet, consectetur adipiscing
     elit,sed do eiusmod tempor.

instead of:

* Some multi-line list item
with subsequent lines not indented.
Doesn't look great.

* Second item. Lorem ipsum dolor
sit amet, consectetur adipiscing
elit,sed do eiusmod tempor.

because the former is much easier on the eyes. Though, both do 
indeed work...

There are two distinct reasons why Markdown supports multiple 
ways of doing some things:

  1. Because markdown also tries to be accomodating. For example, 
it allows some sloppy input and things still work; like allowing 
list items to have *up to* that 4 space indent, rather than 
*requiring* 4. Or allowing two _types_ of *italics*, **and** 
__bold__. Or all the different ways to make an `<hr/>`, or the 
three different list item markers. These accomodations are more 
for the occasional or even accidental markdown user, or for users 
with _olde_ typing habits that die hard. (Admittedly, some of 
them *do* sometimes make special cases look a little prettier.)

  2. As a compromise, to make things more convenient for people 
who use it all the time, but at the expense of it not looking 
*quite* as good. For example, allowing fenced (delimited) code 
blocks instead of only the indented code blocks (fenced are 
easier to copy/paste into). ATX-style headers are faster to type 
(and easier to autogenerate as well). "Lazy-style" list items (as 
the 2nd example above shows (and this current list item too) --- 
where subsequent lines aren't indented) and blockquotes.

It sounds like the kind of multiple-ways-of-doing-things you want 
to avoid is the former (the accomodations), not the latter (the 
conveniences).