DITA Open Toolkit Release 2.0

Release Highlights

DITA Open Toolkit Release 2.0 includes the following significant enhancements:
  • New dita command line tool provides a simple command interface
  • XSLT stylesheets have been converted to XSLT 2.0
  • Processing order of keys and conrefs has been changed to optimize processing speed for many documents
  • Initial preview support for many features from the upcoming DITA 1.3 standard
  • Major refactoring to remove unused, out of date, or deprecated code in Java and XSLT
  • Faster PDF output generation

For details on these and all other enhancements, see the sections below.

Requirements

DITA Open Toolkit Release 2.0 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.0. Issue numbers correspond to the tracking number in the GitHub issues tracker.

Initial Preview Support for DITA 1.3

  • #1649 Support DITA 1.3 link syntax (milestone 2)
  • #1636 Support DITA 1.3 cascade attribute (milestone 2)
  • #1635 Implement DITA 1.3 profiling (milestone 2)
  • #1651 Add new DITA 1.3 highlighting elements (milestone 4)
  • #1652 Add DITA 1.3 markup and xml domain support (milestone 4)
  • #1654 Add DITA 1.3 div element (milestone 4)

Feature Requests

  • The filtering logic has been extended to catch cases which could cause PDF rendering to fail when "exclude" actions in ditaval filtering result in empty elements.
    • #1192 Empty <ul></ul> kills FOP (milestone 1)
    • #1610 Filtered content leads to total fail of PDF rendering duplicate (milestone 1)

  • The format of figure and table references in PDF output can now be defined using the same parameters that govern HTML output.

    The args.figurelink.style and args.tablelink.style Ant parameters are now also considered when generating PDF output. The NUMBER and TITLE options previously available for HTML-based output formats can now also be applied to PDF output. By default PDF uses the new value NUMTITLE to include both the number and title of the referenced figure or table as in previous toolkit versions. The NUMTITLE value is not supported for other transform types.
    • #1267 PDF support for figurelink/tablelink.style (milestone 1)
  • The XSLT processing has been updated to use the XHTML output method for XHTML 1.0 and assign the mandatory xhtml namespace to the the generated HTML root element: 
    <html xmlns="http://www.w3.org/1999/xhtml">
    This ensures the XSL processor formats elements in the output with XHTML syntax (self-closing elements include an additional space for browser compatibility).
    • #1347 Issue with "xsl/dita2xhtml.xsl"? (milestone 1)
  • A new dita command line tool wraps Ant processing into a single command. The CLI sets all required environment variables and allows you to run DITA-OT without setting up anything beforehand. Instead of calling java or ant, you can now run 
    dita -f format -i input [options]
    The command line tool is a wrapper around the Ant interface; it takes the simplified parameters as input, converts them to Ant parameters, and then runs an Ant build. The command-line tool supports a subset of the parameters that are available to the Ant builds. For example, use the -f option instead of -Dtranstype to set the output format, and use -i insted of -Dargs.input to set the input file.
    • #1506 New command line tool (milestone 1)
  • The XSLT stylesheets for preprocessing and transformation types have been converted to version 2.0 and EXSLT extensions like node-set have been removed. If you have customized versions of these stylesheets in your own plugins, you may need to adjust them for compatibility with XSLT 2.0.
    • #1507 Convert XSLT to version 2.0 (milestone 1)
  • Apache Ivy is now used to resolve project dependencies. A new ivy.xml file lists the resources necessary to build the project. Ivy uses this list to resolve and download the necessary resources from an artifact repository, so the corresponding libraries were removed from the Git repository. (They are still included in the /lib/ folder of the appropriate client distribution packages.)
    • #1511 Use Ivy for dependency management (milestone 1)
  • A new html5 transformation type is now available to produce output compatible with the HTML5 recommendation recently published by the W3C. This uses the dita2html5 shell to extend the existing xhtml transform for HTML5-compatible output. The resulting HTML files use the !DOCTYPE html document type declaration instead of the XHTML 1.0 Transitional output generated by the xhtml transformation. To support legacy browsers that don't recognize the preferred short doctype, the SYSTEM keyword is included in the declaration with the "about:legacy-compat" value.
    • #1522 Add HTML5 transtype (milestone 1)
  • The Ant scripts and stylesheets in the HTML and XHTML transformation types have been refactored to reduce code duplication. If you have customized versions of these files in your own plugins, you may need to adjust them for compatibility with DITA-OT 2.0.
    • #1523 Reduce HTML/XHTML code duplication (milestone 1)
  • The custom print filtering code has been replaced with a generated DITAVAL filter file that is applied to all print-oriented transformation types. The dita.transtype.print plug-in extension point introduced in DITA-OT 1.5.4 is used to declare a transtype as a print type. When output is generated via plugins that include this property, the following DITAVAL filter is applied:
    <val>
  <prop att="print" val="yes" action="include"/>
  <prop att="print" val="printonly" action="include"/>
  <prop att="print" val="no" action="exclude"/>
  <prop att="print" action="include"/>
</val>
    • #1524 Use DITAVAL for print filtering (milestone 1)

  • The coderef element now supports fragment identifiers as specified in RFC 5147 along with the custom line-range fragment function previously added in DITA-OT 1.8.

    You can use fragment identifiers to refer to specific parts of a file by line position or range. For example, the following coderef includes a range of lines from an external file in a codeblock.

    <coderef href="Parser.scala#line=4,10" format="scala"/>
    • #1548 Support RFC 5147 in coderef (milestone 1)
  • The list of chunked topics is now included in the full list of DITA topics, rather than generating a separate list for topics that were created as a result of chunking. All chunk-generated content is now treated as if it was part of the original input set.
    • #1561 Combine chunkedtopic lists into fullditatopic list (milestone 1)
  • An Index is now created when generating PDF output via Apache Formatting Objects Processor (FOP).
    • #1569 Index capability with FOP (milestone 1)
  • Single-topic PDFs now include only the topic content, rather than generating a cover page and table of contents as in previous versions of DITA-OT.
    • #1601 Change output for rendering a single topic to PDF (milestone 1)

  • Plugins can now be installed and removed via the new dita command line tool.

    $ dita -install <plugin-zip-path>
$ dita -uninstall <plugin-id>
    Plugins provided as ZIP or JAR files are extracted to the plugins folder on installation. A new plugin folder is created based on the plugin ID in the plugin.xml file. If the plugin.xml is located in a subfolder inside the archive, that subfolder is treated as the plugin folder. After the plugin is extracted, the integration process is run. The uninstall operation removes the subfolder with the specified ID from the plugins folder and runs the integration process to update the list of registered plugins.
    • #1602 Add plug-in installation operation to integration (milestone 1)
  • HTML output now wraps scalable vector graphics (SVG) images in an img element like all other image types, rather than in an embed element. This ensures that SVG images in cross-references are correctly rendered as hyperlinks in HTML-based output formats.
    • #1608 img should be used instead of embed in XHTML output for all image types (milestone 1)
  • The bundled distribution of Apache Ant has been updated from version 1.8.4 to 1.9.2. For details on the changes in recent Ant versions, see Ant Project News.
    • #1612 Update Ant to 1.9.2 (milestone 1)
  • PDF builds no longer require Apache FOP to be present in the fop/lib folder of the PDF plugin. Previous versions of DITA-OT expected to find Apache FOP in the default location and issued an error if the path was not present (even if FOP was available in an alternate location).
    • #1614 ant build should not bail out when fop directory has no lib folder (milestone 1)
  • The deprecated legacy PDF transformation is no longer included in the default distribution packages.
    • #1616 Remove legacy PDF from default distributions (milestone 1)
  • The deprecated integrator.properties file has been removed. The integration-related properties plugindirs and plugin.ignores are now specified along with other configuration properties in the lib/configuration.properties file.
    • #1509 Remove deprecated code (in progress)
  • Additional HTML entities have been added to the entities.properties file that is used in the HTMLHelp transformation to provide support for Greek characters and other commonly used special characters in Windows help files (CHM).
    • #1644 Add more HTML entities to file entities.properties in dost.jar (milestone 2)
  • The @location attributes in integration-generated Ant properties now use the forward slash character (/) as directory separator to ensure that generated pathnames are compatible with both UNIX and Windows.
    • #1643 Integrator task constructs property constructs with platform-dependent path separators (milestone 2)
  • The order of preprocessing stages has been optimized to move keyref processing before conref processing. This provides significant performance gains for source that uses multiple key references within reusable content.
    • #1631 Process keyrefs before conref (milestone 2)
  • Removed support for the rarely used generate.copy.outer=2 option that generated output for content located outside the DITA map directory. If output must be generated for content that is not located in or beneath the directory containing the DITA map file, option 3 should be used instead to shift the output directory so that it contains all output for the publication.
    • #1673 Remove support for generate.copy.outer=2 (milestone 3)
  • New templates and variables have been added to make it easier to include a back cover in PDF output. A new generate-back-cover option is now provided in the basic-settings.xsl file in the cfg/fo/attrs/ folder of the PDF plugin. This option is disabled by default. An empty XSL template named createBackCoverContents has been added to xsl/fo/front-matter.xsl. Custom PDF plugins can enable back cover generation and adjust the template to include images or text on the last page of PDF files.
    • #1671 Add support for generating back cover on PDF (milestone 3)
  • The redundant code that supported legacy FrameMaker syntax for indexterm elements has been removed. The same functionality is available with a preprocessing step.
    • #1667 Remove FrameMaker index syntax support (milestone 3)
  • When generating PDF output for bookmaps, the notices element in frontmatter now uses the preface static contents template to ensure that page numbering is consistent with the numbering scheme used for other frontmatter content.
    • #1186 PDF2: update processTopicNotices staticcontents (milestone 4)
  • Localization strings for all transformation types can now be configured in one place by specifying the variable.file.url parameter.
    • #1188 Localization should be independent of transtype. (milestone 4)
  • An error message has been added to alert users if the root ditamap contains a topicref element that refers to a submap without setting the format attribute to ditamap. In lax processing mode, the debug filter will add the missing attribute for links to maps, but it will not fix any existing incorrect format values.
    • #1310 Improve error message during topicmerge step in case format attribute is incorrect (milestone 4)
  • The DTDs and XML Schemas included with the toolkit have been bundled as plugins to facilitate maintenance and customization.
    • #1508 Move DTDs and XML Schemas to plug-ins (milestone 4)
  • PDF output is now generated faster as a result of performance optimizations in the XSLT stylesheets of the PDF2 plugin.
    • #1672 Performance optimizations for the PDF2 plugin (milestone 4)
  • The default map processing for HTML now generates a cover page with a table of contents in an HTML5 nav element rather than generating a separate ToC file for use in a frameset.
    • #1674 Change HTML default TOC to cover with TOC (milestone 4)
  • Figure descriptions in HTML output now appear in the same paragraph as the figure title.
    • #1695 In XHTML output the figure title and figure description should be in the same paragraph (milestone 4)
  • The interdependent maplink and move-links preprocessing steps have been merged into a single step.
    • #1714 Merge maplink and move-links preprocessing steps (milestone 4)
  • Topic references inside glossarylist elements are now supported in PDF output. They are treated like regular nested topics.
    • #1719 Restore glossarylist check introduced in #1659 (milestone 4)
  • If the lines of program listing are too long to fit into one line, they can now be marked with the ► character (&#x25BA;) to indicate that code continues on the next line. Lines will be automatically wrapped at this character.
    • #1735 Support marking wrapped lines in codeblock (milestone 4)
  • Profiling attributes set on DITA content are now mapped to their equivalent HTML5 data- attributes. This allows you to use Javascript or CSS rules to show/hide parts of the output based on user roles.
    • #1739 Map profiling attributes set on DITA elements to equivalent HTML5 "data-" attributes (milestone 4)
  • A new root-chunk-override parameter has been added to support overrides to the root map chunk value.
    • #1742 Add override for map chunk (milestone 4)
  • The Java code has been refactored to use URI and File objects instead of Strings to permit automatic validation of values.
    • #1544 Use URI and File instead of String (in progress)

Bugs

  • #1095 Empty tags result in invalid HTML (milestone 1)
  • #1239 Essentially needs XercesImpl (milestone 1)
  • #1247 Enable specifying MathML file as image/@href (milestone 1)
  • #1272 chapter numbering confused when chapters and parts in bookmap (milestone 1)
  • #1407 "Ambiguous rule match" in PDF processing XSLT when <imagemap> is used in topic (milestone 1)
  • #1421 Warnings when converting to PDF with XEP (milestone 1)
  • #1462 Support for <table> rowheader in PDF output (milestone 1)
  • #1486 PDF transform does not apply @rowsep correctly (milestone 1)
  • #1607 Keyref not processed for pushed conrefs (milestone 1)
  • #1620 ODT plugin fails due to missing getMax() (milestone 2)
  • #1619 Add validation for attribute generalization (milestone 2)
  • #1103 DITA-OT doesn't rewrite lq/@href (milestone 2)
  • #1668 Fix table cell @id and @headers attributes #1596 (milestone 3)
  • #1634 XML Catalog which has a DOCTYPE declaration is not properly parsed by Integrator task (milestone 3)
  • #1596 xref to table cell of DITA simple table does not result in correct target in <a> element (XHTML output) (milestone 3)
  • #1539 TopicMerge generates multiple topic entries in the merged middle file. (milestone 3)
  • #1231 <screen> and <codebock> do not support all frame attributes (milestone 3)
  • #1086 metadata in ancestor map not inherited by topics in childmap (milestone 3)
  • #1183 PDF2: image/@placement='break' breaks keeps. (milestone 4)
  • #1209 border-after-width.conditionality mismatches border-bottom (milestone 4)
  • #1344 <related-links> element breaks child links (milestone 4)
  • #1488 Doc gives wrong value for onlytopic.in.map, or code uses wrong value (milestone 4)
  • #1678 Potential memory leaks in DITA OT 1.8 (probably also 1.7) (milestone 4)
  • #1679 DITA-OT 2.0 M 3: maprefImpl.xsl: XPTY0004: A sequence of more than one item is not allowed as the first argument of contains() (milestone 4)
  • #1682 DITA-OT 2.0 M 3: nested topicref elements cause false warnings on wrong topic type (DOTX019W) (milestone 4)
  • #1684 Internal links in conreffed topic are not properly re-written (milestone 4)
  • #1693 Preserve @class and @outputclass values for DITA Map topicrefs in XHTML output (milestone 4)
  • #1700 VERSION_PATTERN typo (milestone 4)
  • #1701 Frame attribute not supported for fig element (milestone 4)
  • #1711 The "path2project-uri" is not output in chunked topics [DITA OT 1.8] (milestone 4)
  • #1712 PDF2 pipeline throws MalformedURLException (milestone 4)
  • #1727 Obey @scalefit attribute on an image (milestone 4)
  • #1728 Conref push into codeblock causes angle brackets in output (milestone 4)
  • #1732 xrefs to <preface> topics fail in PDF2 output in 1.8.4 (milestone 4)
  • #1744 copy-to attribute not processed correctly (error DOTX008E) in XHTML transtype on a topicref included in a child map (2.0.1)
  • #1790 FO: Xref processing does not handle case of key with no remote resource or link text (2.0.1)
  • #1806 IDs are not preserved on <bodydiv> element (2.0.1)
  • #1808 DITA-OT 2.0: PDF bookmarks (TOC, index) not in language indicated in source files (2.0.1)
  • #1810 DITA-OT 2.0: typo in PDF-plugin, xsl/fo/toc.xsl ("boookmap") (2.0.1)
  • #1811 Filtering doesn't support @deliveryTarget (2.0.1)
  • #1813 Mappull step fails with nested concept (2.0.1)
  • #1814 Task with links and nested task fails in XHTML (2.0.1)
  • #1815 Convert String to double Error message when we try to generate pdf (2.0.1)
  • #1826 OT 2.0: Map with subject scheme and non-below map fails (2.0.1)