Adding Markdown to Ddoc

[Jakob Bornecrantz]

On Monday, 11 December 2017 at 20:45:38 UTC, Walter Bright wrote:
> On 12/11/2017 6:22 AM, Jakob Bornecrantz wrote:
>> There are loads of implementations of CommonMark 
>> https://github.com/commonmark/CommonMark/wiki/List-of-CommonMark-Implementations
>
> They appear to be libraries that offer an implementation. Does 
> the Markdown used in github, reddit, wikipedia, doxygen, etc., 
> use any of those libraries?

Github in the past used something called Github Flavored 
Markdown, which was Markdown + whatever quirks where in the ruby 
implementation of Markdown + Tables. Not Markdown. The same with 
all of the others, they all had different quirks because the 
markdown "spec" was bad. Let me use a different technology as a 
analogy.

Walter: We should use HTML for DDOC!

Others: Cool, but can you use CommonTML (HTML5), it has this cool 
spec and actual tests that make sure it looks the same, and that 
the code you have written is robust. HTML isn't really a standard 
as such, you are not sure what you get and there is no agreed 
upon testsuit, so you aren't even sure you get the same results 
with different versions of your own code.

Walter: Is this used elsewhere? I really want HTML.

Others: Here is the spec and a bunch of implementations.

Walter: But HTML is more common, its used in Netscape Navigator 
and IE6.

Others: *collective headdesk*


What I'm trying to get at is, use the testsuit and spec, it will 
save you lot of other problems down the road. And you will be 
making the world of Markdown a better place because there will be 
one less implementation that does things slightly differently.

>
>> the one I have written is not listed. That covers 1 and 2.
>
> I didn't know you wrote one. There are 3 Markdown packages on 
> Dub:
>
>     https://code.dlang.org/search?q=markdown
>
> and I don't see your name on them. I strongly recommend you 
> register yours with Dub (if it is in D) and on the commonmark 
> site!

It is not written in D, but the language is close enough in 
concepts that it can be mechanically ported into D, and is 
licensed under BOOST. Feel free to do what ever to it[1].

We first used the markdown parser from vibe.d, when we threw the 
CommonMark testsuit, 10 tests segfaulted and 1 infinite-spun in a 
loop somewhere in the code. We then rewrote from scratch using 
the recommended practices from the CommonMark spec and the XML 
output from cmark as a guide.

The code is used in our documentation system. Both doc-comments 
and outside documentation files are written in CommonMark. The 
doc-comments uses Doxygen tags which is then run through 
CommonMark, most of the time it does nothing to the comments, but 
if you want to write long comments it makes it much more natural 
and enjoyable.

[1] 
https://github.com/VoltLang/Watt/tree/master/markdown/src/watt/markdown