Pier,
I like your idea -- I hate having to check the Xalan xml files into 2
places, xml-xalan, and xml-site. Using Xalan as my example, please let me
verify my interpretation of your memo.
xml-xalan/docs/sources maps to xml-site/sources/xalan and contains all of
our xml source files and entities.ent. When you do a site build, you
transfer entities.ent to xml-site/sources for each subproject build
(book.dtd is looking for "sbk://sources.entities.ent").
xml-xalan/docs doesn't map to xml-site/sources. In fact I keep a copy of
the site-book (xalan.xml) and local-book (xalanLocal.xml) here, and I also
maintain a copy of xalan.xml on xml-site/sources. Right? This is fine with
me. Maintaining a single document (that rarely changes) in two places is a
lot easier than maintaining all the documents (most of which are chaning
all the time) in two places.
Currently one of our documents imports BUGS, DONE, and STATUS (all xml
files) from the xml-xalan root. As I understand it, this would not work
under the new scheme, since the references to these files must be relative
(e.g., ../../BUGS) to work in other environments. But I can adjust to that
if need be.
Site updates would no longer be under the control of each subproject, so we
would have to be careful to always keep our doc repositories in a
presentable state. I guess that's OK in exchange for not having the
headache of each having to update xml-site.
PROPOSAL: I suggest we adjust the naming of doc source directories in our
subproject repositories as follows:
xml-xalan/xdocs
xml-xalan/xdocs/sources
xml-xalan/xdocs/sources/xalan
xml-xalan/xdocs/style (with dtd, stylesheets, resources, and graphics)
-- presumably all mapped to xml-site/style
Why xdocs? To distinguish between our source documents and the html
documents that we distribute. We plan to adopt the Cocoon pattern of
including a docs directory in our distribution with html docs and an xdocs
tree with our sources. Using the same name in the repository helps keep
that distinction clear.
Why xdocs/sources/xalan? Because that maps cleanly to
xml-site/sources/xalan and allows us to build from our repository (and from
an identical structure in our distribution) with no modifications to the
structure of our book, source, stylesheet, and dtd files. I have noticed
some StyleBook problems with "sbk://;sources" references. Sometimes
"sources" means the current directory (where you are running StyleBook),
and sometimes StyleBook cannot find files if the current directory is named
something other than "sources" (such as "docs" in your proposal). So for
reliability, simplicity, and ease of use, I think we should use the same
doc trees (structure and names) in our individual repositories, in the
xml-site repository, and even in our distribution, despite the oddity of
embedding the project name in a project subdirectory. If we don't do this,
I know I'll have to keep experimenting -- and coming up with minor
modifications for each case) to come up with StyleBook builds that work for
all our environments.
-- Don
Pierpaolo Fumagalli <[EMAIL PROTECTED]> on 01/24/2000 08:19:41 PM
Please respond to [EMAIL PROTECTED]
To: [EMAIL PROTECTED]
cc: (bcc: Donald Leslie/CAM/Lotus)
Subject: Re: New XML-SITE module structure, and documentation changes
[EMAIL PROTECTED] wrote:
>
> 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.
The styles in xml-site and in xml-stylebook are the same ones. If you
make a change there, you get a change also in the other module.
> 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.
Exactly... That's why I am willing to get the primary repositories of
XML documents in the subprojects modules... And from there to have a
link in xml-site when things need to go "live"...
> 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.
ok... so all the documentation is now in the project modules? all the
updated ones are there? good. I just need to know it...
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> --------------------
