xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject A better model for site generation
Date Tue, 25 Jan 2000 15:45:01 GMT
People,

as you all know, the xml.apache.org site plus all the documents included
in all the hosted projects are built using XML/XSL technology, driven by
Stylebook, a command line clone of Cocoon written by Pier when working
for IBM.

Stylebook and Cocoon share the exact same design patterns, even if not a
single line of code. This is going to change since we believe in
integration, like many others here.

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.

But every time I think about "forking" the DTDs, I feel bad, knowing the
pain that will generate.

Anyway, I'll do it and see who wins.

On the other hand, we need a better model for site generation: Donald
(Leslie) and Pier were discussing about a standard way to place
documents, DTDs and site skins on the different packages. I agree we
need to define such a thing.

Donald proposed to follow our pattern used in the distribution

 /docs/ -> generated HTML docs
 /xdocs/ -> source XML files

so here is the pattern that we should follow to allow better integration
between projects with site tools and stuff:

 /xml-<project>/[language/] --> root of the project (language is
required only when the projects spans multiple languages, could we move
xalan-j under java/? without loosing CVS information?)

 build.xml -> ant build file
 /src      -> source tree
 /samples  -> samples
 /xdocs    -> document source

a few directories are left for generation (as standard ant build files
do)

 /build    -> building
 /dist     -> distribution
 
so you should not use them for your purposes. NOTE: /docs should never
be used in the CVS. Also, no generated info should be in the CVS rather
than aAll other directories are left for your needs.

 /xdocs        -> XML documents
 /xdocs/dtd    -> their DTDs
 /xdocs/skins  -> the stylebook skins
 /xdocs/images -> images used inside XML documents

Now, to reduce effort Pier proposed to symlink the appropriate
directories to xml-site so that one repository for site skins and DTDs
is located. I like this proposal even if makes the directories and their
contract very solid. this is why we should discuss them here before
doing such a thing and find an agreement.

Then, Pier will work on having a JDK 1.2 on locus (not easy, since we're
running FreeBSD) so that site generation can be done there.

I propose to _remove_ everything from xml-site but the instructions and
scripts on how to generate the site. The script should use CVS to
download the documents from all the different modules, then each project
build.xml file should have a "site" target that generates its
documentation for the web site.

The key is duplication of effort.

I think we should minimize the use of symlinks across CVS modules, since
this is clearly a dirty hack. The only good symlinks are those that
require the presence of information inside the CVS modules, but stuff
that doesn't really belong there as for development purposes.

So, my proposal is:

 1) remove xml-site all together (or leave it with scripts and
instructions)
 2) place the skins under xml-stylebook in a well structured directory
 3) install JDK 1.2 on locus using FreeBSD Linux emulation and the
latest Sun/Imprise/BlackDown JVM for linux.
 4) create a script that generates the web site and place it in
/home/www/xml.apache.org

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

that's it.

I won't stop bugging people around here until we find a global agreement
on this. So, be prepared: I just turned my "pain-in-the-ass" mode on :)

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------
 Come to the first official Apache Software Foundation Conference!  
------------------------- http://ApacheCon.Com ---------------------



Mime
View raw message