db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scott hutinger <s-hutin...@wiu.edu>
Subject Re: Derby documentation in XML DITA
Date Sun, 05 Dec 2004 12:20:31 GMT
Jeff Levitt wrote:

>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!
I have had some off-line communication with Jeff about this subject.  
Here is where I see the current state of the transformation of DITA.

First, I think the DITA.dtd files are needed to do any transformation.  
These files are currently at ../ which means they are missing.  I 
downloaded the DITA.dtd's from IBM's website.  Forrest has a really nice 
architecture currently in the 0.7-dev only code base which allows the 
use of plug-ins.  The plug-in can be hosted, or rather should be hosted 
at a location.  I haven't fully explored this concept, as it could be 
possible to break the plugin unless some information were available 
about downward compatibility.  I asked the forrest-dev list what would 
be the naming convention.  org.apache.derby.dita (or 
org.apache.derby.DITA, although I prefer lower case) should be the 
convention.  But the important thing is how to transform DITA.  One 
could control the output into html, or one could transform to forrest 
xdoc format.  I would prefer to output to xdoc format to stay within the 
forrest model.  Any ideas about this?


View raw message