Topic Specialization Step 4: Extending the Toolkit To Support the Specialization

For many topic specializations you won't require any change to the base Open Toolkit processing because you're using the specialization primarily to support authoring requirements and imposing editorial rules or to define specific reference structures or task structures that don't require any special processing. However, sometimes you want or need different or additional functionality, in which case you have to extend the Toolkit (or whatever tools you're using to process your DITA-based information).

There are two ways to extend a given transformation type in the Open Toolkit, "extension" and "override":

Which of these you use depends on what you need to accomplish for your vocabulary module.

If you are adding support for new element types or attributes, then you should use extension, since the processing for your new types cannot (or rather, should not) interfere with any base processing. For most vocabulary modules you will use extension, as is the case for the FAQ question topic type module.

If you need to implement processing that is specific to a particular publication type, user group within a larger organization, or otherwise limited to specific cases, then you should normally use overrides so you do not modify the the base processing for users of the base transformation type. For example, you might have different customizations of the PDF processor for different product groups within an enterprise. These customizations should be overrides not extensions.

If you need to implement processing that modifies the default processing but that should be used universally within a given organization, then you should use extensions. For example, you might have a corporate standard for specific HTML elements that should be reflected in any HTML output. In that case it would be appropriate to define an extension plugin that overrides the base processing.

Also, for HTML output, you can customize some presentation aspects through the use of custom CSS style sheets without the need to modify the HTML generation itself.

See Configuring and Extending the DITA Open Toolkit for a more complete discussion of extending and overriding Toolkit processing.

For the purposes of this tutorial we will extend the HTML generation to reflect the formatting specifications for FAQ Question.

For the FAQ Question specialization, the HTML formatting specifications are:

There are several ways to achieve this sort of effect, including defining default values for the @output-class attribute in the DTDs (which would then let you style the HTML using a CSS style sheet without the need for a separate transform). However, for the purposes of this tutorial we will create a transform if for no other reason than to see how it's done.

As for creation of the DTDs themselves, the process of creating a specialization-specific XSLT script can be fairly mechanical and not require any great depth of XSLT knowledge, especially if all you're doing is tweaking the HTML output.

The basic process is as follows:
  1. Create a directory to contain your Toolkit plugin, which will consist of the plugin descriptor file (plugin.xml) and the XSLT modules that implement your custom processing.
  2. Create an empty XSLT stylesheet that will hold the templates specific to your specialization.
  3. Create the plugin descriptor document that integrates your XSLT modules into the base transformation type.
  4. Create match templates for each element type and context you'll need to handle
  5. In the base Toolkit-supplied style sheets, find the template that would otherwise handle one of your specialized elements and copy its content and paste it into your local template.
  6. Modify the local template to do whatever you need it to do
  7. Repeat steps 4 through 6 for each specialized element type that needs different processing.