December 12, 2017
Compare:

Output:
https://github.com/vibe-d/vibe.d/blob/master/README.md

Input:
https://raw.githubusercontent.com/vibe-d/vibe.d/master/README.md

Most programmers who use GitHub will be familiar with this and can write docs, tutorials etc. with very little effort. The set of Markdown used for the D documentation shouldn't be needlessly limited (i.e. it shouldn't offer less than CommonMark - GitHub's core markup langauge).
December 12, 2017
On Tuesday, December 12, 2017 10:22:24 meppl via Digitalmars-d wrote:
> On Tuesday, 12 December 2017 at 06:55:45 UTC, Jonathan M Davis
>
> wrote:
> > On Tuesday, December 05, 2017 20:11:33 Walter Bright via
> >
> > Digitalmars-d wrote:
> >> https://help.github.com/articles/basic-writing-and-formatting-syntax/
> >>
> >> Anyone interested in picking up the flag?
> >>
> >> (I know this has come up before, and I've been opposed to it,
> >> but I've
> >> changed my mind.)
> >
> > I confess that looking over that page, I don't see much reason to add any of it to ddoc. It all seems like stuff that we can already trivially do in ddoc, and most (all?) of it is stuff that already has built-in macros. What are we really trying to gain here?
>
> 1) I avoid writing something like $(I foo) into a comment. Because other people may actually read my source code and not just read a generated documentation from a source code. So, I would prefer writing *foo* or _foo_. After all that's the point of markdown: Pure text _looks_ like intended and enables html-generation at the same time.

And then you have to worry about something like int* screwing with things, because the compiler decides that you wanted italics. Honestly, I don't think that something like $(I foo) is very onerous - it's not all that different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar with), but it's shorter and less visually noisy - and it doesn't risk having stuff that isn't supposed to be markdown being treated as markdown.

Personally, I would _very_ much like to see the magic formatting in ddoc kept to a minimum. I don't want to have to guess what the documentation is going to look like or have to constantly generate it to make sure that I didn't screw it up because of some stray character that the compiler decided to treat as special. As it stands, ddoc is fairly clean, and it doesn't have a lot of annoying magic - and the stuff that folks frequently find annoying about it tends to be the magic that it does already have - most notably that it decides to invisibly make some words bold based on what's being documented, forcing you to put _ in front of at least some of those words (and most of us have to actually generate the documentation to catch all of the mistakes that have to do with missing underscores; it would be _much_ nicer if that magic weren't there). IMHO, the less magic formatting that ddoc does the better. I want all of that to be controlled by the macros so that you can look at the source code and clearly see all of the formatting commands without them risking looking like something else.

- Jonathan M Davis

December 12, 2017
On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis wrote:
>
> And then you have to worry about something like int* screwing with things, because the compiler decides that you wanted italics. Honestly, I don't think that something like $(I foo) is very onerous - it's not all that different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar with), but it's shorter and less visually noisy - and it doesn't risk having stuff that isn't supposed to be markdown being treated as markdown.
>
> [...]

Try this one (paste it into http://spec.commonmark.org/dingus/):

# CommonMark

```
    int* ptr;
```
`int*` is a pointer to an integer.

int* is a pointer to an integer.

December 12, 2017
On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:

>
> Try this one (paste it into http://spec.commonmark.org/dingus/):
>
> # CommonMark
>
> ```
>     int* ptr;
> ```
> `int*` is a pointer to an integer.
>
> int* is a pointer to an integer.

The output is

<h1>CommonMark</h1>
<pre><code>    int* ptr;
</code></pre>
<p><code>int*</code> is a pointer to an integer.</p>
<p>int* is a pointer to an integer.</p>

I don't see any problem here.
December 12, 2017
On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:
> On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis wrote:
>>
>> And then you have to worry about something like int* screwing with things, because the compiler decides that you wanted italics. Honestly, I don't think that something like $(I foo) is very onerous - it's not all that different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar with), but it's shorter and less visually noisy - and it doesn't risk having stuff that isn't supposed to be markdown being treated as markdown.
>>
>> [...]
>
> Try this one (paste it into http://spec.commonmark.org/dingus/):
>
> # CommonMark
>
> ```
>     int* ptr;
> ```
> `int*` is a pointer to an integer.
>
> int* is a pointer to an integer.

Coming up with a counter example is easy. Try this:

> To dereference a pointer variable, write *i. To define a pointer variable, write int* i.

Inserting backticks obviously solves this and personally I would be fine with that requirement, but Markdown is not completely harmless. The above line comes out totally as not intended.
December 12, 2017
On Tuesday, 12 December 2017 at 13:50:42 UTC, Bastiaan Veelo wrote:
> On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:
>> On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis wrote:
>>>
>>> And then you have to worry about something like int* screwing with things, because the compiler decides that you wanted italics. Honestly, I don't think that something like $(I foo) is very onerous - it's not all that different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar with), but it's shorter and less visually noisy - and it doesn't risk having stuff that isn't supposed to be markdown being treated as markdown.
>>>
>>> [...]
>>
>> Try this one (paste it into http://spec.commonmark.org/dingus/):
>>
>> # CommonMark
>>
>> ```
>>     int* ptr;
>> ```
>> `int*` is a pointer to an integer.
>>
>> int* is a pointer to an integer.
>
> Coming up with a counter example is easy. Try this:
>
>> To dereference a pointer variable, write *i. To define a pointer variable, write int* i.
>
> Inserting backticks obviously solves this and personally I would be fine with that requirement, but Markdown is not completely harmless. The above line comes out totally as not intended.

speaking of "harm". I would say there is not much harm when the API-docs are broken at a certain place. Furthermore it is never super difficult to fix. In comparison: Bugs in a programming language are from a different world and super much more harmful up to 9000.
December 12, 2017
On Tuesday, 12 December 2017 at 13:50:42 UTC, Bastiaan Veelo wrote:
> On Tuesday, 12 December 2017 at 11:48:24 UTC, Chris wrote:
>> On Tuesday, 12 December 2017 at 11:33:45 UTC, Jonathan M Davis wrote:
>>>
>>> And then you have to worry about something like int* screwing with things, because the compiler decides that you wanted italics. Honestly, I don't think that something like $(I foo) is very onerous - it's not all that different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar with), but it's shorter and less visually noisy - and it doesn't risk having stuff that isn't supposed to be markdown being treated as markdown.
>>>
>>> [...]
>>
>> Try this one (paste it into http://spec.commonmark.org/dingus/):
>>
>> # CommonMark
>>
>> ```
>>     int* ptr;
>> ```
>> `int*` is a pointer to an integer.
>>
>> int* is a pointer to an integer.
>
> Coming up with a counter example is easy. Try this:
>
>> To dereference a pointer variable, write *i. To define a pointer variable, write int* i.
>
> Inserting backticks obviously solves this and personally I would be fine with that requirement, but Markdown is not completely harmless. The above line comes out totally as not intended.

Like with regex, you can always escape characters with special meanings:

To dereference a pointer variable, write \*i. To define a pointer variable, write int* i

However, as you said, code would be between back ticks anyway, and even $(I int) can be messed up, if you're not careful with brackets and spaces etc. - which is true of _any_ markup language. By saying "the compiler decides" to do something that wasn't intended after the programmer has not been careful with the syntax, you can dismiss _any_ syntax, including D's.

Also, to dismiss CommonMark on the grounds that it is not standardized yet (officially) while millions of programmers are familiar with it an use it on GitHub doesn't make much sense, especially while Ddoc is nowhere near CommonMark in terms of usage, familiarity, ease of use and popularity.


December 12, 2017
On Sunday, 10 December 2017 at 06:20:43 UTC, Walter Bright wrote:

> Besides, commonmark has a lot of stuff we don't need, like multiple ways of doing the same thing.

We would have to come with style guidelines to avoid a mix of say:

*italic* and _italic_
# Heading 1 and

Heading 1
==========

But that shouldn't be too hard. Just a few months of bikeshedding :-)
December 12, 2017
On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright wrote:
>
> I have a more pragmatic definition of a standard:
>
> 1. Products that implement it say they adhere to it and defer to it as the authority on correct behavior.
>
> 2. There's more than one such product.
>
> 3. There's more products adhering to that standard than some other competing standard.
>
> So far as I know, commonmarkdown satisfies zero of those.

Looks like Stack Exchange is working on standardizing on CommonMark:
<https://meta.stackexchange.com/questions/238957/will-commonmark-be-adopted-for-se/258587#258587>

December 12, 2017
On Tuesday, 12 December 2017 at 15:59:42 UTC, John Gabriele wrote:
> On Monday, 11 December 2017 at 00:54:00 UTC, Walter Bright wrote:
>>
>> I have a more pragmatic definition of a standard:
>>
>> 1. Products that implement it say they adhere to it and defer to it as the authority on correct behavior.
>>
>> 2. There's more than one such product.
>>
>> 3. There's more products adhering to that standard than some other competing standard.
>>
>> So far as I know, commonmarkdown satisfies zero of those.
>
> Looks like Stack Exchange is working on standardizing on CommonMark:
> <https://meta.stackexchange.com/questions/238957/will-commonmark-be-adopted-for-se/258587#258587>

Rust is as well: <https://github.com/rust-lang/rust/issues/44229>.