DITA Open Toolkit 4.2 Release Notes

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

• DITA-OT 4.2.2 included a regression bug that caused the map-first pre-processing routine to fail with a NullPointerException when maps referred to topics that didn’t exist and other topics contained key references. Processing now proceeds and warns of missing files as in previous versions. #4449, #4454

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

• In earlier versions, the map-first pre-processing routine created extra HTML files in the output folder when branch filtering topic references that include fragments. Duplicate branches are now handled correctly and links are resolved as expected. #4380 #4427
• Earlier versions of map-first pre-processing would sometimes attempt to access topics that were excluded in DITAVAL files, which resulted in spurious errors. XLST transformations and SAX filter pipes are now skipped for any source files that don’t exist. #4383 #4435
• In earlier versions, passing a URL as an input file on the Windows command line resulted in an InvalidPathException error. URI input is now handled correctly on Windows. #4419 #4425
• In debug logging mode, DITA-OT 4.2 no longer passed exceptions to the CLI output. Logging has been corrected to ensure that errors from Ant tasks once again include the stack trace as expected. #4430 #4436
• When missing translations for the PDF “on page” variable were added in DITA-OT 4.2, the Montenegrin translation “na stranici” was accidentally copied to the Swedish language file. The Swedish translation has been updated to use “på sidan” as expected. #4431 #4433
• When project files contained input map names with URI-escaped characters like spaces, earlier versions of DITA-OT used the escape character sequences like %20 in the output file name. The map-first pre-processing routine has been updated to construct the output base file name using the unescaped equivalents. #4412 #4440

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

• When using the in-memory store, earlier versions of the map-first pre-processing pipeline failed to initialize the temporary directory. The directory is now created to ensure that files are processed correctly. #4401
• A NullPointerException that occured when using the in-memory store with map-first pre-processing has also been fixed. #4402
• In DITA-OT 4.2, the HTML5 transformation was updated to include map-level <keywords> metadata in the table-of-contents file index.html. However, this inadvertently also included variable definition keywords from nested topic references. Processing has been updated to only include top-level map keyword metadata. #4405, #4418
• The command-line interface in DITA-OT 4.2 prints colored messages in several additional cases, but these changes accidentally removed the logging level prefixes in terminal environments that don’t support color. These message prefixes now appear in all environments, regardless of color support. #4406 #4409
• DITA-OT 4.2 pruned logging level prefixes from messages by removing anything that appeared between square brackets ][ and ], but this also dropped custom prefixes. Logging has been updated to only remove prefixes that match the default level names like INFO or WARN. #4416

DITA Open Toolkit Release 4.2 uses map-first pre-processing for HTML5 output and includes a new local configuration file, better CLI messages with support for overrides, a new version of the Lightweight DITA plug-in with enhancements to Markdown processing, and updates for the latest DITA 2.0 draft standard.

Map-first HTML5

The HTML5 transformation has been updated to use the map-first pre-processing pipeline that was previously enabled for PDF and HTML Help in DITA-OT 3.0. For details, see Map-first pre-processing. #4225

New runtime configurations

New .ditaotrc configuration files can be used to store DITA-OT runtime configurations in multiple places.

DITA-OT now looks for this file in the current directory or any ancestor directory first, then in the user’s home directory, and finally in the root directory of the DITA-OT installation. These files are read in order and combined with the contents of the local.properties file in the toolkit directory. The first occurrence of a property takes precedence. This approach can be used to define multiple layers of configuration, so personal defaults that apply to multiple projects can be stored in the home folder, with local overrides in project folders. #4217, #4391

CLI message improvements

The log messages that appear in the command line interface have been revised to use more consistent language, better explain the cause, and how the issue can be resolved. #3973, #4287, #4376, #4387

The code that generates CLI error messages has been refactored to make it easier to override and extend messages. The generated messages file is now sorted by ID to make it easier to locate individual messages, and any duplicates are removed during the integration process. #4199

Log messages can now be partially overridden or completely replaced. Custom plug-ins can supply new messages via the dita.xsl.messages extension point as in previous versions, but now this same approach can also be used to override the contents or change the severity level of any of the default messages. #4362

• The only required information is the @id attribute, which is used to identify the message you are overriding.
• To change the message content, specify a new <reason> or <response>.
• To change the severity level, set a new value for the @type attribute (INFO, WARN, ERROR, FATAL, or DEBUG).
• You can omit @type, <reason> or <response>, in which case the previous declaration of the message will provide that value.

Lightweight DITA and Markdown updates

The org.lwdita plug-in has been updated to version 5.7, which includes a series of bug fixes and support for additional DITA constructs in Markdown output, including:

• list parsing performance improvement
• admonition blocks in list items
• HDITA note elements
• multimedia element types
• tight task lists
• footnotes
• block content in tables

The XDITA plug-in has been updated to version 0.3.2, which includes recent changes to the grammar files from OASIS (as of January 26, 2024). This version removes deprecated catalog entries, and resolves #4233. #4366

Updated DITA 2.0 preview

In addition to the DITA 2.0 preview support provided in DITA-OT 3.5 – 4.1, this release includes updated processing for the latest draft versions of the DITA 2.0 grammar files from OASIS (as of January 22, 2024). #4359

Enhancements and changes

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

• HTML5 processing for <note> elements now wraps the note body in a <div> element with the note__body class, allowing it to be styled separately from the note title. For backwards compatibility, the common CSS files have been updated to display the note body inline with the note title to avoid a new line break before the content division element. #3955
• Unreferenced XSLT variables in <xsl:template> blocks have been removed. #4093
• Earlier versions of DITA-OT preserved metadata in submaps, but dropped any <topicmeta> content defined within <mapref> elements. Submap metadata in <mapref> elements is now preserved in a temporary <mapref-topicmeta-container>, which is removed when pre-processing is complete. #4115
• Several pre-processing stylesheets have been extended with additional comments to better explain how processing works, and to mark cases where named templates can be replaced with template modes. #4151, #4176, #4209
• Subject scheme processing has been refactored to support multiple keys in a single @keys attribute on the <subjectdef> element. It now uses the S9API (Saxon’s preferred Java API for XSLT, XQuery, XPath, and XML Schema processing) instead of the Document Object Model (DOM). A new unit test has been added to verify changes in the subject scheme reader code, and the map-first pre-processing pipeline now supports additional subject scheme features. #4296, #4297, #4300, #4302, #4306
• The test coverage for the onlytopic.in.map parameter has been improved using unit tests instead of integration tests. #4310
• The tasks that run after the map-first pre-processing pipeline have been refactored to a dedicated preprocess2.post target to make it easier to add custom steps in between the built-in steps. #4313
• The plug-in integration code has been refactored to remove the redundant Ant layer from the install and uninstall processes. #4329
• For HTML-based output formats, a new dita2html:is-heading-level template mode allows plug-ins to declare their own elements that contribute to heading levels (h1 through h6). For example, a specialization of <bodydiv> could declare itself as a heading level and create its own HTML heading (by calling dita2html:section-heading with the defaulttitle parameter), and any <section> or <example> elements inside will adjust their heading levels accordingly. As part of this change, the parameter interface of the template for (section|example)/title elements has changed — the headLevel parameter is now an integer (1 through 6) instead of a string (h1 through h6). Existing custom code that uses this interface must be modified. #4330, #4368
• XSLT stylesheet headers have been updated from XSLT version 1.0 and 2.0 to version 3.0 to make way for the use of XSLT3 features in future toolkit versions. This is a backwards-compatible change, as there are no changes to the actual code; only the stylesheet headers have been modified for now. To ensure plug-ins remain compatible with future versions of DITA-OT and Saxon-HE, the DITA Open Toolkit project recommends upgrading all stylesheets to XSLT 3.0. #4338
• The CLI no longer uses colors when it’s connected to a pipe or output is redirected to a file. #4393
• Legacy table presentation classes that were deprecated in DITA-OT 2.3 have now been removed from the common CSS files. #4364
  • cellrowborder
  • row-nocellborder
  • cell-norowborder
  • nocellnorowborder
  • firstcol

• The following bundled plug-ins have been upgraded to the latest versions:

  • The Normalized DITA plug-in version 2.0 now uses map-first pre-processing for normalization. #4382
  • The Lightweight DITA plug-in version 5.7 includes the Lightweight DITA and Markdown updates described above. #4388
  • The PDF Theme plug-in version 0.7.2 applies the body line-height attribute to block elements and provides basic styling support for table entries and cover page subtitles or alternative titles. #4389

• Several bundled dependencies have been upgraded to the latest versions:

  • The bundled Apache™ FOP version has been updated to 2.9. #4272, #4288

    (For details on recent changes, see the Apache FOP 2.9 Release Notes.)

  • The logback libraries have been updated to 1.4.14 to resolve a serialization vulnerability in the logback receiver component reported as CVE-2023-6378. #4346 #4361
• Several Java dependencies have been upgraded to include the latest utility versions and fix security issues in bundled libraries. #4390
  • Ant 1.10.14
  • ICU4J 74.2
  • Jackson 2.16.1
  • Jing 20220510
  • JUnit 5.10.2
  • Saxon 12.4
  • SLF4J 2.0.12
  • XML Resolver 5.2.3

Bug fixes

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

• For cross-references to a topic, the target topic’s short description is processed to create a link description. When that <shortdesc> element contained another cross-reference to a file in a different directory, the second link’s description would contain *** instead of the expected link text. Processing has been corrected to ensure that link text is generated as expected. #4244, #4266
• The DITA standard defines a @compact attribute for list elements. Previously, this attribute was published to XHTML and HTML5 as an HTML @compact attribute. However, the @compact attribute was deprecated in HTML4 (over 20 years ago). Now, DITA @compact attributes are published to XHTML and HTML5 as @class="compact" keywords. New rules with the class selectors have been added to the default CSS files. Rules with the legacy @compact list attributes have been marked as deprecated with Sass @warn rules and will be removed from a future version of DITA-OT. Any custom CSS rules referencing the @compact attribute should be updated. #4298, #4303, #4358
• In earlier versions, builds failed with a NullPointerException under certain conditions in map-first pre-processing. The issues have been resolved and integration tests have been updated to catch related errors in the future. #4305
• The map-first pre-processing pipeline in earlier versions treated @href attribute values set to -dita-use-conref-target as resources during the initial parse and rewrote the attribute values. Processing has been corrected to pass these values through unchanged. #4307
• Earlier versions of the map-first pre-processing pipeline failed to update the usr.input.file.list with temporary file names. The list is now generated correctly. #4311
• Missing translations for the PDF “on page” variable have been added to the Bosnian, Finnish, Montenegrin, Romanian, Russian, Swedish, and Simplified Chinese PDF localizations. #4315, #4320
• The classpaths for the install and uninstall subcommands have been separated to allow plug-ins to be removed even if plug-in JAR files have been opened. Earlier versions would fail to delete plug-ins in this case. #4328
• In earlier versions, the HTML5 transformation published metadata to <meta> elements in topic-level HTML files, but not in the table of contents file index.html. Now, it also adds metadata from the root map’s <topicmeta> to the ToC file. #4351, #4352
• Earlier versions did not support non-DITA map references. Processing has been extended to allow <mapref> elements to refer to non-DITA maps, such as Markdown maps that are parsed as DITA. #4353
• The docsrc folder in the DITA-OT 4.1.1 and 4.1.2 release packages contained several unnecessary files. The build scripts have been updated to ensure that these files are no longer included. #4357
• In cases where key definitions were branch-filtered with <dvrResourcePrefix>, earlier versions of the map-first pre-processing pipeline failed to apply the resource prefix to the target file names. Key resolution code has been corrected to use the @filter-copy-to attribute instead of the @href attribute. Once applied, this temporary pre-processing attribute is removed during the map clean step. #4369, #4381
• The missing --deliverable option has been added to the CLI help output. This option can be used to publish a single deliverable in the specified project. #4386

Contributors

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

1. Jarno Elovirta
2. Roger Sheen
3. Chris Papademetrious
4. Robert D Anderson
5. Radu Coravu
6. Andrei Pomacu

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

Documentation updates

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

• DITA-OT error messages
• Migrating to release 4.2
• The .ditaotrc configuration file

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

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

1. Roger Sheen
2. Jarno Elovirta
3. Edit Koselak
4. Stefan Jung

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