## 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`:

    ### plugin.name: rss
    ### plugin.outputDescription: RSS 2.0
    ### plugin.outputExtension: xml
    ### plugin.multiFileOutput: no

    -c
    -e w2x:xed/main.xed
    -t rss.xslt

    # Image files not useful here.
    -step:com.xmlmind.w2x.processor.DeleteFilesStep:cleanUp
    -p cleanUp.files "%{~pO}/%{~nO}_files"

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`:

    ### plugin.outputDescription: Web Help ZIP containing "semantic" (X)HTML 5.0
    ### plugin.outputExtension: zip

    -o webhelp5
    -p webhelp.split-before-level 8
    -p webhelp.use-id-as-filename yes
    -p webhelp.omit-toc-root yes
    -p webhelp.wh-layout simple

    # Generate all HTML files in a subdirectory of the output directory
    # having the same basename as the ".zip" output file.

    -p convert.xhtml-file "%{~pO}/%{~nO}/%{~nO}.xhtml"

    -p transform.out-file "%{~pO}/%{~nO}/%{~nO}_tmp.xhtml"

    -p webhelp.out-file "%{~pO}/%{~nO}/%{~nO}.html"

    -p cleanUp.files "%{~pO}/%{~nO}/%{~nO}_tmp.xhtml"

    -step:ZipStep:zip
    -p zip.out-file "%{O}"

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`.