DITA Open Toolkit 3.3 Release Notes

DITA Open Toolkit 3.3.4 is a maintenance release that includes the following bug fixes.

• In earlier releases, when a topic contained links to files outside of the map directory (but the map itself did not link to anything outside of the map directory), setting the parameter onlytopic.in.map to true would corrupt those peer links in the topics. This has been fixed, and relative links within topics use the expected path. #3333, #3350
• In earlier releases, when a <link> element without link text also specified attributes that resulted in DITAVAL-based flag images, generated link text used the target document’s file name instead of a title. The link text has been fixed to pull a title from the referenced document. #3346
• When a topic title contains elements with @id attributes, and those topics are converted to PDF, earlier releases would place an extra copy of the ID in <fo:marker> elements used to help with headers. The duplicate ID, which resulted in warnings from some FO processors, has been removed. #3347
• DITA-OT distribution packages are now built and tested with the open-source Java distribution OpenJDK 8. #3348
• In earlier releases, cross references to footnotes in XHTML and HTML5 applied superscript styling too early in the build, resulting in errors from later processing stages. This has been corrected, and the build creates the expected styling without any errors. #3349
• In earlier releases, when a map included an <authorinformation> element that did not provide an author or organization, formatters would generate errors when creating PDF metadata based on that empty metadata. The build has been updated to ignore empty author information in source documents. #3351
• In DITA-OT 3.3.3, we updated XHTML and HTML5 processing to make more efficient use of table metadata when calculating table cell positions for accessibility. That processing failed for some tables that used invalid CALS markup. The processing has been updated to make it more tolerant of incorrect input. #3356

For additional information on the issues resolved since the previous release, see the 3.3.4 milestone and changelog on GitHub.

DITA Open Toolkit 3.3.3 is a maintenance release that includes the following bug fixes.

• The code that generates @headers attributes in HTML-based output formats has been simplified to prevent Saxon crashes when processing complex tables. (These attributes help screen readers to identify the header cells to which table cells are related.) #3313
• In recent (3.x) versions of DITA-OT, flagging information is added before generated links are created, so any flags on the topic reference are ignored. Processing has been updated to copy flags from the <topicref> to the links that are generated to point to that topic. #3317
• Earlier versions of DITA-OT failed to honor the effective @xml:lang attribute value when processing links. This error has been corrected to ensure that the closest language value is preserved on the generated <linklist>, so locale-based headings such as ”Related information” are applied correctly. #3321
• The strings files for each supported language now include default translations for the “Trouble” note label that is used for <note> elements with the @type attribute set to trouble. #3322, #3336
• When generating HTML5 output, DITAVAL files can now preserve profiling attributes by default by setting the @action attribute of a <prop> element to passthrough. Earlier versions of DITA-OT would only pass values through if the DITAVAL filter defined matching attribute/value pairs via specific @att and @val settings. #3325
• The LwDITA plugin has been updated to version 2.3.0 to fix several issues in Lightweight DITA processing. (Nested lists are now properly generated in Markdown output when list items starts with inline markup such as bold, or italics. Topic references with the @format attribute set to html will no longer be interpreted as DITA content. LwDITA-specific processing can be applied to HTML topics by setting the @format attribute to hdita.) #3338

For additional information on the issues resolved since the previous release, see the 3.3.3 milestone and changelog on GitHub.

DITA Open Toolkit 3.3.2 is a maintenance release that includes the following bug fixes.

• Earlier versions of DITA-OT would attempt to download remote media objects referenced via the @data attribute of the <object> element, and failed to copy local media objects to the output folder. Processing has been corrected to handle these references correctly. #2722, #2861, #2947, #3306
• DITA-OT 3.3.1 would generate an invalid catalog file with an empty XML namespace when the bundled version 9.8.0.14 of Saxon Home Edition was replaced with Saxon-HE 9.8.0.15. This has been corrected to ensure that the OASIS namespace is used when generating the catalog-dita.xml file. #3284, #3287
  Note: DITA-OT 3.3.2 still ships with Saxon-HE 9.8.0.14, but now also works with version 9.8.0.15.
• In PDF output, the bitmap warning icon has been replaced with the SVG image previously added for the PDF implementation of the hazard domain. The new image appears in <note> elements of type attention, caution, danger, trouble, and warning and is scaled to match the previous icon size. #3304
  Attention: The legacy warning.gif file remains available in the common artwork folder, but will be removed in an upcoming version.
• Translations of the generated string for “continued” index entries have been added to the Bosnian, Danish, Montenegrin, and Vietnamese localizations. #3310

For additional information on the issues resolved since the previous release, see the 3.3.2 milestone and changelog on GitHub.

DITA Open Toolkit 3.3.1 is a maintenance release that includes the following bug fixes.

• When processing content references in cases with more than one possible target for the @conref value, recent versions of DITA-OT warned about the duplicate ID, but failed to include the reference target in the message. The DOTX011W warning now restores this context to aid in troubleshooting. #3248
• When processing source files with tables or figures in <draft-comment> or <required-cleanup> elements, earlier versions of DITA-OT included them in lists and numbered references even when DRAFT output was not active. Hidden elements are now excluded from lists of figures and tables, and when numbering references. #3249
• The @type attribute of the args.css and args.cssroot parameters has been changed to string to better support values that include relative paths. The transtype has also been corrected to string. #3251
• When copying files to a temporary file scheme that flattens the directory structure, the map-first preprocessing routine will now correctly handle indirect content references defined via @conkeyref. #3260
• The integrator and topic reader modules have been modified to use an alternative method supported by the XML APIs library to prevent errors when compiling the toolkit’s JAR file. #3272, #3273
• The dita command now uses a secure connection to the plug-in registry when installing new plug-ins. #3278
  Attention: To ensure data integrity during the plug-in installation process, Transport Layer Security (TLS) will soon be required to access the plug-in registry. If you are using DITA-OT 3.3, 3.2, or 3.2.1 and are unable to upgrade to 3.3.1, modify the registry key in the config/configuration.properties file to switch the URI schema to https://, so the entry reads https://plugins.dita-ot.org/.

For additional information on the issues resolved since the previous release, see the 3.3.1 milestone and changelog on GitHub.

DITA Open Toolkit Release 3.3 includes new attribute sets for HTML5 customization, support for custom integration processing, rotated table cells in PDF output, and hazard statements in HTML output.

Feature Highlights

DITA Open Toolkit Release 3.3 includes the following new features:

• The @rotate attribute on table <entry> elements, which was added in the DITA 1.3 specification, is now supported in PDF output. #1778, #2717, #3161

• A new CustomIntegrator interface provides a mechanism for custom plug-ins to extend the default integration process via service provider classes declared via a Java ServiceLoader. #3175

• HTML5 and XHTML output now provide generic hazard statement styling based on the ISO 3864 and ANSI Z535 standards, with an SVG icon and Sass variables for the corresponding ISO and ANSI color definitions. The ANSI colors are used by default to match the PDF styling previously added in DITA-OT 3.2. #3207, #3231

• A series of new attribute sets has been added to the default HTML5 transformation to facilitate customization with additional ARIA roles, attributes, or CSS classes. Attribute sets are provided for:

  • article
  • banner
  • footer
  • main
  • navigation
  • toc

  If you have previously copied XSL templates (or template modes) to custom plug-ins only to add classes required by web frameworks such as Bootstrap or Foundation (or your company CSS), you may be able to simplify your customizations by using the new attribute sets instead of overriding the default templates.

Enhancements and changes

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

• The dita command now recognizes a wider range of “truthy” property values, including true, yes, 1, and on and handles inconsistently cased values more gracefully. #2225, #3197
• Various XSLT files and other resources have been moved from the root of the DITA-OT installation directory to the base plug-in directory plugins/org.dita.base. #3157 (If your plug-ins use the plugin URI scheme as recommended in the Plug-in coding conventions, this change should not require any modifications to custom plug-in code.)
• The templates key in configuration properties has been deprecated in favor of the <template> element in plugin.xml. #3176
• In HTML5 output, task <steps> are now wrapped in <section> elements and DITA <example>, <prereq>, and <stepsection> elements are also generated as HTML5 <section> elements. #3177
• Java code has been refactored to add missing DITA classes to the list of available Java constants and re-sort the constant definitions. #3178
• Custom <pipeline> modules can now use SAX filters. This makes it possible to configure the module’s behavior at the Ant level and add additional processing to a module. Modules do not have to define nested filters if they prefer not to expose this extension point or do not use SAX internally. #3182

  <pipeline>
    <module class="com.example.Module">
      <filter class="com.example.XmlFilter"/>
    </module>
  </pipeline>

• New extension points have been added to contribute parameters to the debug-filter, map reader, and topic reader Java preprocessing modules. #3187
  • dita.preprocess.debug-filter.param
  • dita.preprocess.map-reader.param
  • dita.preprocess.topic-reader.param
• The DITA-OT fork of the jing-trang project used to provide RELAX NG schema validation in DITA-OT 3.2 has been replaced with the upstream code after the patches provided by George Bina were included. #3188
• Several bundled dependencies have been upgraded to the latest versions. #3191
  • Ant 1.10.5
  • Jackson 2.9.8
  • Saxon-HE 9.8.0-14
  • Xerces-J2 2.12.0
• An additional keyscope test has been added to test interactions with submaps referenced via <mapref>. #3193
• The default character set for code references can now be changed by adding the default.coderef-charset key to the configuration.properties file. The character set values are those supported by the Java Charset class. #3195
• The <ditafileset> now supports nested <includes> and <excludes> elements to more easily control which files get processed (or do not get processed) by each processing step. The copy-files task has been been moved to the end of the preprocessing pipeline to match the order in map-first preprocessing (preprocess2). #3196
• The Gradle build system has been updated to the latest patch release (5.2.1). #3204
• When source files contain an empty conref="" attribute value, DITA-OT now provides a meaningful warning and then ignores this construct, which previously resulted in parser errors. #3217
• Along with the other base plug-in files, the catalog-dita.xml file has been moved from the root of the DITA-OT installation directory to plugins/org.dita.base. External systems that rely on this catalog should be updated with the new location. Ant scripts and DITA-OT plug-ins should use the plug-in directory property to refer to the file as ${dita.plugin.org.dita.base.dir}/catalog-dita.xml. A placeholder with a <nextCatalog> entry is provided in the original location for backwards compatibility, but this file may be removed in an upcoming release. #3230

Bugs

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

• In earlier releases, external URIs referenced via @keyref from within relationship tables resulted in links with broken link text. This has been fixed, and metadata including link text or titles is preserved for external URIs referenced by key within a map. #1439, #3179
• Relative paths in peer or non-DITA key references were not handled correctly in earlier releases. The paths are now adjusted as needed to stay valid in any referencing location. #1951, #2250, #2581, #2620, #3234
• Several fixes have been added to improve support for the @chunk attribute on topic groups (covering both <topicgroup> and any other <topicref> style container that does not reference a file). #2428, #2730, #2843, #3216
  • In earlier releases, using chunk="to-content" on a grouping element within another branch or map that specified chunk="to-content" would result in a NullPointerException. This error has been fixed.
  • In earlier releases, using chunk="to-content" on a nested map would result in the same NullPointerExceptions when the map reference was inside of a chunked branch or map.
  • In earlier releases, <topicgroup> elements with no title that used chunk="to-content" would result in a generated heading in the output file, such as "Chunk1234567". Chunked containers without a heading will no longer result in a generated heading in the output.
  • In earlier releases, <topichead> elements inside of a chunked branch would result in headings that appeared out of order for PDF. This has been fixed; topic headings will appear where expected in the PDF flow.
• In earlier versions, references to keys in local scopes were not processed correctly. In certain other cases, files referenced through mapref were parsed with the root scope instead of their parent scope. Keyref parsing has been improved to reliably detect and preserve key scopes to ensure that all key references are resolved in the correct scopes. #2523, #3141, #3194
• In some recent releases, cross references to local, non-DITA files with formats such as "pdf" or "txt" did not copy those referenced files to the output directory. When appropriate, such as when generating HTML output, these files are now copied to the output directory as they were in earlier releases. #2899
• On Linux and other systems where the DITA-OT installation directory and temporary directory are not on the same volume, plug-in installation would fail when DITA-OT tried to move a non-empty directory. The installation process has been refactored to ensure that plug-ins are correctly installed in these cases. #3162, #3238, #3239
• In earlier versions, setting an @id attribute on a <dt> created duplicate IDs in the XSL-FO file, which caused warnings when rendering FO to PDF. #3180, #3185
• The plugin.rnc RELAX NG Compact Syntax schema used to validate plug-in descriptor files was inadvertently removed from the distribution package and has been restored. #3183, #3220
• The codeblock normalization process would sometimes fail to recognize certain combinations of characters at the beginning of code blocks, resulting in error messages. These adjacent text events are now merged before the indentation is adjusted. #3198
• In earlier releases, some indirect key references to glossary entries could result in XSLT errors when more than one possible key target existed. This is corrected by using the single desired target to resolve such links. #3210
• When the input file set contained resources with different URI schemes (for example local files and external files referenced via HTTPS), earlier versions of DITA-OT would fail with errors. Preprocessing routines have been corrected to ensure the the base directory is correctly calculated in these cases. #3211
• When generating HTML5 output with the nav-toc parameter set to partial, earlier versions would fail to insert table-of-contents navigation in topics whose names contained spaces. The path normalization process has been corrected to ensure that spaces in file and directory names are correctly URL-encoded as %20, and navigation is included. #3213, #3229
• In earlier releases, some revision properties were ignored on <tm> elements in PDF output. This is now corrected, so that revision flagging such as text color or background color are properly supported on trademarks. #3214, #3215
• In documentation and error messages about available transformation types, extensions of an existing transformation could result in duplicate values (such as 3 instances of "pdf"). Duplicates are now removed when listing the available transformation types. #3219
• In earlier releases, duplicate conditions in DITAVAL properties (such as using two DITAVAL documents for a build that each set up rules for rev="rev3") would generate a warning. This message has been reduced in severity and will now appear only as an informational message with verbose logging. #3223
• In earlier releases, content references on elements that specified href="-dita-use-conref-target" would evaluate that value as a literal file name. That token (defined in the DITA specification) is now ignored on elements that also use @conref. #3224
• Revised figures and tables are now marked with change bars in booklists when DITAVAL files define flagging for the corresponding revision values. #3235
• The command line syntax for the dita --install option has been updated to support the “=” equals sign. #3245
  Both of the following formats are now supported:

  dita --install=plug-in-zip
  dita --install plug-in-zip

Contributors

DITA Open Toolkit Release 3.3 includes code contributions by the following people:

1. Jarno Elovirta
2. Robert D Anderson
3. Roger Sheen
4. Simen Tinderholt
5. Eliot Kimber
6. Eric Sirois

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

Documentation updates

The documentation for DITA Open Toolkit Release 3.3 provides corrections and improvements to existing topics, along with new information in the following topics:

• Prerequisite software
• Arguments and options for the dita command
• Generating revision bars
• Adding plug-ins via the registry
• Adding a Java library to the DITA-OT classpath
• Adding Saxon customizations
• Pre-processing extension points
• Migrating to release 3.3

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

DITA Open Toolkit Release 3.3 includes documentation contributions by the following people:

1. Roger Sheen
2. Eliot Kimber
3. Robert D Anderson
4. Jarno Elovirta
5. Quick van Rijt

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