Pier,
I am a bit confused now. I thought the module 'xml-site' was on its way to
getting obsolete. The place where I have been recommended to pick up the
latest styles from is, 'xml-stylebook' not 'xml-site'. This probably makes
sense for some of us because all sources files for a project, which include
the source XML documentation, would then reside togehter under the same
directrory as the module. If we keep XML source files outside (under
xml-site), then people who get the *source drop* will miss out on the XML
documentation which is also part of the source.
This however brings up another issue - that of integrating the entire
xml.apache.org website and creating it in one shot, a convenience we have
if we keep all XML docs under xml-site. But as I realized later on, this is
not such a big drawback since you can always create the HTML docs (by
invoking java and Stylebook) by pointing it to the 'xml-stylebook'
directory. So essentially the recommended structure looked cleaner to me
since, projects can keep their entity files separate (earlier structure had
Java and C entities together in one file), and someone who does not want to
deal with the intricacies of Stylebook can invoke it like a black-box by
just pointing to the right directory.
The Xerces-Java and Xerces-C already have started following this scheme,
(Xerces-Perl is next). But I do not know how far Xalan and the other folks
have gone in this direction. Lets decide on something and fix it once and
for all.
- Anupam
===========================================================
Anupam Bagchi
Advisory Software Engineer
Phone: (408)777-5842 Fax: (408)777-5892
XML Development Group, IBM Cupertino, California
Pierpaolo Fumagalli <[EMAIL PROTECTED]> on 01/24/2000 12:23:18 PM
Please respond to [EMAIL PROTECTED]
To: general@xml.apache.org
cc: [EMAIL PROTECTED], xalan-dev@xml.apache.org,
cocoon-dev@xml.apache.org, fop-dev@xml.apache.org
Subject: New XML-SITE module structure, and documentation changes
I had few problems regenerating the documentation this week-end, mostly
due to my lack of ability on transmitting informations to the proper
people (read, the ones who write documentation).
It's better, so, to fix a couple of stuff, and, at the same time, make
some changes that will inprove, IMVHO, the documenation process of all
our subproject.
The XML-SITE is the basic repository for DTDs, styles and target output.
It's structure will be the following:
/home/cvs/xml-site/style (the shared-repository)
/home/cvs/xml-site/style/dtd (all dtds)
/home/cvs/xml-site/targets (the generated HTML+images)
/home/cvs/xml-site/sources (the source XML)
Since the task is to enable stand-alone document generation, I would
like to propose to each project the following structure:
/home/cvs/xml-XXX/???/docs (the root documentation)
/home/cvs/xml-XXX/???/docs/sources (the project source XML doc files)
/home/cvs/xml-XXX/???/docs/style (a symlink to
/home/cvs/xml-site/style)
Then in "/home/cvs/xml-site/sources" there will be symlinks to each
individual project doc sources. For example:
> /home/cvs/xml-site/sources/xerces-j ->
/home/cvs/xml-xerces/java/docs/sources
Whoever write documentation can commit changes in either the project
module itself, or in the xml-site module, and those changes will be
reflected in the other module.
As for the book files, we need to have two of them, I was thinking about
having two copies of them, one with the sources (that could be used to
generate the documentation) and one in the xml-site module that can be
used to generate on line docs for the website (mainly because in the
shipped docs we don't want to have a link to the top "website" page
(first link in most projects on the sidebar).
How about it? Can I go on and make those tweaks, build the scripts, and
so on?
Pier
--
--------------------------------------------------------------------
- P I E R -
stable structure erected over water to allow the docking of seacraft
<mailto:[EMAIL PROTECTED]> <http://www.betaversion.org/~pier/>
--------------------------------------------------------------------
- ApacheCON Y2K: Come to the official Apache developers conference -
-------------------- <http://www.apachecon.com> --------------------
