DITA Open Toolkit 2.0 Release Notes

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 and options previously available for HTML-based output formats can now also be applied to PDF output. By default PDF uses the new value to include both the number and title of the referenced figure or table as in previous toolkit versions. The 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)
TODO: Add extended description to Release Highlights
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 option instead of to set the output format, and use insted of to set the input file.
- #1506 New command line tool (milestone 1)
TODO: Add to Release Highlights / Migration sections
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 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 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 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 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 and 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= 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 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 . In 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 (►) 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)