Palimpsest: An incomplete puzzle: DITA OT stylesheets

Random thoughts about publishing

Labels

Acrobat DITA Open Toolkit DITA XMetaL FrameMaker DITA__TechComm DOS DRM Flash FrameMaker InDesign Microsoft Word PDF Photoshop RSS feeds STC SWF SnagIt TechComm Suite Twitter XSL DITA OT customizing specialization XSL DITA OT customizing specialization.php XSLT accessibility adobe analysis apostrophes blogs book business cake change management cmd comments concerts conferences cowbell cranky dita ditalini recipes potluck dita ditalini doctrain doctraineast07 doctraineast08 doctrainwest08 documentation drag and drop ePublisher Pro entertainment equations fish flare framemaker review free garlic georgina's gilbane08 globalization graphics WMF green hacking history humor is08 jobs localization madcap music outlook oxygen path names podcasts potluck predictions presentations print on demand publishing punctuation quark ratings recipes regular expressions reviews robohelp screen captures secured PDF specialization stc09 stc2008 structured authoring survey techcomm alliance technical writing tekom thirst for knowledge thunderbird toc2007 trademark training travel unspoken rule user group video games volunteering vote citizenship rights weather web 2.0 webcasts white papers wiki writersua2008 xmetal xml strategist xml xpubs xsl-fo xsl

Palimpsest

An incomplete puzzle: DITA OT stylesheets

Friday, September 05, 2008 — posted by Simon Bate

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: DITA Open Toolkit, specialization, xsl