DLang Spec rewrite (?)

[Borden]

On Monday, 27 May 2013 at 02:11:00 UTC, Andrei Alexandrescu wrote:
> I think it would be great. In particular, an ebook format would 
> be good.
>
> You may want to wait until 
> https://github.com/D-Programming-Language/dlang.org/pull/271 is 
> in. It systematizes macros a lot and it may offer answers to 
> many of your questions.
>
> Andrei

I appreciate the direct answer to my question, Professor. I would 
start anyway, in my own source copy, checking the existing .ddoc 
files and updating, in the few places necessary, the tags from 
HTML4 to HTML5 - most of these changes are to the HEAD section, 
anyway, and shouldn't require changes.

There are two problems that I've already run into, which I'll 
need experienced help with:
1) doc.ddoc and html.ddoc define many of the macros that I need, 
but some of them I'll need to redefine for HTML5. Walter's 
response to how dmd resolves 'macro inheritence' doesn't clarify 
for me whether I should override the non-HTML5-compliant macros 
or rewrite the whole file. I hope it's not the latter.

Also, I don't understand the difference between doc.ddoc and 
html.ddoc - what is each file supposed to do, exactly?

2) One I have my xhtml5.ddoc, it won't compile the .dd sources 
correctly because many of the .dd files aren't written in a 
manner where simple macro expansion will generate HTML5 compliant 
code. To solve this, I'll need guidance on how to change the .dd 
files to get xhtml.ddoc to work without breaking the other files.

To this end it would be most helpful to develop a standard list 
of macros to use in the DLang spec sources and edit the 
non-conforming .dd files to follow it. It seems right now that 
the source files define whatever macros they like and leaves the 
onus on figuring out what each means on the .ddoc files.