xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Pogue <mpo...@apache.org>
Subject Re: A better model for site generation
Date Tue, 25 Jan 2000 20:38:51 GMT
Stefano Mazzocchi wrote:
> I've been playing around with Stylebook for the last two days to come up
> with a better look and feel since our documents use more complex DTDs
> and require more expressive power.

Technically, look and feel should be the role of the Style, not the role
of the DTD.
However, if there is additional *semantic* tagging that you feel is
needed, there's
definitely the opportunity to add this.
> But every time I think about "forking" the DTDs, I feel bad, knowing the
> pain that will generate.

What changes are you suggesting?  Could they be done in an upward
compatible way?

I suggest we use the "theory of parsimony" here, i.e. the DTD should be
as simple as
possible (but not simpler).  For example, Docbook is extremely complex,
even though its expressive power is very high.  Even though each
additional feature provides *some* additional value, it also makes it
harder to learn (which decreases value).  

Let's be very careful not to add more functions, just because we can
(the eternal temptation, especially when it's real easy to add new
functions)...I'd like to keep the tagset to where any "Joe Writer" can
use it, without taking a course in XML first!  

> On the other hand, we need a better model for site generation



> The idea is simple:
> 1) every project has its own docs files, DTD and skin (those who wish to
> use global ones, will have the CVS symlinked for them).


> 2) doc writers should work on their docs and forget about anything else

Yep.  However, they also shouldn't have to learn a new tag set each

> 3) we should not move thing around: it's easy to make mistakes


> 4) generating the site should be as easy as: login; cd
> /home/www/xml.apache.org; ant site

I'd suggest that the site generation should be not be dependent on ANT
(or any other particular tool), by abstracting into a script, i.e.
	cd /home/www/xml.apache.org;
	build-site;  (which might internally call ANT or something else)

View raw message