db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <jlev...@mutagen.net>
Subject Derby documentation in XML DITA
Date Fri, 03 Dec 2004 21:15:30 GMT
I've seen some posts (Thanks Rick) regarding my idea
to move the Derby documentation to DITA, and I wanted
to provide you all with an update on the progress...

As we discussed previously on this list, I proposed to
migrate the Derby documentation to XML DITA to help
make the output more flexible than html.  In testing
DITA, I started with the Getting Started guide since
it was the smallest, and I used it to refine the
process and explore the output options.  The files for
the Getting Started Guide are now in DITA in the
attached zip file (update: The derby-dev list wont let
me attach the zip so I will send to Jean so she can
make it available for download).  To create output
from the DITA files, you need to use the ditamap file
included in the zip. 
This file sets the order and hierarchy of all of the
DITA files, and basically organizes the separate DITA
"topics" into a book.  

I also created a "conrefs" file (gsconrefs.dita) that
is not a topic that is included in the actual book,
but instead simply includes terms and names that can
change from time to time or are used repetitively. 
For example, the name of the product is "Derby," and I
placed that in the gsconrefs.dita file.  The rest of
the files don't actually use the word Derby when it is
needed; instead they point to the conrefs file.  That
way, if the name were to change for any reason, we
don't have to change it in 8 million places, we just
change it once in the conref file and it changes

As for creating html, xml, or pdf output, I have been
experimenting with Saxon and FOP.  I am going to try
Apache's Cocoon as well (and could really use a hand
from anyone who has time or inclination since Cocoon
is new to me).  So far, I have been able to use
Saxon's stylesheets to create individual html files as
well as one complete html file for the whole book.  I
have had some issues with linking between parent and
child topics, however, so if anyone is good with
XSL/XSLT, it might be a good idea to work together to
create some Derby-specific XSL stylesheets for our

As for PDF, I have also successfully used Saxon to
create a .fo file that can be transformed with Apache
FOP to create a PDF.  The PDF is complete, but has
formatting and linking problems.  Once again, if
anyone can help out here with the XSLT, I could use

As for the rest of the documentation, I am already
almost finished with the Reference Manual.  The ref
manual is one of the larger books in the Derby
library, yet it took me much less time to convert to
DITA than the Getting Started Guide, since I spent so
much time refining the process on the first book.

Please post any comments on the DITA approach I used
for the Getting Started guide. And again if you have
any expertise with XSLT, I would appreciate the help!

View raw message