[Dlang-internal] Potential changes to DDoc

[Walter Bright]

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.


> Secondly, HTML is treated differently under Markdown and DDoc. In DDoc anything 
> directly within an HTML tag (i.e. between < and >) is passed through unchanged. 
> However if it's not part of the tag it is treated as regular DDoc text and 
> subject to regular processing. In Markdown all text between a given set of HTML 
> tags is passed through unchanged [3]. I'd prefer to switch to the CommonMark 
> handling, allowing whole blocks of HTML to be passed through directly.

When Markdown and Ddoc conflict, do it the Ddoc way.


> Thirdly and most controversially is how DDoc handles blank lines between 
> paragraphs. Markdown wraps paragraphs in <p></p> tags and collapses multiple 
> blank lines between paragraphs (i.e. ten blank lines is treated the same as 
> one). DDoc inserts $(DDOC_BLANKLINE) macros on each blank line it encounters, 
> which in the default theme inserts <br><br>, in the Phobos theme inserts <div 
> class="blankline"/>, and for LaTeX inserts /par. Phobos docs also have the 
> common practice of hand-wrapping paragraphs in $(P) macros which inserts <p></p> 
> tags.
> 
> The result of DDoc's handling is that under the default theme if you have, say, 
> three blank lines between paragraphs then it results in five blank lines being 
> rendered between them.
> 
> I'm not yet sure it's feasible, but I'd really like to change DDoc to treat 
> paragraphs the way Markdown does--wrap them in, say, a $(P) macro and collapse 
> multiple blank lines. Any desired extra blank lines could be inserted by hand, 
> via the $(BR) macro or similar. However this could change the rendering of 
> existing documentation which depends on the $(DDOC_BLANKLINE) macro.
> 
> What do you think about the proposed changes? Should I try to implement any or 
> all of them?

There is so much written in Ddoc these days that fundamentally changing how it 
works would be very upsetting to a lot of people who have their documents 
broken, for very little benefit.

What I mean by this is there is no existing Markdown text that will be imported 
into Ddoc, so this does not have to be accommodated. Supporting some Markdown 
features is for convenience for Ddoc users. Where Ddoc and Markdown conflict, 
Ddoc takes precedence because there is a lot of legacy Ddoc text and zero legacy 
Markdown text.



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