DLang Spec rewrite (?)

[Jonathan M Davis]

On Sunday, May 26, 2013 18:21:50 H. S. Teoh wrote:
> But right now, Ddoc already translates blank lines to $(BLANKLINE) (or
> something like that). I'm just saying that paragraphs in the input
> should be recognized as such, and automatically wrapped in $(P ...).
> Then you can either define P=<p>$0</p> for HTML, or P=$0\n for LaTeX.

That might work, but also remember that macro expansion is context-free, which 
could cause issues.

> > It would be simple enough to run a program over the .dd file before
> > running it through dmd in order to add the $(P) macros were
> > appropriate, but then I have to worry about getting the logic right on
> > that, and things like code examples could screw with that (you
> > wouldn't want to insert $(P) into code examples).
> 
> That's easy: code examples are delimited by ----. Ddoc already treats
> those differently from normal running text, so I don't see why it would
> be a problem to say that paragraphs in normal text will automatically be
> wrapped in $(P).

In may not be hard, but I'd have to have quite a bit of text written to test 
with to make sure that there isn't a corner case that I'm missing. So, for the 
moment, I don't want to deal with it. And as macro expansion is context free, 
I don't know that you _can_ make it so that replacing $(BLANKLINE) with $(P) 
will work. You'd have to expand each $(BLANKLINE) into )$(P, which could cause 
problems on the first one and the last one, and I don't see how it could take 
--- into account. It would be easy enough to make dmd itself handle it, as it 
could do something more advanced than macro expansion, but then ddoc is doing 
more than macro expansion, and I'm not sure that that's acceptable with 
Walter.

> > So, while it's quite feasible, I'm just putting up with $(P) for now.
> > But we can't have a general ddoc solution for this without changing
> > how ddoc works in a way that makes it so that it's not just a macro
> > system anymore.  Without another program to massage the ddoc in your
> > file first, you're stuck with $(P).
> 
> Which is ugly. One of those nagging things that detract from my
> enjoyment of Ddoc.

I'm already having to have a program for generating a table of contents and 
index. Those _can't_ be done with ddoc, as they require generating stuff 
completely separate from the macros (treating them as markup rather than 
macros really). It's a bit annoying, but it's also not all that hard, and most 
documents written with ddoc probably don't require that sort of thing anyway.

So, yes having to do $(P) is ugly, but I don't know how to get out of that 
without making ddoc more than a macro system, and I don't want to take the 
time right now to make my build program do it for me.

- Jonathan M Davis