db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <jlev...@Mutagen.Net>
Subject Re: Derby documentation in PDF format
Date Fri, 08 Oct 2004 22:05:13 GMT
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

Mime
View raw message