db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean T. Anderson" <...@bristowhill.com>
Subject Re: Derby documentation in PDF format
Date Fri, 08 Oct 2004 17:38:29 GMT
Jonas S Karlsson wrote:

>...
>
>I'm sorry if I wasn't clear. I consider our "src"-files (the .ihtml)
>files to be generated, they were not written by a human:
>  
>
oops! thanks for the clarification!

The *.ihtml files actually are the Derby source for the manuals.

As I understand it, the Cloudscape doc set source is stored in ArborText
Epic. The IBM docs person generated files for Derby from Epic as
multiple html files, then modified those to ihtml for forrest and to
reflect Derby. --Also, I made a heavy pass through the ihtml docs as
well before checking them into the subversion repository.

The IBM docs person said it's easy to generate a single file per book,
but he doubted there was a way to reapply all the changes correctly.

I see several options at this point:

(1) Ask IBM docs to regenerate them as fewer files, then the Derby
community applies all the changes that need to be made, starting from
scratch.
(2) Derby community starts (perhaps slowly) consolidating the existing
ihtml files into a more desirable format.
(3) <==== your fine idea goes here =====>

Incidentally a fewer number of files would have the benefit of reducing
the size and complexity of the forrest site.xml file.  A file gets
associated with the site by an entry in the site.xml file.  If an entry
for that file is not there, forrest generates a left-hand navigation tab
with the entire site contents. It made me sea sick the first time I
encountered it. If you want to see this effect, edit your local copy of
the site.xml to remove all but the "table of contents" and "index"
entries for the manuals, do 'forrest site', then 'forrest run', then
click on a page in one of the manuals.

So, the current site.xml has an entry for every page in every manual.
With the exception of the "table of contents" and "index" pages, 
entries don't have a label so it doesn't explode that navigation bar.
--Imagine 700 files listed in that navigation tab. One problem remains
that I haven't been able to figure out. The pages without a label get
correctly associated with the Manuals tab (and that tab gets built
correctly), but you lose context for the specific manual to which the
page belongs.

This problem would be solved by consolidating many files into fewer so
that all can be listed with a label in site.xml.

 -jean


Mime
View raw message