Running an External DITA Transformation Using the Oxygen XML WebHelp Plugin
History | Edit

There are two main ways to run a DITA to WebHelp (webhelp-responsive, webhelp, webhelp-feedback, webhelp-mobile) transformation using the Oxygen XML WebHelp plugin:

Startup Script from WebHelp Plugin Method

The first method involves running the ditaWebhelp.bat or ditaWebhelp.sh startup script that comes bundled in the WebHelp plugin folder:
  • WEBHELP_PLUGIN_DIR\ditaWebhelp.bat script file (Windows based systems)
  • WEBHELP_PLUGIN_DIR\ditaWebhelp.sh script file (Unix/Linux based systems)
Before using the script to generate output, you must customize it to specify the paths to the Java VM, DITA Open Toolkit, and also to set the transformation type. To do this, open the script file and edit the following variables and parameters:
  • JVM_INSTALL_DIR - Specifies the path to the Java Virtual Machine installation directory on your disk.
  • DITA_OT_INSTALL_DIR - Specifies the path to DITA Open Toolkit installation directory on your disk.
    Note: The scripts reference the dost-patches-DITA-1.8.jar JAR file containing DITA OT 1.8.5-specific patches. If you use DITA OT 1.7, please update that reference to dost-patches-DITA-1.7.jar. If you use DITA OT 2.3.3, no patches are needed, so just remove the reference.
  • TRANSTYPE - Specifies the type of the transformation you want to apply. You can set it to webhelp-responsive, webhelp, webhelp-feedback or webhelp-mobile.
  • DITA_MAP_BASE_DIR - Specifies the path to the directory where the input DITA map file is located.
  • DITAMAP_FILE - Specifies the input DITA map file.
  • DITAVAL_FILE - Specifies the .ditaval input filter that the transformation process applies to the input DITA map file.
  • DITAVAL_DIR - Specifies the path to the directory where the .ditaval file is located.
  • -Doutput.dir - Specifies the output directory of the transformation.

Startup Script from DITA OT Distribution Method

The second method involves using the startup script that comes bundled with each DITA OT distribution.

DITA OT 1.8.5
For DITA Open Toolkit 1.8.5, the general instructions for running the startup script can be found here: http://www.dita-ot.org/1.8/readme/building-output-using-cl-tool.html.
DITA OT 2.3.3
For DITA Open Toolkit 2.3.3, the general instructions for running the startup script can be found here: http://www.dita-ot.org/2.3/parameters/dita-command-arguments.html.
DITA OT Startup Script Examples:
  • DITA_OT_DIR\bin\dita.bat -i path_to_input.ditamap -f webhelp (Windows based systems)
  • DITA_OT_DIR\bin\dita -i path_to_input.ditamap -f webhelp (Unix/Linux based systems)
    Note: For the -format (-f) argument, you use the following transformation types: webhelp-responsive, webhelp, webhelp-feedback or webhelp-mobile.

The downside of this approach is the fact that you will lose certain small fixes and patches that Oxygen XML Editor adds to the automated DITA OT processing. For example, you may lose the ability to process DITA topics that contain entity references inside them.