On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright 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.)

Great to hear this! :)

[Pandoc](http://pandoc.org/) is an excellent widely-used markdown implementation to emulate (or use directly); they support thoughtful additional syntax for definition lists, tables, mathematics, and a few other niceties (including syntax highlighting for D code blocks).

On Wednesday, 6 December 2017 at 04:11:33 UTC, Walter Bright wrote:
> https://help.github.com/articles/basic-writing-and-formatting-syntax/

I think you'll find it is easier said than done to get sane output given existing ddoc pages.

My adrdox does some of this special syntax and to maintain compatibility with Phobos, I had to do some recursive action inside macros and ddoc sections to keep the generated html from being totally bogus.

Of course, if you're willing to do some cleanup work on the Phobos source code, this can be greatly simplified too (indeed, for adrdox, i did fork some of it, but keeping it up to date was actually harder as a fork than just adding another hack to my parser, so i went that way too).

https://help.github.com/articles/basic-writing-and-formatting-syntax/#paragraphs-and-line-breaks

this rule in particular takes quite a bit to make sane with ddoc hybrid stuff!


PS of course yall could also just surrender to me and use my superior system. I'm not actually a fan of markdown syntax though so i don't quite follow it and do other custom extensions which has rustled some feathers in the past.

On 12/7/2017 2:21 AM, Jacob Carlborg wrote:
> On 2017-12-06 05:11, Walter Bright 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.)
> 
> Finally :), this is awesome. Should we implement standard markdown, GitHub markdown or some other extension?

I dunno. Make a case. There's no backward compatibility necessary, so we do not have to worry about the two ways of doing lists, for example. Just '*' will do.

Aside from what Ddoc already does, I'd just stick with:

* Lists
* Nested Lists
* Headings
* Bold
* Italic
* \ escaping
* Quoted text

and skip:

* tables
* links
* emoji

On 2017-12-08 06:35, Walter Bright wrote:

> I dunno. Make a case. There's no backward compatibility necessary, so we do not have to worry about the two ways of doing lists, for example. Just '*' will do.
> 
> Aside from what Ddoc already does, I'd just stick with:
> 
> * Lists
> * Nested Lists
> * Headings
> * Bold
> * Italic
> * \ escaping
> * Quoted text
> 
> and skip:
> 
> * tables
> * links
> * emoji

I think links are pretty important, or do you prefer to use Ddoc macros for that?

I think we should try to support standard markdown [2] plus features from GitHub markdown. Like fenced code blocks and syntax highlighting [3]. For simplicity we can start by only supporting D syntax highlighting.

Just for the record, the link you included in your original post [1], contains some non-standard markdown like:

* Task lists
* Mentioning people and teams
* Referencing issues and pull requests
* Using emoji

[1] https://help.github.com/articles/basic-writing-and-formatting-syntax
[2] https://daringfireball.net/projects/markdown/syntax
[3] https://help.github.com/articles/creating-and-highlighting-code-blocks/

-- 
/Jacob Carlborg

On Thursday, 7 December 2017 at 10:21:21 UTC, Jacob Carlborg wrote:
> On 2017-12-06 05:11, Walter Bright 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.)
>
> Finally :), this is awesome. Should we implement standard markdown, GitHub markdown or some other extension?

Dang! And there you have it: endless complains and issues about the choosen flavour comming ahead of us now... :-(

I would suggest: AsciiDoc! Why? see:http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

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


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


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


> * Mentioning people and teams

Not relevant for Ddoc.


> * Referencing issues and pull requests

LINK2


> * Using emoji

The problem with these is where are the images stored? So no.

On 12/8/2017 1:49 AM, Arjan wrote:
> Dang! And there you have it: endless complains and issues about the choosen flavour comming ahead of us now... :-(

Naturally. Just Say No :-)


> I would suggest: AsciiDoc! Why? see:http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

Yes, well, we don't have to be compatible with 15 different flavors of Markdown, and we've got Ddoc macros for extensions. I only proposed Markdown for the very small number of cases already listed, and no more.

Should probably start with a DIP for it.

On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
> On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
>> * Using emoji
>
> The problem with these is where are the images stored? So no.

Someone thought it's a great idea, to include them into Unicode:

https://unicode.org/emoji/charts/full-emoji-list.html

On Friday, 8 December 2017 at 11:10:16 UTC, Seb wrote:
> On Friday, 8 December 2017 at 10:13:28 UTC, Walter Bright wrote:
>> On 12/8/2017 1:48 AM, Jacob Carlborg wrote:
>>> * Using emoji
>>
>> The problem with these is where are the images stored? So no.
>
> Someone thought it's a great idea, to include them into Unicode:
>
> https://unicode.org/emoji/charts/full-emoji-list.html

pls no emoji support, it's not a unified experience across devices, they should just die out lol

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