source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/dev_ref/extension-points.dita@ 99040

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="extension-points">
  <title>Extension points for plug-ins to the DITA Open Toolkit</title>
  <titlealts>
    <navtitle>Plug-in extension points</navtitle>
  </titlealts>
  <shortdesc>Extensions to the DITA Open Toolkit are supported through a plug-in extension mechanism.</shortdesc>
  <refbody>
    <section>
    <p>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 using a file named <filepath>plugin.xml</filepath>, located in the plug-in's
        root directory; the plug-in directory itself is generally located within the
          <filepath>plugins/</filepath> directory inside of the DITA-OT. This document describes all
        recognized extension points that are available for use within the
          <filepath>plugin.xml</filepath> file.</p>
    </section>
  </refbody>
  <reference id="topic_yxv_wov_kc">
    <title>Plugin configuration file</title>
    <refbody>
      <section>
      <p>The root element of the plugin.xml file is <codeph>&lt;plugin&gt;</codeph>, and must
        specify an <codeph>id</codeph> attribute. The <codeph>id</codeph> attribute is used to
        identify the plugin, as well as to identify whether pre-requisite plugins are available. The
          <codeph>id</codeph> attribute should follow the syntax rules:</p>
      <codeblock>id    ::= token('.'token)*
token ::= ( [0..9] | [a..zA..Z] | ’_’ | ’-’ )+</codeblock>
      <p>The <codeph>&lt;plugin&gt;</codeph> element supports the following child elements: </p>
      <ul>
        <li>
          <p><codeph>&lt;feature&gt;</codeph> defines an <i>extension</i> to contribute to a defined
              <i>extension point</i>. The following attributes are supported:</p>
          <simpletable keycol="1">
            <sthead>
              <stentry>Attribute</stentry>
              <stentry>Description</stentry>
              <stentry>Required</stentry>
            </sthead>
            <strow>
              <stentry><codeph>extension</codeph></stentry>
              <stentry>extension point identifier</stentry>
              <stentry>yes</stentry>
            </strow>
            <strow>
              <stentry><codeph>value</codeph></stentry>
              <stentry>comma separated string value of the extension</stentry>
              <stentry>either <codeph>value</codeph> or <codeph>file</codeph></stentry>
            </strow>
            <strow>
              <stentry><codeph>file</codeph></stentry>
              <stentry>file path value of the extension, relative to
                <filepath>plugin.xml</filepath></stentry>
              <stentry>either <codeph>value</codeph> or <codeph>file</codeph></stentry>
            </strow>
            <strow>
              <stentry><codeph>type</codeph></stentry>
              <stentry>type of the <codeph>value</codeph> attribute</stentry>
              <stentry>no</stentry>
            </strow>
          </simpletable>
        </li>
        <li>
          <p><codeph>&lt;require&gt;</codeph> defines plug-in dependencies. The following attributes
            are supported:</p>
          <simpletable keycol="1">
            <sthead>
              <stentry>Attribute</stentry>
              <stentry>Description</stentry>
              <stentry>Required</stentry>
            </sthead>
            <strow>
              <stentry><codeph>plugin</codeph></stentry>
              <stentry>vertical bar separated list of plug-ins that are required </stentry>
              <stentry>yes</stentry>
            </strow>
            <strow>
              <stentry><codeph>important</codeph></stentry>
              <stentry>flag whether plug-in is required or optional</stentry>
              <stentry>no</stentry>
            </strow>
          </simpletable>
        </li>
        <li>
          <p><codeph>&lt;template&gt;</codeph> defines files that should be treated as
              <i>templates</i>. The following attributes are supported:</p>
          <simpletable keycol="1">
            <sthead>
              <stentry>Attribute</stentry>
              <stentry>Description</stentry>
              <stentry>Required</stentry>
            </sthead>
            <strow>
              <stentry><codeph>file</codeph></stentry>
              <stentry>file path to the template, relative to <filepath>plugin.xml</filepath></stentry>
              <stentry>yes</stentry>
            </strow>
          </simpletable>
        </li>
        <li>
          <p><codeph>&lt;meta&gt;</codeph> defines metadata. The following attributes are
            supported:</p>
          <simpletable  keycol="1">
            <sthead>
              <stentry>Attribute</stentry>
              <stentry>Description</stentry>
              <stentry>Required</stentry>
            </sthead>
            <strow>
              <stentry><codeph>type</codeph></stentry>
              <stentry>metadata name </stentry>
              <stentry>yes</stentry>
            </strow>
            <strow>
              <stentry><codeph>value</codeph></stentry>
              <stentry>metadata value</stentry>
              <stentry>yes</stentry>
            </strow>
          </simpletable>
        </li>
      </ul>
      <p>Any extension that is not recognized by the DITA-OT is ignored; all elements other than
          <codeph>&lt;plugin&gt;</codeph> are optional. Since version 1.5.3 multiple extension
        definitions within a plugin configuration file are combined; in older versions only the last
        extension definition is used. </p>
      </section>
    </refbody>
    <related-links>
      <link href="#topic_vcw_wov_kc"></link>
    </related-links>
  </reference>
  <reference id="topic_myv_wov_kc">
    <title>XML catalogs</title>
    <refbody>
      <section>
      <p>The XML Catalogs extension point is used to update the XML Catalogs used to resolve DTD or
        Schema document types, or to add URI mappings. To do this, first create a catalog with only
        your new values, using the OASIS Catalog format, and place that in your plugin.</p>
      <dl>
        <dlentry>
          <dt><codeph>dita.specialization.catalog.relative</codeph></dt>
          <dt importance="deprecated"><codeph>dita.specialization.catalog</codeph></dt>
          <dd>
            <p>Adds the content of the catalog file defined in <codeph>file</codeph> attribute to
              main DITA-OT catalog file.</p>
            <note type="remember">The <codeph>dita.specialization.catalog</codeph> extension is
              deprecated. Use <codeph>dita.specialization.catalog.relative</codeph> instead.</note>
          </dd>
        </dlentry>
        <dlentry>
          <dt><codeph>org.dita.pdf2.catalog.relative</codeph></dt>
          <dd>
            <p>Adds the content of the catalog file defined in <codeph>file</codeph> attribute to
              main PDF plug-in catalog file.</p>
          </dd>
        </dlentry>
      </dl>
      </section>
      <example>
        <codeblock>&lt;feature extension="dita.specialization.catalog.relative" file="catalog-dita.xml"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_uyv_wov_kc">
    <title>New Ant targets</title>
    <refbody>
      <section>
      <p>The Ant conductor extension point is used to make new targets available to Ant
        processing.</p>
      <dl>
        <dlentry>
          <dt><codeph>dita.conductor.target.relative</codeph></dt>
          <dt importance="deprecated"><codeph>dita.conductor.target</codeph></dt>
          <dd>
            <p>Add Ant import to main Ant build file.</p>
            <note type="remember">The <codeph>dita.conductor.target</codeph> extension is
              deprecated. Use <codeph>dita.conductor.target.relative</codeph> instead.</note>
          </dd>
        </dlentry>
      </dl>
      </section>
      <example>
        <p>To do this, first place your extensions in an Ant project file within your plugin, such
          as myAntStuff.xml. Create a small wrapper file <filepath>myAntStuffWrapper.xml</filepath>
          in the same directory: </p>
        <codeblock>&lt;dummy&gt; &lt;import file="myAntStuff.xml"/&gt; &lt;/dummy&gt;</codeblock>
        <p>Then create the following feature: </p>
        <codeblock>&lt;feature extension="dita.conductor.target.relative" file="myAntStuffWrapper.xml"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_dzv_wov_kc">
    <title>Add Ant targets to the preprocess pipeline</title>
    <refbody>
      <section>
      <p>There are extension points to execute an Ant target before or after all preprocessing. </p>
      <dl>
        <dlentry><dt><codeph>depend.preprocess.pre</codeph></dt><dd>Preprocessing pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.post</codeph></dt><dd>Preprocessing post-target</dd></dlentry>
      </dl>
      <p>In addition, there are extension points to execute an Ant target before a given
        preprocessing step.</p>
      <dl>
        <dlentry><dt><codeph>depend.preprocess.clean-temp.pre</codeph></dt><dd>Clean temp pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.gen-list.pre</codeph></dt><dd>Generate list pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.debug-filter.pre</codeph></dt><dd>Debug and filter pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.conrefpush.pre</codeph></dt><dd>Content reference push pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.move-meta-entries.pre</codeph></dt><dd>Move meta entries pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.conref.pre</codeph></dt><dd>Content reference pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.coderef.pre</codeph></dt><dd>Code reference pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.mapref.pre</codeph></dt><dd>Map reference pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.keyref.pre</codeph></dt><dd>Key reference pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.mappull.pre</codeph></dt><dd>Map pull pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.chunk.pre</codeph></dt><dd>Chunking pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.maplink.pre</codeph></dt><dd>Map link pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.move-links.pre</codeph></dt><dd>Move links pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.topicpull.pre</codeph></dt><dd>Topic pull pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.copy-files.pre</codeph></dt><dd>Copy files pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.copy-image.pre</codeph></dt><dd>Copy images pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.copy-html.pre</codeph></dt><dd>Copy HTML pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.copy-flag.pre</codeph></dt><dd>Copy flag pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.copy-subsidiary.pre</codeph></dt><dd>Copy subsidiary pre-target</dd></dlentry>
        <dlentry><dt><codeph>depend.preprocess.copy-generated-files.pre</codeph></dt><dd>Copy generated files pre-target</dd></dlentry>
      </dl>
      </section>
      <example>
        <p>The following feature adds "myAntTargetBeforeChunk" Ant target to be executed before the
          chunk step in preprocessing: </p>
        <codeblock>&lt;feature extension="depend.preprocess.chunk.pre" value="myAntTargetBeforeChunk"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_lzv_wov_kc">
    <title>New transtype</title>
    <refbody>
      <section>
      <p>The transtype extension point is used to define a new "transtype", or transform type, which
        makes use of targets in your Ant extensions.</p>
      <dl>
        <dlentry>
          <dt><codeph>dita.conductor.transtype.check</codeph></dt>
          <dd>Add new value to list of valid transformation type names.</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.transtype.print</codeph></dt>
          <dd>Declare transtype as a print type.</dd>
        </dlentry>
      </dl>
      </section>
      <example>The following feature defines a transform type of "newtext" and declare it as a print
        type; using this transform type will cause the build to look for a target
          <codeph>dita2newtext</codeph>, defined previously in your Ant extension:
        <codeblock>&lt;feature extension="dita.conductor.transtype.check" value="newtext"/&gt;
&lt;feature extension="dita.transtype.print" value="newtext"/&gt;</codeblock></example>
    </refbody>
  </reference>
  <reference id="topic_tzv_wov_kc">
    <title>XSLT overrides</title>
    <refbody>
      <section>
      <p>The XSLT import extension points are 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: </p>
      <dl>
        <dlentry>
          <dt><codeph>dita.xsl.xhtml</codeph></dt>
          <dd>Override default (X)HTML output (including HTML Help and Eclipse Help) with the
            following</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.xslfo</codeph></dt>
          <dd>Override default PDF output (formerly known as PDF2) with the following</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.docbook</codeph></dt>
          <dd>Override default DocBook output with the following</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.rtf</codeph></dt>
          <dd>Override default RTF output with the following</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.eclipse.plugin</codeph></dt>
          <dd>Override the step that generates plugin.xml for Eclipse with the following</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.conref</codeph></dt>
          <dd>Override conref processing</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.topicpull</codeph></dt>
          <dd>Override topicpull processing (the step that pulls text into &lt;xref&gt; elements,
            among other things)</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.mapref</codeph></dt>
          <dd>Override mapref processing (the step that resolves references to other maps)</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.mappull</codeph></dt>
          <dd>Override mappull processing (the step that updates navtitles in maps and causes
            attributes to cascade)</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.xsl.maplink</codeph></dt>
          <dd>Override maplink processing (the step that generates map-based links)</dd>
        </dlentry>
        <dlentry importance="deprecated">
          <dt><codeph>dita.xsl.fo</codeph></dt>
          <dd>Override the (now deprecated) original PDF output with the following</dd>
        </dlentry>
      </dl>
      </section>
      <example>
        <codeblock>&lt;feature extension="dita.xsl.xhtml" file="xsl/modifyXhtml.xsl"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_gaw_wov_kc">
    <title>Generated text </title>
    <refbody>
      <section>
      <p>The generated text extension point is used to add new strings to the default set of
        Generated Text.</p>
      <dl>
        <dlentry>
          <dt><codeph>dita.xsl.strings</codeph></dt>
          <dd>Add new strings to generated text file. </dd>
        </dlentry>
      </dl>
      </section>
      <example>
        <p>Copy the file <filepath>xsl/common/strings.xml</filepath> to your plugin, and edit it to
          contain the languages that you are providing translations for ("en-us" must be present). 
          Copy the file <filepath>xsl/common/strings-en-us.xml</filepath> to your plugin, and
          replace the content with your own strings, being sure to give them unique name attributes.
          Do the same for each language that you are providing a translation for. </p>
        <p>Use the following extension code to include your strings in the set of generated text: </p>
        <codeblock>&lt;feature extension="dita.xsl.strings" file="xsl/common/strings.xml"/&gt;</codeblock>
        <p>The string is now available to the XSLT "getString" template. </p>
      </example>
    </refbody>
  </reference>
  <reference id="topic_oaw_wov_kc">
    <title>Pass parameters to XSLT</title>
    <refbody>
      <section>
      <p>You can pass parameters from the Ant build to XSLT pipeline stages, usually to have those
        parameters avalable as global &lt;xsl:param&gt; values in your XSLT overrides. Create a
        file insertParameters.xml which contains one or more Ant &lt;param&gt; elements: </p>
      <codeblock>&lt;dummy&gt;
  &lt;!-- Any Ant code allowed in xslt task is possible. Common example: --&gt;
  &lt;param name="paramNameinXSLT" expression="${antProperty}" if="antProperty"/&gt;
&lt;/dummy&gt;</codeblock>
      <p>Pass the value using the following extensions: </p>
      <dl>
        <dlentry>
          <dt><codeph>dita.conductor.html.param</codeph></dt>
          <dd>Pass parameters to HTML and HTML Help XSLT</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.conductor.xhtml.param</codeph></dt>
          <dd>Pass parameters to XHTML and Eclipse Help XSLT</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.preprocess.conref.param</codeph></dt>
          <dd>Pass parameters to conref XSLT</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.preprocess.mapref.param</codeph></dt>
          <dd>Pass parameters to mapref XSLT</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.preprocess.mappull.param</codeph></dt>
          <dd>Pass parameters to mappull XSLT</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.preprocess.maplink.param</codeph></dt>
          <dd>Pass parameters to maplink XSLT</dd>
        </dlentry>
        <dlentry>
          <dt><codeph>dita.preprocess.topicpull.param</codeph></dt>
          <dd>Pass parameters to topicpull XSLT</dd>
        </dlentry>
          <dlentry>
            <dt><codeph>dita.conductor.pdf2.param</codeph></dt>
            <dd>Pass parameters to PDF2 XSLT</dd>
          </dlentry>
      </dl>
      </section>
      <example>
        <codeblock>&lt;feature extension="dita.conductor.html.param" file="insertParameters.xml"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_bbw_wov_kc">
    <title>Add Java libraries to the classpath</title>
    <refbody>
      <section>
      <p>If your Ant or XSLT extensions require additional Java libraries in the classpath, you can
        add them to the global Ant classpath. </p>
      <dl>
        <dlentry>
          <dt><codeph>dita.conductor.lib.import</codeph></dt>
          <dd>Add Java libraries to DITA-OT classpath.</dd>
        </dlentry>
      </dl>
      </section>
      <example>
        <codeblock>&lt;feature extension="dita.conductor.lib.import" file="myJavaLibrary.jar"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_jbw_wov_kc">
    <title>Add diagnostic messages</title>
    <refbody>
      <section>
      <p>Plug-in specific warning and error messages can be added to the set of messages supplied by
        DITA-OT.</p>
      <dl>
        <dlentry>
          <dt><codeph>dita.xsl.messages</codeph></dt>
          <dd>Add new messages to diagnostic message file.</dd>
        </dlentry>
      </dl>
      </section>
      <example>
      <p>To add your own messages, create the message in an XML file
          <filepath>myMessages.xml</filepath>: </p>
      <codeblock>&lt;dummy&gt;
  &lt;!-- See resource/messages.xml for the details. --&gt;
  &lt;message id="myMessageId" type="WARN"&gt;
    &lt;reason&gt;...&lt;/reason&gt;
    &lt;response&gt;...&lt;/response&gt;
  &lt;/message&gt;
&lt;/dummy&gt;</codeblock>
      <p>And incorporate them with the extension: </p>
      <codeblock>&lt;feature extension="dita.xsl.messages" file="myMessages.xml"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_tbw_wov_kc">
    <title>Manage plugin dependencies </title>
    <refbody>
      <section>
      <p>The <codeph>&lt;require&gt;</codeph> element requires the <codeph>plugin</codeph>
        attribute. It is used to identify pre-requisite plug-ins. If the current plugin requires a
        plugin with <codeph>id="plugin-id"</codeph> before it can be installed, it would include the
        following: </p>
      <codeblock>&lt;require plugin="<i>plugin-id</i>"&gt;</codeblock>
      <p>Prerequisite plugins are integrated before the current plugin is integrated. This does the
        right thing with respect to XSLT overrides. If your plugin is a specialization of a
        specialization, it should <codeph>&lt;require&gt;</codeph> its base plugins, in order from
        general to specific. </p>
      <p>If a prerequisite plugin is missing, a warning will be printed during integration. To
        suppress this, but keep the integration order if both plugins are present, add
          <codeph>importance="optional"</codeph> to the <codeph>&lt;require&gt; </codeph>element. </p>
      <p>If your plugin can depend on any one of several optional plugins, separate the plugin ids
        with a vertical bar. This is most useful when combined with importance="optional": </p>
      </section>
      <example>
        <codeblock>&lt;require plugin="pluginA|pluginB" importance="optional"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_dcw_wov_kc">
    <title>Version and support information</title>
    <refbody>
      <section>
      <p>The following extension points are used by convention to define version and support info
        within a plugin:</p>
      <ul id="ul_jxr_hlv_mc">
        <li><codeph>package.support.name</codeph></li>
        <li><codeph>package.support.email</codeph></li>
        <li><codeph>package.version</codeph></li>
      </ul>
      <note>
        <p>The toolkit does not currently do anything with these values, but may do so in the
          future.</p>
      </note>
      <p>The <codeph>package.version</codeph> value should follow the syntax rules:</p>
      <codeblock>version   ::= major ( '.' minor ( '.' micro ( '.' qualifier )? )? )?

major     ::= number
minor     ::= number
micro     ::= number
qualifier ::= ( [0..9] | [a..zA..Z] | ’_’ | '-' )+</codeblock>
      <p>The default value is <codeph>0.0.0</codeph>.</p>
      </section>
      <example>
        <codeblock>&lt;feature extension="package.support.name" value="Joe the Author"/&gt;
&lt;feature extension="package.support.email" value="[email protected]"/&gt;
&lt;feature extension="package.version" value="1.2.3"/&gt;</codeblock>
      </example>
    </refbody>
  </reference>
  <reference id="topic_mcw_wov_kc">
    <title>Create your own extension points</title>
    <refbody>
      <section>
      <p>If your plugin needs to define its own extension point in an XML file, add the string
          "<codeph>_template</codeph>" to the filename before the file suffix. During integration,
        this file will be processed like the built-in DITA-OT templates. To mark the file as a
        template file, use the <codeph>&lt;template&gt;</codeph> element.</p>
      </section>
      <example><codeblock>&lt;template file="myTemplateFile_template.xsl"/&gt;</codeblock></example>
    </refbody>
  </reference>
  <reference id="topic_vcw_wov_kc">
    <title>Example plugin.xml file</title>
    <refbody>
      <section>
      <p>The following is a sample of a plugin.xml file. This file adds support for a new set of
        specialized DTDs, and includes an override for the XHTML output processor. It would go into
        a directory such as <filepath>DITA-OT\plugins\music\</filepath> and referenced supporting
        files would also exist in that directory. A more extensive sample using these values is
        available in the actual music plug-in, available at the <xref format="html"
          href="http://sourceforge.net/projects/dita-ot/files/" scope="external">DITA-OT download
          page</xref> at SourceForge </p>
      </section>
      <example><codeblock>&lt;plugin id="org.metadita.specialization.music"&gt;
  &lt;feature extension="dita.specialization.catalog.relative" file="catalog-dita.xml"&gt;
  &lt;feature extension="dita.xsl.xhtml" file="xsl/music2xhtml.xsl"/&gt;
&lt;/plugin&gt;</codeblock></example>
    </refbody>
  </reference>
</reference>