Adding Markdown to Ddoc

[Jonathan M Davis]

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?

In my experience, the problems with ddoc tend to stem from the fact that
it's a general purpose macro language and not just intended for
documentation generation - there's nothing built-in for generating links to
symbols or a navigation bar like dlang.org has, and while some of it can be
done in ddoc with a bit of work, some of it requires additional scripts or
programs to do it (e.g. while you can add a macro to create a link for a
symbol if you have a website layout designed for it, no macro will be able
to generate a navigation bar with the list of modules in the project; you
need a separate program to generate the list for you, even if that list is
then in ddoc).

I really do like ddoc as a macro language, but the fact that that's all it
is does hamper it for documentation generation, and while you can get
decent, basic documentation out of the box, you can't get anything like
doxygen or ddox gives you. You just have separate modules pages without any
links to anything or anything indicating what the list of modules is. And
you can't even take what's done for Phobos and sanely reuse it, because it's
gotten so complicated and is so thoroughly tied to dlang.org.

At the moment, I'm actually trying to put together a basic set of ddoc files
with a simple program for using dmd to generate the documentation (as
opposed to using a separate generator like ddox does) so that I have
something relatively simple that I can reuse across projects that will allow
my to link documentation with macros like we do in Phobos and have the
navigation bar out of the box - hopefully in a way that's reasonably
understood and customizable as opposed to the mess that Phobos'
documentation generation has become. I suspect that 90+% of folks that
generate documentation just use ddox at this point, because making straight
ddoc look good is a royal pain right now - at least if you want to be able
to reasonably navigate among the documentation pages (or even within a page)
as opposed to just reading the documentation for a single module from top to
bottom.

As for markdown, I fail to see how adding any of it to ddoc would really
help anything, since as far as I can tell, ddoc already does what markdown
does just with macros instead of whatever combination of stray syntax that
markdown uses for different things. And I certainly don't want to have to
fight ddoc because it suddenly decided that some stray bit of syntax which
isn't a macro is suddenly significant and does something special. There
already complaints for how ddoc does special stuff under some circumstances
instead of being purely a question of the macros used:

https://issues.dlang.org/show_bug.cgi?id=16068

That particular problem can be solved by using $(COLON), but the more magic
syntax there is in ddoc, the more landmines it has. It reminds me of how
annoying it is when a piece of software decides that it wants to translate
any emojis you type into a graphical image, and it thinks that parts of a
piece of code that you type are emojis, so your code gets messed up in the
process. Obviously, we're not going to be looking to add emoji support to
ddoc, but any magical syntax we add risks similar problems.

- Jonathan M Davis