Adding Markdown to Ddoc

[Jacob Carlborg]

On 2017-12-08 11:13, Walter Bright wrote:
> On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
>> I think links are pretty important, or do you prefer to use Ddoc 
>> macros for that?
> 
> I just don't see much of any improvement of markdown over LINK2.
> 
> 
>> I think we should try to support standard markdown [2]
> 
> Unfortunately, there's really no such thing.

No, there's no official standard but there is a subset that most 
Markdown implementation support [1]. If we would like to claim that Ddoc 
supports Markdown then I think we need to support that subset, even 
though there already exist a corresponding Ddoc syntax. Otherwise it 
will be confusing and very hard to remember which features are supported 
with Markdown syntax and which are not.

> But as I said, we do have 
> an advantage as Ddoc will not likely be importing existing markdown text 
> from elsewhere, so there's little impetus for compatibility. There's no 
> point to supporting multiple unordered list syntaxes, for example.

Well, if you claim that Ddoc supports Markdown syntax then people will 
expect all of it to work.

>> plus features from GitHub markdown. Like fenced code blocks and syntax 
>> highlighting [3]. For simplicity we can start by only supporting D 
>> syntax highlighting.
> 
> Ddoc already does code blocks and syntax highlighting.

Yes, but people will be more familiar with Markdown than with Ddoc.

>> Just for the record, the link you included in your original post [1], 
>> contains some non-standard markdown like:
> 
> I know. That's why I produced a list.
> 
> 
>> * Task lists
> 
> Not relevant for Ddoc.

This might be useful if Ddoc is used for other things than documentation 
for programming APIs, like we use for dlang.org. But I agree.

>> * Using emoji
> 
> The problem with these is where are the images stored? So no.

There are no images stored. Emojis are part of the Unicode standard, so 
the only thing that is needed is a proper Unicode font. But I don't 
think we need it.

BTW, GitHub has a specification for their Markdown implementation [2]

[1] https://daringfireball.net/projects/markdown/syntax
[2] https://github.github.com/gfm/

-- 
/Jacob Carlborg