Andrei's Google Talk

[Steven Schveighoffer]

On Fri, 06 Aug 2010 18:54:51 -0400, Walter Bright  
<newshound2 at digitalmars.com> wrote:

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

First, for 5 and 6, that is what CSS is for.

Second, I agree with all your other points (except for the eye bleeding  
thing).

But I find the tagging for just formatting (such as $(P, $(B $(TT) very  
hard to read and hard to diagnose.

It looks to me like writing D code like this:

mixin("int i = 1;");
mixin("i += 2;");

instead of this:

int i = 1;
i += 2;

Sure, the mixins are dynamic, but you are not using them in a dynamic  
way...

Wouldn't it be better to just write html when that's all your asking ddoc  
to do?  Or does the risk of blindness dissuade you too much?

FWIW, I work with HTML, CSS, php, and smarty templates every day.  I  
understand the value of dynamic content, but I don't use dynamic  
techniques to generate static content, that's written in good old html.

-Steve

-Steve