DITA Open Toolkit 3.7 Release Notes

DITA Open Toolkit 3.7.2 is a maintenance release that fixes issues reported in DITA-OT 3.7, which includes stable IDs in re-used content, a common variable format for generated text strings, and an updated preview of features for the latest draft of the upcoming DITA 2.0 standard, such as the new “combine” chunk action, the <titlealt> element, and the alternative titles domain.

DITA-OT releases follow semantic versioning guidelines. Version numbers use the major.minor.patch syntax, where major versions may include incompatible API changes, minor versions add functionality in a backwards-compatible manner and patch versions are maintenance releases that include backwards-compatible bug fixes.

Tip: Download the dita-ot-3.7.2.zip package from the project website at dita-ot.org/download.


DITA-OT is designed to run on Java version 8u101 or later and built and tested with the Open Java Development Kit (OpenJDK). Compatible Java distributions are available from multiple sources:

DITA-OT 3.7.2

DITA Open Toolkit 3.7.2 is a maintenance release that includes the following bug fixes.

  • In version 3.7.1, processing failed when link targets contained unexpected syntax. The URL processing and validation filters in the Java code have been updated to support mailto: links and additional URI schemes. #3730, #3912
  • The DITA 1.3 grammar files have been updated to allow the @outputclass attribute on the <change-historylist> element. #3905, #3911
  • Processing will now report an error when a project file param is used to define a parameter that should be set with a dedicated key instead. #3913, #3915
  • When parallel processing was enabled with parallel=true, some files were occasionally skipped with “folder could not be created” errors when different processes tried to create the same directory. Processing has been updated to handle concurrent directory creation. If the directory already exists, processing will now continue without errors. #3917, #3925
  • The jackson-databind library has been updated to the latest patch version to address a reported security vulnerability: CVE-2020-36518. #3923

For additional information on the issues resolved since the previous release, see the 3.7.2 milestone and changelog on GitHub.

DITA-OT 3.7.1 released March 23, 2022

DITA Open Toolkit 3.7.1 is a maintenance release that includes the following bug fixes.

  • In earlier versions, paths or filenames with typewriter apostrophes “'” or tilde “~” characters caused HTML builds to fail. Processing has been updated to ensure that these characters are handled correctly. #2844, #3880
  • On Windows, referencing images on another disk drive caused builds to fail. Resources with different drive letter paths are now handled correctly. #3635, #3885
  • As of version 3.6, XSL messages with serialized XML elements included only the text content. Processing has been revised to include the original XML element structure as in DITA-OT 3.5.4 and earlier releases. #3662, #3893
  • When publishing documents with nested topics or multiple glossary entries in the same file, generating @copy-to attributes with force-unique=true caused earlier versions of DITA-OT to create redundant copies of each file. The ForceUniqueFilter has been updated to properly handle references to separate topics within the same file. #3750, #3894
  • Earlier versions failed with errors when generating HTML5 output for chunked topics that include links between inner topics. Chunk processing has been updated to ensure that links between nested topics are generated correctly when the @chunk attribute is defined with to-content select-topic. #3846, #3881
  • The bundled Apache Xerces™ XML parser has been upgraded to version 2.12.2, which includes security updates to mitigate the vulnerability described in CVE-2022-23437 when handling specially crafted XML document payloads. #3857, #3860
  • Strict processing mode has been updated to stop processing when images are missing. Earlier versions reported errors in this case, but allowed processing to continue. #3858, #3871
  • In earlier versions, the PDF2 dita.xsl.xslfo.i18n-postprocess extension point did not work, because the extension point and the XSLT templates were defined in the same place. The templates have been moved to a new file to ensure that templates in custom plug-ins take precedence when using the extension point. #3861, #3862
  • The DITA-OT 3.7 distribution package contained a spurious fop.jar file with an empty manifest in the root folder. The unnecessary Java archive has been removed. #3864
  • Earlier versions generated incorrect links to nested topics when the parent topic contained a key reference and was re-used in different key scopes. Processing has been updated to preserve the fragment identifiers and ensure that links are generated correctly when topics are duplicated for each key scope. #3867, #3874
  • In earlier versions, the branch filtering routine did not handle nested subtopics correctly. Processing has been corrected to properly re-write topic references with ditavalrefs and inner topics. #3875, #3887
  • Messages in build logs now contain location information when available. #3877, #3884
    The following error messages now include the name of the file where the issue was found:
    • DOTJ041E
    • DOTJ045I
    • DOTJ046E
    • DOTJ052E
    • DOTJ060W
    • DOTJ074W
    • DOTJ077F
    • DOTX008E
    • DOTX065W
  • The German and French translations for Caution, Notice, and Remember note labels have been updated to align with the signal words defined in ANSI Z535. #3882, #3883
  • When publishing to HTML, builds would fail when image paths contained a ? query component or # fragment identifier. Processing has been updated to handle these references correctly. #3886, #3892
  • The “Notice” strings added to PDF2 in DITA-OT 1.7.1 have been moved to the base plugin to ensure that all signal words for safety levels are defined in the same location. #3888, #3899

For additional information on the issues resolved since the previous release, see the 3.7.1 milestone and changelog on GitHub.

DITA-OT 3.7 released January 17, 2022

DITA Open Toolkit Release 3.7 includes stable IDs in re-used content, a common variable format for generated text strings, and an updated preview of features for the latest draft of the upcoming DITA 2.0 standard, such as the new “combine” chunk action, the <titlealt> element, and the alternative titles domain.

Common format for generated text

Prior to DITA-OT 3.7, there were two different XML structures for adding or modifying generated text (gentext). The base plug-in org.dita.base and any custom overrides defined via the dita.strings.xsl extension point used a root element <strings>, with individual strings in <str> elements with @name attributes. This format was previously used for HTML, and all other output formats except PDF.

Figure 1. Base strings file structure prior to DITA-OT 3.7
<?xml version="1.0" encoding="utf-8"?>
<strings xml:lang="en-US">
  <str name="String1">English generated text</str>

The PDF plug-in org.dita.pdf2 used a root element <vars> with an XML namespace, and strings in <variable> elements with @id attributes.

Figure 2. PDF2 strings file structure prior to DITA-OT 3.7
<?xml version="1.0" encoding="UTF-8"?>
<vars xmlns="http://www.idiominc.com/opentopic/vars">
  <variable id="String1">English generated text</variable>

Starting with DITA-OT 3.7, these structures have been deprecated and replaced with a new unified format. All files now use <variables> as the root element, with the <variable> elements previously used in PDF strings. The new format supports the XSL parameters used by the earlier PDF strings format to pass dynamic information such as chapter numbers or figure titles.

Figure 3. New common variable format as of DITA-OT 3.7
<?xml version="1.0" encoding="UTF-8"?>
  <variable id="String1">English generated text</variable>

The old formats are still supported, but plug-in developers should update any generated text files to reflect the new structure, as support for the old formats may be removed in a future release. #3817

Updated DITA 2.0 preview

In addition to the DITA 2.0 preview support provided in DITA-OT 3.5 and 3.6, this release adds support for the DITA 2.0 “combine” chunk action, and updated processing for the latest DRAFT versions of the DITA 2.0 DTD and RELAX NG grammar files from OASIS (as of January 2022). #3674, #3760, #3809, #3833, #3847

  • The new “combine” chunk action can be used to merge content into new output documents.

    When the @chunk attribute is set to combine on a map, branch, or map reference, all source DITA documents grouped by that reference will be combined into a single document in the output.

    (Support for the DITA 2.0 “split” chunk action has not yet been implemented.)

    Note: The new chunk action is only applied if the root map has a DITA 2.0 doctype, such as:

    <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA 2.0 Map//EN" "map.dtd">

    If the root map uses an unversioned (or 1.x) doctype, DITA 1.3 processing will be applied, and 2.0 chunk actions will be ignored. With a 2.0 root map, any 1.3 chunk actions are ignored.

  • The new <keytext> element can be used to define variable text referenced by @keyref. Although the DITA 2.0 grammar files in this release support the use of <keytext> in authored files, DITA-OT 3.7 does not yet have processing support for the element.
  • The new alternative titles domain and <titlealt> element (separate from the <titlealts> element in DITA 1.3) may be used when you need to use an alternate title, such as for a navigation title, search title, link title, subtitle, or title hint.
  • The new @appid-role attribute is available on <resourceid>. The default is context-sensitive-help.
  • The @keyref attribute was added to all elements in the highlighting domain and the new emphasis domain.
  • The @href, @format, and @scope attributes are now used consistently for linking elements.
  • Several obsolete elements and attributes have been removed from DITA 2.0, including:
    • <anchor>
    • <anchorref>
    • <data-about>
    • <hasInstance>
    • <hasKind>
    • <hasNarrower>
    • <hasPart>
    • <hasRelated>
    • <longquoteref>
    • <relatedSubjects>
    • <sectiondiv>
    • <subjectRel>
    • <subjectRelHeader>
    • <subjectRelTable>
    • <subjectRole>
    • @anchorref from <map>
    • @copy-to
    • @href, @format, @type, @scope, @reftitle from <lq> (@keyref remains)
    • @locktitle
    • @longdescref
    • @mapkeyref
    • @print
    • @query
    • @specentry from <stentry>
    • @spectitle

DITA documents that reference the draft grammar files can be parsed, and where features overlap with DITA 1.3, those features will work as expected.

Note: Other new or revised features proposed for DITA 2.0 are not yet supported. Additional features will be implemented in future versions of DITA-OT as the specification evolves.

Enhancements and changes

DITA Open Toolkit Release 3.7 includes the following enhancements and changes to existing features:

  • The Dockerfile has been updated to better support the official dita-ot-action that was introduced in 3.6.1 to publish documentation via GitHub Actions whenever your source files are changed. The Dockerfile adds the SHELL command and installs the locales and tzdata packages as part of the base image, so custom actions can be simplified to a series of scripting hooks. #3665
  • In earlier versions, IDs defined on elements in reusable components were not preserved when the parent element was included in other topics via content reference. In this case, element IDs were always randomized to prevent duplicate IDs, but this made it difficult to cross-reference reused content. The conref preprocessing module has been updated to retain the original IDs whenever possible, and only generate a randomized ID if the original would not be unique in the new context. This ensures that content references produce stable anchors in HTML and named destinations in PDF output. #3736, #3739
  • Additional support for Ant <style> was added to make custom <pipeline> configurations more consistent with XSLT tasks in Ant. A stylesheet can be passed as an Ant resource, providing support for classpath-based plug-in resources. #3780
  • The mappull processing step has changed how related links are generated with args.rellinks. Starting in 3.7, noparent will not generate any ancestor links and nofamily will not generate sibling, cousin, ancestor, or descendant links. Prior to 3.7, args.rellinks=all did not actually include all links. Now it will. As in previous versions, the default value for PDF output is nofamily, and other output formats include all link roles except ancestor links. #3792, #3850
  • Mapref processing was improved to remove any duplicate @keyscope values. Prior to 3.7 it was possible that <mapref> and <map> would contribute the same @keyscope value when the value was defined on both. #3796
  • A commonattributes mode was added to the HTML5, PDF, and XHTML plug-ins to allow for easier extension. This is a backwards compatible change, however, existing plug-ins should be changed to use the new commonattributes mode. #3806
    Figure 4. Named template prior to version 3.7
    <xsl:template name="commonattributes">
      <!-- whole copy of commonattributes named template with customizations -->
    Figure 5. Template mode as of version 3.7
    <xsl:template match="@* | node()" mode="commonattributes">
      <xsl:param name="default-output-class" as="xs:string*"/>
        <xsl:with-param name="default-output-class" select="$default-output-class"/>
      <!-- customizations -->
  • The copy-to preprocessing module has been updated to preserve fragment-only links. This ensures that any local anchors do not change when original topic resources are copied to new resources defined by the @copy-to attribute. #3811, #3832

  • HTML5
    • The order of elements in the <head> element of the HTML template files was changed to facilitate overrides. The common CSS stylesheets and any custom CSS files specified via args.css now come after the contents of the custom header file specified via args.hdf. This change better supports use cases in which the custom header file is used to insert references to external CSS stylesheets for frameworks like Bootstrap. In previous versions of DITA-OT, framework styles took precedence over any equivalent rules in the user’s custom stylesheet. This change allows rules in custom CSS files specified via args.css to override any of the framework styles as necessary. #3770
    • The legacy gen-user templates that were originally used to add content to the <head> element have been deprecated and will be removed in a future release. For each of these templates, parameter-based customizations are available that can be used to specify files that contain content that extends the default processing. #3835, #3849
      • gen-user-head → use args.hdf instead
      • gen-user-header → use args.hdr
      • gen-user-footer → use args.ftr
      • gen-user-scripts → use args.hdf
      • gen-user-styles → use args.css
    • Support for the legacy media format Adobe Flash has been removed. All major browser vendors block Flash Player in recent versions, making it difficult to view Shockwave Flash content. #3791
    • The HTML5 stylesheets were updated to use XSL modes instead of named templates. #3794
      This is a backwards compatible change, however, existing plug-ins should be changed to use modes instead of named templates for:
      • copyright
      • gen-endnotes
      • generateDefaultMeta
      • generateCssLinks
      • generateChapterTitle
      • processHDF
      • generateBreadcrumbs
      • processHDR
      • processFTR
      • generateCharset
  • PDF
    • The new @note__image attribute set was added to combine attributes for images or icons for notes. #3529 #3660
    • Japanese font mappings have been updated to ensure characters are rendered correctly. #3768, #3769
      • The logical font Sans now prefers MS-Gothic, Hiragino Kaku Gothic Pro, HiraKakuProN-W3, or YuGothic over Arial Unicode MS.
      • For Serif text, MS-Mincho, Hiragino Mincho Pro, HiraMinProN-W3, or YuMincho are preferred to Arial Unicode MS.
      • For Monospaced text, MS-Gothic, Hiragino Kaku Gothic Pro, HiraKakuProN-W3, YuGothic, or Arial Unicode MS are used.
    • The source code for the renderer-specific PDF plug-ins for Antenna House Formatter (AXF) and RenderX XEP have been extracted to dedicated code repositories. The renderer-specific plug-ins are still distributed with DITA-OT. Only the source code location changed, allowing for easier maintenance. #3807, #3813
      This allows the plug-ins to be updated separately by commercial software vendors or open source contributors independent of the DITA-OT release cycle:
  • Several bundled dependencies have been upgraded to new versions:
  • Up until DITA-OT 2.4, the log4j logging library was bundled as a dependency of the Apache™ Formatting Objects Processor (FOP). DITA-OT 2.4 upgraded FOP to version 2.1, and removed the log4j library, but left the corresponding configuration files behind. The obsolete log4j.properties files have now been removed from the distribution package. #3841


DITA Open Toolkit Release 3.7 provides fixes for the following bugs:

  • In PDF output generated with previous versions, “Warning” note labels used the same attribute set as “Danger” note labels. Processing has been corrected to apply the dedicated attribute set defined for warning note labels. Both attribute sets are empty by default, but this change makes it easier for custom plug-ins to define separate styling for danger and warning notes. #3709
  • HTML5 output generated by earlier versions defined the character set twice in the <head> element, which certain HTML validation services reported as an error. The legacy <meta> element that specified the content type with an @http-equiv attribute has been removed in favor of the simpler version, which defines only the character set: <meta charset="UTF-8">. #3715, #3738
  • Key references were not properly expanded within content references when using key scopes. Processing has been updated to create unique topics for all resources, including resource-only topics. #3733, #3775
  • The command line interface now respects the convention to disable colored output when either the TERM=dumb or NO_COLOR environment variables are set, or the --no-color option is passed to the dita command. #3741
  • The German localization of the PDF Preface header strings included the page numbers twice, and the prodname parameter was missing. The default German strings have been aligned to include the product name and page numbers in the same pattern as other languages. #3742
  • Column and row separators defined via the <tgroup> element were ignored. HTML processing has been corrected to ensure separators are applied as expected in HTML5 and XHTML table groups. #3751, #3752
  • The PDF2 internationalization configuration for the service mark character used an incorrect decimal code &#2120;, which corresponds to the U+0848 MANDAIC LETTER ATT character: ࡈ. The language files have been updated to use the correct hexadecimal code &#x2120; for the U+2120 SERVICE MARK character: ℠. #3754
  • When plug-ins were installed on Windows systems, the integration process wrote Windows-style backslash “\” characters as path separators to the generated properties files, which caused errors if the same DITA-OT installation was used on other operating systems. All resources generated by the integrator now use UNIX-style slashes “/” as path separators, which work on Linux, macOS, and Windows. This ensures DITA-OT installations remain portable for use in continuous integration systems and other cross-platform publishing scenarios. #3755, #3759
  • Project files that included empty values in <param> elements failed with errors. Processing has been updated to allow processing to continue. #3761, #3824
  • In PDF output, figure descriptions were rendered before the image and title. Processing has been updated to correct the order of elements within figures. The image now appears first, followed by title and description. #3765, #3766
  • When processing simple tables such as parameter tables with no explicit header elements, earlier versions failed to assign IDs to generated elements. IDs are now generated correctly in these cases. #3778
  • XHTML processing has been refined to correct the order of contents within <object> elements. Any <desc> or <longdesc> content is now generated after any <param> element to ensure the resulting XHTML files pass EPUBCheck validation. #3779
  • HTML output generated from SVG files that specified height or width values in centimeters or inches were not scaled properly. Length values are now converted to pixels to ensure images are scaled correctly. #3785, #3786
  • When publishing documents with peer map references, spurious errors were reported for missing files, link text, and navigation titles when the peer maps were not available at processing time. Processing has been updated to relax these requirements for peer maps, and allow processing to complete without errors. #3790
  • Table of contents navigation in HTML5 output used a <nav> element with the ARIA @role attribute set to toc. Certain accessibility tools flagged this as an error. The invalid role has been replaced with the navigation landmark role. A new toc class allows custom CSS styles to target the ToC navigation. CSS rules that use the nav[role='toc'] selector can be simplified to nav.toc. #3800, #3801
  • A 17-year-old bug in the content reference implementation has been resolved. When the original conref code was updated to XSLT 2.0 years ago, the syntax was not adjusted to account for the differences between XSLT 1.0 and 2.0, which caused errors in the selection of the first topic in a document. #3842
  • DITA 1.3 grammar files have been updated to include hotfixes from the latest OASIS errata branch, which resolve issues with the available attributes on <change-historylist> and <colspec> elements. #3843


DITA Open Toolkit Release 3.7 includes code contributions by the following people:

  1. Jarno Elovirta
  2. Roger Sheen
  3. Radu Coravu
  4. Eric Sirois
  5. Robert D Anderson
  6. Eliot Kimber
  7. Chris Papademetrious
  8. Julien Lacour
  9. Toshihiko Makita
  10. Dmitriy Krasilnikov
  11. David Bertalan
  12. Jake Bourne
  13. Jason Fox
  14. Joe D. Williams

For the complete list of changes since the previous release, see the changelog on GitHub.

Documentation updates

The documentation for DITA Open Toolkit Release 3.7 provides corrections and improvements to existing topics, along with new information in the following topics:

For additional information on documentation issues resolved in DITA Open Toolkit Release 3.7, see the 3.7 milestone in the documentation repository.

DITA Open Toolkit Release 3.7 includes documentation contributions by the following people:

  1. Roger Sheen
  2. Jarno Elovirta
  3. Lief Erickson
  4. Jason Fox
  5. Nicolas Delobel
  6. Stefan Eike

For the complete list of documentation changes since the previous release, see the changelog.