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!
