Creating DITA Map transformation scenarios is similar to creating scenarios in the main editing area. See here for more details.
When creating a new scenario you can choose the type of output the DITA-OT ANT scenario will generate:
Depending on the chosen type of output Oxygen will generate values for the default ANT parameters so that you can execute the scenario right away without further customization.
In the Scenario Edit Parameters Tab you can customize all the parameters which will be sent to the DITA-OT build file.
All the parameters that can be set to the DITA-OT build files for the chosen type of transformation (eg: XHTML) are listed along with their description. The values for some important parameters are already filled in. You can find more information about each parameter in the DITA OT Documentation
Using the toolbar buttons you can Add, Edit or Remove a parameter.
Depending on the parameter type the parameter value will be a simple text field for simple parameter values, a combo box with some predefined values or will have a file chooser and an editor variables selector to simplify setting a file path as value to a parameter.
In the Scenario Filters Tab you can add filters to remove certain content elements from the generated output.
You have two ways in which to define filters:
If you already have a DITAVAL file associated with the transformed map you can specify the path to it and it will be used when filtering content. You can find out more about constructing a DITAVAL file in the DITA OT Documentation.
You can configure a simple list of attribute (name, value) pairs which when present on an element in the input will remove it from output.
In the Advanced Tab you can specify advanced options for the transformation.
You have several parameters that you can specify here:
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
directory configured in the Parameters tab will be used.
You can specify a build target to the build file. By default no target is necessary and the default "init" target is used.
You can specify a custom Java Virtual Machine to run the ANT transformation. By default is the Java Virtual Machine used by <oXygen/>.
This parameter allows you to set specific parameters to the Java Virtual Machine used by ANT.
Example 4.6. Increasing the memory for the ANT process
Sometimes, when performing a large DITA map transformation you may want to increase the memory allocated to the Java Virtual Machine from the default value (64 MB) to a higher value (256MB). You can do this easily by setting the value '-Xmx256m' without quotes to the "JVM Arguments" text field. In this way you can avoid the Out of Memory ( OutOfMemoryError ) messages received from the ANT process.
You can specify all the additional libraries (jar files or additional class paths) which will be used by the ANT transformer.
Example 4.7. Additional jars specified for XHTML
For example the additional jars specified for XHTML are the DITA-OT dost and resolver jars, xerces and saxon 6 jars.
In the Output Tab you can configure options related to the place where the output will be generated.
You have several parameters that you can specify here:
All the relative paths which appear as values in parameters are considered relative to the base directory. The default value is the directory where the transformed map is located.
This directory will be used to store pre-processed temporary files until the final output is obtained.
The folder where the final output content will be copied.
The transformation output can then be opened in a browser or even in the editor if specified.
This tab appears only when selecting to generate PDF output using the IDIOM FO Plugin and allows you to choose the FO Processor.
You can choose between two processors:
This processor comes bundled with <oXygen/>. You can find more information about it here.
The RenderX XEP processor. You can add it very easy from here.
If you select XEP in the combo and XEP was already installed in <oXygen/> you can see the detected installation path appear under the combo.
XEP is considered as installed if it was detected from one of the following sources:
XEP was added as an external FO Processor in the <oXygen/> preferences. See here. |
The system property "com.oxygenxml.xep.location" was set to point to the XEP executable file for the platform (eg: xep.bat on Windows). |
XEP was installed in the frameworks/dita/DITA-OT/demo/fo/lib directory of the <oXygen/> installation directory. |
The DITA-OT contributors recommend the use of the IDIOM FO Plugin to transform DITA Maps to PDF as opposed to using the standard PDF target in the DITA-OT framework.
As IDIOM is also bundled with <oXygen/> the PDF2 - IDIOM FO Plugin output format should be your first choice in transforming your map to PDF. If you do not have a XEP licence you can transform using Apache FO Processor.