On Mon, Dec 29, 2014 at 04:10:35PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/29/2014 3:47 PM, H. S. Teoh via Digitalmars-d wrote: > >We've already had to resort to $(COMMA) hacks to work around comma > >issues in Phobos docs. :-( > > It's not a hack. The macro system is designed to work that way. All > markup systems require some sort of escape mechanism. Including > Markup.
I wasn't defending Markdown, btw. As you pointed out elsewhere, it does have its own set of limitations... but OTOH, it was never *designed* to be all-encompassing. It was just an attempt to reduce the tedium of HTML tag soup by using shorter, more visually-appealing syntax to represent some of the most common constructs. I'm not a big fan of Markdown, though. It's better than raw HTML, but only just so. > >Not to mention that as it stands, ddoc is only really convenient for > >HTML output; while it's certainly *possible* to target it for > >non-HTML output, it's a pain. > > More correctly, Ddoc works well for any markup that has a > fundamentally nested structure. LaTeX does not. That's not true; LaTeX supports nested structures quite well. > But at least you can make it work with LaTeX. Whatcha gonna do with > Markdown? Again, I wasn't defending Markdown. > Ddoc has worked extremely well for being adaptible for different HTML > output Yes, it works well with HTML, but not so well for other output formats. > - like the online docs have undergone numerous facelifts while > requiring zero changes to the Ddoc source code. It also has been able > to generate ebooks from the documentation, again with zero source code > changes, just a new set of macro definitions. > > CandyDoc has been done with it, also with zero source changes. This is not really accurate... if all you care for is plain text copy-n-pasted from source code comments, with a smattering of tags added on top to eliminate the most egregious eyesores, then sure, you can just write straight text in the ddoc comments and it will Just Work(tm). But as soon as you try to do anything more with it -- output correctly-formed XHTML, for example, ddoc doesn't work. Try making it output paragraphs correctly encapsulated in <p>...</p> blocks sometime. It doesn't work, because ddoc doesn't understand what paragraphs are, it only knows what blank lines are, but blank lines are not a reliable indicator of paragraph breaks (e.g., what about the break between a section heading and a paragraph? Or between a quoted code block and a paragraph before/after the code?). The only way to get it right is to turn your ddoc comments into tag soup. Are you seriously suggesting that we have to write ddoc tag soup while coding? Or that we first write in plain text then go back afterwards and wrap every paragraph in $(P ...) macros? The only reason zero source code changes were required, was because the ddoc comments were already written with the requisite tag soup to begin with. Which is OK, if that's the "correct" way to use ddoc... but in that case, the page on dlang.org that describes ddoc should be revised to not give the false impression that you can just write documentation comments in plain text format and expect to get nice output from it. T -- Живёшь только однажды.