Migrating to release 4.2

DITA-OT 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.

Note:
This topic provides a summary of changes in DITA-OT 4.2 that may require modifications to custom stylesheets or plug-ins. For more information on changes in this release, see the DITA-OT 4.2 Release Notes.

Common CSS changes

DITA-OT 4.2 includes several changes to the cascading style sheets generated by the HTML5 plug-in.

  • 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
  • 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
  • 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
Attention:
In publishing environments that do not use the default CSS files — or those that include HTML generated by older versions of DITA-OT — these styles may need to be implemented in custom stylesheets.

Upgrade stylesheets to XSLT3

DITA-OT 4.2 updates XSLT stylesheet headers 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. This approach has been chosen to help identify any external or third-party incompatibilities that might result from switching to XSLT3.

Attention:
The next major version of DITA-OT will upgrade template content to use XSLT3 syntax.

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.

Change any occurrences of <xsl:stylesheet version="1.0"> or <xsl:stylesheet version="2.0"> in custom plug-in stylesheets to at least <xsl:stylesheet version="3.0">.

Map-first pre-processing

DITA-OT provides a map-first pre-processing option as an alternative to the default preprocess operation. The method, which was introduced in DITA-OT 2.5 as an experimental feature, has since been improved and is ready for use in production scenarios. Map-first pre-processing provides the same functionality as the default preprocess, but takes a different approach.

The internal extension points that run before or after individual steps in the original preprocess pipeline (preprocess.*.pre/preprocess.*.post) are not available in the newer map-first pre-processing pipeline (preprocess2), which is used in the PDF and HTML Help transformations as of DITA-OT 3.0, and in HTML5 and Normalized DITA output as of DITA-OT 4.2.

Tip:
See Map-first pre-processing for information on how to use (or test) map-first pre-processing, or revert to the legacy preprocess target.