Configuring a DITA transformation

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:

 

Figure 4.58. Select DITA Transformation type

Select DITA Transformation type

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.

[Tip]Tip

If you want to transform your DITA topics to various formats using the DITA Open Toolkit you can open them in the DITA Maps Manager view using the "Open" button located on the internal toolbar and transform them from here.

 Customizing the DITA scenario
 The Parameters tab

In the Scenario Edit Parameters Tab you can customize all the parameters which will be sent to the DITA-OT build file.

 

Figure 4.59. Edit DITA Ant transformation parameters

Edit DITA Ant transformation parameters

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.

 

Figure 4.60. Edit DITA parameters dialog

Edit DITA parameters dialog

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.

 The Filters tab

In the Scenario Filters Tab you can add filters to remove certain content elements from the generated output.

 

Figure 4.61. Edit Filters tab

Edit Filters tab

You have two ways in which to define filters:

Use DITAVAL file

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.

Exclude from output all elements with any of the following attributes

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.

 The Advanced tab

In the Advanced Tab you can specify advanced options for the transformation.

 

Figure 4.62. Advanced settings tab

Advanced settings tab

You have several parameters that you can specify here:

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 directory configured in the Parameters tab will be used.

Build target

You can specify a build target to the build file. By default no target is necessary and the default "init" target is used.

Ant Home

You can specify a custom ANT installation to run the DITA Map transformation. By default it is the ANT installation bundled with <oXygen/>.

Java Home

You can specify a custom Java Virtual Machine to run the ANT transformation. By default it is the Java Virtual Machine used by <oXygen/>.

 JVM Arguments

This parameter allows you to set specific parameters to the Java Virtual Machine used by ANT. By default it is set to -Xmx256m which means the transformation process is allowed to use 256 megabytes of memory.

 

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.


Libraries

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.


 The Output tab

In the Output Tab you can configure options related to the place where the output will be generated.

 

Figure 4.63. Output settings tab

Output settings tab

You have several parameters that you can specify here:

Base directory

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.

Temporary files directory

This directory will be used to store pre-processed temporary files until the final output is obtained.

Output folder

The folder where the final output content will be copied.

Output file options

The transformation output can then be opened in a browser or even in the editor if specified.

 The FO Processor tab

This tab appears only when selecting to generate PDF output using the IDIOM FO Plugin and allows you to choose the FO Processor.

 

Figure 4.64. FO Processor configuration tab

FO Processor configuration tab

You can choose between two processors:

Built-in (Apache FOP)

This processor comes bundled with <oXygen/>. You can find more information about it here.

XEP

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.
[Tip]Tip

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.