On Fri, 06 Aug 2010 18:54:51 -0400, Walter Bright
<newshou...@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
