Donald_Leslie@lotus.com wrote:
>
> 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").
I don't really transfer them... Those are symlinks on the server, so,
they already exist in two places but in an atomic way (one file, two
locations).
> 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.
Good for me... Also because usually in the docs you generate to ship
with the distribution you don't want to have the initial button in the
sitemap that points back to "../index.html".
> 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.
Keep them in the same directory and there will be no problems, and keep
the links in your source files as "./BUGS", "./STATUS"... or a
subdirectory of it "./files/BUGS"... If you don't use "../something" you
won't have problems.
> 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.
One can rebuild a single project or all of them... Since there's no JDK
1.2 on locus for sidemap images generation, I will go on running the
thing like once a week...
> 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
Yep right...
> 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.
You want to keep also the generated HTML under CVS? It doesn't make much
sense to me, but, hey, it's your module :)
> 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.
It doesn't really mean what are your directory names, until we keep the
sbk:// thing... But since it seems to create some confusion, I was
thinking about removing it and standardizing the directory naming...
It's up to you. I just do the build.
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> --------------------
