On 1/25/2018 7:59 AM, John Gabriele wrote:
> What do you think about supporting two modes of operation:

Multiple modes makes things even worse :-(

On 1/25/18 5:34 AM, rjframe wrote:
> Another advantage to supporting a variety of features is that support for
> making README.md the generated index.html becomes possible (like Doxygen
> can do). Supporting a limited subset greatly restricts that ability, as
> the README would have to limit itself to the intersection of [GH-]Markdown
> and DDocDown(?).

I quite like the idea of making README.md the index page, since people are used to it from Github and et al. It's something to keep in mind for a future enhancement.

On Friday, 26 January 2018 at 07:11:33 UTC, Walter Bright wrote:
> On 1/25/2018 7:59 AM, John Gabriele wrote:
>> What do you think about supporting two modes of operation:
>
> Multiple modes makes things even worse :-(

As a matter of practicality, and from a maintenance cost perspective, I agree with everything you've said in this thread. From a "first five minutes" point of view, I have to disagree.

Supporting a half-assed "Markdownish" syntax, where some Markdown bits work and others don't, where fenced code blocks require "---" and backticks are unsupported, is bound to be a point of frustration to someone giving D a legitimate look.

This is one of those ecosystem things like IDE support that maybe by itself won't be enough to turn people away, but on a list of cons it will carry weight. If we're going to support Markdown in Ddoc, then we ought to really support Markdown. Failure to go whole hog on this is just going to create one more pain point for people motivated to look, but not motivated to leave their comfort zone.

And here we've got someone who's not only willing to do it, but actually implementing it! We ought to run with it.

On 1/27/2018 12:08 AM, Mike Parker wrote:
> And here we've got someone who's not only willing to do it, but actually implementing it! We ought to run with it.


I agreed with David to not call it Markdown support, so we do not raise false expectations. We simply implement what we need, and document it.

On 2018-01-27 09:08, Mike Parker via Dlang-internal wrote:
> On Friday, 26 January 2018 at 07:11:33 UTC, Walter Bright wrote:
>> On 1/25/2018 7:59 AM, John Gabriele wrote:
>>> What do you think about supporting two modes of operation:
>> 
>> Multiple modes makes things even worse :-(
> 
> As a matter of practicality, and from a maintenance cost perspective,
> I agree with everything you've said in this thread. From a "first five
> minutes" point of view, I have to disagree.
> 
> Supporting a half-assed "Markdownish" syntax, where some Markdown bits
> work and others don't, where fenced code blocks require "---" and
> backticks are unsupported, is bound to be a point of frustration to
> someone giving D a legitimate look.
> 
> This is one of those ecosystem things like IDE support that maybe by
> itself won't be enough to turn people away, but on a list of cons it
> will carry weight. If we're going to support Markdown in Ddoc, then we
> ought to really support Markdown. Failure to go whole hog on this is
> just going to create one more pain point for people motivated to look,
> but not motivated to leave their comfort zone.
> 
> And here we've got someone who's not only willing to do it, but
> actually implementing it! We ought to run with it.

I can't agree more with your words, Mike.
DDoc is already super-hard for people to get used to as it's very un-intuitive and relies on many under-documented features.
My vote is fully on "implement as much Markdown as possible without brekage". Everything else will be annoying.

A good example from the past is Vibe'd Markdown parser. It's used e.g. on code.dlang.org, but as you can see it doesn't support the full MarkDown spec:

- It doesn't support all variations of inline HTML elements

http://code.dlang.org/packages/mir-algorithm

- It doesn't auto-highlight URLs

http://code.dlang.org/packages/buffer

- It doesn't support all variations of tables

http://code.dlang.org/packages/dubbio

- It treats code blocks with backticks differently to indented blocks (see "Dub" on "Compile & Run")

http://code.dlang.org/packages/dlang-tour

...

(for a long time it didn't even support advanced features like tables which lead to even more broken pages)

The problem is that people are used to all things Markdown supports and they just expect it to work as it does on GitHub.
How should they know that Vibe.d's MarkDown parser doesn't support these features?
Even if they do know that Vibe.d is used for the registry (and that already filters out a majority), they would end up here:

http://vibed.org/api/vibe.textfilter.markdown

Which helps them ... not at all. I don't want DMD's documentation to have the same issues.
Shouldn't we learn from the mistakes of the past?

Or in other words: it's great that run.dlang.io now supports -D (e.g. https://run.dlang.io/is/5F3rOX),
but a developer shouldn't need to use run.dlang.io to learn the documentation system of a language.
It should have a minimal cognitive overhead.

On 1/27/18 1:54 AM, Walter Bright wrote:
> On 1/27/2018 12:08 AM, Mike Parker wrote:
>> And here we've got someone who's not only willing to do it, but actually implementing it! We ought to run with it.
> 
> 
> I agreed with David to not call it Markdown support, so we do not raise false expectations. We simply implement what we need, and document it.

To make myself plain (in case I didn't before) I strongly disagree with this approach.

I agree with Mike et al that DDoc should support as much standard Markdown as is possible modulo conflicts with DDoc features. I'm willing to do the work (and indeed have done most of it already), and as I've explained before I believe the downsides are few and well mitigated.

On Saturday, 27 January 2018 at 18:15:04 UTC, David Gileadi wrote:
> On 1/27/18 1:54 AM, Walter Bright wrote:
>> On 1/27/2018 12:08 AM, Mike Parker wrote:
>>> And here we've got someone who's not only willing to do it, but actually implementing it! We ought to run with it.
>> 
>> 
>> I agreed with David to not call it Markdown support, so we do not raise false expectations. We simply implement what we need, and document it.
>
> To make myself plain (in case I didn't before) I strongly disagree with this approach.
>
> I agree with Mike et al that DDoc should support as much standard Markdown as is possible modulo conflicts with DDoc features. I'm willing to do the work (and indeed have done most of it already), and as I've explained before I believe the downsides are few and well mitigated.

+1

On Saturday, 27 January 2018 at 13:42:39 UTC, Sebastian Wilzbach wrote:
> On 2018-01-27 09:08, Mike Parker via Dlang-internal wrote:
>> And here we've got someone who's not only willing to do it, but
>> actually implementing it! We ought to run with it.

+1

>
> I can't agree more with your words, Mike.
> DDoc is already super-hard for people to get used to as it's very un-intuitive and relies on many under-documented features.
> My vote is fully on "implement as much Markdown as possible without brekage". Everything else will be annoying.

+1

I do remember getting a bit frustrated because I just wanted to document and continue coding, but I couldn't "just". I mean I don't mind having to learn yet another doc language, but I'd prefer not to, is all I'm saying.

Of course there'll be ddoc specific things (standard sections for eg, ditto is a big help), but it really is quite ugly to see all those macros when markdown is just so much easier on the eyes (and aesthetics do matter a lot),  and on ---/```, my instinct is to write ``` for code blocks - because everyone else does, github does, bitbucket, slack, and many apps just follow the same, because people are used to it. New comers will just know how to write docs without having to dig through ddoc docs, it just seems a win/win to just support markdown, and call it that.

On Tuesday, 23 January 2018 at 21:11:26 UTC, Walter Bright wrote:
> Remember, Ddoc macros are not being removed. For the cases of using some other language,
>
>    $(SOME_OTHER_LANGUAGE
>        ...
>    )
>
> will still work, and will of course work with the inevitable languages that do not have syntax highlighting builtin to Ddoc.

Have you ever actually tried this? If not, please do. Spoiler alert! It won't work right. Behold:

Given this D:

---
/++
        $(MY_LANG
                if(a<foo> < 10) {
                        printf("<i>not</i>\n");
                }
        );

        Macros:
                MY_LANG=<pre>$0</pre>
+/
module a;
---


dmd -D a.d will spit out something like this:

```html

    <pre>               if(<code class="code">a</code><foo> &lt; 10) {
                        printf("<i>not</i>\n");
                }
        </pre>

```


That won't render anything remotely close to what it should. The printf contents will come out as italic instead of showing the original code. It will incorrectly highlight the variable `a` because dmd thought it was referring to the module name `a` (this is ddoc's biggest misfeature PLEASE REMOVE IT FOR THE LOVE OF ALL THAT IS GOOD!!!).

And most damningly: the C++ template argument, <foo>, gets output without any character escaping, causing a browser to think it is an html tag, breaking the output entirely.


Of course, you could write:

---
        $(MY_LANG
                if(a$(LT)foo$(RT) $(LT) 10) {
                        printf("$(LT)i$(RT)not$(LT)/i$(RT)\n");
                }
        );
---

but pleeeease, be realistic, that will not be used.


At least the ``` block, like the --- and existing `code` sections, could automatically escape those characters and suppress other ddoc processing inside.



As I constantly remind people, `foo` is NOT equivalent to $(D foo) and does NOT simply rewrite one into the other. It also performs output character replacement (like ---) and THAT is why I added that code in the first place. The shorthand syntax of `foo` vs $(D foo) was a side-effect; the real goal was this escaping. (of course, everyone loves the syntax too...)

The same reasoning would apply to the ``` blocks.

On 2/2/2018 9:16 PM, Adam D. Ruppe wrote:
> Have you ever actually tried this?
Yes, I use it now and then. You can see it in the CCODE macro used on the dlang web site source. There's also CPPCODE, CONSOLE, and GRAMMAR (for the BNF grammar code).