DLang Spec rewrite (?)

[Borden]

Good evening, Professor,

On Sunday, 26 May 2013 at 02:05:55 UTC, Andrei Alexandrescu wrote:
> What vexes me is that all the sugar you propose goes against 
> what you opened with...

I'm not trying to cause any offence, and I apologise if any of my 
phrasing or comments are construed that way. I know that I can be 
a little bit terse at times but I hope it's taken in the best 
possible way because I have full respect for the design and 
implementation of the language.

On Sunday, 26 May 2013 at 02:05:55 UTC, Andrei Alexandrescu wrote:
> I can hypothesize that the shortest  path between where we are
> and what you're trying to accomplish is a few dozens of macro
> definitions. Did you try doing that and failed?

Indeed, it has run into some snags:

1) One of the first problems I ran into was coming up with rules 
for spec.dd. My original objective was to enclose the $(TOC) 
macro into <nav> tags, consistent both with the HTML5 spec and 
ePUB3. However, <p> tags are not allowed within the <nav> tags, 
but I also don't want to strip out the explanation the 
informative information. I don't know how to define TOC to keep 
the $(P) macro outside of the <nav> element which will enclose 
the TOCENTRY items.

2) Consider, for example, parsing arrays.dd (my comment can be 
easily applied to any other file). Unless I'm miscounting 
parentheses, $(H4) macros are not being used within $(H3) macros. 
Therefore, how do I get DDoc to parse the file so that it ends up 
with nested <section> tags? for example:
<section><h3>Dynamic Arrays</h3>
<section><h4>Array Declarations</h4>
Content
</section></section>

3) Consider, for example, this part from abi.dd:
$(GRAMMAR
$(I MangledName):
     $(B _D) $(I QualifiedName) $(I Type)
     $(B _D) $(I QualifiedName) $(B M) $(I Type)

$(I QualifiedName):
     $(I SymbolName)
     $(I SymbolName) $(I QualifiedName)

$(I SymbolName):
     $(I LName)
     $(I TemplateInstanceName)
)
Say I want to style this using a descriptions list, the <dl> tag. 
That's easy enough, but now how do I tell DDoc to tag the $(I) 
macros using <dt> and <dd> tags?

4) Furthermore (still referring to the example above, because the 
issue applies to other areas), how do I tell DDoc that $(I)s 
within a $(GRAMMAR) macro are to be formatted using descriptions 
list syntax, but keep the other $(I) macros as regular <i> 
elements?

5) The link-related macros appear, by and large, to use relative 
URLs. If I'm compiling only the DLang Spec into an ePUB, the 
standard, I believe, requires that the links be resolvable. 
That's easy enough if the relative URL in question points to 
another page in the spec. However, if the link points to another 
page on the website or a library document, which (for now) won't 
be in the ePUB, is the only way to identify and fix those links 
going to be by hand?

These are the problems that I've run into thus far. I'm doing my 
best to appreciate the design and theory of DDoc, but maybe it's 
too much of a paradigm shift for me and I end up fighting the 
macros?