DITA Open Toolkit 4.3 Release Notes

DITA Open Toolkit Release 4.3 includes new init and validate subcommands that can be used to set up projects from a template and check files for errors before publishing. You can now publish multiple formats on the command line at once, add raw DITA to Markdown files, and publish bookmaps with PDF themes.

Preview Init subcommand

The new init subcommand initializes a project with files from a template. #4509, #4523

The initial implementation is a preview feature designed to illustrate how project templates work. You can use templates as a starting point for new publications with required metadata, media assets, or custom stylesheets, or provide examples of your organization’s preferred markup.

• For a list of available templates, run dita init --list
• To add files from a template to the current directory, run dita init template

The folder hierarchy in the template will be copied to the current working directory by default. To write the files to a different location, add the --output option and specify the desired path. The directory will be created if it doesn’t exist. If any of the template files are already present, an error will appear.

Validate subcommand

A new validate subcommand can be used to check input files for errors before publishing. #4397, #4400

This command runs the pre-processing routines in strict mode and reports any errors or warnings. This is ideal for continuous integration scenarios, as it allows you to quickly check contributions for errors without building output.

A new depend.validate extension point defines an Ant target to run with the dita validate subcommand after pre-processing, so you can extend the default validation mechanisms with your own checks.

Multiple output formats from CLI

You can now publish multiple formats at once from a single dita command sequence. #4486

dita -i sample.ditamap -f html5 -f pdf

dita --input=sample.ditamap --format=html5
dita --input=sample.ditamap --format=pdf

This can be used as a simple alternative to a DITA-OT project file that defines multiple deliverables.

Lightweight DITA and Markdown updates

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

• Language identifiers in fenced code blocks can now be processed with an optional prefix to enable syntax highlighting in environments that require different keywords. For example, if Markdown files contain code blocks with JavaScript code, they may start with ```js to display the code block with syntax highlighting on GitHub. The plug-in can now add a prefix like language- to the DITA @outputclass value, included in HTML5 as class="language-js" for HTML5-compliant syntax highlighting with libraries like Prism. #228
• Admonition types are no longer case-sensitive, so both !!! note and !!! Note will be rendered as DITA <note> elements, regardless of the capitalization of the @type keyword. #229
• If you need to include DITA content that has no equivalent markup in Markdown DITA syntax, you can now use raw DITA XML directly in Markdown files. You can use this approach to include things like <xmlelement> or <hazardstatement>, which would otherwise be impossible to express in Markdown. #217
• Earlier versions would crash when processing Markdown files that did not begin with a heading. These files are now converted to valid DITA with an empty <title> element, and an error message appears in the log to aid in debugging. #223

Bookmap support in PDF themes

Table of contents (ToC) styles have moved to the root style key. ToC styling has also been extended for better bookmap support, so you can now specify styles for each level with dedicated keys such as style-toc-part, style-toc-chapter, etc.

Parts and chapters now also support their own local contents listings, which you can enable by setting the corresponding layout key, for example chapter-layout: MINITOC. You can then define styling for each level via keys like style-part-toc-chapter, or style-chapter-toc-1.

A new default theme provides basic styling such as font settings, indentation, and title numbering for a range of commonly used elements. This theme is not intended for publishing as is, but can serve as a foundation for custom themes, and reduce the number of elements you need to style yourself. To use the default theme as the baseline for your own custom theme, add extends: default to your theme file. #112, #114

Preview DITA 2.0 updates

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

• HTML5 processing now supports the @height and @width attributes on the DITA 2.0 <video> element to ensure that videos are scaled correctly. #4570
• HTML5 and PDF processing has been updated to support the new DITA 2.0 emphasis domain elements: <em> for emphasis and <strong> for strong emphasis. #4571

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 4.3 includes the following enhancements and changes to existing features:

• To reduce page load times, HTML5 output now uses lazy loading for external images. #4001, #4005 Local and peer image resources are loaded eagerly as in previous versions, but images defined with @scope="external" are now output with the @loading attribute set to "lazy" by default. A new set-image-loading template mode allows custom plug-ins to override the default behavior if necessary.
• The Java code for the map-first pre-processing routines now includes Javadoc comments to document how the various stages are implemented. This documentation is not published separately, but is available to developers who need to extend map processing or topic processing in custom plug-ins. Many development environments extract and display the Javadoc information while viewing the source code. #4404
• The Java code has been modernized to use more standard library features and reduce dependencies on external libraries, and restructured with automatic refactoring tools to make it easier to read and maintain. #4407, #4441, #4442, #4444, #4498
• A new DOTJ088E error message makes it easier to identify XML parsing exceptions in the log. #4408 The error appears when the input is in some way invalid but can still be parsed. The message content begins with “XML parsing error:” and provides additional context from the parser in the <reason>. As with other error messages, custom plug-ins may override the message content or severity.
• DITA-OT uses the Xerces SecurityManager to protect against the so-called “billion laughs attack”, an entity expansion technique that can cause XML parsers to run out of memory and overload the CPU when parsing maliciously crafted files. DITA-OT will now stop parsing and report an error when processing any files that exceed the entity limit imposed by the security manager library. #4542, #4556
• Several bundled dependencies have been upgraded to the latest versions:
  • Apache™ FOP 2.10 (including the Apache XML Graphics and Batik libraries) #4519, #4565

Bug fixes

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

• In earlier versions, installing a plug-in from a path that contained the at-sign character “@” failed with an InvalidArgumentException. The implementation has been updated to ensure these paths are handled correctly. #4354, #4558
• Earlier versions issued the DOTJ037W twice when running transformations with the validate parameter set to false. This warning has been moved from the Java code to Ant, which ensures that it only appears once for each transformation. #4377, #4396

Contributors

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

1. Jarno Elovirta
2. Julien Lacour
3. Robert D Anderson
4. Roger Sheen
5. Andrei Pomacu
6. Chris Papademetrious
7. Jason Fox

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.3 has been reorganized to simplify the navigation in HTML versions and reduce the number of parts in PDF output. All of the content from previous versions is still available, though arranged slightly differently. The diagram in Figure 1 shows the previous structure on the left, and the new locations on the right.

dita init samples path/to/dita-ot-dir/docsrc/samples

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

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

1. Roger Sheen
2. Jarno Elovirta
3. Lief Erickson
4. Stefan Weil

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