Plug-in descriptor file

Plug-in identifiers

idplug-in

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.

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.

Sample <xmlelement>plugin</xmlelement> element

Plug-in elements

plugin

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 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. Sample <xmlelement>extension-point</xmlelement> element <extension-point id="dita.xsl.html5" name="HTML5 XSLT import"/> feature feature value file

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 Sample <xmlelement>feature</xmlelement> 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"/> meta meta

An optional element that defines metadata.

The following attributes are supported:

Attribute Description Required? type Metadata name Yes value Metadata value Yes Sample <xmlelement>meta</xmlelement> element <meta type="foo" value="bar"/> require 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 Sample <xmlelement>require</xmlelement> element template template dita:extension

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 Sample <xmlelement>template</xmlelement> element <template file="build_dita2html5_template.xml"/> transtype transtypeplugin.xml

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 Sample <xmlelement>transtype</xmlelement> 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 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 deprecated When , identifies this parameter as deprecated No required When , identifies this parameter as required No val 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 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.