(X)HTML/XML in DDoc

[Borden]

Good evening, all,

I imagine that this is a sensitive topic, so I'll do my best not 
to flame bait and I hope that readers will assume that I mean the 
best if I don't word things very diplomatically:

I think that the DDoc spec does an excellent job in creating a 
common-sense, low-burdensome way to document source code in-line. 
I think its rules are largely clear and unambiguous. 
Unfortunately, I'm finding that the clarity breaks down once 
macros are introduced.

What sticks out for me is the spec's aversion to XHTML, clearly 
stated in "D's goals for embedded documentation" (number 4) and 
under the bit for Embedded HTML, which discourages HTML in favour 
of macros.

I want to understand why DDoc prefers macros to some XML-based 
markup. I've observed the following things about working with 
DDoc:
1) The DLangSpec is written almost entirely in macros. Most of 
the macros defined for the DLangSpec simply rewrite HTML tags 
into a macro. It seems that the macros copy the functionality of 
the HTML tags without adding any usefulness or clarity to them.
2) In fact, I'm finding that macros make the documentation less 
flexible to work with. For example, in trying to create a .ddoc 
to parse the DLangSpec files into HTML 5, I'm noticing that the 
DLangSpec sources define and use a lot of SECTION# macros, which 
simply turn the SECTION# heading into a <h#> and raw-dumps the 
second argument. Because of the way it's been set up, I have to 
find and redefine each of these SECTION# macros and, even when I 
do, I can't redefine the macros to use HTML5's nested <section> 
tag system.
3) I do find the macros extremely helpful in mass-producing 
repetitive lines of HTML where only one or two attributes change 
in each line. Of course, since macros don't have any logic to 
them (such as looping, conditions, etc.), they can only shorten 
my workload so much.

Maybe the problem is that the DLangSpec simply stretches the 
capabilities of DDoc far too much. I know that XML is verbose, 
redundant and often a nightmare to work with, but lots of tools 
are available to manage the tedium of XML and convert files to 
and from any format that you like - which seems to be what DDoc 
was designed to but can only accomplish after it's parsed into 
HTML!

So these are my thoughts, and I invite feedback on them. I'm not 
really proposing anything - except for, maybe, changing the 
DLangSpec source into a more wieldy format...