# Plug-in descriptor file

The plug-in descriptor file (plugin.xml) controls all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and then integrates those changes into the core DITA-OT code.

## Validating plug-ins

DITA-OT includes a RELAX NG schema file that can be used to validate the plugin.xml files that define the capabilities of each plug-in.

To ensure the syntax of your custom plug-in is correct, include an `<?xml-model?>` processing instruction at the beginning of the plugin.xml file, immediately after the XML prolog:

`<?xml-model href="https://www.dita-ot.org/rng/plugin.rnc" type="application/relax-ng-compact-syntax"?>`

If your authoring environment does not apply this schema automatically, point your editor to dita-ot-dir/resources/plugin.rnc to associate the schema with your plug-in file.

## Plug-in identifiers

Every DITA-OT plug-in must have a unique identifier composed of one or more dot-delimited tokens, for example, `com.example.rss`. This identifier is used to identify the plug-in to the toolkit for installation, processing, and when determining plug-in dependencies.

Note:
The default DITA-OT plug-ins use a reverse domain naming convention, as in `org.dita.html5`; this is strongly recommended to avoid plug-in naming conflicts.
Each token can include only the following characters:

- Lower-case letters (a-z)
- Upper-case letters (A-Z)
- Numerals (0-9)
- Underscores (_)
- Hyphens (-)

## `<plugin>`

The root element of the plugin.xml file is `<plugin>`, which has a required `@id` attribute set to the unique plug-in identifier.

Figure 1. Sample `<plugin>` element

    <plugin id="com.example.html5-javascript">

## Plug-in elements

The `<plugin>` element can contain the following child elements:

`<extension-point>`

  An optional element that defines a new extension point that can be used by other DITA-OT plug-ins.

  The following attributes are supported:

  Attribute | Description | Required?
  --- | --- | ---
  id | Extension point identifier | Yes
  name | Extension point description | No

  Like plug-in identifiers, extension point identifiers are composed of one or more dot-delimited tokens.

  Note:
  Extension point identifiers should begin with the identifier of the defining plug-in and append one or more tokens, for example, `org.dita.example.pre`.
  Figure 2. Sample `<extension-point>` element

      <extension-point id="dita.xsl.html5" name="HTML5 XSLT import"/>

`<feature>`

  An optional element that supplies values to a DITA-OT extension point.

  The following attributes are supported:

  Attribute | Description | Required?
  --- | --- | ---
  extension | Identifier of the DITA-OT extension point | Yes
  value | Comma separated string value of the extension | Either the `@value` or `@file` attribute must be specified
  file | Name and path of a file containing data for the extension point. Depending on the extension point, this might be specified as an absolute path, a path relative to the plugin.xml file, or a path relative to the DITA-OT root. | Either the `@value` or `@file` attribute must be specified
  desc | Feature description | No
  type | Type of the `@value` attribute | No

  Figure 3. Sample `<feature>` elements

  If more than one `<feature>` element supplies values to the same extension point, the values are additive. For example, the following are equivalent:

      <feature extension="org.dita.example.extension-point" value="a,b,c"/>

      <feature extension="org.dita.example.extension-point" value="a"/>
      <feature extension="org.dita.example.extension-point" value="b"/>
      <feature extension="org.dita.example.extension-point" value="c"/>

`<metadata>`

  An optional element that defines metadata.

  The following attributes are supported:

  Attribute | Description | Required?
  --- | --- | ---
  type | Metadata name | Yes
  value | Metadata value | Yes

  Figure 4. Sample `<metadata>` element

      <metadata type="foo" value="bar"/>

`<require>`

  An optional element that defines plug-in dependencies.

  The following attributes are supported:

  Attribute | Description | Required?
  --- | --- | ---
  plugin | The identifier of the required plug-in. To specify alternative requirements, separate plug-in identifiers with a vertical bar. | Yes
  importance | Identifies whether the plug-in is `required` (default) or `optional`. DITA-OT provides a warning if a required plug-in is not available. | No

  Figure 5. Sample `<require>` element

      <require plugin="org.dita.html5"/>

`<template>`

  An optional element that defines files that should be treated as templates.

  Template files can be used to integrate DITA-OT extensions. Templates typically extend the default transformation-type-specific build files via `<dita:extension>` elements. When the plug-in installation process runs, template files are used to recreate build files, and the specified extension points are replaced with references to the appropriate plug-ins.

  The following attributes are supported:

  Attribute | Description | Required?
  --- | --- | ---
  file | Name and path to the template file, relative to the plugin.xml file | Yes

  Figure 6. Sample `<template>` element

      <template file="build_dita2html5_template.xml"/>

`<transtype>`

  An optional element that defines a new output format (transformation type).

  The following attributes are supported:

  Attribute | Description | Required?
  --- | --- | ---
  name | Transformation name | Yes
  desc | Transformation type description | No
  abstract | When true, sets the transformation type as abstract, meaning it can be extended by other plug-ins, but cannot be used directly. For example, the `org.dita.base` plug-in defines an abstract base transformation type that is extended by other DITA-OT plug-ins. | No
  extends | Specifies the name of the transformation type being extended | No

  Figure 7. Sample `<transtype>` element

      <transtype name="base" abstract="true" desc="Common">
        [...]
        <param name="link-crawl"
               desc="Specifies whether to crawl only topic links found in maps, or all discovered topic links."
               type="enum">
          <val>map</val>
          <val default="true">topic</val>
        </param>
        [...]
      </transtype>

  The `<transtype>` element may define additional parameters for the transformation type using the following child elements.

  `<param>`

    An optional element that specifies a parameter for the transformation type.

    The following parameter attributes are supported:

    Attribute | Description | Required?
    --- | --- | ---
    name | Parameter name | Yes
    desc | Parameter description | No
    type | Parameter type (enum, file, string) | Yes
    deprecated | When true, identifies this parameter as deprecated | No
    required | When true, identifies this parameter as required | No

  `<val>`

    A child of `<param>` (when `@type`=enum) that specifies an enumeration value.

    The following attributes are supported:

    Attribute | Description | Required?
    --- | --- | ---
    default | When true, sets the enumeration value as the default value of the parent `<param>` | Only for the default `<val>`

Any extension that is not recognized by DITA-OT is ignored. Since DITA-OT version 1.5.3, you can combine multiple extension definitions within a single plugin.xml file; in older versions, only the last extension definition was used.

## Example plugin.xml file

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.

This plugin.xml file would go into a directory such as DITA-OT/plugins/music/ 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 on SourceForge.

    <plugin id="org.metadita.specialization.music">
      <feature extension="dita.specialization.catalog.relative"
               file="catalog-dita.xml"/>
      <feature extension="dita.xsl.xhtml" file="xsl/music2xhtml.xsl"/>
    </plugin>