db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Susan Cline <...@MeepZor.Com>
Subject Re: Derby documentation in XML DITA
Date Tue, 07 Dec 2004 17:02:33 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
> everywhere.
> 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
> purposes. 
> 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
> it!
> 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!

Hi Jeff,

I just downloaded the Getting Started Guide in DITA format
from the Derby web site.  I think the zip file is missing
a whole directory called 'dtd' which contains the *.dtd
files for the individual files.

When you attempt to view the XML through a browser the
following appears:

<!DOCTYPE reference PUBLIC "-//IBM//DTD DITA Reference//EN" 

Can you provide a new zip file that contains the dtd dirctory?

If I missed something, please let me know!



View raw message