You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by Joel Rosi-Schwartz <Jo...@Etish.org> on 2004/10/07 14:15:32 UTC
Derby documentation in PDF format
I personally found the PDF document set that was available for Cloudscape 10
beta to be very useful. I am hopeful that this packaging of the documentation
will be carried forward into Derby. Has there been any consideration toward
providing this?
Thanks,
Joel
Re: Derby documentation in PDF format
Posted by Joel Rosi-Schwartz <Jo...@Etish.org>.
I would like to express my joy with this community. Every questions and/or
suggestion that I have made has actually led to conversation that moved the
item forward. I have been following all of the threads, not just mine, and
this seems to be the general state of affairs. The team are real doers and it
is a pleasure a watch the progress as this project comes together.
Kudos and thanks for the great efforts.
- Joel
On Friday 08 October 2004 15:06, Jean T. Anderson wrote:
> Jonas S Karlsson wrote:
> >Jean T. Anderson wrote:
> >>The IBM docs person generated html for each Cloudscape manual, with
> >>multiple files per manual, and did a first pass at modifying them to
> >>reflect the Derby name and to modify them so Forrest could ingest them.
> >>If I remember right, there are roughly 700 src files. Forrest ingests
> >>those files, adds the site navigation, and outputs the built files.
> >
> >I can't find the source with the correct markup anywhere in the tree.
> >I only find generated HTML files, I think.
>
> I put a brief writeup on the Derby web site source files here:
> http://incubator.apache.org/derby/papers/derby_web.html#3.+Modify+files+in+
>the+src+tree+
>
> The source files for the manuals are in
> src/documentation/content/xdocs/manuals/*.ihtml .
> Forrest puts the built files under build/site.
>
> >I hope we're not planning on editing generated HTML-files, because
> >that'd be a nightmare. It'd be like adding functionality and fixing bugs
> >in Derby by directly modifying the compiled class files.
>
> It isn't a terrific idea to edit the generated HTML files; see
> http://incubator.apache.org/derby/papers/derby_web.html#8.+Considering+a+qu
>ick+fix+to+the+build+tree%3F
>
> >>while to generate the web site. Right now, with PDF generation off, it
> >>takes about 20 minutes to build the site on my Gentoo linux box. It
> >
> >8 minutes for me, actually Forrest seems to be built to allow for
> >dynamic generation of pages from source, so one may not need to
> >actually update/checkin html pages, but I guess that's a totally
> >another issue.
>
> 8 minutes? You're on a faster box .... :-) Actually, the build time does
> vary depending on what changes are being made. For example, changes to
> the site.xml file result in longer build times.
>
> Forrest builds any source files it finds under the xdocs subdirectory.
> The generated html pages must be checked in. Those changes only become
> visible when a Derby mentor issues an 'svn update' command; see
> http://nagoya.apache.org/eyebrowse/ReadMsg?listName=derby-dev@db.apache.org
>&msgNo=202
>
> You have lots of excellent questions, which I'll try to capture into the
> derby_web.html page. I whacked that page together quite quickly. Please
> let me know how I can improve it to make it more helpful/useful.
>
> -jean
Re: Derby documentation in PDF format
Posted by Jonas S Karlsson <js...@yesco.org>.
Jeff wrote:
> Yes the main bottleneck in getting our information into DITA will be
> getting the doc content into the new format. Once it is done, we will
> have vastly improved the quality of the documentation's retrievability.
> Add the fact that we will be single-sourced and able to create output in
> any format we want, and we have a good case for the conversion.
I still don't know what exact format is used for the Derby docs, since
the source files have not been made available.
Jean mentioned:
> 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
But ArborText Epic is "just" an XML editor (and Content Engine) as I
understand it. It does not limit or specify (?) which format to
use. Actually, I find that docbook is quite often mentioned as the
source format used in that editor/environment.
So, just to calm my curiosity ;)
What is the current XML format used for the soure doc files?
How different is this format from Docbook? (Can I see an example)
/Jonas
Re: Derby documentation in PDF format
Posted by Jeff Levitt <jl...@Mutagen.Net>.
Thanks again Scott,
Yes the main bottleneck in getting our information into DITA will be
getting the doc content into the new format. Once it is done, we will
have vastly improved the quality of the documentation's retrievability.
Add the fact that we will be single-sourced and able to create output in
any format we want, and we have a good case for the conversion.
I also appreciate the offer to help. If no one has any objections or
concerns, I will start working on this, perhaps first with the "Getting
Started with Derby" book first as it is the smallest. If I need any
help, I'll take you up on your offer, Scott, as well as anyone else who
may want to help. Once the first book is converted, we can take a look
at it and see if it works out for everyone, and depending on the wishes
of the community, we can continue on with the conversion of the other books.
How does this sound? If no one has any objections, I will begin working
on this.
Thanks,
Jeff
scott hutinger wrote:
> Yes Jeff, that does help get a better handle on portions.
>
> I think a lot of this information is that content isn't written in the
> format it actually should be. I think the real world defines this
> very well, as going to a store and trying to dig into how the
> information is sorted (most likely not), sometimes gets frustrating.
> I think currently for Derby, since the documentation is within a
> linear format, that portions of DITA are not really important as of
> today, although possibly in the future this might become very
> important. I am very disappointed most of the time, trying to find
> the information I want. I see that DITA is trying to get writers to
> think in a new manner or mode, which looks like it might fit within a
> model that really is good. I do think that even though the current
> documentation may be within a linear format, it doesn't need to be
> after put within DITA.
>
> I do see some very interesting use of this, not even related to
> documentation. For instance Sun Studio Creator has some pre-made
> clips of "How to Use", which I think would be easy to incorporate
> within DITA. For those that use SQL once every couple years, that
> would be handy, and could be 'embedded' within the documentation, and
> pulled out easily. Of course, of main importance, taking the current
> documentation and getting it in a format easier to modify. My
> thoughts are that this looks like a very good step in a direction that
> would fix the immediate needs of the mainline documentation with the
> target being reuse. Possibly some drawbacks might exist at the start
> (unknown at this time), but I don't really think this is all that
> important.
>
> I would have to thank Jeff for thinking about getting the
> documentation in this format. :-) Also, if any help is needed in this
> area, I can give time to this.
>
> My thoughts only,
>
> scott
>
>
>
> Jeff Levitt wrote:
>
>> Thank you Scott,
>>
>> To save you or anyone else who is interested some time, one of the
>> documents at that site provides a great overview to the advantages of
>> DITA. It is located at:
>>
>> http://www.oasis-open.org/committees/download.php/6637/DITA-technologyreview.pdf
>>
>>
>> It is 16 pages long, but you probably only need to scan the first 7
>> pages or so to get a sense of what issues led to the creation of
>> DITA, its advantages, and how it works. The rest is more technical,
>> down to the language level.
>>
>> Hope that helps!
>> Jeff
>>
>> scott hutinger wrote:
>>
>>> I just thought others might like to know that looking at some of the
>>> DITA information might be a bit on the verbose side, and might take
>>> a bit more time to get feedback on this. I am by no means a
>>> document specialist, and I am a bit uncertain how many in this group
>>> really are? Possibly Jeff might be the best person to get any
>>> information on 'what might be any possible objections'?
>>>
>>> DITA seems to look like a very good alternative to the current
>>> problems in my view, but I just follow this group very closely, so
>>> guess I don't count :-)
>>> But I have been looking at all the DITA information since this
>>> morning, and thought I might be able to help a bit in this, but...a
>>> lot of information to look over exists.
>>>
>>> From what I have seen, I think it looks great!
>>>
>>> scott
>>>
>>> Jeff Levitt wrote:
>>>
>>>> Jean T. Anderson wrote:
>>>>
>>>>> 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
>>>>>
>>>>>
>>>>>
>>>>>
>>>> I am the 'IBM docs person' that Jean and Jonas mentioned in their
>>>> responses earlier. I'm very glad to see that people liked the
>>>> Cloudscape PDF's. In a perfect world, I would have created a
>>>> solution that would allow you to generate whole PDF's of each of
>>>> the docs for Derby. Unfortunately, I did not have enough time
>>>> before I had to have a solution in place to contribute the docs to
>>>> Derby, so my quick fix was to create the html for Forrest that you
>>>> now find with Derby.
>>>>
>>>> But now that I have more time, I have been trying to come up with a
>>>> solution to several issues that the html presents, many of which
>>>> have already been brought up in this discussion. Indeed, html is
>>>> not a very good source format. Ideally, it would be nice to have
>>>> XML source. This would solve several problems. First, we could
>>>> use the XML to generate one PDF, or many html files, or just one
>>>> large html file. In effect, we would have a single source that
>>>> would allow us to output the documentation into any format we
>>>> want. In addition, the conversion to XML would remove these
>>>> "blank" files that Jonas mentioned.
>>>>
>>>> I would like to convert the Derby documentation to XML DITA. DITA
>>>> is an open-source initiative for creating XML-based documentation.
>>>> You can find out more about the DITA open-source standard
>>>> initiative at
>>>> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
>>>>
>>>> Converting to XML DITA solves the above problems, but also improves
>>>> the QUALITY of the documentation immensly. DITA allows you to
>>>> create "articles" of information based on the books' contents that
>>>> can stand alone on their own or within the book context. ALL of
>>>> the information in the 6 Derby books would be placed in articles
>>>> that are classified as either concepts, reference material, or
>>>> tasks. In addition, we can further classify them as installation,
>>>> configuration, development, adminstration, any many other
>>>> descriptive catergories. Then, users can sort the documentation by
>>>> catergory, allowing them to look up only "development reference" or
>>>> "installation tasks" etc, independent of the books. And users who
>>>> still want to use the book motif can use provided mapping files
>>>> that automatically resort the articles into the proper order for
>>>> each book and generate html, PDF's, etc. DITA basically solves all
>>>> of our problems and improves the retrievability of the documentation.
>>>>
>>>> The conversion to DITA will take quite a bit of time. In the
>>>> meantime, we could still use the current setup to modify the html
>>>> files and build with Forrest. But once the conversion is done and
>>>> we recontribute the new doc set to Derby, I think the benefits far
>>>> outweigh the delay.
>>>>
>>>> I would be interested in what members of the community think about
>>>> this proposal. If there are no objections, I could begin work on
>>>> this very soon.
>>>>
>>>> Jeff Levitt
>>>>
>>>
>>>
>>
>
>
Re: Derby documentation in PDF format
Posted by scott hutinger <s-...@wiu.edu>.
Yes Jeff, that does help get a better handle on portions.
I think a lot of this information is that content isn't written in the
format it actually should be. I think the real world defines this very
well, as going to a store and trying to dig into how the information is
sorted (most likely not), sometimes gets frustrating. I think currently
for Derby, since the documentation is within a linear format, that
portions of DITA are not really important as of today, although possibly
in the future this might become very important. I am very disappointed
most of the time, trying to find the information I want. I see that
DITA is trying to get writers to think in a new manner or mode, which
looks like it might fit within a model that really is good. I do think
that even though the current documentation may be within a linear
format, it doesn't need to be after put within DITA.
I do see some very interesting use of this, not even related to
documentation. For instance Sun Studio Creator has some pre-made clips
of "How to Use", which I think would be easy to incorporate within
DITA. For those that use SQL once every couple years, that would be
handy, and could be 'embedded' within the documentation, and pulled out
easily. Of course, of main importance, taking the current documentation
and getting it in a format easier to modify. My thoughts are that this
looks like a very good step in a direction that would fix the immediate
needs of the mainline documentation with the target being reuse.
Possibly some drawbacks might exist at the start (unknown at this time),
but I don't really think this is all that important.
I would have to thank Jeff for thinking about getting the documentation
in this format. :-) Also, if any help is needed in this area, I can
give time to this.
My thoughts only,
scott
Jeff Levitt wrote:
> Thank you Scott,
>
> To save you or anyone else who is interested some time, one of the
> documents at that site provides a great overview to the advantages of
> DITA. It is located at:
>
> http://www.oasis-open.org/committees/download.php/6637/DITA-technologyreview.pdf
>
>
> It is 16 pages long, but you probably only need to scan the first 7
> pages or so to get a sense of what issues led to the creation of DITA,
> its advantages, and how it works. The rest is more technical, down to
> the language level.
>
> Hope that helps!
> Jeff
>
> scott hutinger wrote:
>
>> I just thought others might like to know that looking at some of the
>> DITA information might be a bit on the verbose side, and might take a
>> bit more time to get feedback on this. I am by no means a document
>> specialist, and I am a bit uncertain how many in this group really
>> are? Possibly Jeff might be the best person to get any information
>> on 'what might be any possible objections'?
>>
>> DITA seems to look like a very good alternative to the current
>> problems in my view, but I just follow this group very closely, so
>> guess I don't count :-)
>> But I have been looking at all the DITA information since this
>> morning, and thought I might be able to help a bit in this, but...a
>> lot of information to look over exists.
>>
>> From what I have seen, I think it looks great!
>>
>> scott
>>
>> Jeff Levitt wrote:
>>
>>> Jean T. Anderson wrote:
>>>
>>>> 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
>>>>
>>>>
>>>>
>>>>
>>> I am the 'IBM docs person' that Jean and Jonas mentioned in their
>>> responses earlier. I'm very glad to see that people liked the
>>> Cloudscape PDF's. In a perfect world, I would have created a
>>> solution that would allow you to generate whole PDF's of each of the
>>> docs for Derby. Unfortunately, I did not have enough time before I
>>> had to have a solution in place to contribute the docs to Derby, so
>>> my quick fix was to create the html for Forrest that you now find
>>> with Derby.
>>>
>>> But now that I have more time, I have been trying to come up with a
>>> solution to several issues that the html presents, many of which
>>> have already been brought up in this discussion. Indeed, html is
>>> not a very good source format. Ideally, it would be nice to have
>>> XML source. This would solve several problems. First, we could use
>>> the XML to generate one PDF, or many html files, or just one large
>>> html file. In effect, we would have a single source that would
>>> allow us to output the documentation into any format we want. In
>>> addition, the conversion to XML would remove these "blank" files
>>> that Jonas mentioned.
>>>
>>> I would like to convert the Derby documentation to XML DITA. DITA
>>> is an open-source initiative for creating XML-based documentation.
>>> You can find out more about the DITA open-source standard initiative
>>> at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
>>>
>>> Converting to XML DITA solves the above problems, but also improves
>>> the QUALITY of the documentation immensly. DITA allows you to
>>> create "articles" of information based on the books' contents that
>>> can stand alone on their own or within the book context. ALL of the
>>> information in the 6 Derby books would be placed in articles that
>>> are classified as either concepts, reference material, or tasks. In
>>> addition, we can further classify them as installation,
>>> configuration, development, adminstration, any many other
>>> descriptive catergories. Then, users can sort the documentation by
>>> catergory, allowing them to look up only "development reference" or
>>> "installation tasks" etc, independent of the books. And users who
>>> still want to use the book motif can use provided mapping files that
>>> automatically resort the articles into the proper order for each
>>> book and generate html, PDF's, etc. DITA basically solves all of
>>> our problems and improves the retrievability of the documentation.
>>>
>>> The conversion to DITA will take quite a bit of time. In the
>>> meantime, we could still use the current setup to modify the html
>>> files and build with Forrest. But once the conversion is done and
>>> we recontribute the new doc set to Derby, I think the benefits far
>>> outweigh the delay.
>>>
>>> I would be interested in what members of the community think about
>>> this proposal. If there are no objections, I could begin work on
>>> this very soon.
>>>
>>> Jeff Levitt
>>>
>>
>>
>
Re: Derby documentation in PDF format
Posted by Jeff Levitt <jl...@Mutagen.Net>.
Thank you Scott,
To save you or anyone else who is interested some time, one of the
documents at that site provides a great overview to the advantages of
DITA. It is located at:
http://www.oasis-open.org/committees/download.php/6637/DITA-technologyreview.pdf
It is 16 pages long, but you probably only need to scan the first 7
pages or so to get a sense of what issues led to the creation of DITA,
its advantages, and how it works. The rest is more technical, down to
the language level.
Hope that helps!
Jeff
scott hutinger wrote:
> I just thought others might like to know that looking at some of the
> DITA information might be a bit on the verbose side, and might take a
> bit more time to get feedback on this. I am by no means a document
> specialist, and I am a bit uncertain how many in this group really
> are? Possibly Jeff might be the best person to get any information
> on 'what might be any possible objections'?
>
> DITA seems to look like a very good alternative to the current
> problems in my view, but I just follow this group very closely, so
> guess I don't count :-)
> But I have been looking at all the DITA information since this
> morning, and thought I might be able to help a bit in this, but...a
> lot of information to look over exists.
>
> From what I have seen, I think it looks great!
>
> scott
>
> Jeff Levitt wrote:
>
>> Jean T. Anderson wrote:
>>
>>> 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
>>>
>>>
>>>
>>>
>> I am the 'IBM docs person' that Jean and Jonas mentioned in their
>> responses earlier. I'm very glad to see that people liked the
>> Cloudscape PDF's. In a perfect world, I would have created a
>> solution that would allow you to generate whole PDF's of each of the
>> docs for Derby. Unfortunately, I did not have enough time before I
>> had to have a solution in place to contribute the docs to Derby, so
>> my quick fix was to create the html for Forrest that you now find
>> with Derby.
>>
>> But now that I have more time, I have been trying to come up with a
>> solution to several issues that the html presents, many of which have
>> already been brought up in this discussion. Indeed, html is not a
>> very good source format. Ideally, it would be nice to have XML
>> source. This would solve several problems. First, we could use the
>> XML to generate one PDF, or many html files, or just one large html
>> file. In effect, we would have a single source that would allow us
>> to output the documentation into any format we want. In addition,
>> the conversion to XML would remove these "blank" files that Jonas
>> mentioned.
>>
>> I would like to convert the Derby documentation to XML DITA. DITA is
>> an open-source initiative for creating XML-based documentation. You
>> can find out more about the DITA open-source standard initiative at
>> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
>>
>> Converting to XML DITA solves the above problems, but also improves
>> the QUALITY of the documentation immensly. DITA allows you to create
>> "articles" of information based on the books' contents that can stand
>> alone on their own or within the book context. ALL of the
>> information in the 6 Derby books would be placed in articles that are
>> classified as either concepts, reference material, or tasks. In
>> addition, we can further classify them as installation,
>> configuration, development, adminstration, any many other descriptive
>> catergories. Then, users can sort the documentation by catergory,
>> allowing them to look up only "development reference" or
>> "installation tasks" etc, independent of the books. And users who
>> still want to use the book motif can use provided mapping files that
>> automatically resort the articles into the proper order for each book
>> and generate html, PDF's, etc. DITA basically solves all of our
>> problems and improves the retrievability of the documentation.
>>
>> The conversion to DITA will take quite a bit of time. In the
>> meantime, we could still use the current setup to modify the html
>> files and build with Forrest. But once the conversion is done and we
>> recontribute the new doc set to Derby, I think the benefits far
>> outweigh the delay.
>>
>> I would be interested in what members of the community think about
>> this proposal. If there are no objections, I could begin work on
>> this very soon.
>>
>> Jeff Levitt
>>
>
>
Re: Derby documentation in PDF format
Posted by scott hutinger <s-...@wiu.edu>.
I just thought others might like to know that looking at some of the
DITA information might be a bit on the verbose side, and might take a
bit more time to get feedback on this. I am by no means a document
specialist, and I am a bit uncertain how many in this group really
are? Possibly Jeff might be the best person to get any information on
'what might be any possible objections'?
DITA seems to look like a very good alternative to the current problems
in my view, but I just follow this group very closely, so guess I don't
count :-)
But I have been looking at all the DITA information since this morning,
and thought I might be able to help a bit in this, but...a lot of
information to look over exists.
From what I have seen, I think it looks great!
scott
Jeff Levitt wrote:
> Jean T. Anderson wrote:
>
>> 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
>>
>>
>>
>>
> I am the 'IBM docs person' that Jean and Jonas mentioned in their
> responses earlier. I'm very glad to see that people liked the
> Cloudscape PDF's. In a perfect world, I would have created a solution
> that would allow you to generate whole PDF's of each of the docs for
> Derby. Unfortunately, I did not have enough time before I had to have
> a solution in place to contribute the docs to Derby, so my quick fix
> was to create the html for Forrest that you now find with Derby.
>
> But now that I have more time, I have been trying to come up with a
> solution to several issues that the html presents, many of which have
> already been brought up in this discussion. Indeed, html is not a
> very good source format. Ideally, it would be nice to have XML
> source. This would solve several problems. First, we could use the
> XML to generate one PDF, or many html files, or just one large html
> file. In effect, we would have a single source that would allow us
> to output the documentation into any format we want. In addition, the
> conversion to XML would remove these "blank" files that Jonas mentioned.
>
> I would like to convert the Derby documentation to XML DITA. DITA is
> an open-source initiative for creating XML-based documentation. You
> can find out more about the DITA open-source standard initiative at
> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
>
> Converting to XML DITA solves the above problems, but also improves
> the QUALITY of the documentation immensly. DITA allows you to create
> "articles" of information based on the books' contents that can stand
> alone on their own or within the book context. ALL of the information
> in the 6 Derby books would be placed in articles that are classified
> as either concepts, reference material, or tasks. In addition, we can
> further classify them as installation, configuration, development,
> adminstration, any many other descriptive catergories. Then, users
> can sort the documentation by catergory, allowing them to look up only
> "development reference" or "installation tasks" etc, independent of
> the books. And users who still want to use the book motif can use
> provided mapping files that automatically resort the articles into the
> proper order for each book and generate html, PDF's, etc. DITA
> basically solves all of our problems and improves the retrievability
> of the documentation.
>
> The conversion to DITA will take quite a bit of time. In the meantime,
> we could still use the current setup to modify the html files and
> build with Forrest. But once the conversion is done and we
> recontribute the new doc set to Derby, I think the benefits far
> outweigh the delay.
>
> I would be interested in what members of the community think about
> this proposal. If there are no objections, I could begin work on this
> very soon.
>
> Jeff Levitt
>
Re: Derby documentation in PDF format
Posted by Jeff Levitt <jl...@Mutagen.Net>.
Jean T. Anderson wrote:
>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
>
>
>
>
I am the 'IBM docs person' that Jean and Jonas mentioned in their
responses earlier. I'm very glad to see that people liked the
Cloudscape PDF's. In a perfect world, I would have created a solution
that would allow you to generate whole PDF's of each of the docs for
Derby. Unfortunately, I did not have enough time before I had to have a
solution in place to contribute the docs to Derby, so my quick fix was
to create the html for Forrest that you now find with Derby.
But now that I have more time, I have been trying to come up with a
solution to several issues that the html presents, many of which have
already been brought up in this discussion. Indeed, html is not a very
good source format. Ideally, it would be nice to have XML source. This
would solve several problems. First, we could use the XML to generate
one PDF, or many html files, or just one large html file. In effect,
we would have a single source that would allow us to output the
documentation into any format we want. In addition, the conversion to
XML would remove these "blank" files that Jonas mentioned.
I would like to convert the Derby documentation to XML DITA. DITA is an
open-source initiative for creating XML-based documentation. You can
find out more about the DITA open-source standard initiative at
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
Converting to XML DITA solves the above problems, but also improves the
QUALITY of the documentation immensly. DITA allows you to create
"articles" of information based on the books' contents that can stand
alone on their own or within the book context. ALL of the information
in the 6 Derby books would be placed in articles that are classified as
either concepts, reference material, or tasks. In addition, we can
further classify them as installation, configuration, development,
adminstration, any many other descriptive catergories. Then, users can
sort the documentation by catergory, allowing them to look up only
"development reference" or "installation tasks" etc, independent of the
books. And users who still want to use the book motif can use provided
mapping files that automatically resort the articles into the proper
order for each book and generate html, PDF's, etc. DITA basically
solves all of our problems and improves the retrievability of the
documentation.
The conversion to DITA will take quite a bit of time. In the meantime,
we could still use the current setup to modify the html files and build
with Forrest. But once the conversion is done and we recontribute the
new doc set to Derby, I think the benefits far outweigh the delay.
I would be interested in what members of the community think about this
proposal. If there are no objections, I could begin work on this very soon.
Jeff Levitt
Re: Derby documentation in PDF format
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
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
Re: Derby documentation in PDF format
Posted by Jonas S Karlsson <js...@yesco.org>.
Hi Jean,
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:
Jean T. Anderson wrote:
:>>The IBM docs person generated html for each Cloudscape manual, with
:>>multiple files per manual, and did a first pass at modifying them to
:>>reflect the Derby name and to modify them so Forrest could ingest them.
:>>If I remember right, there are roughly 700 src files. Forrest ingests
:>>those files, adds the site navigation, and outputs the built files.
:>>
:>>
:[Jonas wrote:]
:>
:>I can't find the source with the correct markup anywhere in the tree.
:>I only find generated HTML files, I think.
:>
:>
:I put a brief writeup on the Derby web site source files here:
:http://incubator.apache.org/derby/papers/derby_web.html#3.+Modify+files+in+the+src+tree+
:
:The source files for the manuals are in
:src/documentation/content/xdocs/manuals/*.ihtml .
:Forrest puts the built files under build/site.
These may be input files for the Forrest, but they are not the
documentation source, for example, the following file is not written
by hand, it's generated by some tool. It's clear to me when reading
files like:
src/documentation/content/xdocs/manuals/reference/sqlj11.ihtml
No person wrote that file directly, as you say in:
Jean wrote (much earlier)
:The IBM docs person generated html for each Cloudscape manual, with
:multiple files per manual, and did a first pass at modifying them to
:reflect the Derby name and to modify them so Forrest could ingest them.
:If I remember right, there are roughly 700 src files. Forrest ingests
:those files, adds the site navigation, and outputs the built files.
What you're referring to as src files are generated HTML-files,
generated from each small section from the original markup language
(like docbook or similar) is the original source.
That they are so small and plentiful is causing the issue of that
generated PDF-files are "less than optimal".
Jean wrote:
:To be honest, I did enable PDF generation initially for the Derby site,
:but it resulted in a PDF file per web page and I thought that was quite
:a bit less than optimal. If anybody wants to see what that looks like,
:forrest steps are outlined in
What I'm saying is that we should be editing the original source,
which contains markup, cross references, index word information, and
other things, in fewer files (because nobody would be able to
efficiently edit information on the level of the src/.../*.ihtml).
It may be that not a docbook format was used, but maybe we somehow can
convert these files to that (or whatever other variant of
documentation markup typically used by apache projects), I'm assuming
that they are in some kind of xml-format.
The reason I'm making a point of this is that all kinds of problems
are going to creep up here once the manuals are going to be edited.
For example, just consider the numbering of the pages in the /src
tree, adding a new page in the middle would not be an easy process,
and then adding links from the index pages would be a lot of hard
work, instead of having a tools doing it the right way. (Generate
indices).
For imagining the potential problems regarding indices, look at one of
the indices files:
src/documentation/content/xdocs/manuals/reference/sqlj275.ihtml
:<li>javax.sql.ConnectionPoolDataSource
:<A HREF="sqlj255.html#IDX1211">(1211)</A>, <A HREF="sqlj259.html#IDX1225">(1225)</A>
:</li>
:<li>javax.sql.DataSource
:<A HREF="sqlj255.html#IDX1209">(1209)</A>, <A HREF="sqlj259.html#IDX1223">(1223)</A>
:</li>
These are all generated, the (1211) are referencenumbers which provide
backlinks in the actual documents. These are all generated, and should
not be added/written by hand...
:<P>In order to qualify as a resource manager in a J2EE system, J2EE requires
:these basic areas of support:
:<A NAME="IDX1209"></A>
:<LI>JNDI support.
:<A NAME="IDX1208"></A>
:<A NAME="IDX1209"></A>
What I guess I'm suggesting is that we'd transform what ever actual
source files that the manual was written in to a well known format
like docbook, and from these generated webpages and manuals using
forrest.
Or am I seeing potential problems where there are none?...
best regards,
Jonas
Re: Derby documentation in PDF format
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jonas S Karlsson wrote:
>Jean T. Anderson wrote:
>
>
>>The IBM docs person generated html for each Cloudscape manual, with
>>multiple files per manual, and did a first pass at modifying them to
>>reflect the Derby name and to modify them so Forrest could ingest them.
>>If I remember right, there are roughly 700 src files. Forrest ingests
>>those files, adds the site navigation, and outputs the built files.
>>
>>
>
>I can't find the source with the correct markup anywhere in the tree.
>I only find generated HTML files, I think.
>
>
I put a brief writeup on the Derby web site source files here:
http://incubator.apache.org/derby/papers/derby_web.html#3.+Modify+files+in+the+src+tree+
The source files for the manuals are in
src/documentation/content/xdocs/manuals/*.ihtml .
Forrest puts the built files under build/site.
>I hope we're not planning on editing generated HTML-files, because
>that'd be a nightmare. It'd be like adding functionality and fixing bugs
>in Derby by directly modifying the compiled class files.
>
>
It isn't a terrific idea to edit the generated HTML files; see
http://incubator.apache.org/derby/papers/derby_web.html#8.+Considering+a+quick+fix+to+the+build+tree%3F
>>while to generate the web site. Right now, with PDF generation off, it
>>takes about 20 minutes to build the site on my Gentoo linux box. It
>>
>>
>
>8 minutes for me, actually Forrest seems to be built to allow for
>dynamic generation of pages from source, so one may not need to
>actually update/checkin html pages, but I guess that's a totally
>another issue.
>
>
>
8 minutes? You're on a faster box .... :-) Actually, the build time does
vary depending on what changes are being made. For example, changes to
the site.xml file result in longer build times.
Forrest builds any source files it finds under the xdocs subdirectory.
The generated html pages must be checked in. Those changes only become
visible when a Derby mentor issues an 'svn update' command; see
http://nagoya.apache.org/eyebrowse/ReadMsg?listName=derby-dev@db.apache.org&msgNo=202
You have lots of excellent questions, which I'll try to capture into the
derby_web.html page. I whacked that page together quite quickly. Please
let me know how I can improve it to make it more helpful/useful.
-jean
Re: Derby documentation in PDF format
Posted by Jonas S Karlsson <js...@yesco.org>.
Jean T. Anderson wrote:
> The IBM docs person generated html for each Cloudscape manual, with
> multiple files per manual, and did a first pass at modifying them to
> reflect the Derby name and to modify them so Forrest could ingest them.
> If I remember right, there are roughly 700 src files. Forrest ingests
> those files, adds the site navigation, and outputs the built files.
I can't find the source with the correct markup anywhere in the tree.
I only find generated HTML files, I think.
I hope we're not planning on editing generated HTML-files, because
that'd be a nightmare. It'd be like adding functionality and fixing bugs
in Derby by directly modifying the compiled class files.
> while to generate the web site. Right now, with PDF generation off, it
> takes about 20 minutes to build the site on my Gentoo linux box. It
8 minutes for me, actually Forrest seems to be built to allow for
dynamic generation of pages from source, so one may not need to
actually update/checkin html pages, but I guess that's a totally
another issue.
/Jonas
Re: Derby documentation in PDF format
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jonas S Karlsson wrote:
>...
>I'm not sure what is a "page" in Forest, but it seems to me that to
>determine what should be a "webpage" should be definable and should
>not be limited by the markup language.
>
>
A "file" is the logical unit Forrest works with. Forrest reads input
files in various formats, then outputs them to the built site. For all
about Forrest, see http://forrest.apache.org.
The IBM docs person generated html for each Cloudscape manual, with
multiple files per manual, and did a first pass at modifying them to
reflect the Derby name and to modify them so Forrest could ingest them.
If I remember right, there are roughly 700 src files. Forrest ingests
those files, adds the site navigation, and outputs the built files.
>I'd expect to find for each manual the following options:
>- one webpage per manual containing the complete manual (for download/searching)
>
>
No; many files were generated per manual.
>- a PDF-file per manual
>
>
Not per manual, no; but Forrest does support generating a PDF file for
each web page (file). These would be expensive to build with so many files.
>- a set of webpages, similarly to what we have now, but with one page
> per chapter, but not like this:
>
> http://incubator.apache.org/derby/manuals/reference/sqlj09.html#HDRSII-SQLJ-18919
>
> This is a page I find utterly useless <jta snipped>
>
>
I agree this isn't optimal. And generating a PDF file for it probably
wouldn't make sense.
Another issue that crops up when there are this many files is it takes a
while to generate the web site. Right now, with PDF generation off, it
takes about 20 minutes to build the site on my Gentoo linux box. It
takes about 40 minutes on a Solaris sparc machine available to me for
testing. It was for this reason that I suggested testing new pages on a
seed site on http://incubator.apache.org/derby/papers/derby_web.html.
>I hope that these are not limitations of Forest, because now I can't
>see the trees because of the Forest.
>
>
No, it isn't a Forrest limitation.
It's possible that if we invest more time looking into Forrest (and
Cocoon) we might find ways to improve the existing setup.
-jean
Re: Derby documentation in PDF format
Posted by Jonas S Karlsson <js...@yesco.org>.
I'm very happy that we got the manuals online as HTML again,
but...
Joel Rosi-Schwartz wrote:
>I personally found the PDF document set that was available for Cloudscape 10
And me personally, can't deal with PDF, they are only good for
printing. ;) Something which I seldomly do.
Jean T. Anderson wrote:
> Another option might be to consolidate the pages for each manual back
> into a single page, or into a smaller number of pages.
I'm not sure what is a "page" in Forest, but it seems to me that to
determine what should be a "webpage" should be definable and should
not be limited by the markup language.
I'd expect to find for each manual the following options:
- one webpage per manual containing the complete manual (for download/searching)
- a PDF-file per manual
- a set of webpages, similarly to what we have now, but with one page
per chapter, but not like this:
http://incubator.apache.org/derby/manuals/reference/sqlj09.html#HDRSII-SQLJ-18919
This is a page I find utterly useless, containing too little
information, is not searchable, seems to be a chapter, but that
page does not link to what subpages there are, only a next, which
makes you feel like you're navigating between sentences by clicking
next.
I hope that these are not limitations of Forest, because now I can't
see the trees because of the Forest.
/Jonas
Re: Derby documentation in PDF format
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Joel Rosi-Schwartz wrote:
>I personally found the PDF document set that was available for Cloudscape 10
>beta to be very useful. I am hopeful that this packaging of the documentation
>will be carried forward into Derby. Has there been any consideration toward
>providing this?
>
>
Each manual on the Derby site
(http://incubator.apache.org/derby/manuals/index.html) is composed of
multiple pages. Forrest can generate PDFs for each linked page on the
site -- that feature is controlled by a setting in the skinconf.xml file:
<!-- Do we want to disable the PDF link? -->
<disable-pdf-link>true</disable-pdf-link>
However, enabling/disabling PDF generation is an "all or nothing" deal
(see
http://issues.apache.org/eyebrowse/BrowseList?listName=user@forrest.apache.org&by=subject&from=648189&to=648189&first=1&count=7).
To be honest, I did enable PDF generation initially for the Derby site,
but it resulted in a PDF file per web page and I thought that was quite
a bit less than optimal. If anybody wants to see what that looks like,
forrest steps are outlined in
http://incubator.apache.org/derby/papers/derby_web.html . You could
check out the derby site, locally change the PDF flag to false in the
skinconf.xml and rebuild ('forrest site').
Another option might be to consolidate the pages for each manual back
into a single page, or into a smaller number of pages.
-jean