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" "..\dtd\reference.dtd">
Can you provide a new zip file that contains the dtd dirctory?
If I missed something, please let me know!
Thanks,
Susan
