[Dlang-internal] Potential changes to DDoc

[rjframe]

On Wed, 24 Jan 2018 16:55:12 -0700, David Gileadi wrote:

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

I actually think supporting multiple methods means the cognitive load may 
be reduced for people that don't already know Markdown. When I first read 
some Markdown spec, I quickly realized I could ignore the fact that there 
are three ways to do a bulleted list and just do what I already do - if 
there was only one way to do it, I'd have to remember that one way (which 
would probably not be _my_ way). Reading someone else's Markdown is still 
easy - '+' for bulleted lists is still obviously a list, even though I use 
'*'.

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

Agreed. It would also be easy to go back and add the alternative syntax 
later though, right? Start with one way to do it, and if/when people 
complain, add the alternative methods as needed.

>>  > 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.
 
Another advantage to supporting a variety of features is that support for 
making README.md the generated index.html becomes possible (like Doxygen 
can do). Supporting a limited subset greatly restricts that ability, as 
the README would have to limit itself to the intersection of [GH-]Markdown 
and DDocDown(?).