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.
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
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
extension="depend.org.dita.pdf2.index" value="transform.topic2fo.index"/> in your plug-in
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
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).
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
<isset>guards to set properties with plain
<property>declarations instead. #3297
- The logging level for Apache HTTP Client libraries has been reduced to
INFOto quiet the default log output. This information can be displayed if necessary by enabling verbose logging. #3307, #3308
ConrefPushParserhas 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
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
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: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: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-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
- To work around an open issue with Apache Formatting Objects Processor FOP-2520, DITA-OT 3.4 uses
- 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
DITA Open Toolkit Release 3.4 includes code contributions by the following people:
- Jarno Elovirta
- Robert D Anderson
- Roger Sheen
- Radu Coravu
- Eliot Kimber
- Toshihiko Makita
For the complete list of changes since the previous release, see the changelog on GitHub.
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:
- Publishing with project files
- Running the dita command from a Docker image
- Migrating to release 3.4
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:
- Roger Sheen
- Lief Erickson
- Jarno Elovirta
- Robert D Anderson
- Eliot Kimber
- Ursula Kallio
- Jason Fox
- Radu Coravu
For the complete list of documentation changes since the previous release, see the changelog.