db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jonas S Karlsson" <...@yesco.org>
Subject Re: Derby documentation in PDF format
Date Fri, 08 Oct 2004 16:14:40 GMT
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


Mime
View raw message