DLang Spec rewrite (?)

[Borden]

On Saturday, 25 May 2013 at 23:28:46 UTC, Jonathan M Davis wrote:
> aside from you, I'm not aware of anyone complaining about it 
> any time recently.

Good evening, Jonathan,

I'm not sure whether you mean that nobody's complained recently
about the spec being in DDoc lately, because, as in my first
link, I found that more people disliked the macros feature of
DDoc (2 + me) than liked it (0).

To answer your question, regarding concrete examples, these
issues are in the context of wanting to translate the DLangSpec
pages into HTML5 so that I can compile them into an ePUB document:

1) the DLangSpec files (pick any one) use SECTION# macros, where
# is a number. In the DDoc conversion files to HTML, these
SECTION# macros convert to <h#> tags and encase the contents
within them. However, I'm not aware of any facility within DDoc,
short of hand-writing a parser, to allow these SECTION# macros to
be nested in order to take advantage of HTML5's <section> tags.

2) The macros are not self-documenting. For example, consider
$(LNAME2 pointers, Pointers) in arrays.dd. The easiest way, I
know, to figure out what $(LNAME2) means is to read the posix.mak
to see that arrays.dd gets pumped through ddoc.dd. Now, a search
through doc.ddoc to find the declaration LINK2=<a
href="$1">$+</a> at last tells me that argument 1 is the path to
the link and everything that follows that is the text to appear
in the link. The point is that, as I struggle through modifying
the existing .ddoc templates to compile to HTML5, I need to keep
flipping back and forth between the source and the .ddoc to make
sure that anything I'm redefining I'm doing correctly.

3) Again using LINK2, if I were to delete the LINK2= line from
doc.ddoc and forget to readd it, my experience is that dmd -D
will quietly drop instances of $(LINK2) without telling me.

4) Again using the same example, if LINK2 gets defined in
multiple DDoc files, how do I know for certain which definition
it calls when dmd runs against the files?

5) I find that a lot of the DLangSpec is written from an HTML
point of view, so maybe it just needs rewriting to make the
macros descriptive. For example, consider $(B dmd) and $(B -gc)
on lines 881-882 of abi.dd. By default, these get converted into
<b>dmd</b> and <b>-gc</b> Say I want commands (like dmd) to be
bolded but I want command-line arguments not to be bolded.
There's no way to write B= to single out some $(B)s and not
others. Now, I know the knee-jerk response is "Yes, but HTML
works the exact same way." That's true, but CSS *does* give you a
bunch of selectors to cherry-pick, say, "only the <b> tags of
class X" or "the element with this id." Meaning that all I have
to do is find the Bs I want to change and add a class="" without
having to worry about updating any of the other Bs. Is there a
simple way to do this in DDoc?

These are just a few of the observations that I have. As I said
in the other threads, my ePUB effort has ground to a halt because
I find that I'm fighting to read the spec sources rather than
figuring out how to produce clean and pretty HTML5 code that can
get compiled into an ePUB.