Setting DITA-OT Common Parameters


The Common Parameters tab provides General and PDF parameters that DITA administrators can apply to CMS DITA-OT transformation processes.

Choose whether to leave the default parameters as is or choose to further adjust parameters to suit your organization's needs and preferences.

General parameters apply to all DITA transformation output formats supported by the DITA-OT, and PDF parameters apply to only DITA PDF transformation output format types.

See DITA-OT: Common Parameters for details about each common parameter available in the CMS, and see DITA-OT: PDF Parameters for details about each PDF parameter available in the CMS.

Important
Keep in mind that these parameters may have nuanced differences from version to version of the DITA-OT, so be sure to match the DITA-OT documentation version you reference with the installed DITA-OT version.

To set common parameters of the DITA-OT:

  1. Navigate to Administration > DITA > DITA-OT Parameters.

    The Common Parameters and Advanced Parameters tabs display.

  2. Select the Common Parameters tab.

    The general- and PDF-specific parameters display.

    Common Parameters Tab

  3. Select the information icon to the right of each respective parameter name to learn about the parameter's function and available values.

    DITA-OT Parameter Information

  4. If you need to modify parameter values, click within the respective parameter value field and select the preferred setting.

    Use the table below for reference.

    Parameter

    Output Formats

    Default Value

    Description

    force-unique

    General

    false

    Generate copy-to attributes to duplicate <topicref> elements. The allowed values are true and false; the default value is false.

    Setting this to true ensures that unique output files are created for each instance of a resource when a map contains multiple references to a single topic.

    processing-mode

    General

    lax

    Specifies how DITA-OT handles errors and error recovery. The following values are supported:

    • strict – When an error is encountered, DITA-OT stops processing

    • lax (default) – When an error is encountered, DITA-OT attempts to recover from it

    • skip – When an error is encountered, DITA-OT continues processing but does not attempt error recovery

    outer.control

    General

    warn

    Specifies whether to warn or fail if content is located outside the directory containing the DITA map. The following values are supported:

    • fail – Fail quickly if files are going to be generated or copied outside of the directory.

    • warn (default) – Complete the operation if files will be generated or copied outside of the directory, but log a warning.

    • quiet – Quietly finish without generating warnings or errors.

    generate.copy.outer

    General

    1

    Adjust how output is generated for content that is located outside the directory containing the DITA map. The following values are supported. The following values are supported:

    • 1 (default) – Do not generate output for content that is located outside the DITA map directory.

    • 3 – Shift the output directory so that it contains all output for the publication.

      See Handling content outside the map directory for more information.

    args.figurelink.style

    General

    NUMBER

    Specifies how cross references to figures are styled in output. The allowed values are NUMBER, TITLE, and NUMTITLE.

    Specifying NUMBER results in "Figure 5"; specifying TITLE results in the title of the figure. Corresponds to the XSLT parameter FIGURELINK.

    Note

    Support for PDF was added in DITA-OT 2.0. By default PDF uses the value NUMTITLE, which is not supported for other transformation types. For example, this results in this format: Figure 5. Title.

    args.tablelink.style

    General

    NUMBER

    Specifies how cross references to tables are styled. The allowed values are NUMBER, TITLE, and NUMTITLE.

    Specifying NUMBER results in "Table 5"; specifying TITLE results in the title of the table. Corresponds to the XSLT parameter TABLELINK.

    Note

    Support for PDF was added in DITA-OT 2.0. By default PDF uses the value NUMTITLE, which is not supported for other transformation types. For example, this results in this format: "Table 5. Title".

    pdf.formatter

    PDF

    fop

    Specifies the XSL processor. The following values are supported:

    • ah – Antenna House Formatter

    • xep – RenderX XEP Engine

    • fop (default) – Apache FOP

    org.dita.index.skip

    PDF

    no

    Disable index processing. The allowed values are yes and no; the default value is no.

    Up until DITA-OT 3.4, indexing code was provided in the PDF plug-in and only available for PDF output. In version 3.4 and above, indexing is provided by a separate plug-in to allow other transformations to access the results.

    If you have overridden PDF index processing via the transform.topic2fo target in the past, you can set the org.dita.index.skip property to yes and re-enable the transform.topic2fo.index target with <feature extension="depend.org.dita.pdf2.index" value="transform.topic2fo.index"/> in your plug-in configuration.

    org.dita.pdf2.chunk.enabled

    PDF

    false

    Enables chunk attribute processing. The following values are supported:

    • true – Enables chunk processing

    • false (default) – Disables chunk processing

    Troubleshooting

    If you require other parameters not listed in this tab, select the Advanced Parameters tab to add the parameter name and value.

Next Steps (optional):

Set parameters in the Advanced Parameters tab to suit your organization's needs and preferences.