Advanced Tab (DITA-OT Transformations)

When you create a new transformation scenario or edit an existing one, a configuration dialog box is displayed that allows you to customize the transformation with various options in several tabs.

The Advanced tab allows you to specify advanced options for the transformation scenario.

Figure 1. Advanced Settings Tab

You can specify the following options:

Prefer using the "dita" command: When selected, Oxygen XML Author Eclipse plugin will attempt to use the dita.bat executable script (dita.sh for macOS and Linux) that is bundled with DITA-OT to run the transformation. If not selected, the transformation will run as an ANT process. Also, when this option is selected, other options (Custom build file, Build target, Ant Home) become unavailable. This setting is checked by default in newly created DITA-OT transformation scenario.
Note: Even when this option is selected, the dita.bat (dita for macOS and Linux) executable cannot be used in some cases. For example, if the DITA Map is published from a remote location or if the fix.external.refs parameter is enabled in the Parameters tab, the transformation is started as an ANT process instead of using the executable.
Custom build file: If you use a custom DITA-OT build file, you can specify the path to the customized build file. If empty, the build.xml file from the dita.dir parameter that is configured in the Parameters tab is used. You can specify the path by using the text field, the Insert Editor Variables button, or the Browse button.
Build target: Optionally, you can specify a build target for the build file. If no target is specified, the default init target is used.
Additional Ant arguments: You can specify additional Ant-specific command-line arguments (such as -diagnostics).
Ant Home: You can choose between the default or custom Ant installation to run the transformation.
Java Home: You can choose between the default or custom Java installation to run the transformation. The default path is the Java installation that is used by Oxygen XML Author Eclipse plugin.
Note: It may be possible that the used Java version is incompatible with the DITA Open Toolkit engine. If you encounter related errors running the transformation, consider installing a Java VM that is supported by the DITA-OT publishing engine and using it in the Java Home text field.
JVM Arguments: This parameter allows you to set specific parameters for the Java Virtual Machine used by Ant. When performing a large transformation, you may want to increase the memory allocated to the Java Virtual Machine. This will help avoid Out of Memory error messages (OutOfMemoryError). For example, if it is set to -Xmx2g, the transformation process is allowed to use a maximum 2 gigabytes of memory. If you do not specify an -Xmx value in this field, by default, the application will use a maximum of about a quarter of the total memory available on the machine.
Libraries: By default, Oxygen XML Author Eclipse plugin adds libraries (as high priority) that are not transformation-dependent and also patches for certain DITA Open Toolkit bugs. You can use this button to specify additional libraries (JAR files or additional class paths) to be used by the transformer.
Tip: You can specify the path to the additional libraries using wildcards (for example, ${oxygenHome}/lib/*.jar).