[Dlang-internal] Potential changes to DDoc

[David Gileadi]

On 1/22/18 8:23 PM, 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 :-)

Markdown doesn't support multiple ways of doing things because of trying 
to accommodate multiple Markdown schemes--from the beginning the John 
Gruber designed the format with multiple ways of doing things [1]. As he 
says in his philosophy section, "Markdown is intended to be as 
easy-to-read and easy-to-write as is feasible" and "the single biggest 
source of inspiration for Markdown’s syntax is the format of plain text 
email." He intended it to support things that people already do, like 
start bullet lists with - or * or +, and have it just work.

We can pick out parts of Markdown to support, but it won't be true to 
the intended vision of Markdown and it will have the effect of annoying 
people who know Markdown because when they try to write it the way 
they're used to it won't do what they expect ("wait, I can only use + 
for lists? I always use dashes! And why aren't my headers working?") [2].

If we go this route then we shouldn't say we support Markdown.

> 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.

These things are all true.

I haven't yet made the corresponding changes to the documentation, but 
my intent is to show a few examples of Markdown like CommonMark's (very 
short) help page does [3], provide a link for more information about 
Markdown, and a (preferably short) list of items DDoc Markdown doesn't 
support, along with the reasons why.

If instead we support just few Markdown features, I believe we should 
avoid saying we support Markdown at all. This would probably result in 
somewhat longer documentation describing each feature.

As for the test suite, as I mentioned I'm generating it from 
CommonMark's test suite. This allows it to be comprehensive and accurate 
without building it from scratch. It also reduces the potential for 
bugs, although I can't argue with the fact that more code == more bugs.

The cognitive load on users depends on what kind of users we're talking 
about. For those who don't know Markdown the load is indeed greater, 
although Markdown's focus on supporting things people already do with 
plain text reduces its impact.

However for people who already know Markdown (and I suspect that's most 
developers who have used things like Github), the fewer standard 
Markdown features we support the greater the cognitive load is. Those 
developers will have to keep in mind both the standard features of 
Markdown and the list of things DDoc's Markdown doesn't support. The 
shorter we make that second list, the smaller the cognitive load.

>  > 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.

No, but it would make life more difficult for someone who currently 
generates their documents with harbored-mod and would like to switch to 
built-in DDoc instead. However this is probably not a large audience.

>  > 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.

I agree. I mentioned it because I feel strongly about trying to support 
as much standard Markdown as we can, for the reasons I mentioned 
earlier. One argument against supporting many Markdown features is the 
additional code and its associated burdens, and I was attempting to 
argue in advance that it doesn't add large amounts of additional code.


[1] https://daringfireball.net/projects/markdown/syntax, see the two 
different styles of headers, two styles of links, and different 
triggering characters for list items and horizontal rules.

[2] I say this while fully aware that there are parts of Markdown that 
we won't support. However not supporting a feature because it conflicts 
with existing features is different than not supporting it for 
philosophical reasons.

[3] http://commonmark.org/help/