DLang Spec rewrite (?)

[Jonathan M Davis]

On Saturday, May 25, 2013 21:30:44 Walter Bright wrote:
> On 5/25/2013 8:55 PM, Jonathan M Davis wrote:
> >> 3) Again using LINK2, if I were to delete the LINK2= line from
> >> doc.ddoc and forget to readd it, my experience is that dmd -D
> >> will quietly drop instances of $(LINK2) without telling me.
> > 
> > Then perhaps dmd should be fixed so that it complains. That's a quality of
> > implementation issue and probably easily fixed.
> 
> It's quite deliberate, is not a QoI issue, and doesn't need to be fixed.

Hmmmm. Because it's designed with idea that you can make multiple passes? 
Well, regardless of why, the fact that it doesn't give an error doesn't harm 
ddoc's expressiveness. So, in questions of whether ddoc is powerful enough or 
expressive enough to do something (which appears to be the thrust of Borden's 
complaints) aren't affected by it.

My main complaint about ddoc is actually not a complaint about ddoc but about 
html. I find it very annoying to have to put $(P ) around every paragraph. Stuff 
like LaTeX does that automatically based on blank lines, which is way better 
IMHO, but if you're targetting HTML, then unfortunately, you need to mark 
paragraphs. The only way to fix that with regards to ddoc would be to make it 
so that ddoc understood that blank lines meant new paragraphs and inserted 
<p></p> appropriately, when generating html, but that would make it so that 
ddoc was less general, and there might be other negatives to that I haven't 
thought of. So, we just get to deal with $(P ) I guess.

And it's easy enough to write a program to handle the stuff that ddoc _can't_ 
do (like generate a table of contents from all of your CHAPTER tags), that 
ddoc's limitations really aren't a big deal, and its flexibility is fantastic.

- Jonathan M Davis