Extension points for plug-ins to the DITA Open Toolkit

 

Extensions to the DITA Open Toolkit are supported through a plug-in extension mechanism. Plug-ins may do a number of things, such as adding support for specialized DTDs or Schemas, integrating processing overrides, or providing entirely new output transforms. Extensions are integrated with a file named plugin.xml, located in the plug-in's root directory. This document describes all recognized extension points in the plugin.xml file.

The root  element of the file is <plugin>, and must specify an id attribute. The id attribute is used to identify the plugin, as well as to identify whether pre-requisite plugins are available.

Remaining elements are all optional:

• The <feature> element may be used to update the XML Catalogs used to resolve DTD or Schema document types. To do this, first create a catalog with only your new values, using the OASIS Catalog format, and place that in your plugin. Next create a <feature> element, with the extension attribute set to "dita.specialization.catalog.relative", the value attribute set to the name of your local catalog file, and the type attribute set to "file". For example:
  • <feature extension="dita.specialization.catalog.relative" value="catalog-dita.xml" type="file" />
• The <feature> element may be used to override various steps of XSLT processing. For this, the extension attribute indicates the step that the override applies to; the value attribute is a relative path to the override within the current plugin; the type attribute should be set to "file". The plugin installer will add an XSL import statement to the default code, so that your override becomes a part of the normal build. The following XSLT steps are available to override in the core toolkit:
  

  • Override default XHTML output with the following: <feature extension="dita.xsl.xhtml" value="xsl/modifyXhtml.xsl" type="file"/>

  • Override default DocBook output with the following: <feature extension="dita.xsl.docbook" value="xsl/sample.xsl" type="file"/>

  • Override default RTF output with the following: <feature extension="dita.xsl.rtf" value="xsl/sample.xsl" type="file"/>
  • Override the step that generates plugin.xml for Eclipse with the following: <feature extension="dita.xsl.eclipse.plugin" value="xsl/sample.xsl" type="file"/>
  • Override conref processing: <feature extension="dita.xsl.conref" value="xsl/sample.xsl" type="file"/>
  • Override topicpull processing (the step that pulls text into <xref> elements, among other things): <feature extension="dita.xsl.topicpull" value="xsl/sample.xsl" type="file"/>
  • Override mapref processing (the step that resolves references to other maps): <feature extension="dita.xsl.mapref" value="xsl/sample.xsl" type="file"/>
  • Override mappull processing (the step that updates navtitles in maps and causes attributes to cascade): <feature extension="dita.xsl.mappull" value="xsl/sample.xsl" type="file"/>
  • Override maplink processing (the step that generates map-based links): <feature extension="dita.xsl.maplink" value="xsl/sample.xsl" type="file"/>
  • Override the (now deprecated) original PDF output with the following: <feature extension="dita.xsl.fo" value="xsl/modifyXhtml.xsl" type="file"/>
• The <require> element requires the plugin attribute. It is used to identify pre-requisite plug-ins. If the current plugin requires a plugin with id="plugin-id" before it can be installed, it would include the following:
  • <require plugin="plugin-id">

The following is a sample of a complete plugin that defines new document types and extends the XHTML processing:

<plugin id="org.example.myplugin"> <feature extension="dita.specialization.catalog.relative" value="catalog-dita.xml" type="file"/> <feature extension="dita.xsl.xhtml" value="xsl/mySpecialization2xhtml.xsl" type="file"/> </plugin>