Hacking vs. elegance
When modifying or adapting existing code to your purposes, there are two extremes in how you implement the changes:
- You can change what needs to be changed to get the work done (hacking).
- You can make changes using a provided framework for integrating changes with existing code -(elegance).
The DITA OT offers many opportunities for hacking, but it also provides a number of frameworks within which you can formalize your changes (separate CSS files, XSL override templates, and so on). It’s up to you and your circumstances to decide between speed and maintainability. In general, you can start changes as hacks (just to get things working or as a proof of concept). Once you have the behavior you need, you can go back and reimplement the changes using the appropriate framework.
Comments and backups
No matter which route you take, it’s vitally important that you add comments explaining your changes. The DITA OT consists of many thousands of lines of code distributed over dozens of files. You need comments to keep track of your changes.
Attaching the contributor’s name and the date to comments can save many hours of searching and re-work. For example:
<!-- SFB 27-Jan-2009: Changed external to peer -->
Before you start to make changes, make a backup of the original file. Nothing is more frustrating than changing something and not being able to undo your changes because of a minor typo that might take hours to find. It’s better to have a backup copy, which you can either restore or check with a file-comparison utility (diff), and proceed from there.
Finally, if you have source code management software available to you, use it! Common source code systems include Subversion, CVS, Perforce, IBM Rational ClearCase, and Microsoft Visual SourceSafe, but there are many more.
Output formats
The standard DITA OT distribution can create a number of output formats, including:
- XHTML—essentially HTML that uses XML syntax rules.
- Microsoft HTML Help (.chm files)—built from XHTML output.
- Eclipse help—a Java integrated development environment (IDE), the help is built from XHTML output.
- PDF—Adobe Acrobat format documents, generated using XSL-FO.
This paper focuses on XHTML-based modifications, mostly because the concepts of HTML and CSS should be familiar to most readers. However, many of the same principles used to generate XHTML output can be applied to generating XSL-FO output for PDF files.
Next Page:
DITA OT Overview