DLang Spec rewrite (?)

[Borden]

On Sunday, 26 May 2013 at 03:56:08 UTC, Jonathan M Davis wrote:
> AFAIK, your recent posts on ddoc are the first that anyone has 
> complained about it in quite some time. There are plenty of
> folks who want various improvements to the online documentation,
> but doesn't necessarily require doing anything to ddoc, and it's
> rarely the case that someone complains about ddoc itself.

That's fair, and has probably only come up now because I've 
decided - granted with very little experience in DDoc - to kick 
the proverbial hornets' nest by diving head-first into it and do 
crazy things with the source.

On Sunday, 26 May 2013 at 03:56:08 UTC, Jonathan M Davis wrote:
> Normally, you'd nest things by nesting macros. e.g.
>
> $(NESTED stuff $(NESTED more stuff $(NESTED yet more stuff) 
> $(NESTED other
> stuff)))

Indeed. I suppose, in addition to my grievances about error 
checking, is suggesting that DDoc should include parentheses 
closure checking?

On Sunday, 26 May 2013 at 03:56:08 UTC, Jonathan M Davis wrote:
> However, ddoc should allow you to do pretty much anything that 
> involves simply transforming the content of a macro to 
> somethnig else. The macro takes a set of arguments and then 
> creates something new with them by rearranging them and adding 
> stuff around them and the like.

And maybe that's what my biggest frustration with the macros is 
(or at least how they're implemented in the DLang spec): they 
read like an abstracted wrapper for HTML, and someone like me 
immediately yearns for the extra features that got simplified out.

Say, for example, we have a $(B) macro, and I want some of them 
to have ids or classes and others not (since my eventual CSS file 
will have special formatting rules for them). To add this 
functionality, I would have to find all of the $(B)s and rewrite 
them to say $(B id, class, content). For each one that I miss, 
I'm going to have an empty <b> element with its id set to the 
content!

On Sunday, 26 May 2013 at 03:56:08 UTC, Jonathan M Davis wrote:
> The exact set of macros used with the online documentation may 
> very well be too specific to html 4, and it may be that the
> macros will have to be rewritten and moved around in the
> documentation

And now I think we're getting to the heart of the problem. I 
might have a more favourable opinion of macros if they were more 
descriptive of the content in the DLang spec source files. That 
would allow a fair bit more flexibility.

Still, I don't think there's any avoiding that any macros 
requiring nested formatting or special parameters will require 
them to be written with their intended output formats 'in mind' 
to work correctly. And, of course, I am very reluctant to attack 
any of this lest I start breaking the website, Latex or PDF 
generation in getting the DLang spec 'HTML5 ready'.

Hence, why I'm at a standstill.