Adding Markdown to Ddoc

[Jonathan M Davis]

On Tuesday, December 12, 2017 10:22:24 meppl via Digitalmars-d wrote:
> On Tuesday, 12 December 2017 at 06:55:45 UTC, Jonathan M Davis
>
> wrote:
> > On Tuesday, December 05, 2017 20:11:33 Walter Bright via
> >
> > Digitalmars-d 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.)
> >
> > I confess that looking over that page, I don't see much reason
> > to add any of it to ddoc. It all seems like stuff that we can
> > already trivially do in ddoc, and most (all?) of it is stuff
> > that already has built-in macros. What are we really trying to
> > gain here?
>
> 1) I avoid writing something like $(I foo) into a comment.
> Because other people may actually read my source code and not
> just read a generated documentation from a source code. So, I
> would prefer writing *foo* or _foo_. After all that's the point
> of markdown: Pure text _looks_ like intended and enables
> html-generation at the same time.

And then you have to worry about something like int* screwing with things,
because the compiler decides that you wanted italics. Honestly, I don't
think that something like $(I foo) is very onerous - it's not all that
different from <i>foo</i> or [i]foo[/i] (which plenty of folks are familiar
with), but it's shorter and less visually noisy - and it doesn't risk having
stuff that isn't supposed to be markdown being treated as markdown.

Personally, I would _very_ much like to see the magic formatting in ddoc
kept to a minimum. I don't want to have to guess what the documentation is
going to look like or have to constantly generate it to make sure that I
didn't screw it up because of some stray character that the compiler decided
to treat as special. As it stands, ddoc is fairly clean, and it doesn't have
a lot of annoying magic - and the stuff that folks frequently find annoying
about it tends to be the magic that it does already have - most notably that
it decides to invisibly make some words bold based on what's being
documented, forcing you to put _ in front of at least some of those words
(and most of us have to actually generate the documentation to catch all of
the mistakes that have to do with missing underscores; it would be _much_
nicer if that magic weren't there). IMHO, the less magic formatting that
ddoc does the better. I want all of that to be controlled by the macros so
that you can look at the source code and clearly see all of the formatting
commands without them risking looking like something else.

- Jonathan M Davis