2. Creating useful add-on descriptors

2. Creating useful add-on descriptors
	Appendix A. Packaging an add-on for XMLmind XML Editor integrated add-on manager

Above example, pnm_imagetoolkit.xxe_addon, is not very informative. It lacks at least an a:abstract element which describes the purpose of the add-on.

Unless you intend to always write minimal add-on descriptors, you'll want to install the XXE configuration which provides support for this document type. This configuration is available as an add-on called "XMLmind XML Editor Configuration Pack". Download and install it using menu item Options → Install Add-ons.

a:addon attributes:

location

URL of the .zip file containing the add-on.

Not required when the .xxe_addon file is itself contained in the .zip file.

Required when the .xxe_addon file is downloaded by the integrated add-on manager in order to show to the user all available add-ons. In such case, location must point to the .zip file.

a:addon elements:

a:category

Required. The category of the add-on. Contains one of the following elements: a:translation, a:dictionary, a:configuration, a:foProcessorPlugin, a:imageToolkitPlugin, a:virtualDrivePlugin or a:otherCategory.

a:otherCategory has a required name attribute (a few words at most).

a:name

Required. The name of the add-on (a few words at most).

a:version

Required. Version number of the add-on. Examples: 1, 1.0, 1.2.1, 2.1.0_05, 1.0.0-alpha1, 2.0.1-beta02.

a:requires

Specifies the name of an add-on required by this add-on. It is possible to have several a:requires elements.

"Apache FOP 1.x XSL-FO processor plug-in" example:

<a:requires>Apache Batik image toolkit plug-in</a:requires>
<a:requires>JEuclid image toolkit plug-in</a:requires>

Note that there is no need to specify indirect dependencies. When A requires B and B requires C, just specify B, and not B and C.

a:excludes

Specifies the name of an add-on which cannot be installed together with this add-on. It is possible to have several a:excludes elements.

"RenderX XEP XSL-FO processor plug-in" example:

<a:excludes>Apache FOP 1.x XSL-FO processor plug-in</a:excludes>

Note that there is no need to specify indirect dependencies. When A excludes B and B excludes C, just specify B, and not B and C.

a:author

The author of the add-on. Same content as XHTML p (a subset of XHTML in fact).

a:date

The release date of the add-on in YYYY-mm-dd ISO format^[9]. Example: 2021-03-31.

a:abstract

The purpose of the add-on. Same content as XHTML p.

a:documentation

Use this element if the a:abstract is not sufficient to describe the purpose of the add-on. Same content as XHTML div.

a:xxeVersion

Specifies the version of XXE required to run this add-on. Same format as a:version, except that it may be followed by "+" to specify a version number and above.

Example: 11.2.1 means: strictly requires XXE 11.2.1. Will not work with 11.2.0, 11.2.2 or 11.3.0.

Example: 11.2+ means: requires XXE 5.2.0 and above. Works with 11.2.0, but also with 11.2.1, 11.2.2, 11.3, etc.

Without this element, the add-on is assumed to work with any version of XXE.


In order to prevent link errors, any add-on which contains Java™ code (e.g. a jar) must have an `a:xxeVersion` equals to the version of XXE against which the code has been compiled. Of course, this `a:xxeVersion` must not have the "`+`" modifier. Typically such add-ons are: XSL-FO processor plug-ins. Image toolkit plug-ins. Virtual drive plug-ins. Configurations, customizing XXE for a given document type, which include custom commands written in Java™.

In order to prevent link errors, any add-on which contains Java™ code (e.g. a jar) must have an a:xxeVersion equals to the version of XXE against which the code has been compiled. Of course, this a:xxeVersion must not have the "+" modifier.

Typically such add-ons are:

XSL-FO processor plug-ins.
Image toolkit plug-ins.
Virtual drive plug-ins.
Configurations, customizing XXE for a given document type, which include custom commands written in Java™.

a:platforms

Specifies the platforms required to run the add-on. Contains one or more of the following elements:

a:windows: Any version of Windows.
a:unix: Means macOS or any other Unix like Linux, FreeBSD, etc.
a:mac: Any version of macOS whatever the processor used by the Mac.
a:macIntel: Any version of macOS for a Mac having an Intel processor.
a:macARM: Any version of macOS for a Mac having an ARM (Apple Silicon, M1, etc) processor.
a:genericUnix: Any Unix other than macOS, for example, Linux, FreeBSD, etc.
a:linux: Any version of Linux.
a:otherPlatform: Other platform having a name attribute matching Java™ system property os.name and optionally also os.arch.

a:otherPlatform has a required name attribute. The value of this attribute can be a plain string, examples:

<a:otherPlatform name="Linux" />

<a:otherPlatform name="Linux/amd64" />

or a regular expression (when attribute regexp is specified with value true), examples:

<a:otherPlatform name="l[^x]+x" regexp="true" />

<a:otherPlatform name="l[^x]+x/.+64" regexp="true" />

In both cases, the value of attribute name is matched (case-insensitive) against the value of Java™ system property os.name, optionally followed by "/" then by system property os.arch.

Without this element, the add-on is assumed to run on all platforms supported by XXE.

All platform elements may contain a a:postInstallShell child element. This element may be used to specify a script which is to be executed after the add-on has been installed.

<a:platforms>
  <a:unix>
    <a:postInstallShell>chmod a+x xep_finish_install</a:postInstallShell>
  </a:unix>

  <a:windows />
</a:platforms>

Note that the current working directory of this script is the directory where the add-on has been installed.

^[9]Note that the CSS style sheet for XXE add-ons allows to specify the date using a more convenient format.


1. Why packaging add-ons?		Appendix B. Porting an XXE v9 command to XXE v10