DITA Open Toolkit 3.7 Release Notes

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

• In earlier versions, links to non-DITA resources were broken in branch filtering scenarios that used the <dvrResourcePrefix> or <dvrResourceSuffix> elements to adjust the names of filtered topic files. Processing has been corrected to only rename DITA resources, and preserve the original names of non-DITA resources like images or other assets. #2704, #3947
• The image metadata processing failed to determine the height and width of images referenced via keyrefs. The @format attribute value is now set to image in the temporary .job.xml file, so the image dimensions can be read from the file metadata. #3353, #3963
• In earlier versions, builds failed with a NullPointerException when projects contained references with absolute paths pointing outside the folder where the DITA map is located. A new guard has been added to handle these cases more gracefully. #3366, #3977
• In DITA-OT 3.5.4 and later, builds failed with a NullPointerException when parsing specialized topics containing only table rows or cells. The table normalization filter has been updated to process these cases correctly. #3597, #3962
• When passing DITA maps as --resource files with absolute paths on Windows, the temporary files folder path was added to the map path, resulting in invalid references. Processing has been updated to properly compute the file path for map resources with absolute paths. #3724, #3964
• DITA-OT 3.6 always used the bundled open-source Saxon Home Edition (HE), even when a license for Saxon Professional Edition (PE) or Enterprise Edition (EE) was available in the DITA-OT classpath. The configuration has been updated to allow DITA-OT to use a licensed Saxon XSLT processor if present. #3727, #3949
• 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, #3945
• On Windows, publishing speed was slower when running DITA-OT with recent Java versions, because the file canonicalization cache is no longer enabled by default in Java 12 and newer (see JDK-8207005). The Java commands in the dita.bat and ant.bat wrapper scripts have been updated to re-enable caching. #3932, #3933
• On Windows, DITA-OT 3.6 failed to build output when input file paths contained non-ASCII characters. The encoding of the .job.xml file in the temporary directory has been explicitly set to UTF-8 to ensure that builds complete regardless of the operating system locale and input file path encoding. #3934, #3943
• In earlier versions, builds failed with a NullPointerException when custom plug-ins referenced missing stylesheets. A new guard has been added to handle these cases more gracefully. #3959, #3960
• When writing messages to the console in DITA-OT 3.6, <xsl:message> references to an XML element recursively printed its descendants. The logging code has been updated to properly serialize the nodes in XSL messages. #3969, #3978
• The DOTJ085E error message has been aligned for consistency with other messages. #3972
• In DITA-OT 3.7, content references to topic elements were not resolved when publishing to HTML. Processing has been corrected to ensure that topic conrefs are handled correctly. #3976, #3979
• In earlier verions, builds failed with a NullPointerException when processing maps that contained elements without @class attributes, such as inside <foreign> elements. Processing has been updated to handle these situations correctly. #3980, #3981
• In earlier versions, builds would fail with XSLT errors when named templates returned an empty sequence. Processing has been relaxed to allow processing to continue under these circumstances. #3991, #3992
• The bundled Jackson data format dependency was updated to resolve a security vulnerability in the SnakeYAML library, which has been updated to version 1.31. #3999 #4000

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

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 2.13.2.2 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 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
• 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 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

<?xml version="1.0" encoding="utf-8"?>
<strings xml:lang="en-US">
  <str name="String1">English generated text</str>
</strings>

<?xml version="1.0" encoding="UTF-8"?>
<vars xmlns="http://www.idiominc.com/opentopic/vars">
  <variable id="String1">English generated text</variable>
</vars>

<?xml version="1.0" encoding="UTF-8"?>
<variables>
  <variable id="String1">English generated text</variable>
</variables>

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.

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

  <xsl:template name="commonattributes">
    <!-- whole copy of commonattributes named template with customizations -->
  </xsl:template>

  <xsl:template match="@* | node()" mode="commonattributes">
    <xsl:param name="default-output-class" as="xs:string*"/>
    <xsl:next-match>
      <xsl:with-param name="default-output-class" select="$default-output-class"/>
    </xsl:next-match>
    <!-- customizations -->
  </xsl:template>

• 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:

    • org.dita.pdf2.axf
    • org.dita.pdf2.xep
• Several bundled dependencies have been upgraded to new versions:
  • Ant 1.10.12 #3821
  • FOP 2.6 #3774
  • Gradle 7.2 #3803
  • ICU4J 70.1 #3821
  • Jackson 2.13.0 #3821
  • JUnit 4.13.2 #3821
  • Logback 1.2.8 #3821, #3837, #3838
  • RenderX XEP 3.6.3 #3813
  • Saxon 10.6 #3485, #3805,
  • SLF4J 1.7.32 #3821
  • Xerces 2.12.1 #3821
• 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

Bugs

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 ࡈ, which corresponds to the U+0848 MANDAIC LETTER ATT character: ࡈ. The language files have been updated to use the correct hexadecimal code ℠ 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

Contributors

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:

• Migrating to release 3.7
• DITA 2.0 preview support
• Customizing generated text
• Installing DITA-OT via Homebrew

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.