Andrei's Google Talk

[Walter Bright]

Don wrote:
> The reason they're the same is that the docs were originally written in 
> html. The original conversion to ddoc was done via search and replace.
> One of the HUGE benefits of ddoc is that it does highlighting of the D 
> code. That instantly saved Walter a lot of time.
> Seriously, converting it to ddoc did improve productivity.

Here's what it has done, and this is real live experience because they were 
originally 100% html:

1. Yes, Don is right. It has improved ENORMOUSLY the productivity in those 
documents. I'm talking doubling or even tripling it.

2. I can comment out sections with $(COMMENT blah blah) and have them elided 
from the output. HTML comments remain in the output.

3. It has enabled the site to be written in correct, conforming HTML. 
Previously, it was a mess, and I didn't know what was wrong with it because it 
rendered ok anyway.

4. HTML has zero provision for conditional compilation. Want two HTML pages from 
the same source? Write two HTML pages. Note that the D1 and D2 docs are 
generated from the same source, this makes it easy to determine what's different 
between them.

5. It enabled me to produce a common look & feel for the whole site, which is 
hundreds of pages. This was just impossible before.

6. Even better, I can *change* the look and feel of the site with just editting 
a handful of macros.

7. I can update URLs across the site trivially, such as if bugzilla changes its URL.

8. As Don mentioned, it will automagically syntax highlight D code.

9. Grep doesn't work well with HTML tags. You really need an HTML-aware editor. 
Ddoc works with any editor (all you really need is a parentheses matcher).

10. HTML is a visually butt-ugly format that makes my eyes bleed pus. Very hard 
to read.