DITA Open Toolkit 2.5.4 Release Notes

DITA Open Toolkit Release 2.5.4 includes the following bug fixes.

• In earlier releases, plugins that contributed variables (or strings) did not work when the variables were contributed with mixed case (such as pt-BR instead of pt-pt). This has been fixed, so that the case of @xml:lang is ignored when contributing variables. #2226, #2790, #2803
• In DITA-OT 2.5, external cross references to DITA topics, such as <xref href="http://example.com/onlineTopic.dita" scope="external">, resulted in build failures due to an improperly set XSLT variable. This setting has been corrected to ensure external references are resolved as expected. #2772
• External links in <related-links> collections were dropped from PDF output in DITA-OT 2.4 and 2.5. These links now appear using the @href attribute value as link text, as in earlier releases. #2795, #2802
• In DITA-OT 2.5, cross references to targets within the same document, such as <xref href="#topicid/sampleFigure"/>, caused build errors when the onlytopic.in.map parameter was set to true. Processing has been corrected to ensure these links are generated correctly. #2800
• In DITA-OT 2.4 and 2.5, the <property> element in reference topics resulted in an "Ambiguous rule match" message from Saxon when building HTML5. This message has been removed. #2801
• In earlier releases, when chunk="by-topic" was specified on a <topicref> element that did not specify the @href attribute, the build would end in a null pointer exception. This error has been removed and the build will continue. #2805
• In earlier releases, when a map reference (such as <mapref>) referred to a map in a subdirectory, and that referenced map included elements with @conref attributes, the step that resolved map references did not properly adjust paths in @conref, resulting in unresolvable content references. This has been fixed, and @conref attributes in nested maps in subdirectories now resolve properly. #2806

• The documentation includes minor changes with corrections and improvements to existing topics.

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

DITA Open Toolkit Release 2.5.3 includes the following bug fixes.

• In DITA-OT 2.5, the gen-list pre-processing step listed resource-only references with @scope="peer" as local files when the onlytopic.in.map parameter was set to true. This caused later processing steps to generate errors as they tried to read the peer files (even when they were not DITA). Pre-processing has been updated to avoid reading these files, which also removes the build errors. #2759, #2761
• In previous versions of DITA-OT, the copy-files pre-processing step would stop the build with an error if the destination directory for copied files did not (yet) exist. The copy process has been adjusted to create the destination directory if necessary and allow the build to continue. #2768
• DITA-OT 2.5 would crash when publishing maps that contained <ditavalref> elements without valid hyperlink references in the @href attribute. Pre-processing has been updated to be more tolerant in these cases. The branch-filter step will now proceed as if the <ditavalref> were not specified, which allows the build to finish. #2769

• The documentation includes minor changes with corrections and improvements to existing topics.

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

DITA Open Toolkit Release 2.5.2 includes the following bug fixes.

• In DITA-OT 2.5.1, the mappull step could fail when a map referenced a DITA document where the root element was filtered out. The filtered document is now processed correctly. #2743
• In the original 2.5 release, setting a revision property to "flag" in the DITAVAL resulted in build errors if the DITAVAL did not also specify a start and end image for that flag. The build errors no longer appear. #2749

• The documentation includes minor changes with corrections and improvements to existing topics.

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

DITA Open Toolkit Release 2.5.1 includes the following bug fixes.

• In DITA-OT 2.5 and earlier, key resolution did not comply with the DITA specification’s requirement to use <linktext> from a key definition as valid replacement text for all uses of that key. #1590, #2014, #2719

  In addition, several less common cases are fixed:

  • Previously, a <keyword> anywhere within the key definition was used as the first choice for link text, even if that keyword was located within <linktext>. As defined by the DITA specification, the replacement keyword is taken only from within <keywords>.
  • Previously, the @navtitle attribute was used as fallback text in some cases, while <navtitle> was ignored. The <navtitle> element is now used before checking the deprecated @navtitle value for all cases.
  • Previously, @navtitle was used as link text even for local DITA topics where that value was ignored in favor of a navigation title in the topic. Now @navtitle and <navtitle> are only used when locked or when the topic is not local DITA.
• In some cases, invalid DITA content resulted in build crashes from PDF, XHTML, or HTML5 processing modules that expect required elements to be present. For example, this could happen when an element such as <ol> (which requires at least one list item) used DITAVAL filtering to exclude all items from the list. The code has been updated to more gracefully handle elements that are missing required children. #2701, #2712
• One DITA 1.3 RNG module in the grammar files for the DITA 1.3 specification contained a typo in a default attribute value. The typo will be corrected in the next DITA 1.3 errata, and is now fixed in the DITA-OT copy. #2705
• On Windows only, chunking a DITA document using the "by-topic" method would lose the root chunk and result in processing errors. The chunking process has been updated to handle Windows file paths correctly; the chunking process now produces the same results on all systems. #2706, #2728
• HTML5 output restores support for the @spectitle attribute on <simpletable> elements and for the @specentry attribute on <stentry> elements. Support for those attributes was missing after the HTML5 and XHTML code bases split in release 2.4. #2714
• In the original 2.5 release, a <topicref> that included a reference to a local topic ID (such as href="file.dita#root") could cause build failures when another element in the document used the same ID. The reference is now handled properly. #2716

• The documentation includes minor changes with corrections and improvements to existing topics.

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

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

Java Application Programming Interface

DITA-OT 2.5 includes a new Java API to allow developers to embed DITA-OT more easily into other Java programs. #2604

Map-first preprocessing

DITA-OT 2.5 introduces an experimental map-first preprocessing option as an alternative to the default preprocess operation. The new method provides the same functionality, but takes a different approach.

Whereas the default preprocessing routine handles both maps and topics at the same time, the map-first approach begins by processing maps as far as possible, and only then starts processing topics. This simplifies the processing logic and creates cleaner module responsibilities, which makes it easier to process only those topics that are actually referenced after filtering, for example, or to only process the map to validate the map structure.

See Experimental map-first preprocessing, #2497

Improved PDF support for DITA composite documents

When publishing PDF output from a DITA composite document (a DITA document with a root <dita> element), earlier versions of DITA-OT included only the first topic, and links to topics within <dita> elements were broken. The PDF output now includes the full content of the referenced document, and links to any element within the document are correct. #1077, #1904, #2679

Attributes from the <dita> element are now preserved when merging topics. In previous releases, attributes like @xml:lang set on the <dita> element were lost during the PDF "topic merge" process. #1298, #2698

Publishing with multiple DITAVAL filter files

The args.filter parameter, which previously allowed you to specify a single DITAVAL file for filtering or flagging, now accepts a list of URIs. The system path separator character is used to delimit individual file paths in the list of values (semicolon ‘;’ on Windows, and colon ‘:’ on macOS and Linux). DITAVAL files are evaluated in the order specified, so conditions specified in the first file take precedence over matching conditions specified in later files, just as conditions at the start of a DITAVAL document take precedence over matching conditions later in the same document. #2637

This feature allows you to manage your conditions independently or combine conditions from multiple sources. For example, you can now manage your filter conditions (that might change rarely) separately from revisions, or easily combine flagging conditions from different products when those products are published together.

You can then pass the filenames to the dita command as follows:

dita --input=userguide.ditamap --format=pdf --filter=filters.ditaval:flags.ditaval

DITAVAL properties are now more flexible so that plug-ins can provide a common set of DITAVAL conditions and override the args.filter parameter. Initialization code has been cleaned up so that it does not set unnecessary properties. #2681

Default PDF style improvements

Several legacy styles have been modified or removed in the default PDF plug-in org.dita.pdf2, including the following:

A separate org.dita.pdf2.legacy plug-in can be used to restore the original settings. See Migrating to release 2.5, #2519.

Features

DITA Open Toolkit Release 2.5 includes the following new features:

• The PDF transformation now uses variables to control ordered list numbering and unordered list bullets. This allows list styles to be more easily configured in overrides or by locale. #1134
• In PDF output, monospaced elements now inherit the font size from their parent elements. In earlier versions, the base-font attribute-set caused monospaced elements to reset font sizes unnecessarily. Removing these extra calls to base-font allows monospace elements to retain the current font size. #1230
• A new property named remove-broken-links is available to automatically remove any unresolved links. Setting the parameter to true will remove map-based links that do not resolve, as well as links coded within <related-links>. The default value is false. #1431
• The copy-html step in the pre-processing stage has been updated to work like copy-image, with a parameter for the destination directory. This allows more flexibility for extended transformation types that use these targets. #1964
• DITA-OT now processes DITA elements nested within <foreign> and <unknown> elements. Previously these elements were ignored and treated as part of the <foreign> or <unknown> content, so that (for example) @conref targets were not retrieved and links were not properly handled. #2569
• A new internal parameter named temp.output.dir.name allows plugin developers to direct output to a location within the existing temporary directory, which allows for additional post-processing before files are placed in the output directory. #2670
• Eclipse Help output can now be created as a JAR file. When the args.eclipsehelp.jar.name property is specified for an Eclipse build, the generated content will all be zipped in a JAR file with the name taken from that property. #2684
• A new path2rootmap processing instruction is now added to topics in the temporary directory that includes a relative path to the root map. This helps to preserve links when generating output for content that is not located in or beneath the directory containing the DITA map file. #2707

Enhancements and changes

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

• DITA-OT now works with Saxon-HE (home edition) 9.4.0.3. Some XSLT modules in earlier versions relied on Java extensions that are not available in Saxon-HE; those dependencies have all been removed. #1238, #2668
• Product name processing has been revised to better support overrides in PDF customizations. The existing text-only mode is now used to enable customizations to support elements that add text (such as trademark symbols). #2293, #2693
• Earlier versions of DITA-OT created empty and unnecessary <fo:inline> elements for some elements when generating PDF output; those empty elements have been removed. #2419
• An <abbr> abbreviation wrapper has been added to <menucascade> output for improved HTML5 and XHTML accessibility. This allows screen readers to detect and read the right angle bracket > submenu separator that appears between menu items as accessible text. In English, for example, this will be read as “and then”. #2446, #2516
• PDF output did not properly evaluate DITAVAL flagging conditions for <step> and <choice> elements within tasks, or for root topic elements. In addition, topics in sub-directories did not render image flags properly for any elements. These issues are all resolved. #2459, #2674
• Error messages in dita command output now appear in red on terminals that support ANSI escape codes, such as on Linux or macOS. The new property cli.color can be set to false to disable the color. (Colored output is not supported on Windows consoles such as cmd.exe or PowerShell). #2552
• The args.logdir and args.debug properties have been deprecated. To write the log to a file, use dita --logfile=file or ant -l file to set the path to the log. #2579
• Plug-in configuration has been extended to support configuration of parser features. For example, you can now toggle XInclude processing or change error recovery options. #2594
• The file info filter configuration has been generalized to allow all modules to be configured via Ant. #2601
• In earlier versions, invalid IDs in a topic could break the build with a Null Pointer Exception if the topic was used twice in a map. Processing for topics that appear more than once has been improved to avoid this condition. #2657
• DITA-OT now uses Saxon functionality to write XSLT messages to a logger instead of to standard output. This provides a more consistent approach to logging messages across all modules. #2664
• Earlier processing for branch filtering could place <ditavalref> elements ahead of <topicmeta>, which would not be valid in a source map. Pre-processing has been revised to ensure the map remains valid after the branch filtering process. #2672
• The bundled Ant version has been updated to 1.10.1. #2677
• A common set of string variables is now used for the localized quotation marks that are used to wrap quotations in <q> elements; previous versions had one set of variables for PDF and another for other transformation types. #2703

Bugs

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

• In previous releases, when a child map specified the @chunk attribute on the <map> element, the resulting generated map in the temp directory no longer had the @chunk attribute. The attribute is now preserved. #1210
• In earlier releases, resource-only topics would generate HTML5 and XHTML topics when they were used as the target of a content reference; topics referenced from resource-only topics also generated output even when the parameter onlytopic.in.map was set to override this behavior. Processing has been modified to ensure these extra files are no longer generated. #1734, #2077, #2694
• In previous releases, root level containers in a bookmap were dropped from PDF if they did not have a title or reference a topic. This occurred with <preface>, <chapter>, <appendices>, <appendix>, and any grouping element in the front or back matter. In addition, PDF builds would fail if a grouping element without title or @href was the only child of a map. These are all fixed by letting processing fall through to topics within the group. #1848, #2092, #2614, #2648, #2683
• Links directly to nested topics in HTML5 were broken; HTML5 output now generates the correct links. #2443, #2685, #2686, #2702
• When a @copy-to attribute is used to copy a topic to a new directory, earlier versions generated CSS paths based on the original location. CSS paths are now generated based on the new location. #2491
• Using the same name in two different key scopes is now supported as defined in the DITA 1.3 specification. #2541
• In earlier releases, when maps referenced content outside of the map directory and generate.copy.outer=1 was used, HTML5 or XHTML output would copy images to the wrong location outside of the output directory. The images are now copied to the proper location. #2550, #2682
• The DOTX010E error included extra spacing around the @conref attribute value. The extra spaces have been removed. #2646
• In earlier releases, key definitions for some images were marked as format="html" in the .job.xml file, limiting their use with later image processing. These now use format="image" as intended. #2653
• In DITA-OT 2.4, when new topics were generated by the Branch Filtering process, the generated topics were not added to the .job.xml configuration file. They are now added properly. #2659
• When setting link text, some link targets caused topicpullImpl.xsl to generate the following message XPTY0004: A sequence of more than one item is not allowed as the first argument of normalize-space(). The XSLT data type has been corrected to prevent this. #2665
• When key definitions reference files outside the map scope, key references to images could be resolved with the wrong path. The key definitions are now processed correctly. #2568, #2667
• If maps contained <ditavalref> elements and key definitions pointing to non-DITA files (such as images), earlier versions attempted to filter the non-DITA files and returned errors. The branch filtering process has been corrected to apply only to DITA files. #2669
• In previous releases, HTML5 builds failed when processing <table> elements that contained multiple <tgroup> elements. This is resolved by retrieving column definitions from the <tgroup> element. #2676
• When chunking a document, earlier releases dropped the @xml:lang attribute from the root topic. The correct @xml:lang attribute is now preserved on any chunked topics. #2022, #2678
• In HTML5 tables, some required table classes were missing when args.html5.classattr=no was specified for the build. #2688, #2689
• When a DITA topic that is used in the map is referenced using <coderef>, code references would embed the normalized file from the temporary directory. The original copy is now read from the source URI so that the original source appears in the code block. #2690
• In earlier releases, keys that referred to nested topics were not properly resolved. Key references to nested topics are now correctly resolved as a reference to the nested topic. #2691
• In PDF output from previous releases, the table of contents inserted a generated “Chapter :” prefix in front of the navigation title for the <appendices> element. This prefix has been removed. #2695

Contributors

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

1. Jarno Elovirta
2. Robert D. Anderson
3. Alexey Mironov
4. Roger Sheen
5. Shane Taylor
6. Bob Thomas
7. Vitaliy Danylyuk
8. Lionel Moizeau
9. Eliot Kimber
10. Holger Voormann

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.5 provides corrections and improvements to existing topics, along with new information:

• New Java API
• Experimental map-first preprocessing
• Migrating to release 2.5

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

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

1. Roger Sheen
2. Robert D. Anderson
3. Jarno Elovirta
4. Shane Taylor
5. Ed Porter
6. Eero Helenius
7. Lionel Moizeau
8. George Bina
9. Rene Mjartan

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