DITA Open Toolkit 3.4 Release Notes

DITA Open Toolkit 3.4 is a feature release that provides new features and enhancements, including an official Docker container image, a separate plug-in for PDF indexing, a new option to skip HTML5 cover pages, and initial support for project files that allow you to define multiple deliverables in advance, and publish them all at once.

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

Requirements

DITA-OT is designed to run on Java version 8u101 or later and built and tested with the Open Java Development Kit (OpenJDK). Compatible Java distributions are available from multiple sources:

DITA-OT 3.4 released November 9, 2019

DITA Open Toolkit Release 3.4 includes an official Docker container image, a separate plug-in for PDF indexing, a new option to skip HTML5 cover pages, and initial support for project files that allow you to define multiple deliverables in advance, and publish them all at once.

Docker container image

Docker is a platform used to build, share, and run portable application containers. As of version 3.4, the DITA-OT project provides an official Docker container image that includes everything you need to run the toolkit and publish DITA content from a containerized environment. #3358

New indexing plug-in

DITA-OT 3.4 extracts the PDF indexing code to a separate org.dita.index plug-in, and adds a new depend.org.dita.pdf2.index extension point that can be used to add custom index processing targets to PDF output.

The built-in index processing has been disabled and deprecated. If you have overridden index processing via the transform.topic2fo target in the past, you can set the new org.dita.index.skip property to yes and re-enable the transform.topic2fo.index target with <feature extension="depend.org.dita.pdf2.index" value="transform.topic2fo.index"/> in your plug-in configuration.

#3390, #3396

Skip HTML5 cover pages

The HTML5 transformation supports a new property that determines whether a table of contents file should be generated to link to the other topics from the input map. The html5.toc.generate parameter is set to yes by default, and creates a cover page named index.html as with previous versions of DITA-OT. If you’re using the nav-toc parameter to embed navigation links in topics, you can set html5.toc.generate to no to stop creating the extra file. #3301

Project files

DITA-OT 3.4 introduces new project files to define publication projects with multiple deliverables. Projects specify a context, output folder, and publication for each deliverable. A re-usable context groups source files and filters, and a publication defines an output format with transformation parameters. You can pass a project file to the dita command to publish multiple deliverables at once.

Project files may be defined in one of three formats: XML, JSON, or YAML. The XML format can be validated with a RELAX NG schema provided in the resources folder of the DITA-OT installation (project.rnc).

#3243, #3256, #3262, #3265, #3268, #3269, #3276, #3298, #3300, #3382, #3388, #3394

Enhancements and changes

In addition to the highlights mentioned above, DITA Open Toolkit Release 3.4 includes the following enhancements and changes to existing features:

  • The original preprocessing and map-first preprocessing pipelines have been simplified to process only the merged root map, where previous versions would redundantly process all DITA maps. #3250
  • Conref processing has been updated to resolve content references to specializations of the referencing element #3264
  • The obsolete build_demo.xml script that was previously used to build Ant samples has been removed from the source code repository. (The file was removed from distribution packages with version 2.1.) #3288
  • Ant scripts have been refactored to simplify <condition> elements with <isset> guards to set properties with plain <property> declarations instead. #3297
  • The logging level for Apache HTTP Client libraries has been reduced to INFO to quiet the default log output. This information can be displayed if necessary by enabling verbose logging. #3307, #3308
  • The ConrefPushParser has been converted from a SAX filter to a DOM filter. #3315
  • Travis CI build stages are now used to run tests and deployments in parallel to speed up continuous integration builds. #3329
  • Several bundled dependencies have been upgraded to the latest versions.
  • XSLT error messages now include location information in more cases to make it easier to find the source of the problem. #3334, #3339, #3341
  • DITA-OT 3.4 no longer includes the TocJS and troff transformation plug-ins in the default distribution. #3363, #3364
    Note: If necessary, legacy plug-ins may be re-installed from earlier DITA-OT distributions, but they are no longer actively maintained or supported by the core toolkit committers. The source code is available on GitHub for anyone interested in maintaining the plug-ins for use with future toolkit versions.
  • The LwDITA plug-in has been updated to version 2.3.2, pulling in a number of fixes for Lightweight DITA processing, including support for absolute links and strikethrough in Markdown input, and updated processing for escaped characters and nested blocks in Markdown output. #3371, #3408
  • The args.logdir parameter (deprecated since DITA-OT 2.5) has been removed. To write the log to a file, use dita --logfile=file or ant -l file and specify the path to the log file. #3398, #3399
  • The source code for the DITA 1.1 and 1.2 plug-ins has been removed from the core repository and extracted to dedicated code repositories. The plug-ins themselves remain available in the DITA-OT 3.4 distribution package. #3401

Bugs

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

  • Several issues have been resolved in the PDF rendering of a generated index:
    • To work around an open issue with Apache Formatting Objects Processor FOP-2520, DITA-OT 3.4 uses <fo:block> instead of <fo:wrapper> to create the destinations for index links. In previous versions of DITA-OT, index terms that appeared in source files between section titles and paragraph content (and several other places) created empty space in PDF output. #2455, #2914, #3381
    • When publishing to PDF with Antenna House Formatter, destination anchors for index links now use <fo:wrapper> instead of <fo:inline>. In previous versions of DITA-OT, index terms that appeared in source files between section titles and other section content created empty space in PDF output. #3042, #3379
    • Index links are now created correctly when entries have subterms. In previous versions, terms with multiple <index-see-also> subterms failed to generate links for all but the first reference, and dropped all instances of a term if even one instance had a sub-term, an <index-see> or <index-see-also> child. #3314, #3320, #3373
    • References to unavailable <index-see> terms are filtered from the final index. Previous versions would create invalid links if the target terms were not available in the current publication context. #3391
  • Cross-reference links to other topics from short descriptions no longer cause build errors. #3078, #3324
  • In earlier versions, incorrect parameters passed to the dita command could cause the build to fail with a NullPointerException. The Java code has been updated to issue an appropriate error message in these cases, instead of crashing the build. #3360

Contributors

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

  1. Jarno Elovirta
  2. Robert D Anderson
  3. Roger Sheen
  4. Radu Coravu
  5. Eliot Kimber
  6. Toshihiko Makita

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

Documentation updates

The documentation for DITA Open Toolkit Release 3.4 provides corrections and improvements to existing topics, sample project files in the docsrc/samples/ folder, a Glossary, PDF index, and new information in the following topics:

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

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

  1. Roger Sheen
  2. Lief Erickson
  3. Jarno Elovirta
  4. Robert D Anderson
  5. Eliot Kimber
  6. Ursula Kallio
  7. Jason Fox
  8. Radu Coravu

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