db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean T. Anderson" <...@bristowhill.com>
Subject [doc] What should the DITA source produce and how should it be produced?
Date Thu, 03 Mar 2005 00:45:25 GMT
I'm starting a new topic for questions raised on the thread "[doc] Where 
should the DITA source files be checked in?" -- for the start of that 
thread, see

Andrew McIntyre asked:

> This brings up several other question: should we have a copy of the built documentation
checked in with the source for developer reference or only keep a copy in derby/site? 
It seems sensible to keep a copy of the build doc with the source it 
goes with, but would you just keep the built doc for the Developer's Guide?

> Is there a convenient way for the source to live in derby/code/{branch} and also be built
by the forrest from derby/site? 

We can specify non-default file locations in the forrest configuration 
files; however, it has been excrutiating to build all the manuals with 
each web site update.

I strongly urge not using forrest to build the manuals. Instead build 
the docs separately, then check the built doc into the forrest source.

The navigation that forrest adds to the built manual pages isn't always 
useful nor desirable. See the original discussions at 
and also in DERBY-79 at http://issues.apache.org/jira/browse/DERBY-79

> Will we keep versions of the docs on the site for the trunk and the branches if they
diverge significantly? 

good question.

> If not, what version do we keep up, latest development docs or latest stable docs?

good question.

> Won't this setup still require regenerating HTML/PDFs each build or is there a way to
have forrest only update them if the source is newer than the output? 

No; we could include the built docs as a "raw" product.

Discussion about xsl by Jeff Levitt and Scott Hutinger are in 



View raw message