On 1/22/18 11:35 AM, John Gabriele wrote:
> On Monday, 22 January 2018 at 18:17:37 UTC, David Gileadi wrote:
>> On 1/22/18 10:37 AM, John Gabriele wrote:
>>> On Monday, 22 January 2018 at 05:03:41 UTC, Walter Bright wrote:
>>>> On 1/20/2018 10:33 AM, David Gileadi wrote:
>>>> {snip}
>>>>
>>>>> Appendix A: Planned Markdown support
>>>>> ------------------------------------
>>>>>
>>>>> I plan to support the following Markdown features, as specified by CommonMark [4]:
>>>>>
>>>>> {snip}
>>>>
>>>>> - Nesting lists
>>>>
>>>>    1. cat
>>>>    2. dog
>>>>    3. box
>>>>
>>>> is fine for ordered lists, using * for unordered ones is plenty good enough.
>>>
>>> For maximum ease of reading, nesting, and for consistency, I suggest following the 4-space rule. That is, list item *content* (not the markers) always starts at multiples of 4 columns in; additional paragraphs of a list item are also indented 4 spaces; code blocks indented 4 spaces. For example: <https://gist.github.com/uvtc/379bca988270ba8b44a30efabbfa9d6b>.
>>
>> Thanks for the suggestion. However, since I'm trying to stick to the CommonMark spec I've implemented their rules for determining when indented text continues a list item, etc.
> 
> AFAICT, CommonMark does indeed follow the 4-space rule, though may also provide the extra flexibility of leaving out some prefixing spaces. Try copying and pasting my gist example (above) into [the CommonMark dingus](http://spec.commonmark.org/dingus/). It works as expected.
> 
> Note also, for multiple lines in a list item, the continued lines line up vertically with the first (same indentation throughout). It's really a nifty consistency across all list types that makes nesting clear cut.

It does indeed support 4-space formatting if you write your Markdown that way, but its actual rule is a bit different. See example 218 and subsequent examples for details, plus the preceding discussion [1].

[1] http://spec.commonmark.org/0.28/#example-218

On Monday, 22 January 2018 at 05:03:41 UTC, Walter Bright wrote:
> On 1/20/2018 10:33 AM, David Gileadi wrote:
>> [...]
> And thank you for doing this! This will be a nice addition to Ddoc.

+1, thanks a lot!

I think there were a few misunderstandings - see below:

On 2018-01-22 06:03, Walter Bright via Dlang-internal wrote:
>> - Nesting lists
> 
>    1. cat
>    2. dog
>    3. box
> 
> is fine for ordered lists, using * for unordered ones is plenty good enough.

I think David was talking about _nested_ lists, e.g.

1. cat
1.1. dog
1.2. box

or

* cat
  - dog
  - box

http://spec.commonmark.org/0.28/#lists

-> Yes, would be awesome. The current way is quite verbose and forces you to be consistent with indentation to avoid losing the overview:

$(UL
  $(LI cat)
  $(LI
    $(UL
      $(LI dog)
      $(LI box)
    )
  )
)

If you don't indent consistently (and many people

>> - Inline links, although I'm not sure if I will support reference links [5]
> 
> Ddoc already recognizes URLs and creates links for them

Inline links are something different, e.g. [foo](https:...)
See also: http://spec.commonmark.org/0.28/#links

The equivalent in today's Ddoc is the ugly $(LINK2 link, text) macro.
-> I would love to have inline links in Ddoc!

>> - Code blocks fenced with ```, ~~~ and DDoc's existing ---
> The existing --- is good, no need to add more options.

Imho ``` is almost ubiquitously known, so according to the rule of least astonishment [1] three backticks should be supported
(and I doubt it's hard to do so). This will also allow to copy/paste better between GitHub, Ddoc and other Markdown documentations/wikis.

[1] https://en.wikipedia.org/wiki/Principle_of_least_astonishment


>> I don't plan to support the following Markdown features:
> - Tables

I know that this might be hard to do, but if you have time after your initial round this one would be cool to have too.
At Phobos and dlang.org there are many of these nasty tables:

https://github.com/dmd/phobos/blob/617f6b0e592a079de134317bee180f76200f4b6c/std/math.d#L6560

David, thanks a lot for championing this project and pushing it forward!
I saw that you already joined Slack and #dmd, so please feel free to ask questions there.

There are two advises I can give you that as they will save you a lot of frustration and work:

> Open your PR early

Most discussions happen either on GitHub or Slack.
As not everyone is active on Slack, a GitHub PR is usually a good place for a in-depth conversation.
Also looking at your work allows us to give you feedback early on and avoid unnecessary work / it drifting in the wrong direction.

> Split your changes into minimal chunks

Ideally each point on your TODO list translates to one small PR.
This allows fast review and as a bonus avoids rebasing conflicts.
This point is usually underestimated, but it's vastly easier to pull a 30 lines change (+tests) than a 1K diff.

On 2018-01-20 19:33, David Gileadi via Dlang-internal wrote:
> (I don't know if this is the right forum for this post, so if not
> please let me know.)
> 
> I'm working on adding Markdown support to DDoc. I'm doing it by
> modifying the highlightText method in doc.d [1].
> 
> 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.
> 
> 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.
> 
> 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?
> 
> -Dave
> 
> 
> 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
> - Styling text with * (but not with _)
> - Quoting text blocks with >
> - Code blocks fenced with ```, ~~~ and DDoc's existing ---
> - Backtick-quoted code as it currently works in DDoc
> - Nesting lists
> - Thematic breaks (<hr>)
> - Inline links, although I'm not sure if I will support reference links [5]
> - Markdown escapes with \
> - HTML, although that's a discussion item (see above)
> 
> 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
> 
> 
> [1] https://github.com/dgileadi/dmd/tree/ddoc-markdown
> [2] https://github.com/dlang/dmd/blob/master/res/default_ddoc_theme.ddoc#L70
> [3] http://spec.commonmark.org/0.28/#html-blocks
> [4] http://spec.commonmark.org/0.28/
> [5] http://spec.commonmark.org/0.28/#reference-link

On 1/22/2018 10:17 AM, David Gileadi wrote:
> However, since I'm trying to stick to the CommonMark spec I've implemented their rules for determining when indented text continues a list item, etc.

Good!


> I'm currently not supporting indented code blocks, however. I could potentially support them within list items, but right now I don't intend to.

Also a good decision.

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 :-)

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.

Just pick the most reasonable method, and do that.

(For example, using --- or ``` or ~~~ or 4 space indent for code blocks. Gahhh. Just use ---, because it works and looks fine, and we already do it.)


> 1. It's easier for people who already know Markdown to use when the list of
> unsupported features is small.

Markdown is so trivial I can't believe this is an issue. (I myself use different markdowns on different systems. The differences are simply not a problem.)


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


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

On 1/22/2018 5:50 PM, Sebastian Wilzbach wrote:
>> Split your changes into minimal chunks
> 
> Ideally each point on your TODO list translates to one small PR.
> This allows fast review and as a bonus avoids rebasing conflicts.
> This point is usually underestimated, but it's vastly easier to pull a 30 lines change (+tests) than a 1K diff.

I totally agree with "chunking" it into multiple independent PRs.

On 1/22/18 6:50 PM, Sebastian Wilzbach wrote:
> David, thanks a lot for championing this project and pushing it forward!
> I saw that you already joined Slack and #dmd, so please feel free to ask questions there.
> 
> There are two advises I can give you that as they will save you a lot of frustration and work:
> 
>> Open your PR early
> 
> Most discussions happen either on GitHub or Slack.
> As not everyone is active on Slack, a GitHub PR is usually a good place for a in-depth conversation.
> Also looking at your work allows us to give you feedback early on and avoid unnecessary work / it drifting in the wrong direction.

Thanks for the advice. I went ahead and create a PR [1].

I'd been avoiding a PR because I've been rebasing my changes on master rather than merging, and I didn't want to cause confusion by rewriting history. Should I switch to merging changes from master now that I created a PR?

>> Split your changes into minimal chunks
> 
> Ideally each point on your TODO list translates to one small PR.
> This allows fast review and as a bonus avoids rebasing conflicts.
> This point is usually underestimated, but it's vastly easier to pull a 30 lines change (+tests) than a 1K diff.

I haven't managed to do that so far, but it may be possible to do so after the fact.


[1] https://github.com/dlang/dmd/pull/7764

On 1/22/18 9:56 PM, David Gileadi wrote:
> ...I went ahead and create a PR [1].

This is far from the first typo I've made today. I think I need more sleep.

On Sunday, 21 January 2018 at 17:55:20 UTC, Jacob Carlborg wrote:
> I'm the author of the current Ddoc default theme. As far as I know it's common practice to reset the style for standard tags because the browsers might render it differently otherwise.

AFAIK, w3c and gcc docs don't do that. I'd say browsers must render it as they like, why not?