How can you debug a DITA transformation?

Question

I know XSLT in general can be debugged, but how exactly would one go about debugging a DITA transformation, considering its modular XSLT structure and the fact that stylesheets are pointed to by the catalog.xml file?

I want to be able to step through the code during runtime, and be able to set break points, etc.

Answer 1

If you are using the Oxygen editor, you can debug Toolkit transforms using the technique described here (from the Oxygen 14.2 documentation):

Debugging PDF Transformations

1. To debug a DITA PDF transformation scenario using the XSLT Debugger follow these steps: Go to Options > Preferences > XML > XML Catalog, click Add and select the file located at [Oxygen Install Directory]\ frameworks\dita\DITA-OT\plugins\org.dita.pdf2\cfg\catalog.xml;

2. Open the map in the DITA Maps Manager and create a DITA Map PDF transformation scenario;

3. Edit the scenario, go to the Parameters tab and change the value of the clean.temp parameter to no;

4. Run the transformation scenario;

5. Open in Oxygen XML the stage1.xml file located in the temporary directory and format and indent it;

6. Create a transformation scenario for this XML file by associating the topic2fo_shell.xsl stylesheet located at OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/org.dita.pdf2/xsl/fo/topic2fo_shell_fop.xsl;

7. In the transformation scenario edit the Parameters list and set the parameter locale with the value en_GB and the parameter customizationDir.url to point either to your customization directory or to the default DITA OT customization directory. It's value should have an URL syntax like:file://c:/path/to/OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/org.dita.pdf2/cfg.

8. Debug the transformation scenario.

I found this topic by searching for "debug toolkit" in the Oxygen online help.

These instructions are specifically for PDF, but you should be able to adapt these instructions to HTML-based transforms as well.

Answer 2

There is always the good old trick of adding print statements around in the code, which is xslt translates to <xsl:message>. Here is a snippet from my frontmatter transformation:

<!-- 
<xsl:message>createFrontMatter_1.0</xsl:message>
<xsl:message>artworkPrefix=<xsl:copy-of select="$artworkPrefix"/></xsl:message>
<xsl:message>customizationDir.url=<xsl:value-of select="$customizationDir.url"/></xsl:message>
<xsl:message>imageLogoPath=<xsl:value-of select="$imageLogoPath"/></xsl:message>
<xsl:message>imageNotePath=<xsl:value-of select="$imageNotePath"/></xsl:message>
<xsl:message>imageWatermarkPath=<xsl:value-of select="$imageWatermarkPath"/></xsl:message>
<xsl:message>page-width=<xsl:value-of select="$page-width"/></xsl:message>
<xsl:message>page-height=<xsl:value-of select="$page-height"/></xsl:message>
-->

If I uncomment this, I get a nice debugging block of text in the output log, showing the various values for the settings I use.