On 12/8/2017 7:53 AM, Steven Schveighoffer wrote:
> +1000, I can't imagine why you'd want emoji in your documentation.

No D-Man emoji, sigh.

On 12/8/2017 7:30 AM, Jacob Carlborg wrote:
> Otherwise it will be confusing and very hard to remember which features are supported with Markdown syntax and which are not.

This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.

On 2017-12-09 02:49, Walter Bright wrote:

> This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.

Yes, but I haven't yet seen any official documentation saying that Ddoc supports Markdown syntax.

-- 
/Jacob Carlborg

On 12/8/17 6:49 PM, Walter Bright wrote:
> On 12/8/2017 7:30 AM, Jacob Carlborg wrote:
>> Otherwise it will be confusing and very hard to remember which features are supported with Markdown syntax and which are not.
> 
> This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.

For instance, as I've been working on adding Markdown features I was surprised to discover that DDoc's current support for backtick-delimited code only works within a single line. Most implementations I've seen allow it to span hard-wrapped lines, as long as it's within a single paragraph.

I'd like to support as many Markdown features as we can, but there will always be a some differences--particularly those that conflict with existing DDoc features.

On Saturday, 9 December 2017 at 21:05:04 UTC, David Gileadi wrote:
> For instance, as I've been working on adding Markdown features I was surprised to discover that DDoc's current support for backtick-delimited code only works within a single line. Most implementations I've seen allow it to span hard-wrapped lines, as long as it's within a single paragraph.

I kinda object to calling the ddoc `` thing markdown, since that wasn't the intention. When I added it, I had exactly one goal: be able to write `<xml samples>` in ddoc without it breaking the html output. At the same time, I didn't want it to accidentally trigger if someone pasted a linker error in their doc:

undefined reference to `foo'
undefined reference to `bar'

So it was limited to a single line and required a matching ` to trigger the new code. Then, btw, it does NOT just wrap it in a $(BACKTICK) macro. It first *escapes the string*, for example turning < into &lt;, etc, THEN wraps it in the macro.


Though, the reason it uses ` as the delimiter is because markdown does it so it looks familiar... but it wasn't actually based on a desire to be markdown.

Similarly, my adrdox thing has some markdown-ish features, but it is explicitly NOT markdown, giving me the freedom to avoid brain damage. (I am not a fan of markdown, it is such a mess and hard to write.)

On 12/9/17 2:25 PM, Adam D. Ruppe wrote:
> On Saturday, 9 December 2017 at 21:05:04 UTC, David Gileadi wrote:
>> For instance, as I've been working on adding Markdown features I was surprised to discover that DDoc's current support for backtick-delimited code only works within a single line. Most implementations I've seen allow it to span hard-wrapped lines, as long as it's within a single paragraph.
> 
> I kinda object to calling the ddoc `` thing markdown, since that wasn't the intention. When I added it, I had exactly one goal: be able to write `<xml samples>` in ddoc without it breaking the html output. At the same time, I didn't want it to accidentally trigger if someone pasted a linker error in their doc:
> 
> undefined reference to `foo'
> undefined reference to `bar'
> 
> So it was limited to a single line and required a matching ` to trigger the new code. Then, btw, it does NOT just wrap it in a $(BACKTICK) macro. It first *escapes the string*, for example turning < into &lt;, etc, THEN wraps it in the macro.
> 
> 
> Though, the reason it uses ` as the delimiter is because markdown does it so it looks familiar... but it wasn't actually based on a desire to be markdown.
> 
> Similarly, my adrdox thing has some markdown-ish features, but it is explicitly NOT markdown, giving me the freedom to avoid brain damage. (I am not a fan of markdown, it is such a mess and hard to write.)

That makes sense--thanks for the background.

To be fair to markdown, it does also require matching backticks and escapes < and > within backtick-quoted sections. But I agree that some markdown "features" are rather messy.

On 12/9/2017 12:23 PM, Jacob Carlborg wrote:
> On 2017-12-09 02:49, Walter Bright wrote:
> 
>> This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.
> 
> Yes, but I haven't yet seen any official documentation saying that Ddoc supports Markdown syntax.

There isn't any, because officially saying Markdown is supported is too vague. There is no Markdown standard.

But what Ddoc does do should be officially documented, and is as far as I know.

On 12/9/2017 1:05 PM, David Gileadi wrote:
> On 12/8/17 6:49 PM, Walter Bright wrote:
>> On 12/8/2017 7:30 AM, Jacob Carlborg wrote:
>>> Otherwise it will be confusing and very hard to remember which features are supported with Markdown syntax and which are not.
>>
>> This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.
> 
> For instance, as I've been working on adding Markdown features I was surprised to discover that DDoc's current support for backtick-delimited code only works within a single line. Most implementations I've seen allow it to span hard-wrapped lines, as long as it's within a single paragraph.

The:

---
code
---

is for multiline code blocks.


> I'd like to support as many Markdown features as we can,

Only the ones that make good sense for Ddoc, not as many as technically possible.


> but there will always be a some differences--particularly those that conflict with existing DDoc features.

Yes, and keep in mind there is no such thing as standard Markdown. Every implementation has significant differences.

On Sunday, 10 December 2017 at 01:19:13 UTC, Walter Bright wrote:
> On 12/9/2017 12:23 PM, Jacob Carlborg wrote:
>> On 2017-12-09 02:49, Walter Bright wrote:
>> 
>>> This is way overstating the case. Ddoc already supports some markdown, and some markdown in different ways.
>> 
>> Yes, but I haven't yet seen any official documentation saying that Ddoc supports Markdown syntax.
>
> There isn't any, because officially saying Markdown is supported is too vague. There is no Markdown standard.
>
> But what Ddoc does do should be officially documented, and is as far as I know.

since commonmark exists, is specified and is compatibale to many markdown-languages,  I claim there is a markdown standard:  http://spec.commonmark.org/

commonmark is the common denominator of the markdown-languages.

On 12/9/2017 9:17 PM, meppl wrote:
> since commonmark exists, is specified and is compatibale to many markdown-languages,  I claim there is a markdown standard: http://spec.commonmark.org/

It certainly wants to be the standard, but until most everyone decides to follow it, it is not. There is no list of anyone on that site conforming to it.

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