DLang Spec rewrite (?)

[Andrei Alexandrescu]

On 5/26/13 10:45 PM, Borden wrote:
> 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.

Just define the macros that differ and when compiling docs do this:

dmd $FLAGS doc.ddoc html.ddoc html5.ddoc myfile.dd

That way the macros defined in html5.ddoc will override those in the 
previous files.

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

doc.ddoc is the general skeleton file for defining the online 
documentation. html.ddoc contains HTML-specific macros only, without 
having anything to do with our site's specific format.

> 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.

Yup, you got your work cut for you. Then again, wait til that diff is 
merged. It fixes a bunch of problems.


Andrei