Andrei's Google Talk

[retard]

Sat, 07 Aug 2010 16:54:03 +0200, Jacob Carlborg wrote:

> On 2010-08-07 00:54, Walter Bright 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.
> 
> I think for any serious HTML work you need a server side language to
> help you.

Comparing hand-written html to ddoc is a bit unfair. I've used several 
CMS and template systems. They even have good support for D. My 
experiences tell me that

1. ddoc has worse productivity than real document generators such as 
doxygen or good cms/markup/web template systems.

2. these other systems also support commenting out stuff

3. these other systems also support generating correct, conforming HTML/
XML/TeX/PDF/MAN/whatever. With ddoc you need to use some semi-official 
templates you need to dig from the newsgroup archives. Doxygen provides 
all this by default. How is that bad for productivity?

4. these other systems also support conditional compilation

5-6. these other systems also support separating the style/layout from 
the structure.

7. ditto (and it's better than what ddoc produces by default)

8. ditto (and it's better than what ddoc produces). ddoc doesn't extract 
all components of symbol signatures in a structured way.

9. ditto

10. the other systems look better than ddoc

So overall the other systems are much better and I also think I could 
write something 10 times better than ddoc in 2..7 days if someone would 
give me an untainted GPL licensed frontend that didn't look so butt ugly.