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...
- (X)HTML/XML in DDoc Borden
-
