Login
Home CMS Documentation Home CMS 10 DITA Processing Pipeline Initial DITA Configuration DITA Administration DITA Open Toolkit Parameters Common Parameters

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-uniqueGeneral 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-modeGeneral laxSpecifies 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.controlGeneral 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 3Adjust 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 – Do not generate output for content that is located outside the DITA map directory.

    • 3 (Default) – 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.styleGeneral 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.styleGeneral 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.formatterPDF fopSpecifies 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.enabledPDF falseEnables 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.