DITA Open Toolkit 2.2.5 Release Notes

DITA Open Toolkit Release 2.2.5 includes the following bug fixes.

• In earlier toolkit versions, the Word RTF transformation produced invalid RTF output when source files contained tables with absolute column widths. Processing has been modified to treat all widths as proportional, including units given in inches, centimeters, millimeters, or points. Absolute units are not respected, but the toolkit now generates valid RTF output rather than crashing. #1190, #2333
• References to empty ditamap files threw the DOTX031E error message during the mapref processing stage. The toolkit no longer checks for subelements in the map and will now continue processing as long as a root node is available. #1549, #2336
• Several error messages generated during index processing for PDF output have been clarified to better explain the cause of the error and provide more helpful information on how to resolve the issue. #1709, #2327
• Links to <dlentry> elements were broken in PDFs generated via Apache FOP, as FOP does not support the @id attribute on table rows. To work around this issue, DITA-OT now moves the ID from the <dlentry> to an <fo:inline> element in the first term when rendering PDF output via FOP. #1764, #2198
• The DITA-OT 2.0 HTML5 transformation declared several XSL extension points that were not fully implemented:
  • dita.xsl.html5
  • dita.xsl.html5.toc
  • dita.xsl.html5.cover
  Three new templates now provide the necessary <dita:extension> elements to add custom XSLT processing to the HTML5 transformation. #1876, #2313, #2342
• The OASIS catalogs for DITA 1.3 pointed to a series of non-existent resources. The catalog files have been updated to remove spurious file references and errata have been submitted to OASIS for inclusion in the original source catalogs. #2266, #2320
• Performance of previous toolkit versions suffered substantially if a single warehouse topic was used to store a large number of blocks for reference instead of multiple smaller warehouse topics with the same total number of blocks. An expensive XPath expression in the content reference processing phase was replaced with an optimized expression that dramatically reduces publication time in cases with thousands of following siblings. #2307, #2309
• In JavaHelp output, the copy-css task was called too early, before the user.csspath parameter was evaluated, so CSS files were copied to a folder named ${user.csspath} rather than to the intended location. JavaHelp processing has been corrected to avoid the duplicate dependency on the copy-css task and ensure that CSS files are handled correctly. #2311
• Two unimplemented parameter extension points were removed from the HTML5 plug-in:
  • dita.conductor.html5.param
  • dita.conductor.html5.toc.param
  Implementers who want to add parameters to the HTML5 transformation can instead require the base HTML plug-in as well as the HTML5 plug-in and extend the base HTML plug-in's parameter extension points #2312, #2314
• Content reference range processing has been modified to use before << and after >> expressions rather than following-sibling and check that the conref end target actually exists. #2315
• When a <topicsetref> element is used to refer to a <topicset>, previous toolkit versions threw DOTX019W errors, suggesting that every reference in the original <topicset> also specified @type="topicset". Map reference processing has been modified to drop the @type attribute as part of the resolution. This prevents such unintended side effects by ensuring that the type no longer cascades further down the resolved branch. #2321, #2338
• Support for flagging in HTML output has been imported (rather than included) and moved before the extension point to allow custom plug-ins to override flagging behavior. #2329

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

DITA Open Toolkit Release 2.2.4 included the following bug fixes.

• The <title> is now used as link text when links are specified using a <title> element (or specialized variant) as link target. This approach allows the toolkit to be more lenient when authors link to a <glossterm> rather than to the parent <glossentry> element, or to figure or table titles instead of the <fig> or <table> element structure recommended by the DITA 1.3 specification. #2283
• The default value for the args.copycss parameter has been explicitly set to no. Previous toolkit versions never initialized a default value, and only copied the custom .css file if the parameter was set to yes. #2278
• Hyperlink reference processing has been modified to guard against error conditions caused by Windows-style path separators in @href attribute values. Any backslashes are converted to forward slash (“/”) characters to ensure that the attribute values are valid URI references according to RFC 3986. #2274
• A typo was fixed in the common string logic for the PDF plug-in to retrieve the proper localized string for the task “Results” label that appears when args.gen.task.lbl is set to YES. #2270, #2216, #2203
• DITA-OT 2.2 introduced a regression in which topics referenced via keys in submaps were not included in the table of contents. The keyref resolution mechanism has been corrected to ensure that key references in submaps are correctly resolved. #2264
• A new DOTJ068E error message was added to report cases when a conref "mark" action is used to mark a target element without a corresponding content reference target (for example, when the order of the "mark" element and the pushed element is reversed). #1293

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

DITA Open Toolkit Release 2.2.3 included the following bug fixes.

• Specifying the source of a long quote with a @keyref attribute on a <longquoteref> element caused a Null Pointer Exception. The keyref parser has been modified to ensure that key references on long quote references are correctly resolved. #2246
• The keyscope cascading mechanisms for branch filtering have been modified to comply with the DITA 1.3 specification. In cases where no @keyscope attribute is specified on a filtered branch, the prefix and/or suffix values specified in <dvrKeyscopePrefix> / <dvrKeyscopeSuffix> are now used as the effective key scope names. Key scope prefixes and suffixes are no longer propagated to descendant key scopes, but only applied to the branch parent. #2240
• PDF: In DITA-OT 2.2.2, if a <link> element contained both <linktext> and a description in the <desc> element, the hyperlink was rendered with the contents of the <desc> element appended to the contents of the <linktext> element. Link processing has been modified to ensure that <link> elements with descriptions are rendered correctly. #2236
• PDF: Index term processing has been revised to ensure that indexes in PDF output generated with Apache FOP correctly include page ranges when @start and @end attributes are defined on <indexterm> elements and the terms of the index range appear on different pages. A single page reference is generated in cases where both occurrences of the index term appear on the same page. #2214
• ODT: The OpenDocument Text transformation has been revised to support SVG images for which image dimensions are not specified via @height and @width attributes. #2211

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

DITA Open Toolkit Release 2.2.2 included the following bug fixes.

• PDF: In earlier DITA-OT 2.x releases, short description content was not rendered when publishing from a bookmap with the args.chapter.layout parameter set to BASIC. Short descriptions are now rendered properly. #2023
• Windows: The name of the JAR file for Apache Ant has been corrected to fix the ANT_HOME is set incorrectly or ant could not be located error that appeared when running the bundled Ant version on Windows in DITA-OT 2.2. #2172
• The order in which plug-ins are integrated has been revised to guarantee that the base DITA-OT plug-ins always come first. This ensures that base target code cannot be overridden. #2180
• Content references with relative paths were not properly resolved to the target document in some cases. The conref base URI resolution mechanism was fixed to ensure that relative references are now resolved correctly. #2192
• The documentation has been updated with links to the final DITA 1.3 specification.

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

DITA Open Toolkit Release 2.2.1 included the following bug fixes.

• PDF: Several templates in the pr-domain.xsl file used value-of rather than apply-templates to output the element contents. This prevented flagging from working as intended in PDF output. This has been corrected to ensure that elements in the programming domain are properly flagged. #2170
• The name of the JAR file for the Apache Commons library that provides reusable Java components has been corrected in the integrator Ant script to fix the NoClassDefFoundError error that appeared when the integrator ran in DITA-OT 2.2. #2163
• PDF title metadata is now generated correctly for DITA maps that set the @xml:lang attribute. In certain cases, previous versions of DITA-OT displayed the XMP structure: 1 label in the Document Properties dialog instead of the map title. #2154

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

DITA Open Toolkit Release 2.2 requires the Java Runtime Environment (JRE) version 7 or later.

DITA 1.3 support

DITA Open Toolkit 2.2 provides processing support for the OASIS DITA 1.3 specification. Initial preview support for this specification was added in version 2.0 of the toolkit; version 2.2 extends this foundation to support key scopes and branch filtering along with additional DITA 1.3 features.

Because DITA 1.3 is fully backwards compatible with previous DITA DTDs and schemas, DITA-OT 2.2 provides the 1.3 materials as the default DTDs for processing. The XML Catalog resolution maps any references for unversioned DITA doctypes to the 1.3 DTDs. All processing ordinarily dependent on the 1.0, 1.1, or 1.2 definitions continues to work as usual, and any documents that make use of the newer DITA 1.3 elements or attributes will be supported with specific new processing.

New HTML5 output

• The HTML5 transformation has been moved to a separate plug-in to facilitate customization of modern HTML5-based output. The default CSS has been refactored in Sass as a foundation for further extensions with CSS frameworks, custom plug-ins and future toolkit versions. (The original XHTML plug-in remains available to support existing legacy HTML-based output formats such as TocJS, HTML Help and JavaHelp.) #2099
• The HTML5 transformation has been extended with a new nav-toc parameter that can be used to generate a table of contents in the HTML5 <nav> element of each page. The navigation can then be rendered in a sidebar or menu via CSS. This parameter is disabled by default (none), but can be enabled by setting the value to partial (which includes the current topic in the ToC along with its parents, siblings and children), or full (which generates a ToC for the entire map). #2103

PDF supports new languages

Features

DITA Open Toolkit Release 2.2 includes the following new features:

• The args.artlbl parameter previously provided in HTML-based transformations to show the source file name along with referenced images has been added to the PDF transformation. For inline images, the label appears immediately after the image; for standalone images, it appears on a line following the image. #2072, #2062
• In PDF output, any index entries that begin with special characters are now moved to a dedicated section of the index. (Previous toolkit versions issued a warning and dropped any unexpected index terms.) #2073, #2071
• The plug-in configuration file resources/plugins.xml generated by the integration process now adds the @xml:base attribute to each plug-in configuration element so that file paths in the plug-in configuration can be resolved relative to the plug-in folder. This makes it easier to share a DITA-OT distribution with others via a version control system or bundle it with an application without re-running the integration process in each installation location. #2018
• The move-meta-entries and mappull steps have been merged. The mappull step has been moved into move-meta-entries and an empty target for mappull is retained for backwards compatibility. #1995
• The generation of page masters and page sequence masters in the PDF plug-in has been modularized to make it easier to extend or override the default set of masters. #1984
• The PDF plug-in has been extended with two new extension points for flagging-preprocess and i18n-postprocess to alllow plug-ins to customize these steps of the flagging process. #1976
• The key definition reading process has been moved from the gen-list preprocessing module to the keyref module to further modularize the code and support additional DITA 1.3 use cases for keys, such as a map that includes a map that then includes another map with a key definition. #1962
• The mapref processing stage has been moved to the beginning of the preprocessing pipeline to simplify keyref processing and support DITA 1.3 branch filtering by allowing all processing to be performed on a single map. #1961
• The dita -install option can now be used to integrate multiple plug-ins at once. If no file or url argument is provided, the integration process reloads plug-ins from the plugins directory, so you can unzip multiple plug-ins to the plugins directory and run dita -install to integrate them all at once. #1957
• The PDF transformation has been extended with XML catalog support for RenderX XEP. The main DITA-OT catalog file is now used to ensure that doctypes such as SVG graphics pass validation when generating PDF output using XEP. #1955
• The Java code has been refactored to use URI-based processing (rather than File objects or Strings) wherever possible to permit automatic validation of values and support the use of external URIs. This allows non-file resources to be processed with commands such as dita -i http://example.com/test.ditamap -f html5. #1544, #1953
• Plug-in folders are now sorted before the integration process runs to ensure predictable results and consistent order each time plug-ins are reloaded. #1905
• The metadata format in the plugin.xml file for the org.dita.xhtml plug-in has been refactored with abstract transtypes that group common parameters used in multiple transformation types. This approach allows common parameters to be defined in one place and re-used for multiple output formats as necessary. #1866
• The dita command options have been extended to add -t as a synonym for the -temp option used to specify the location of the temporary directory. #1836, #2039
• The validation of the table group @cols attribute has been relaxed to support use cases in which tables containing auto-generated @cols values are reused via content references. #1835
• The format of the plugin.xml file has been extended to allow plug-ins to specify the list of public parameters added for each transformation type and announce extensions to a list of arguments defined in another transtype. #1757

Enhancements

DITA Open Toolkit Release 2.2 includes the following enhancements and changes to existing features:

• PDF: Table body rows now use the keep-together.within-page attribute to prevent page breaks within rows. #2118
• PDF: List item numbers are now aligned with the baseline to prevent issues when list items include icons or other inline elements that affect line spacing. #2117
• PDF: Step section bodies within task topics now honor the $side-col-width value from basic-settings.xsl, which defines a uniform indent relative to the page margin and aligns with other body text. (Earlier toolkit versions used a hard-coded 9-mm start-indent setting.) #2116
• PDF: The index generation process has been rewritten using XSL keys for better performance. The optimizations yield significantly faster PDF builds when using Apache FOP. #2098, #2086
• HTML5 and XHTML table border processing has been optimized to match the expected output based on the table width, column separation, row separation and frame settings in the source files, permit easier integration of CSS frameworks, and output valid documents. #2097
• The task headings (About this task, Procedure, etc.) and flags for Optional and Required steps in the PDF transformation have been synchronized with those available in the common string files, XHTML and ODT transformations. Source files that make use of these options should now yield more more consistent results when generating output in multiple formats. #2088
• PDF: The index groups for Numerics and Special Characters have been aligned for greater consistency across languages. #2080, #2074
• PDF: The “pointing finger” image hand.gif is no longer used to highlight <note> elements, as it may be considered offensive in some cultures. The image file is still available for backwards compatibility with any customization that references it, and the "Note Image Path" variables are still present to permit the use of custom image files, but they are now empty by default. Text-only note labels appear instead, and the default indentation is reduced by the width of the empty note image column.
  Note: The warning.gif file is still used for Attention, Caution, Danger and Warning admonitions.
  #2076, #1577
• The outer.control parameter description was corrected to clarify how the DITA-OT handles content files that are not located in or below the directory containing the master DITA map. #1707 #2066
• Formatter-specific code for XSL-FO rendering engines has been removed from the PDF plug-in and split into separate plug-ins for Apache FOP, Antenna House Formatter and RenderX XEP. #2058
• The classpath order is now retained when generating the env.sh and env.bat environment files to ensure predictable results when a plug-in that uses Java libraries presupposes a certain classpath order. #2053
• The PDF2 flagging step that converted stage1.xml to stage1a.xml in the PDF process has been refactored to take advantage of the flagging information added during the common preprocessing stage. #2049, #2047
• The dita.bat Windows batch file for the dita command now sets the DITA_HOME variable to point to the correct location of the DITA-OT. #2046
• PDF: A new axf.opt parameter has been added to specify the user configuration file for Antenna House Formatter. #2041
• Processing mode coverage has been improved to treat error messages as fatal errors, so the DITA-OT will now stop processing if any source files are missing when the processing-mode parameter is set to strict. #1986
• Table columns for which no width is defined in a <colspec> element are no longer set to 1* per the CALS Table Model. Instead, empty @colwidth attributes are generated to allow formatter-specific auto-layout. The FO processor can then set the width of the columns based on the column content. #1970

Bugs

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

• Inconsistency in naming of flow name, region definition #2128
• Third relcolspec title on a reltable no longer taken into account for publishing #2119
• Topic in temp folder is not wellformed #2109
• gradle build fails with ‘Could not load FFI Provider ..’ on Windows #2108
• Behavior of the force-unique flag #2105
• Site builds fail after html5 changes #2101
• Generated HTML table is invalid according to HTML5 specs #2095
• Fix table and figure list to include number, title #2093
• Remove obsolete info from codepage list #2091
• Add axf.jar into log-processor taskdef classpath #2090
• Add PFD2 index groups for a-breve, a-circ in Romanian #2081
• Ambiguous message for example with two titles #2078
• Table not localized in French translation org.dita.pdf2 - fr.xml #2061
• French translation of Table of contents is incorrect #2060
• Fix ODT title generation #2059, #2034
• Catch null FileInfo object being referenced in move-meta. #2051
• Flagging preprocess grabs too much with check for defaults #2050, #2048
• Error message not properly formatted #2027
• Can no longer publish to XHTML image with data protocol #2012
• Ensuring @chunk inside topicgroups functions as expected. #2009, #1991
• Copy-to usage with URI support does not properly work #2006
• Cannot publish remote HTTP DITA Map to XHTML #2003
• Branch filtering does not seem to work with entire DITA Maps #1992
• Add proper mappings for topicrefs with copy-to attributes in JavaHelp #1989
• Use the fragment part of KeyDef @href attribute when building @conref #1974
• Remove unwanted $PATH2PROJ remnant from $entry-file definition (glossary entry file resolution fails from term and abbreviated-form DOTX058W) #1967, #1966
• DITA-OT 2.0 - Build Error (Windows) - Illegal character - keyref target #1823
• abbreviated-form and term keyref links are not resolved when chunk="to-content" #1816
• Two levels of map ref causes good key ref to fail #1605

Contributors

DITA Open Toolkit Release 2.2 includes contributions by the following people:

1. Jarno Elovirta
2. Robert D. Anderson
3. Roger Sheen
4. Eero Helenius
5. Radu Coravu
6. Tom Glastonbury
7. Kendall Shaw
8. Eliot Kimber
9. Chris Nitchie
10. Stefan Eike

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