[Dlang-internal] Potential changes to DDoc
John Gabriele
jgabriele at fastmail.fm
Tue Jan 23 17:07:41 UTC 2018
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).
More information about the Dlang-internal
mailing list