A recent post on the dita-users Yahoo group asked how to customize the DITA OT stylesheets in view of the fact that there isn't much documentation available.

From my work customizing and otherwise perverting the DITA OT, I can sympathize with these frustrations. When I started investigating OT customizations, I found many well-crafted tutorials on how to customize and specialize the OT.  These were a great starting point, but they only got me so far.  In its current state, the documentation is an incomplete jigsaw puzzle; the trees and buildings are filled in nicely, but the sky is still waiting for someone with patience.  (Block that metaphor!)

Because there is no documentation available at the individual template level, you need to reconsider the task at hand.  I look on it as debugging, decoding, or sleuthing. With that in mind, I find the following to be very useful:

• Find a good visual grep-like utility. I use AgentRansack, a free version of FileLocator Pro (it's free and amazing). This enables me to locate all files that contain a particular class identifier. The visual aspect of the tool allows me to see the context quickly.
• Use a programmer's editor that supports XML and XSL. We use Oxygen. Not only does it help check validity and closes tags automatically, but it also provides a handy sidebar that lists the templates and their modes.
  
• Liberally spread <xsl:comment> or <xsl:message> directives through the stylesheets you're examining. That helps figure out where you are. Use <xsl:value-of> or <xsl:copy-of> to figure out what you've got.
• Once you've figured out what happens in one of the OT templates, add comments. Now the next time you come back to it, you won't waste time.
  

Probably the best form of documentation that the OT could provide here is additional comments in the stylesheets, particularly about the order of processing.  I find I add many comments about where to find the template that handles nodes from an  <xsl:apply-templates> directive.

One further note.  On Tuesday, September 23, I'll be presenting the third of our "Best Practices in Structured Authoring and Publishing" joint Webinar series with JustSystems.  In this presentation I'll describe a number of approaches you can use to customize DITA OT output.  For more information, visit the JustSystems web site.

Labels: XSL DITA OT customizing specialization

10:12 AM Permalink |