[Dlang-internal] Potential changes to DDoc

[David Gileadi]

Thanks for looking this over.

On 1/21/18 10:03 PM, Walter Bright wrote:
> On 1/20/2018 10:33 AM, David Gileadi wrote:
>> I've been trying to make my changes non-breaking, in that existing 
>> DDoc files should be rendered the same as they currently are. However 
>> I've realized that there may need to be some breakage, and I'd like to 
>> discuss it.
>>
>> First of all, the CSS styles in the default DDoc theme remove all 
>> styling from headers, blockquotes, list items, pre and code sections, 
>> etc. [2] The effect of this is that Markdown features like headers, 
>> quotes, etc. don't display correctly under the default theme. I'd like 
>> to modify the default DDoc theme to avoid de-styling these elements.
> 
> I don't understand how styling enters into this. Markdown, such as:
> 
>     * cat
>     * dog
>     * horse
> 
> should be simply rewritten by the highlighter to:
> 
>     $(UL
>     $(LI cat)
>     $(LI dog)
>     $(LI horse)
>     )
> 
> and then let the macros do their thing.

Right, and that's exactly what I'm doing. Styling enters into it because 
Ddoc ships with a default theme, and that theme doesn't render things 
like headings properly. With Markdown support Ddoc will now generate 
headings, so the default theme needs to support them too. I'll follow 
Jacob's suggestion for adding styles for headings and other elements.

I'll leave HTML and blank line handling as-is.

[snip]

> 
>> Appendix A: Planned Markdown support
>> ------------------------------------
>>
>> I plan to support the following Markdown features, as specified by 
>> CommonMark [4]:
>>
>> - Headings, both the ATX and setext kind
> 
> No reason to support both. ATX looks simpler to me, so go with that.
> 
>> - Styling text with * (but not with _)
> 
> Yes, just stick with one. The * is good.
> 
>> - Quoting text blocks with >
> 
> Ok.
> 
>> - Code blocks fenced with ```, ~~~ and DDoc's existing ---
> 
> The existing --- is good, no need to add more options.
> 
>> - Backtick-quoted code as it currently works in DDoc
> 
> Ok. (This has been a big success in Ddoc.)
> 
>> - Nesting lists
> 
>     1. cat
>     2. dog
>     3. box
> 
> is fine for ordered lists, using * for unordered ones is plenty good 
> enough.
> 
>> - Thematic breaks (<hr>)
> 
> Just pick one style for that, I suggest the 3 underscores.
> 
>> - Inline links, although I'm not sure if I will support reference 
>> links [5]
> 
> Ddoc already recognizes URLs and creates links for them
> 
>> - Markdown escapes with \
> 
> Ok
> 
>> - HTML, although that's a discussion item (see above)
> 
> I wouldn't change the HTML behavior.
> 
>> I don't plan to support the following Markdown features:
>>
>> - Indented code blocks because existing DDoc comments are often 
>> already indented
>> - Using --- for HRs and second-level headings because DDoc uses it as 
>> a code block fence
>> - Tables
>> - Backtick-quoting code across multiple lines
>> - Github-specific features like task lists, mentioning people and 
>> teams, referencing issues and pull requests, and emoji
> 
> Yes, don't waste time on those things.
> 
> And thank you for doing this! This will be a nice addition to Ddoc.

You're very welcome.

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:

1. It's easier for people who already know Markdown to use when the list 
of unsupported features is small.
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.
3. The additional code for implementing the same feature with different 
triggering characters is small.

Incidentally, to me help stick to the CommonMark spec I'm using its test 
suite to generate a Ddoc page that tests the Markdown support [2]. I'm 
currently at about 40% compliance. When I'm done I plan to make the 
generated page part of DDoc's test suite.


[1] 
https://github.com/dlang-community/harbored-mod#differences-from-vanilla-markdown
[2] https://github.com/dgileadi/ddoc-commonmark-spec