DITA Open Toolkit 4.0 Release Notes

DITA-OT 4.0 requires Java 17 and includes a new plug-in for easier PDF customization, project file improvements, updates to LwDITA processing, and support for the split chunking feature in the latest drafts of the upcoming DITA 2.0 standard.

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-4.0.zip package from the project website at dita-ot.org/download.

Requirements: Java 17

DITA-OT 4.0 is designed to run on Java version 17 or later and built and tested with the Open Java Development Kit (OpenJDK). Compatible Java distributions are available from multiple sources:
Note: The Java virtual machine is generally backwards compatible, so class files built with earlier versions should still run correctly with Java 17 and DITA-OT 4.0. If your DITA-OT installation contains plug-ins with custom Java code, you may need to recompile these with Java 17 — but in most cases, this step should not be necessary.

DITA-OT 4.0 released November 12, 2022

DITA Open Toolkit Release 4.0 includes a new plug-in for easier PDF customization, project file improvements, updates to LwDITA processing, and support for the split chunking feature in the latest drafts of the upcoming DITA 2.0 standard.

New PDF theme plug-in

DITA-OT 4.0 includes the com.elovirta.pdf plug-in, which extends the default PDF2 plug-in with a new theme parameter. The --theme option takes a path to a theme file and changes the styling of the PDF output without requiring changes to XSLT stylesheets.

Themes can be used to adjust basic settings like cover page images, page sizes, numbering, font properties, background colors and borders, spacing, and running content like page headers and footers.

To generate PDF output with a custom theme, pass the theme file to the dita command with the --theme option:

dita --project=samples/project-files/pdf.xml \
     --theme=path/to/custom-theme-file.yaml
Tip: For information on the available theming options and a sample YAML theme, see PDF themes.

Project file improvements

  • The re-usable <publication> element in DITA-OT project files can now be overridden with additional parameters (or modified parameter settings) by adding new <param> elements to the referencing element. #3682, #3907

    This allows common publications to be defined in one place, re-used in others, and overlaid with local variations when the common settings need to be adjusted in certain cases.

    <project xmlns="https://www.dita-ot.org/project">
      <publication transtype="html5" id="common-html5">
        <param name="nav-toc" value="partial"/>
      </publication>
      <deliverable>
        <context>
          <input href="root.ditamap"/>
        </context>
        <output href="./out"/>
        <publication idref="common-html5">
          <!-- Define publication-specific parameter settings -->
          <param name="nav-toc" value="full"/>
        </publication>
      </deliverable>
    </project>
  • The <publication> element in DITA-OT project files now supports nested <profile> elements. When both context and publication contain profiles, they are applied in order: publication profiles first, context profiles second. #3690, #3895

    This allows publications to define filter criteria that are applied to the content of the individual publication (in addition to those specified for the entire deliverable context).

    <project xmlns="https://www.dita-ot.org/project">
      <deliverable name="Name" id="site">
        <context name="Site" id="site">
          <input href="site.ditamap"/>
          <profile>
            <ditaval href="site.ditaval"/>
          </profile>
        </context>
        <output href="./site"/>
        <publication transtype="html5" id="sitePub" name="Site">
          <profile>
            <!-- Define publication-specific filters -->
            <ditaval href="site-html5.ditaval"/>
          </profile>
        </publication>
      </deliverable>
    </project>

Lightweight DITA and Markdown updates

The org.lwdita plug-in has been updated to version 3.3, which includes Markdown processing improvements.

  • DITA-OT 4.0 includes processing updates to reflect recent changes to the latest drafts of the LwDITA profile from OASIS
  • Add support for Markdown files without first-level headings
  • Better support for Python-Markdown Attribute Lists
  • Markdown input improvements:
    • Improve subscript and superscript support
    • Fix backslash escapes in code phrases (applies only to @format=markdown, as MDITA does not support code phrases)
    • Add support for table spanning
  • In previous releases, standard Markdown syntax could be used to indicate a span of code by wrapping it with backtick quotes (`). These constructs were converted to DITA <codeph> elements on import, and rendered as <code> elements in HTML output. This support has been removed from MDITA processing to align with LwDITA, which does not support code phrase markup.

Updated DITA 2.0 preview

In addition to the DITA 2.0 preview support provided in previous releases (3.5, 3.6, and 3.7), DITA-OT 4.0 includes updated processing support for the latest drafts of the DITA 2.0 DTD and RELAX NG grammar files from OASIS (as of November 7, 2022). #4040

  • The new “split” chunk action can be used to break content into new output documents. #3942

    When the @chunk attribute is set to split on a map, branch, or map reference, each topic from the referenced source document will be rendered as an individual document.

    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.

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.

Code references now default to UTF-8 encoding

The default character set for code references has been changed from the system default encoding to UTF-8.

This allows a wider range of characters to be used without needing to specify the @format attribute on the <coderef> element as described in character set definition or change the default encoding in the configuration.properties file. #4046
Note: If you have code references that require a different encoding, use either of these mechanisms to specify the character set explicitly.

Enhancements and changes

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

  • When publishing with project files, separate temporary folders are now created for each deliverable in the project. This facilitates debugging and troubleshooting, as it makes it easier to inspect the temporary files that have been created for each deliverable. #3757, #3898
  • The legacy attribute set reflection in PDF2 has been replaced with code that generates new attribute sets directly. This change is backwards-compatible as the old attribute set reflection code has been retained, but PDF2 now uses the new attribute set generation mechanism everywhere reflection was used. Custom plug-ins that still use reflection should be updated to the new approach, as the legacy code may be removed in a future version. #3827, #3829
  • Attribute generation routines in XSLT stylesheets have been refactored from the old XSLT 1.0 style <xsl:value-of select="…"> to the modern XSLT 2 notation: <xsl:attribute select="…"/>. #3830
  • Many Ant targets refer to skip properties that can be used to skip preprocessing steps. In earlier releases, these properties were not set or named consistently; these properties are now generated automatically with more consistent naming and behavior. #3851
  • When an included file uses a character set that is neither the system default nor matches the explicit character set definition in the include, reading the file may fail. A new DOTJ084E error message makes it easier to debug character set encoding issues like this in source files. #3891
  • Grammar caching and validation has been added for RELAX NG–based DITA topics and maps. Together these enhancements make publishing faster and more reliable for RNG-based content. #3926
  • Many XSLT files have been updated to use #current for the processing mode. This simplifies the code and makes it easier to read and maintain. #3974

Bug fixes

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

  • In earlier releases, unexpected or invalid markup in a plugin.xml file might throw errors, but the installation would still show as successful. This has been fixed, and plug-in installation will now fail when the integration process does not work. #2641, #3825
  • In earlier releases, the @frame="none" attribute on tables was not properly handled for PDF output. This issue has been fixed, and the table border is now handled correctly. #3303, #3852, #3854
  • In 3.7 and some earlier releases, including namespaced elements such as <m:math> or <svg:svg> in a topic that is chunked would result in build failures. The chunking process now handles these elements without errors. #3684
  • The FINALOUTPUTTYPE XSLT parameter has been removed from maplinkImpl.xsl and mappullImpl.xsl; this parameter is a legacy of very early code and has never been used by DITA-OT. #4018
  • In DITA-OT 3.7.4, publishing failed with an IllegalArgumentException when images were referenced with an HTTP URI scheme. Processing has been corrected to set the missing @scope attribute to external per DITA 1.3 specification: The scope attribute. #4032, #4039

Contributors

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

  1. Jarno Elovirta
  2. Radu Coravu
  3. Robert D Anderson
  4. Toshihiko Makita
  5. Eric Sirois
  6. Chris Papademetrious
  7. Julien Lacour
  8. Roger Sheen

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.0 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 4.0, see the 4.0 milestone in the documentation repository.

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

  1. Roger Sheen
  2. Jarno Elovirta

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