Implementing Overrides for Common Processing

You can use the same args.xsl parameter as for the XHTML transform to specify a custom top-level transform that includes overrides to the base processing.

The Toolkit's XHTML transform provides a parameter, args.xml, by which you can specify the top-level XSLT transform to be used by the transformation type. You normally use this facility to apply overrides to the base processing provided by the transformation type.

Note that there is an important distinction between extending a transformation type and overriding a transformation type. Extensions are provided through Toolkit plugins that are integrated with the base transformation type and apply to all uses of that transformation type. For example, the DITA for Publishers formatting-d.html and formatting-d.fo Toolkit plugins extend the base XHTML and PDF transforms with support for the DITA for Publishers formatting domain elements. These extensions are used unconditionally by all invocations of the XHTML and PDF transformation types.

When you override a transformation type you are changing the base processing for a specific invocation of the transformation type. Overrides are not integrated with the base transformation type. Rather, they are implemented as new top-level XSLT transforms that import the base transformation (e.g., dita2xhtml.xsl) and include or import custom XSLT code that extends or overrides the base processing.

You normally use overrides to achieve output results that are specific to a particular document, document type, or delivery target. For example, you might want to output specific topic-level metadata for a specific kind of publication or even for a specific single publication. When dealing with Publishing use cases, where every publication might have different requirements it is likely that you may need to implement publication-specific overrides to achieve some specific effect.

Note also that the general override strategy for HTML-based outputs like EPUB and Kindle is different from the override strategy for PDF output using the Toolkit's built-in PDF transformation type. The PDF transformation type has its own customization framework that provides a different way to apply overrides to the transformation (it also allows extension using integrated plugins).

You can override the EPUB and Kindle processing by creating a new top-level XSLT transformation that includes the base map2epub.xsl or map2kindle.xsl transforms provided by the respective Toolkit plugins and that also includes your custom XSLT transform that does whatever you need. Because the EPUB and Kindle transforms are both based on the XHTML transform you can normally use a single override file with the XHTML, EPUB, and Kindle transformation types.

The top-level transformation can be packaged as a separate Open Toolkit plugin that depends on, but does not integrate into, the base transformation type it extends. This is the best thing to do if you must distribute the extension to different systems. If the override will only be used on a single machine you can put the top-level transformation anywhere. However, in this case the top-level transformation will necessarily have system-specific URIs for the Toolkit-provided base transformations, which means it is not portable.

A typical "local" top-level transformation file looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  exclude-result-prefixes="xs"
  version="2.0">
  
  <xsl:import href="/Applications/oxygen/frameworks/dita//DITA-OT/plugins/org.dita4publishers.epub/xsl/map2epub.xsl"/>
  <xsl:include href="my-html-overrides.xsl"/>
  
</xsl:stylesheet>

This example is a "local" override that uses an absolute URI to import the base transformation, in this case the EPUB map2epub.xsl transform. It also includes the local overrides, here in the file my-html-overrides.xsl. The corresponding transformation for the Kindle transformation type would include the Kindle-specific top-level transform and the same overrides (assuming that you want the EPUB and Kindle outputs to reflect the same overrides, which would normally be the case).

The overrides themselves can be anything you need and can override either the base XHTML processing from the dita2xhtml transformation type or can override the EPUB- and Kindle-specific processing from the EPUB or Kindle plugins. For most overrides you would be overriding the base XHTML processing.

To use the override transformation you simply specify the path and filename of the transformation as the value of the args.xml Ant parameter for the XHTML, EPUB, or Kindle transformation types.

To package an override as a Toolkit plugin you create a plugin.xml file that defines the plugin and use a relative URI to include the base transformation type, relative to the plugin's location as deployed in a Toolkit. You put the plugin.xml and override transform into their own uniquely-named directory within the Toolkit's plugins/ directory.

The plugin.xml file should look like this:
<?xml version="1.0" encoding="UTF-8"?>
<plugin id="my.unique.plugin.name">
  
  <require plugin="org.dita4publishers.epub"/> 
  
</plugin>

Where the bold text should reflect a unique name for this particular plugin.

This plugin descriptor simply establishes a dependency on the Toolkit transformation type it overrides, e.g., the EPUB plugin.

Assuming that you are deploying the plugin to the plugins/ directory and that your override template is at the root of its own plugin's directory, then the top-level transform should look like this:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  exclude-result-prefixes="xs"
  version="2.0">
  
  <xsl:import href="../org.dita4publishers.epub/xsl/map2epub.xsl"/>
  <xsl:include href="my-html-overrides.xsl"/>
  
</xsl:stylesheet>

With this plugin you can then specify the transformation within your plugin as the value of the args.xml Ant parameter.