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

For many topic specializations you won't need to change the base Open Toolkit processing because you're using the specialization primarily to support authoring requirements, impose editorial rules, or define specific reference structures or task structures that don't require any special processing. However, sometimes you need 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":
  • Extension uses any extension points provided by the transformation type to hook in additional processing needed by a specific vocabulary module.
  • Override involves creating a new transformation type that includes and overrides the base transformation type.

Which you use depends on what you need to accomplish.

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, including the FAQ question topic type module, you will use extension.

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 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 stylesheets without modifying 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:
  • The question statement (the topic title) should be introduced with "Q. " and the title itself should have a light pastel background.
  • The answer should be introduced with "A. " in the same size and font as the title.

There are several ways to achieve this effect, including defining default values for the @outputclass attribute in the DTDs (which would then let you style the HTML using a CSS stylesheet). However, for 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 may 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 stylesheets, find the template that would otherwise handle one of your specialized elements, 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.