[Dlang-internal] Potential changes to DDoc

[Sebastian Wilzbach]

On 2018-01-27 09:08, Mike Parker via Dlang-internal wrote:
> On Friday, 26 January 2018 at 07:11:33 UTC, Walter Bright wrote:
>> On 1/25/2018 7:59 AM, John Gabriele wrote:
>>> What do you think about supporting two modes of operation:
>> 
>> Multiple modes makes things even worse :-(
> 
> As a matter of practicality, and from a maintenance cost perspective,
> I agree with everything you've said in this thread. From a "first five
> minutes" point of view, I have to disagree.
> 
> Supporting a half-assed "Markdownish" syntax, where some Markdown bits
> work and others don't, where fenced code blocks require "---" and
> backticks are unsupported, is bound to be a point of frustration to
> someone giving D a legitimate look.
> 
> This is one of those ecosystem things like IDE support that maybe by
> itself won't be enough to turn people away, but on a list of cons it
> will carry weight. If we're going to support Markdown in Ddoc, then we
> ought to really support Markdown. Failure to go whole hog on this is
> just going to create one more pain point for people motivated to look,
> but not motivated to leave their comfort zone.
> 
> And here we've got someone who's not only willing to do it, but
> actually implementing it! We ought to run with it.

I can't agree more with your words, Mike.
DDoc is already super-hard for people to get used to as it's very 
un-intuitive and relies on many under-documented features.
My vote is fully on "implement as much Markdown as possible without 
brekage". Everything else will be annoying.

A good example from the past is Vibe'd Markdown parser. It's used e.g. 
on code.dlang.org, but as you can see it doesn't support the full 
MarkDown spec:

- It doesn't support all variations of inline HTML elements

http://code.dlang.org/packages/mir-algorithm

- It doesn't auto-highlight URLs

http://code.dlang.org/packages/buffer

- It doesn't support all variations of tables

http://code.dlang.org/packages/dubbio

- It treats code blocks with backticks differently to indented blocks 
(see "Dub" on "Compile & Run")

http://code.dlang.org/packages/dlang-tour

...

(for a long time it didn't even support advanced features like tables 
which lead to even more broken pages)

The problem is that people are used to all things Markdown supports and 
they just expect it to work as it does on GitHub.
How should they know that Vibe.d's MarkDown parser doesn't support these 
features?
Even if they do know that Vibe.d is used for the registry (and that 
already filters out a majority), they would end up here:

http://vibed.org/api/vibe.textfilter.markdown

Which helps them ... not at all. I don't want DMD's documentation to 
have the same issues.
Shouldn't we learn from the mistakes of the past?

Or in other words: it's great that run.dlang.io now supports -D (e.g. 
https://run.dlang.io/is/5F3rOX),
but a developer shouldn't need to use run.dlang.io to learn the 
documentation system of a language.
It should have a minimal cognitive overhead.