Running an External DITA Transformation Using the Oxygen XML WebHelp Plugin

This topic explains how to run an external DITA to WebHelp transformation using the Oxygen XML WebHelp plugin.

To run a DITA to WebHelp (webhelp-responsive, webhelp, webhelp-feedback, webhelp-mobile) transformation using the Oxygen XML WebHelp plugin, use the following:

DITA-OT 2.x versions
  • 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)
DITA-OT 1.x versions
  • WEBHELP_PLUGIN_HOME_DIR\dita.bat script file (Windows based systems)
  • WEBHELP_PLUGIN_HOME_DIR\dita.sh script file (Unix/Linux based systems)
Warning: You can also invoke the DITA OT WebHelp publishing using a startup script but you will lose certain small fixes and patches that Oxygen XML Editor added to the automated DITA OT processing.
The dita.bat and the dita.sh files are located in the home directory of the Oxygen XML WebHelp Plugin. Before using them to generate a WebHelp system, customize them to match the paths to the JVM, DITA Open Toolkit, and Saxon engine, 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 dita.bat and dita.sh scripts reference the dost-patches-DITA-1.8.jar JAR file containing DITA OT 1.8-specific patches. If you use DITA OT 1.7, update that reference to dost-patches-DITA-1.7.jar. If you use DITA OT 2.0, 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, webhelp-feedback and 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.

The optional parameter -Dargs.filter can be used to specify a filter file to be used to include, exclude, or flag content.