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.
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 DITA-OT for installation, processing, and when determining plug-in dependencies.

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 (-)

<xmlelement>plugin</xmlelement>

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

Plug-in elements Perhaps all the following tables should have a Data type column? That would match with the DITA spec; also, it seems as if some attributes must take a predefined set of values.

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.

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. 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 type Type of the value attribute No

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"/>

 meta

An optional element that defines metadata.

The following attributes are supported:

Attribute Description Required? type Metadata name Yes value Metadata value Yes 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. The DITA-OT provides a warning if a required plug-in is not available. No 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 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 , 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

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 (, , ) Yes val A child of param (when type=) that specifies an enumeration value.

The following attributes are supported:

Attribute Description Required? default When , sets the enumeration value as the default value of the parent param Only for the default val

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