History | Edit

Problem

Referencing a DITA topic, map, or binary resource (for example, image) that is located outside of the folder where the main DITA map is located leads to problems when publishing the content using the DITA Open Toolkit.

Solution

The DITA-OT does not handle it well when references are outside the directory where the published DITA map is found. By default, it does not even copy the referenced topics to the output directory.

To solve this, choose one of the following options:
  • Create another DITA map that is located in a folder path above all referenced folders and reference from it the original DITA map. Then transform this DITA map instead.
  • Edit the transformation scenario and in the Parameters tab edit the fix.external.refs.com.oxygenxml parameter. This parameter is used to specify whether or not the application tries to fix such references in a temporary files folder before the DITA Open Toolkit is invoked on the fixed references. The fix has no impact on your edited DITA content. The allowed values are false and true. The default value is false.
    Important: The fix.external.refs.com.oxygenxml parameter is only supported when the DITA OT transformation process is started from Oxygen XML Editor.
  • For PDF output, you can edit the transformation scenario and in the Parameters tab set the value of the generate.copy.outer parameter to 3. This parameter specifies whether to generate output files for content that is not located in or beneath the directory containing the DITA map file. By setting the value of this parameter to 3, the transformation scenario shifts the output directory so that it contains all output for the publication.
    Important: This method is recommended for transformation scenarios that use an external DITA-OT.