DITA Open Toolkit 2.4.4 Release Notes

DITA Open Toolkit 2.4.4 is a maintenance release that fixes issues reported in DITA-OT 2.4, which includes Apache FOP 2.1, a new long-form syntax for dita command options, and additional code referencing extensions.

Issue numbers correspond to the tracking number in the GitHub issues tracker.

Maintenance Release 2.4.4

DITA Open Toolkit Release 2.4.4 includes the following bug fixes.

  • DITA-OT 2.4 threw errors if non-XML DITA topics (such as Markdown files) were referenced in DITA maps. The source format information is now retained to ensure these topics are processed correctly when the DITA-OT Markdown plug-in is installed. #2564
  • In HTML5 transformations, DITA-OT 2.4 threw XSLT warnings if a topic included copyright metadata in the prolog. The redundant templates have been removed to ensure that copyright metadata is correctly processed. #2573, #2574, #2610
  • In earlier versions of DITA-OT, the HTML5 transformation generated an empty <nav> element for table-of-contents navigation when the nav-toc parameter was set to partial and the @chunk attribute for a topic reference was set to-content. Processing has been updated to produce valid navigation links with to-content chunks. #2577 #2578
  • If an index term was defined in a map, a redundant empty citation was created in the index when generating PDF output with Apache FOP. Index processing has been revised to ensure that links to index terms defined in maps work properly for FOP. #2584, #2589
  • When reading the local.properties file, the Ant basedir property is set to the root directory of the DITA-OT installation. This change ensures that the local.properties file in the installation directory can be read consistently, even in cases when custom build scripts override the basedir property beforehand. #2586
  • When generating PDF output, earlier versions of DITA-OT applied the @keep-with-next.within-line attribute to list item labels, which is not valid on <fo:list-item-label> formatting objects. The list label attribute sets have been revised to generate valid XSL:FO output. #2602
  • Parameter processing in variable resolution has been adjusted to ensure that nested <param> elements are taken into account when parameters are passed as a document node. #2603
  • The command-line help and documentation for the dita command mistakenly included the equals sign in the descriptions of the --install and --uninstall options. The correct syntax separates these options from their values with a space instead. To install a single plug-in from a local ZIP file, for example, use dita --install filename. #2605
  • 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.

Maintenance Release 2.4.3

DITA Open Toolkit Release 2.4.3 includes the following bug fixes.

  • In PDF output generated with earlier versions of DITA-OT and RenderX XEP, the <indexterm> hierarchy for multilevel entries in the PDF index was not properly indented. Index term indentation has been corrected to properly reflect the entry hierarchy as authored in DITA source files. #1525
  • In earlier versions of DITA-OT, specifying a relative path for the temporary directory on the command line would cause PDF processing to fail. DITA-OT now checks whether the dita.temp.dir property is set to an absolute path and responds with an error message otherwise. #2038
  • In certain cases, DITA-OT 2.4 generated broken links in PDF output for related topics and reported “unresolved internal destination” warnings in the console when processing topic references with the @collection-type attribute set to family. Link rewrite processing has been corrected to ensure that links are generated properly. #2522
  • Default settings for several parameters have been removed from the configuration.properties file. #2555
    Values for these parameters can be passed as usual to the dita command or included in build scripts:
    • default.language
    • generate-debug-attributes
    • processing-mode
  • In previous versions of DITA-OT, the HTML5 transformation generated <simpletable> output with column widths specified in <col> elements as direct children of the <table> element. A <colgroup> wrapper element has been added for compatibility with the HTML5 standard. #2563

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

Documentation updates

The DITA-OT 2.4.3 documentation includes corrections and improvements to existing topics, along with new content on Configuration properties.

Maintenance Release 2.4.2

DITA Open Toolkit Release 2.4.2 includes the following bug fixes.

  • DITA-OT 2.0 threw a null pointer exception when producing Eclipse Help output from a bookmap with a <glossarylist> that referenced a composite <dita> topic. Processing has been updated to properly handle root <dita> elements or any other elements without @class attributes. #1885
  • HTML5 output generated with DITA-OT 2.4.1 included spurious namespace attributes for <taskbody> and <simpletable> elements. The extra result prefixes (ditamsg, dita2html and related-links) have been excluded to ensure they no longer appear in output files. #2542
  • Earlier versions of DITA-OT failed to ignore empty props specialization attributes during the filtering process. Processing has been updated to treat any empty attributes specialized from @props like empty default profiling attributes such as @audience="", which are ignored. #2547
  • The xml-apis-ext library that FOP depends on to render SVG images was missing in DITA-OT 2.4. The distribution package has been updated to provide support for SVG images in PDF output. #2548
  • If an input map contained topic references with duplicate @copy-to attribute values, earlier versions of DITA-OT failed to generate additional output topics. Processing now applies the force-unique parameter to ensure that unique output files are created for each instance of a resource when a map contains multiple references to a single topic. #2551
  • Support for the args.breadcrumbs parameter provided in earlier versions of DITA-OT was never fully implemented and has been removed. HTML customizations that rely on the XSLT BREADCRUMBS parameter will need to re-implement this functionality in custom plug-in code. #2554

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

Maintenance Release 2.4.1

DITA Open Toolkit Release 2.4.1 includes the following bug fixes.

  • In DITA-OT 2.3 and 2.4, setting the force-unique parameter to true had no effect. Processing has been corrected to properly generate the copy-to attributes that ensure unique file names for each instance of a resource when a map contains multiple references to a single topic. #2520
  • HTML5: In DITA-OT 2.4, the text content of table cells was partially propagated to the CSS @class attribute. Table processing has been updated to remove the legacy XHTML CSS class mode and ensure that @class attribute values are generated correctly. #2524
  • Saxon 9.7.0.11 reported an error when producing output from DITA content: The context item for axis step ./@class is absent. This was resolved by modifying the $localclass variable in the output-message template to use the $ctx context variable as a parent. #2526, #2535
  • Earlier versions of DITA-OT did not correctly override the default @scope and @format attribute values for topic references with values from the key definition. Keyref processing has been updated to properly handle scope and format definition for non-local non-DITA targets. #2529
  • In earlier versions of DITA-OT, the dita.xsl.html5.cover extension point did not respond to overrides declared in custom plug-ins. The extension point has now been moved to the template file to ensure that it can be overridden as intended. #2537
  • In cases where a single topic is used in multiple key scopes (and copies of the topic are created), earlier versions of DITA-OT used the same target for key references to both key scopes. Key targets are now rewritten to point to the new resource to ensure that duplicate link targets in key scopes are correctly resolved. #2539

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

Documentation updates

The DITA-OT 2.4.1 documentation includes corrections and improvements to existing topics, along with new content.

Requirements

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

Release Highlights

DITA-OT 2.4 includes Apache FOP 2.1, a new long-form syntax for dita command options, and additional code referencing extensions.

Apache FOP 2.1

DITA-OT 2.4 bundles the latest version of Apache™ FOP (Formatting Objects Processor). #1958, #2399

FOP 2.1 builds on the OpenType CFF font support added in FOP 2.0, with additional font support and enhancements for PDF accessibility, including PDF/UA (PDF/Universal Accessibility) and PDF/A-3.

For details on recent changes in FOP, see the Release Notes for versions 2.0 and 2.1.

Note:

To conserve memory, accessible PDF output is disabled by default in FOP 2.1. To generate accessible PDFs from DITA-OT, set the args.fo.userconfig parameter and include the <accessibility>true</accessibility> option in your custom FOP configuration file.

For more information, see Apache FOP Accessibility.

New long-form syntax for dita command options

All dita command options can now be specified with a GNU-style option keyword preceded by two hyphens. For example:

dita --input=userguide.ditamap --format=html5

DITA-OT parameters can now be passed to the dita command with this same syntax: --parameter=value.

When set with this method, properties are validated against the toolkit’s plug-in configuration. An error message appears if a property is not recognized or if an enumerated property value is invalid. #2422, #2492
Attention: Unix-style single-letter options (preceded by a single hyphen) are also available in some cases for backwards compatibility. The X-Toolkit–style single-hyphen keyword variants supported by previous releases (such as -input) have been deprecated and may be removed in an upcoming release.

Extended code reference processing

DITA-OT 2.4 provides additional support for extracting a range of lines from code references based on the content of the target file. Instead of specifying line numbers, you can now also select lines to include in the code reference by specifying keywords (or “tokens”) that appear in the referenced file. #2469

DITA-OT supports the token pointer in the URI fragment to extract a line range based on the file content. The format for referencing a range of lines by content is:

uri ("#token=" start? ("," end)? )?

Lines identified using start and end tokens are exclusive: the lines that contain the start token and end token will be not be included. If the start token is omitted, the range starts from the first line in the file; if the end token is omitted, the range ends on the last line of the file.

Tip: This approach can be used to reference code samples that are frequently edited. In these cases, referencing line ranges by line number can be error-prone, as the target line range for the reference may shift if preceding lines are added or removed. Specifying ranges by line content makes references more robust, as long as the token keywords are preserved when the referenced resource is modified.

For more information, see Extended code reference processing.

Standalone HTML5 plug-in

The HTML5 transformation introduced in release 2.0 as part of the XHTML plug-in was moved to a separate HTML5 plug-in in release 2.2, but that version of the HTML5 transformation still depended on the XHTML plug-in for certain common processing.

In release 2.4, all dependencies between HTML5 and XHTML have been removed to ensure that HTML5 processing can be further refactored in the future without affecting XHTML output, or other HTML-based transformations such as eclipsehelp, htmlhelp or javahelp.

#2405, #2511

Legacy plug-ins removed

DITA-OT 2.4 no longer includes the following legacy transformation plug-ins in the default distribution:

Table 1. Legacy plug-ins
Plug-in Source code location
DocBook https://github.com/dita-ot/org.dita.docbook
Eclipse Content https://github.com/dita-ot/org.dita.eclipsecontent
OpenDocument Text https://github.com/dita-ot/org.dita.odt
Word RTF https://github.com/dita-ot/org.dita.wordrtf
Note: If necessary, legacy plug-ins may be re-installed from earlier DITA-OT distributions, but they are no longer actively maintained or supported by the core toolkit committers. The source code is available on GitHub for anyone interested in maintaining the plug-ins for use with future toolkit versions.

#1542

Resolved issues

In addition to the highlights mentioned above, DITA Open Toolkit Release 2.4 includes the following changes.

Enhancements and changes

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

  • Move to Java 8 #2026
  • TM output #1245, #2404
  • Bug in "dita-utilities.xsl" getVariable when called from string context #2512, #2513
  • HTML5 generates duplicate class attributes #2503
  • Use Sass // comment syntax for partials copyrights #2502
  • Change HTML5 to use libsass instead of Compass #2499
  • Add sign-off requirement to contribution #2471
  • Add copyright based on Git history #2467
  • Run dita command with only properties file #2465, #2468
  • Map temporary files to source/result files using job configuration #2462
  • Use job mapper when transforming topics to final output #2453
  • Move chunk target detection to chunk module #2437
  • Replace named template with mode for easy override of static content #2412
  • Remove lax integration process #2151

Bugs

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

  • Fix error when <linktext> contains <tm> #2303 #2394
  • Build fails when <navtitle> in <relcell> has child elements #2347, #2390

Contributors

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

  1. Jarno Elovirta
  2. Robert D. Anderson
  3. Eliot Kimber
  4. Eero Helenius
  5. Roger Sheen
  6. Radu Coravu

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.4 includes corrections and improvements to existing topics, along with new content.

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

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

  1. Roger Sheen
  2. Jarno Elovirta
  3. Mark Giffin

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