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
