Packaging your customization as a w2x plugin

Command-line utility w2x and desktop application w2x-app support plugins.

Let’s suppose you have created a plugin called “rss” which may be used to convert DOCX to RSS. Once registered with w2x, this plugin may be invoked as it were a stock conversion, for example:

w2x -o rss my.docx my.xml

Other example, using a plugin called “wh5_zip” (see description below):

w2x -o wh5_zip -p zip.include-top-dir false my.docx my.zip

In w2x-app, you'll find the registered plugins in the "Convert to" combobox and in the "Output format" screen of the setup assistant.

Anatomy of a plugin

A plugin is simply a plain text file, using an UTF-8 character encoding, having a ".w2x_plugin" file suffix, containing a number of w2x command-line arguments and starting with comment lines containing information about the plugin (for example, its name). Example, w2x_install_dir/sample_plugins/rss/rss.w2x_plugin:

Field Name	Default Value	Description
plugin.name:	Basename of the ".w2x_plugin" file without its extension.	The name of the plugin (a single word).
plugin.outputDescription:	The name of the plugin.	A short description (just a few words) of the output format of this plugin.
plugin.outputExtension:	xml	Preferred extension for the files created by this plugin.
plugin.multiFileOutput:	no	Whether this plugin creates multiple files or just a single one. A boolean: “true”, “yes”, “on”, “1” or “false”, “no”, “off”, “0”.

The above rss plugin converts DOCX to RSS. This process is partly implemented by XSLT 1.0 stylesheet w2x_install_dir/sample_plugins/rss/rss.xslt which is part of this plugin. Stylesheet rss.xslt transforms its input, the semantic XHTML 1.0 Transitional file created by the Edit step (invoked using -e w2x:xed/main.xed), to RSS.

Aside XSLT 1.0 stylesheets, a plugin may also include XED scripts as well as ".jar" files containing support code and/or custom conversion steps implemented in Java™. Example, w2x_install_dir/sample_plugins/wh5_zip/wh5_zip.w2x_plugin:

The above wh5_zip plugin specializes the stock conversion called webhelp5 (Web Help containing XHTML 5.0) by giving specific values to some of its parameters (e.g. -p webhelp.wh-layout simple) and also by archiving all the output files in a single “.zip” file.

This last step, -step:ZipStep:zip, is implemented by a custom conversion step found in w2x_install_dir/sample_plugins/wh5_zip/src/ZipStep.java. This Java™ code is compiled and archived in w2x_install_dir/sample_plugins/wh5_zip/zip_step.jar by the means of ant build file w2x_install_dir/sample_plugins/wh5_zip/src/build.xml.

Note that these ".jar" files, just like the ".w2x_plugin" files, are automatically discovered and loaded by w2x and w2x-app during their startup phase.

Registering a plugin with w2x

A plugin is registered with both w2x and w2x-app by copying all its files anywhere inside directory w2x_install_dir/plugin/.

However it's strongly recommended to group all the files comprising a plugin in a subdirectory of its own having the same name as the plug-in (e.g. w2x_install_dir/plugin/rss/).

If the .dmg distribution has been used to install XMLmind Word To XML on the Mac, the plugin directory is WordToXML.app/Contents/Resources/w2x/plugin/.

Alternatively, this plugin may be installed anywhere you want provided that the directory containing the ".w2x_plugin" file is referenced in the W2X_PLUGIN_PATH environment variable. Example: set W2X_PLUGIN_PATH=C:\Users\John\w2x\rss;C:\temp\w2x_plugins.

The W2X_PLUGIN_PATH environment variable (or, equivalently, the W2X_PLUGIN_PATH Java™ system property; e.g. -DW2X_PLUGIN_PATH=C:\Users\John\w2x\rss;C:\temp\w2x_plugins) may contain absolute or relative directory paths separated by semi-colons (";"). A relative path is relative to the current working directory.

The W2X_PLUGIN_PATH environment variable may also contain "+", which is a shorthand for w2x_install_dir/plugin/. Windows example: set W2X_PLUGIN_PATH=..\sample_plugins;+. Linux/macOS example: export W2X_PLUGIN_PATH=+;/home/john/w2x_plugins.