DITA Open Toolkit 2.1.2 Release Notes

DITA Open Toolkit 2.1.2 is a maintenance release that includes fixes for reported issues.


DITA Open Toolkit Release 2.1 requires the Java Runtime Environment (JRE) or Java Development Kit (JDK), version 7 or later.

Resolved issues

The following items are included in DITA Open Toolkit Release 2.1. Issue numbers correspond to the tracking number in the GitHub issues tracker.

Maintenance Release 2.1.2

DITA Open Toolkit Release 2.1.2 includes the following bug fixes:

  • Index terms starting with “Ñ” are no longer dropped from Spanish PDF indexes. They are now handled with the correct Spanish sort order and placed in a group between “N” and “O”, under the “Ñ” heading.
    • #2068 Add support for n-tilde in Spanish index
  • References to external code samples are now resolved properly when @coderef attributes target non-XML resources and the output directory is shifted by setting the generate.copy.outer parameter to 3.
    • #2044 Non-XML coderef fails on outer context
  • Warnings for deprecated templates are now displayed with the correct message prefix: DOTX.
    • #2043 Warning for deprecated templates fails

Maintenance Release 2.1.1

DITA Open Toolkit Release 2.1.1 includes the following bug fixes:

  • Whitespace in <image> elements is now ignored in PDF output to prevent errors when rendering XSL:FO.
    • #1985 XEP error: Element 'fo:external-graphic' must be empty
  • Any proportional table column widths expressed in the CALS table model as "*" are now normalized to the equivalent "1*" value to prevent errors while generating XHTML output.
    • #1978 colwidth="*" causes Fatal Error! Cannot convert string "" to a double
  • In DITA Open Toolkit 2.0.1, the line ending characters in shell files were inadvertently changed to Windows (CRLF) line endings. The correct UNIX (LF) line endings have now been restored.
    • #1954 bin/ant throws errors when executed in Ubuntu shell

Feature requests and changes

DITA Open Toolkit Release 2.1 includes the following new features and changes:

  • In PDF output, inline <codeph> elements in topic titles now inherit the font size from the surrounding title text.
    • 1874 Codephrase used in topic title has very small font
  • Image metadata processing has been refactored to improve the processing speed by determining width and height without reading the entire image into memory.
    • 1883 Faster implementation for ImgUtils.getWidth/getHeight
  • Obsolete CHM configuration files have been removed from the PDF2 plugin.
    • 1897 DITA OT 2.1.dev chm properties folder in org.dita.pdf2

Milestone 1 included the following new features and changes:

  • The chapterBody XSL template mode has been refactored to create additional HTML5 groups in the generated HTML <body> element.

    DITA topics are now mapped to the HTML5 <article> element, DITA <section> to <section>, and DITA <fig> to <figure>.

    HTML5 @aria-labelledby accessibility attributes are also generated to associate each article with its heading. This helps to improve the accessibility and interoperability of HTML output by providing structural information to assistive technologies such as screen readers.
    • 1179 Added HTML generation extension for body content
  • Additional file formats referenced from <image> elements are now copied to output. Any references that are not DITA, DITA map, or image, are now treated as resources and also copied, so you no longer need extra <copy> operations in your project build scripts to include such assets in output.
    • 1687 More recognized default resource extensions in the plugins base
  • DITA-OT now fails with a fatal error (DOTA013F) if a specified .ditaval filter file is not available. This ensures that unexpected output is not generated if the filter file is missing or invalid.
    • 1703 Link to missing DITAVAL file should show a relevant error code in the console
  • The generate-debug-attributes and processing-mode configuration options have been moved to runtime properties, so you can now pass these parameters at build time to specify whether the @xtrf and @xtrc debugging attributes should be generated, and how the DITA-OT handles errors and error recovery. For more information, see common Ant paramters.
    • 1799 Move configuration options to runtime properties
  • The deprecated Java command line tool has been removed in favor of the dita command introduced in DITA-OT 2.0.

    If you previously generated output via a Java command sequence such as
    java -jar lib/dost.jar /i:input-file /transtype:transformation-type /parameter-name:value
    you should now use the following syntax instead:
    dita -f transformation-type -i input-file -o output-dir
    • 1800 Remove old Java command line tool
  • The custom FileUtils code used to handle input and output in earlier versions of DITA-OT has been replaced with the Apache Commons IO utilities library.
    • 1803 Use Commons IO
  • Support for the args.odt.img.embed parameter has been removed from OpenDocument format transformations.

    The previous default behavior was to embed images as Base64-encoded text, but editors do not use this as a default. Instead, office packages such as LibreOffice will convert embedded images into linked images on opening and saving an ODT file.
    • 1832 Remove support for args.odt.img.embed
  • Keydef processing has been removed from the XHTML rendering code

    Keys are now resolved in one preprocessing step, whereas in earlier versions of DITA-OT, the XHTML code returned to the keydef.xml file to look up targets for phrase elements and pull in text when needed. This change affects non-linking elements that can't take @href attributes, such as <ph>, <keyword>, <cite>, <dt>, <term>, and <indexterm> (when $INDEXSHOW is active).
    • 1837 Remove keydef processing from XHTML rendering code
  • A new dita.parser extension point has been added to allow plug-ins to contribute a custom parser for DITA files.

    If a custom DITA parser is defined, the preprocessing routines will use it during the gen-list and debug-filter stages to output DITA XML.
    • 1847 Extension-point for custom DITA parsers


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

  • 1513 Suspected memory leak in OT bug preprocess
  • 1694 Cannot convert string to double
  • 1854 integrator.xml should also load the necessary "commons-io.jar"
  • 1870 PDF2 output plugin fails rendering tables
  • 1872 Link to index term repeats itself
  • 1877 Searchtitle Incorrectly Used for HTML Title
  • 1888 build.xml help target documentation is incorrect ant interface
  • 1889 @class missing from choicetable XHTML output
  • 1890 properties table XHTML output
  • 1894 Fix unitless length-to-pixels
  • 1921 Error reported during flagging
  • 1922 Index continued markers don't work if both primary and its secondary entries continue
  • 1927 In the key() function, the node supplied in the third argument (or the context node if absent) must be in a tree whose root is a document node
  • 1932 when running ./dita, console shows "No such file or directory" when directory contains spaces

Milestone 1 provided fixes for the following bugs:

  • 1415 Filtering doesn't support default for rev flagging
  • 1840 Keyref processing doesn't use only first keyword or term
  • 1849 Some XSLT XPaths do not properly use the @class attribute to select elems

Maintenance Release 2.0.1

Note: DITA Open Toolkit Release 2.1 also included the following bug fixes that were released earlier this year with maintenance version 2.0.1.
  • #1744 copy-to attribute not processed correctly (error DOTX008E) in XHTML transtype on a topicref included in a child map
  • #1790 FO: Xref processing does not handle case of key with no remote resource or link text
  • #1806 IDs are not preserved on <bodydiv> element
  • #1808 DITA-OT 2.0: PDF bookmarks (TOC, index) not in language indicated in source files
  • #1810 DITA-OT 2.0: typo in PDF-plugin, xsl/fo/toc.xsl ("boookmap")
  • #1811 Filtering doesn't support @deliveryTarget
  • #1813 Mappull step fails with nested concept
  • #1814 Task with links and nested task fails in XHTML
  • #1815 Convert String to double Error message when we try to generate pdf
  • #1826 OT 2.0: Map with subject scheme and non-below map fails