An incomplete puzzle: DITA OT stylesheets

Simon Bate / DITA2 Comments

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.

About the Author

Simon Bate

Twitter

Involved in TechComm all my working life (since the time of vacuum tubes, core memory, punch cards, and bone implements). I've worked as a writer, a manager, and—for the past score of years—building software tools for TechComm. My motto is "Let the computer do the work." Outside of work, I balance the calories I create and consume in the kitchen with weight-training sessions at the gym. I also sing Tenor in various choirs and choruses.

2 Comments on “An incomplete puzzle: DITA OT stylesheets”

  1. Wow, that reminds me of a job a few years back: I had to adjust the DocBook XSL stylesheets according to the desired layout and to also handle certain specializations.
    I saw myself (using UltraEdit) looking inside the plethora of files and folders for the right place to add my own little hooks (and trying to understand the original designers intention).
    In the end, I had the very strong feeling, that creating an XSL conversion from scratch would have been about the same effort. BUT with the added benefit of much less work later on.
    It seems to me that not so much has changed from DocBook to DITA.
    – Michael

  2. Wow, that reminds me of a job a few years back: I had to adjust the DocBook XSL stylesheets according to the desired layout and to also handle certain specializations.
    I saw myself (using UltraEdit) looking inside the plethora of files and folders for the right place to add my own little hooks (and trying to understand the original designers intention).
    In the end, I had the very strong feeling, that creating an XSL conversion from scratch would have been about the same effort. BUT with the added benefit of much less work later on.
    It seems to me that not so much has changed from DocBook to DITA.
    – Michael

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.