DITA Open Toolkit 3.6 Release Notes
DITA Open Toolkit 3.6.1 is a maintenance release that fixes issues
reported in DITA-OT 3.6, which includes performance enhancements such
as processing in parallel and in memory, support for PDF changebars with Apache™ FOP, and an updated preview of features for the latest draft of the upcoming DITA 2.0
standard, including the
<video> elements, and the
new emphasis domain.
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.
- You can download the Oracle JRE or JDK from oracle.com/technetwork/java under commercial license.
- OpenJDK is a free open-source implementation of Java available from adoptopenjdk.net.
- Free OpenJDK distributions are also available from other vendors, including Amazon Corretto, Azul Zulu, and Red Hat.
DITA Open Toolkit 3.6.1 is a maintenance release that includes the following bug fixes.
- In DITA-OT 3.6, builds failed with a NullPointerException when Ant targets in custom
<pipeline>elements were run without passing references to the new Ant project by setting the
@inheritRefsattribute on the
true. This case will no longer cause the build to fail, but custom plug-ins should still set targets to inherit references to ensure that processing runs as expected. #3656, #3657
jsasscompiler used in the HTML5 plug-in build process up to DITA-OT 3.6 relied on LibSass, which has been deprecated in favor of Dart Sass and caused errors when building on the 64-bit extension of the ARM architecture. The SCSS source files are now converted to CSS using the official Dart Sass compiler, which allows DITA-OT distribution builds to run on recent Macs and other ARM systems. #3659
- In DITA-OT 3.6, builds failed with a NullPointerException when an unset logger was called. A new guard has been added to handle these cases more gracefully. #3667, #3706
- The DOTX037W warning message that appears when source documents have no title has been updated to clarify references to the fallback text that will be used for the HTML page title. #3669, #3670
- DITA-OT 3.6 failed with an IllegalArgumentException when maps contained topic references to e-mail addresses or other peer resources that are not accessible at build time. Processing has been updated to properly handle non-file references. #3677, #3698
- In DITA-OT 3.6, branch filtering with nested subtopics failed with an IllegalArgumentException: URI has a fragment component. Processing has been updated to correctly transform references that contain anchors. #3680, #3696
- DITA-OT 3.6 in-memory processing calculated absolute paths incorrectly when merging maps. The merge map and topic parsers have been updated to properly compute absolute locations. #3687, #3699
- DITA-OT 3.6 introduced a regression that prevented PDF2 custom font mappings from resolving properly. The PDF pre-processor task has been updated with a delegating URI resolver to ensure that custom resources in PDF plug-ins are applied as expected. #3688, #3695
- Custom rules used to adjust the names and locations of output files in the map-first pre-processing routine were no longer applied in DITA-OT 3.6. Preprocessing has been updated to ensure that stylesheets specified via the result.rewrite-rule.xsl parameter are correctly applied. #3689, #3697
- In DITA-OT 3.6, a regression prevented multi-level key references from resolving properly. Processing has been updated to ensure that topic metadata is correctly copied between key definitions and key references that point to other keys. #3694, #3701
- The GitHub Packages Docker registry used to publish DITA-OT Docker images prior to version 3.6
has been superseded by the GitHub Container Registry. The new registry offers anonymous access to public
container images, so you can use it without a GitHub account. As of DITA-OT 3.6.1, the official image is
published to the new registry at ghcr.io.
If you’ve pulled from
docker.pkg.github.com/dita-ot/dita-ot/dita-ot:versionin the past, update your workflow to pull from
- The DITA-OT project now provides an official dita-ot-action that can be used to publish documentation via GitHub Actions whenever your source files are changed.
- The documentation for DITA Open Toolkit Release 3.6.1 provides corrections and improvements to existing topics, along with new information in the following topics:
DITA-OT 3.6 released December 19, 2020
DITA Open Toolkit Release 3.6 includes performance enhancements such
as processing in parallel and in memory, support for PDF changebars with Apache FOP, and an updated preview of features for the latest draft of the upcoming DITA 2.0
standard, including the
<video> elements, and the
new emphasis domain.
Preprocessing module code can now be run in parallel by setting the parallel parameter to true. The performance benefits this option provides depend heavily on the source file set, the DITA features used in the project, and the computer doing the processing, but under the right circumstances, you may see notable improvements when this option is enabled.
DITA-OT 3.6 introduces a new Store API with preview support for in-memory processing. The Cache Store can be activated by setting the store-type parameter to memory. In-memory processing provides performance advantages in I/O bound environments such as cloud computing platforms, where processing time depends primarily on how long it takes to read and write temporary files. For more information, see Store API – Processing in memory.
Additional performance improvements
DITA-OT 3.6 includes a series of related changes designed to improve the performance of DITA transformations.
A new --repeat option can be passed to the dita command to run the process a certain number of times. This option can be used by plug-in developers to measure performance. (Timings for the first transformation are often dominated by Java warm-up time.) #3616To run a conversion five times, for example, use --repeat=5. The duration of each execution will appear in the console when the final transformation is complete.
$ dita --input=docsrc/samples/sequence.ditamap --format=html5 --repeat=5 1 11281ms 2 4132ms 3 3690ms 4 4337ms 5 3634ms
- The DITA-OT Java code uses a new caching
DitaClass.getInstance(cls)factory method rather than generating
DitaClassinstances directly. This allows previously created instances to be re-used, which reduces the number of instances that need to be created. #3569
- The Java code for several preprocessing modules has been refactored to use concurrent sets or queues. This helps to speed up certain operations during preprocessing, allowing builds to complete faster. #3570
- The Java code now uses a
Jobobjects, which significantly improves UTF-8 encoding performance when writing the .job.xml file. #3583
PDF changebars with Apache FOP
For DITA-OT 3.4, the bundled Apache™ Formatting Objects Processor library was upgraded to version 2.4, which included support for changebars, but those features were not yet enabled in DITA-OT 3.4 pending further testing. DITA-OT 3.6 removes the FOP-specific overrides that disabled changebars in earlier versions, allowing the default PDF2 flagging routines to be applied when generating PDFs with FOP. For details, see Generating revision bars.
Plug-ins that implemented custom FOP flagging by overriding the org.dita.pdf2.fop/xsl/fo/flagging_fop.xsl stylesheet in prior versions will need to be updated, as this file is no longer available in DITA-OT 3.6. #3511, #3591
Updated DITA 2.0 preview
In addition to the DITA 2.0 preview support provided in DITA-OT 3.5, this release includes updated processing support for the latest DRAFT versions of the DITA 2.0 DTD and RELAX NG grammar files from OASIS (as of October 2020). #3586, #3601, #3617, #3652
- Where earlier DITA versions relied on the
<object>to embed media in DITA source files, DITA 2.0 provides new
<video>elements that correspond to their HTML5 equivalents.
- For HTML5 compatibility, the new emphasis domain adds support for the
<em>elements in addition to the existing
<i>elements in the highlighting domain.
- The troubleshooting domain has been updated with additional constructs that can be used to provide detailed diagnostic information.
- Several obsolete elements and attributes have been removed from DITA 2.0, including:
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.6 includes the following enhancements and changes to existing features:
@rotateattribute on table
<entry>elements is now respected when generating HTML5 output. The rotation is implemented by setting the CSS
vertical-rlto rotate the cell content. This property is rendered correctly in Mozilla Firefox, but unevenly supported by other browsers. The
rotateclass is passed to HTML5 output, so custom plug-ins can implement alternative presentation rules in CSS if necessary. #3448, #3541, #3651
- User-facing text for the dita command line interface has been extracted to a strings file to facilitate editing. The cli_en_US.properties is provided in the resources folder as a basis for customization and localization. #3495, #3523
- The new
Storeimplementation that supports in-memory processing includes an immutable document reader method that can be used to request a document that doesn't need to change during processing. This approach facilitates caching and helps to speed up processing. #3506, #3548
- In earlier versions, variations in reference capitalization could cause unexpected results when building output on case-sensitive file systems. DITA-OT now warns when file references use incorrect case. (For example, if maps reference Topic.dita, but the filename on disk is actually topic.dita.) In strict processing mode, this is considered a fatal error; in lax processing mode, the file reference is rewritten to use the same case as the file system. #3535
- The --filter option can now be passed to the dita multiple times in a single command-line invocation to apply conditions from several DITAVAL files at once. #3556
- The bundled Apache Formatting Objects Processor (FOP) has been upgraded to version 2.5, which includes security updates to various embedded libraries. #3558, #3630
- The deprecated
msgprefixXSL variable (“DOTX”) has been removed. This variable was originally deprecated in DITA-OT 2.3, but still defined in several stylesheets. Importing the common XSL module output-message.xsl no longer requires this variable to be defined. #3562
- The S9api message listener from the Saxon API is now used to forward log
messages to the
DITAOTLogger. This allows message levels and error codes to be passed from XSLT to Java code for improved debugging. #3564
- HTML5 output now includes additional metadata to indicate that the content was produced using
DITA Open Toolkit.
<meta name="generator" content="DITA-OT"/>
- Up to version 3.5, DITA-OT included the
Dublin Core Metadata Element Set in both XHTML and HTML5 output. For DITA-OT 3.6, this capability was extracted
to a separate plugin, and Dublin Core metadata is no longer generated in the default HTML5 output.
If necessary, the org.dita.html5.dublin-core plug-in can be installed from the plug-in registry at dita-ot.org/plugins to add Dublin Core metadata to HTML5. To install the plug-in, run the following command:
dita install org.dita.html5.dublin-core
- In XHTML output, previous versions failed to distinguish Notice note types from regular notes, prefixing both with Note. Support has been backported from HTML5 to XHTML to prefix notices with Notice as expected. #3599, #3600
- Unused code for flagging and key processing has been removed along with related files that have been deprecated since version 2.1, including the base flag.xsl stylesheet, the generated keydef.xml file, and schemekeydef.xml. #3602, #3603
Remaining inline style attributes were removed from HTML5 code, which prevented custom plug-ins from overriding the presentation of the corresponding elements, including:
- syntax diagrams
- long quote citations
- Boolean states
These changes move the default presentation rules to CSS to allow users to override these styles in custom stylesheets. The output is visually equivalent to the results generated by previous toolkit versions. #3632Important: In publishing environments that do not use the default common CSS files, these styles may need to be implemented in custom stylesheets.
DITA Open Toolkit Release 3.6 provides fixes for the following bugs:
Folder names in development build archives previously included the “
+” plus sign, which caused errors when running from the unpacked directory. The snapshot folder name syntax has been updated to use the “
@” at sign instead, which allows builds to run directly from the extracted folder. #2414, #3623
- The Java code has been refactored to anticipate cases where resources are missing or incorrectly defined.
File.toURI()method has been updated to ensure that the generated URI for a directory will always end in a trailing slash. This prevents unexpected errors in cases when the
Fileinput points to a path that doesn’t exist. #3621, #3624, #3626
JobSourceSethas been fixed to handle cases where the
- In DITA-OT 3.5.4, the HTMLHelp stylesheet map2hhcImpl.xsl included an invalid code remnant left over from previous edits. The unnecessary line has been removed. #3627, #3634
DITA Open Toolkit Release 3.6 includes code contributions by the following people:
- Jarno Elovirta
- Roger Sheen
- Robert D Anderson
- Radu Coravu
- David Bertalan
For the complete list of changes since the previous release, see the changelog on GitHub.
The documentation for DITA Open Toolkit Release 3.6 provides corrections and improvements to existing topics, along with new information in the following topics:
- Store API – Processing in memory
- DITA 2.0 preview support
- Migrating to release 3.6
- Speeding up builds
- Common parameters
- Using the dita command
- Arguments and options for the dita command
For additional information on documentation issues resolved in DITA Open Toolkit Release 3.6, see the 3.6 milestone in the documentation repository.
DITA Open Toolkit Release 3.6 includes documentation contributions by the following people:
- Roger Sheen
- Jarno Elovirta
- Lief Erickson
- Heston Hoffman
For the complete list of documentation changes since the previous release, see the changelog.