DITA Open Toolkit 2.3.3 Release Notes

DITA Open Toolkit Release 2.3.3 includes the following bug fixes.

• Lax processing now tolerates hyperlink references with leading or trailing whitespace in the @href attribute value, such as:

  <xref href=" http://www.example.com" format="html">

  Earlier versions of DITA-OT would convert the space to its URL-encoded equivalent %20 and fail with an error. The URI validation routines have been modified to issue a warning and continue processing in lax mode, but still fail in strict mode. #2440, #2488
• In certain cases, earlier versions of DITA-OT resolved relative paths to related links from the temporary directory rather than from the input DITA map file. Processing has been modified to ensure that links are generated correctly regardless of the target file location. #2017, #2444
• Several errors in the DITA 1.3 subjectScheme catalog file were corrected to ensure that the module files and entities for the DITA Map Subject Classification Domain are properly resolved. Corresponding errata have been submitted to OASIS to ensure the fixes are applied to the official catalogs. #2458
• Related link processing has been adjusted to handle cases that generate empty related links groups. #2464
• The mappull preprocessing step that pulls content from referenced topics into maps has been updated to use the XML catalog to resolve external entity references to their locally cached equivalents. #2470
• In PDF output generated by earlier versions of DITA-OT, roman numerals were used to number pages in the Notices section, assuming notices are most commonly located in the front matter, which uses roman numbering by default. The toolkit now checks whether the <notices> element is inside <backmatter>, and uses arabic numbering as appropriate. #2474
• When processing topics with unsupported languages, DITA-OT erroneously claimed it couldn't find the language en_us rather than mentioning the unsupported language. The DOTX001W message now includes the original, most complete value of the ancestor language to assist in troubleshooting. #2477
• In DITA-OT 2.3.2, reference targets for link-like elements such as <abbreviated-form> in short descriptions were incorrectly calculated in some cases. Processing has been updated to ensure that links are correctly resolved by adjusting references as necessary to match the path to the target document. #2482
• The copy-to processing routine failed to update image paths, resulting in invalid references in topics copied to locations other than the original or peer directories. Processing has been updated to ensure that image references are adjusted as necessary to reflect the location of the referencing document. #2486
• PDF: Definitions for several missing localization variables have been added to the Finnish, Romanian, Russian, and Swedish strings files. #2487

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

DITA Open Toolkit Release 2.3.2 included the following bug fixes.

• In earlier versions of DITA-OT, relative paths to cross-references from short descriptions were sometimes interpreted incorrectly if the source and target topics were located in different directories. New XSL functions now ensure that these references are correctly resolved. #1599
• In DITA-OT 2.3, the HTML5 transtype failed on topics with tables when the args.xhtml.classattr parameter was set to no. Processing has been updated to handle these cases and correctly exclude the DITA class ancestry information when publishing HTML5 output. #2413, #2424
• In DITA-OT 2.3, the PDF2 build target dependency list contained redundant entries. The integration process has been corrected to remove the duplicates. #2439, #2451
• The script that checks for Antenna House installations has been updated to include installation paths with spaces as used by recent versions of Antenna House for Windows – C:\Program Files\Antenna House and the (x86) equivalent. #2441

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

DITA Open Toolkit Release 2.3.1 included the following bug fixes.

• The distribution package for the 2.3 release included several unnecessary subfolders and appended the Git commit ID to the version number in the lib/configuration.properties file. The extra directories have been removed and the otversion in the properties file has been corrected. #2395
• In DITA-OT 2.3, temporary file folders specified via the dita.temp.dir parameter were interpreted as relative to the folder where the Java process started. This regression has been fixed to ensure that temporary folders are once again interpreted as relative to the base directory of the Ant process as in previous toolkit versions. #2398
• On Windows, the dita command would not run correctly if the name of a folder in the path to the DITA-OT 2.3 installation directory included spaces. The dita.bat script has been modified to support installation paths with spaces. #2400
• The DITA 1.3 DTD, Schema, and RNG files have been updated to the final "OASIS Standard" copy; this change updates the OASIS link and date in many header files, but does not affect how the grammar files work. In addition, the catalog has been updated to restore two entries that will eventually be shipped in the DITA 1.3 Errata from OASIS. #2401
• Fixed an issue where some front-matter sections, such as <draftintro> and <bookabstract>, caused page numbering to switch back and forth between Roman numerals and body-style Arabic numerals. #2408

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

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

Single .zip distribution package

DITA Open Toolkit now ships as a single distribution package in a .zip archive, as modern versions of Linux and OS X no longer have the file permission issues that originally required the additional .tar.gz distribution package. #2269

Enhanced HTML5 output

The HTML5 table processing has been refactored to use valid HTML5 markup, HTML5 best practices, and better CSS properties for styling. BEM-style CSS classes are now generated with the name of the containing element, the name of the attribute, and the value of the attribute. #2239

Common CSS files are now generated using separate modules for each DITA domain, implemented as Sass partials to better support extensions with CSS frameworks, custom plug-ins and future toolkit versions. #2195, #2196, #2218, #2369

New language support

PDF, HTML, and XHTML transformation types have been updated to support Bosnian, Montenegrin, and Vietnamese, including localized string files and (for PDF) index collation. #2150, #2360

Internationalization improvements

Features

DITA Open Toolkit Release 2.3 includes the following new features:

• The args.eclipsehelp.toc parameter for Eclipse Help, which has not worked properly for several releases after it was made obsolete in DITA-OT 1.3, has been removed. #1116, #2354
• DITA 1.3: Initial support has been added for the @orient attribute on <table> elements. These changes allow Antenna House Formatter to render tables in landscape mode when the @orient attribute is set to land. A future release will provide extended support for multi-page landscape tables with additional rendering engines. #1777, #2387
• To permit automated building and testing on any platform, the HTMLHelp version of the documentation is no longer included in the distribution package. An HTMLHelp version of the documentation can still be built on Windows using the downloaded distribution package. #2130
• SAX pipes can now be configured in Ant <pipeline> tasks. This allows new tasks to take advantage of in-memory processing without the need to write out files to disk. #2144
• The process for generating topic headers in the PDF transformation type has been simplified to use a single template with mode="insertTopicHeaderMarker". This reduces the amount of work needed to format titles differently in the header and body. #2155
• The HTML5 transformation type supports two new extension points dita.conductor.html5.param and dita.conductor.html5.toc.param, allowing plugins to provide new parameters for HTML5 processing. #2185
• Processing for @copy-to has been moved out of the gen-list preprocessing module and into a separate step. This improves processing for <topicref> elements that use @copy-to and @keyref. #2210
• The DITA-OT preprocessing step that reads images for information about height and width now supports reading dimension metadata from SVG images. #2230
• The PDF transformation type has been updated to support the @expanse value "page" for elements that use the attribute. In addition, the <msgblock> element has been updated to support @frame and @scale, which generally appear on the same elements that use @expanse. #2317, #2352
• Cross-references to footnotes now generate hyperlinks in PDF output. #2359, #2364

Enhancements

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

• PDF: Information from the README.txt files in the org.dita.pdf2 plugin have been moved to the “PDF plug-in structure” topic in the DITA Open Toolkit Developer Reference. Now that all useful information is available in the documentation, the README.txt files have been removed. #1860
• PDF: In earlier versions of DITA-OT, filtering out all rows from a <simpletable> element resulted in invalid XSL-FO. When all rows are filtered out, the XSL-FO file now contains an empty (but valid) table so that processing can continue. #1924, #1950
• Guava libraries are now used to simplify access to collections in Java code (among other things). #2122
• HTML: The documentation for the args.hdr and args.ftr options now clarifies that header and footer files must be specified using an absolute path. The options have always required an absolute path, but the documentation for earlier releases did not include this requirement. #2133
• The dita command will now run using Java headless mode by default. This optimizes the use of system resources during a build and prevents the build process from stealing focus from other applications. #2140
• HTML: Static text for XHTML tables and figures (such as "Table 5") is now surrounded with a <span> element, making it easier to style or hide the static text using CSS. In addition, HTML5 output is updated to use semantic elements for figure and table captions. #2160
• Two members of the AbstractPipelineModuleImpl class have been marked as protected, to allow plugins to access them from derived classes. #2177
• PDF: The I18N Java and XSLT processing code has been merged into single task. This is not visible to most users of the PDF code, apart from a reduction in processing time. It also eliminates the need for a stage3.fo file in the temporary directory; instead, topic.fo is generated directly from stage2.fo. #2179
• In a previous release, the HTML5 extension point dita.conductor.html5.param was declared but not implemented. The improper declaration was removed and the extension was properly implemented. #2181
• HTML: In previous releases, short descriptions in <abstract> elements were rendered as division elements (<div>), rather than paragraphs (<p>). Processing has been revised to ensure that short descriptions are consistently rendered as paragraphs, regardless of whether they appear in <abstract> elements. #2191
• The order of the chunk and move-meta-entries pre-processing stages has been switched so that chunk comes first. This ensures that metadata is properly pulled or pushed into the chunked version of DITA topics. #2207
• HTML: The process for handling @othertype on a <note> element in HTML has been updated to use XSLT 2.0 best practices. #2217
• PDF: Earlier versions used an <fo:inline> element as a link target within topic titles, which can result in extra white space for certain common customizations. The process now places an ID on <fo:wrapper>, which removes the extra element and extra white space. #2229
• XSLT processing now uses a single parameter for message IDs rather than combining one parameter for the error number with another parameter for severity. This simplifies message processing and allows a greater range of message IDs in the future. In addition, the DOTX071W message will display a warning for customizations that use the older, deprecated parameters. #2231
• Common XSLT utility templates have been rewritten as functions. In addition, XSpec tests have been created so that the functions are now covered by automated DITA-OT testing. #2233
• The distribution integration and docs stages of the build process are now run in a forked JVM . #2241
• PDF: A reference to the PDF2 catalog has been added to catalog-dita.xml. In previous releases, running topic2fo_shell.xsl directly would fail because the XSLT processor couldn't resolve paths that use the cfg: scheme. #2249
• The distribution package is now built via a fully automated Continuous Integration process. #2268
• HTML5: A new stable ID generation process has been implemented, instead of relying on the generate-id() function. By removing reliance on a dynamic value, this change enables automated testing of @id and @headers (generated for table accessibility). This also speeds up regression testing when comparing HTML output with previous versions. #2276
• A new ditaFileset function has been implemented to replace list files. This has no visible impact for builds, but improves the processing model overall and allows the older way of working with individual list files to be deprecated in a future release. #2277
• The build script for HTMLHelp, build_dita2htmlhelp.xml, now uses an environment variable to locate the HTMLHelp compiler. This allows the process to build a CHM file when the HTML Help Workshop is not installed on the C: drive. #2288
• HTML5: new extension points allow for customization of HTML5 output, HTML5 TOC processing, and HTML5 cover processing. These extension points were declared (but not implemented) in DITA-OT 2.2; this was addressed in 2.2.5 by removing the declarations. In DITA-OT 2.3, the declarations are restored and properly implemented. #2305
• The startcmd scripts are now generated by the DITA-OT integration process. This ensures that the CLASSPATH setting in the scripts is updated with any new or required Java libraries referenced by custom plug-ins. #2341
  Important: Users who still run DITA-OT using a custom start script based on a copy of startcmd may need to update their script after installing custom plug-ins. The CLASSPATH declarations are stored in alphabetical order, so they should only change when new plug-in libraries are added. To avoid these issues, run DITA-OT using the dita command instead of the deprecated startcmd scripts.
• PDF: Index group headings now appear in the PDF bookmarks. The new bookmarks will always appear in collapsed form under the Index heading. For example, a large index that covers every heading in English will now have bookmarks for "Special characters", "Numerics", and every letter from "A" to "Z". #2350
• PDF: The antiquewhite background color has been removed from table heads and key column contents in <simpletable> and <properties> tables to synchronize presentation with <choicetable> and provide a more uniform customization baseline between PDF output and HTML-based formats. #2382, #2386
• Localization variables that are no longer used in PDF processing have been deprecated and will be removed in an upcoming release. #2383

Bugs

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

• PDF: The message "No topicTitleNumber mode template" has been removed. This removes extraneous messages that appeared when processing a bookmap with <notices> or <bookabstract>, or which refers to a subject scheme map. #1931
• HTML: trademark symbols previously only appeared for <tm> elements in English and a select few languages. This was a legacy of processing carried over from beta processing before DITA-OT 1.0; HTML trademark processing will now work the same regardless of document language. #2065
• Processing for <coderef> elements could be broken when the <coderef> was part of a larger section reused by conref. This is fixed by resolving <coderef> during the topic-fragment step of preprocessing. #2141
• The AXF document-info attribute @title is deprecated; XSL-FO output for Antenna House output should use the @document-title attribute instead. #2161, #2162
• When using keys, referencing a file outside of the current directory causes processing to fail. Previously, the target file URI was resolved against the root of the temp directory. This has been updated to resolve the URI against the source file URI, which should always yield the correct result. #2190, #2223
• In previous releases, specializations of the <link> element did not work as intended. The corresponding XSLT template mode related-links:link has been modified to properly handle new elements that are based on the <link> element. #2197, #2199
• Circular key definitions, when an element used @keyref to refer to a key on the same element, resulted in a stack overflow in KeydefReader. This construct is now reported as an error with message DOTJ069E. #2227
• Publishing failed when using <term> with keyref and chunking, as the chunking module created file references with backslashes. Processing has been updated to convert any backslashes to slashes before using the resolve-uri function in XSLT. This ensures that the attribute values are valid URI references according to RFC 3986. #2243
• PDF: In the simplified Chinese variables file (zh-CN), additional translations have been provided for some static strings that previously appeared in English. #2294, #2353
• Resource-only topic references were considered duplicates by key processing, resulting in renamed output files in some cases. The resource-only instances are now ignored when determining whether to rename output files. #2304
• PDF code was cleaned up to remove a broken message that could not be triggered #2326, #2351
• In previous releases, specifying a @keyscope attribute on the root <map> element would cause builds to fail. Processing has been modified to handle this situation correctly. #2339

Contributors

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

1. Jarno Elovirta
2. Robert D. Anderson
3. Eero Helenius
4. Roger Sheen
5. Eliot Kimber
6. Radu Coravu
7. Shane Taylor
8. Stefan Eike
9. George Bina
10. Kristen James Eberlein

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

Documentation updates

The documentation for DITA Open Toolkit Release 2.3 includes corrections and improvements to existing topics, along with several notable enhancements, including:

• The DITA Open Toolkit User Guide includes new topics on additional methods of publishing via the dita command:
  • Using a properties file
  • Migrating Ant builds
• The DITA Open Toolkit Developer Reference includes several new sections dedicated to customization:
  • Customizing PDF output provides an overview of approaches commonly used to customize the default PDF output and includes recommendations on best practices and additional resources.
  • Migrating customizations highlights customization-related changes in recent releases to assist plug-in developers in updating overrides to work with the latest toolkit versions.

• Travis CI continuous integration is used to automatically publish the latest development version of the documentation on the project website at dita-ot.org/dev whenever changes are pushed to the develop branch of the dita-ot/docs repository on GitHub.

• In the latest development version of the documentation, page footers now include Edit this page links that open the DITA source file for the topic in oXygen XML Web Author.

  The web-based authoring workflow prompts users to log in to GitHub and fork the dita-ot/docs repository if necessary. Changes saved in the authoring environment are committed to a new branch, and a pull request is created to submit changes for review by the DITA-OT documentation team.

For additional information on documentation issues resolved in DITA Open Toolkit Release 2.3, see the 2.3 milestone in the documentation repository.

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