Overriding XSLT stylesheet processing

XSLT, a W3C standard, is a language for transforming XML into other formats.

XSLT stylesheets are written in XML syntax.

In the final stage of processing, the DITA Open Toolkit runs XSLT stylesheet transforms (using either SAXON or Xalan) to produce output files. In certain cases, it is possible to override stylesheet processing to customize the output.

The following figure shows the XSLT stylesheet for the note element.

The following XSLT stylesheets in the ditaot/xsl directory perform output transformation for various types of output (specified by setting the transtype). For those stylesheets marked with an asterisk (*) in the following table, you can override the default stylesheet with one you create.

Transtype (*can be overridden) XSLT stylesheet(s)
*docbook map2docbook.xsl, dita2docbook.xsl
eclipsecontent map2eclipse.xsl, map2plugin-cp.xsl
eclipsehelp map2eclipse.xsl
htmlhelp map2hhc.xsl, map2hhp.xsl
*javahelp dita2html.xsl
*pdf dita2fo-shell.xsl
troff dita2troff-step1-shell.xsl, dita2troff-step2-shell
*wordrtf dita2rtf.xsl
*xhtml dita2xhtml.xsl

How to override an XSLT stylesheet (generic instructions)

Follow these steps to override XSLT processing in a build:
  1. In the ditaot/xsl directory, make a copy of the stylesheet you want to override and save it with its own unique name (don't replace the stylesheet that was originally included with the Toolkit).
    Note: It is also possible to create a new stylesheet and use <xsl:import> to import the existing default stylesheet, and then make any changes you want to the existing targets.
  2. In your new stylesheet, make any changes you want to the existing stylesheet code, and save it.
  3. In your Ant build script, specify the "args.xsl" property with name of your new stylesheet.
  4. Run your Ant build script.

XSLT override example

Follow these steps to modify the processing for a PDF target to remove the author list from the title page of the .pdf file. (The default XSLT stylesheet for PDF will add one author line to the title page for every <author> element in the <prolog> section of each file in the source tree.)

  1. In the xsl directory of the Toolkit, make a copy of the file dita2fo-shell.xsl and save it as xdita2fo-shell.xsl.
  2. Delete the following text in the file near line 134:
    <fo:block font-size="11pt" font-weight="bold" line-height="1.5">
    <xsl:text>[vertical list of authors]</xsl:text>
    <xsl:for-each select="//author">
    <fo:block font-size="11pt" font-weight="bold" line-height="1.5">
    [<xsl:value-of select="."></xsl:value-of>] </fo:block>
  3. Add the following line to the Ant target in your build script:
    <property name="args.xsl" value="${basedir}/xsl/xdita2fo-shell.xsl"/>
  4. Run your Ant script again and verify that the .pdf output file does not have an author list on the first page.