DITA Open Toolkit 3.2 Release Notes

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

DITA Open Toolkit Release 3.2 includes new command-line options, support for RELAX NG parsing and validation, preliminary processing for the XDITA authoring format proposed for Lightweight DITA, and a plug-in registry that makes it easier to discover and install new plug-ins.

Feature Highlights

DITA Open Toolkit Release 3.2 includes the following new features:

• The dita command has been extended with several new arguments and options to improve the usability of the plug-in installation and removal processes.

  • The --plugins argument shows a list of the currently installed plug-ins
  • The --transtypes argument shows the available output formats (transformation types)
  • The --force option can be passed to dita --install to overwrite an existing plug-in with a new version.

  When the plug-in integration process runs, the console now shows a list of plug-ins that were added or removed. #1960, #3037, #3070, #3120, #3109, #3110

• RELAX NG schemas can now be used to parse and validate DITA topics and maps without installing additional plug-ins. #2019, #3106

  To use a RELAX NG schema instead of a DTD or schema, add an <?xml-model?> processing instruction at the beginning of the file, immediately after the XML prolog, for example:

  <?xml-model href="urn:oasis:names:tc:dita:rng:topic.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>

• DITA-OT 3.2 adds preliminary processing for the XDITA authoring format proposed for Lightweight DITA in addition to the preview support for the MDITA and HDITA authoring formats provided in DITA-OT 3.0.

  The org.oasis-open.xdita plug-in version 0.2.2 is now bundled with the default distribution. XDITA is a subset of DITA designed for users who want to write DITA content but who do not want (or need) the full power of DITA. #3108 #3136

  Tip: For examples of cross-format content sharing between topics in XDITA, HDITA, extended-profile MDITA, and DITA 1.3, see the LwDITA sample files in the DITA-OT installation directory under plugins/org.oasis-open.xdita.v0_2_2/samples.

• DITA-OT 3.2 supports a new plug-in registry that makes it easier to discover and install new plug-ins. The registry provides a searchable list of plug-ins at dita-ot.org/plugins.

  For more information, see Adding plug-ins via the registry. #3028, #3101

• A new parameter link-crawl has been added to control whether links within topics are followed.

  By default, links within topics are followed, as are links in any found topics, so that a map with one topic can end up processing any number of topics. When link-crawl is set to map instead of the default topic, DITA-OT will only process topics that are actually referenced in the map. #3102

Enhancements and changes

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

• Text-only entries in relationship tables (with link text but no @href attribute) now create plain text entries in the related links section of relevant topics. This update also removes an unnecessary error message for <link> or <xref> elements that do not specify @href. #1132, #3030
• XSL-FO output for for <section> and <example> elements has been updated for consistency, ensuring that all default sections use the same blocks and attribute sets. #1248, #3057
• In earlier versions, PDF builds would finish with BUILD SUCCESSFUL even when the XSL-FO process failed. This behavior has been adjusted so the build fails if the XSL-FO processor cannot create the PDF file. #1414, #1831, #3137
• In earlier releases, when XHTML and HTML5 processing encountered an unknown element with no fallback processing, the result appeared in yellow. These output processes have been updated to generate a warning for this case, and to remove the yellow formatting. #2033, #3035
• The default TOC alignment of "justify" has been removed for PDF output with FOP. This was originally added to work around a defect in FOP; that defect is resolved, so the workaround can be removed. #2403, #3036
• When a grammar file (DTD, Schema, or RNG) cannot be found, DITA-OT previously issued a "file cannot be loaded" exception that only referred to the map or topic. A new message has been added to distinguish between topics that cannot be found and grammar files that are not available or not installed properly. #2461, #3124
• Most values for the @chunk attribute have no meaning for PDF processing, which always produces a single output file. Beginning with this release, chunk processing will be disabled by default in PDF. It can be re-enabled for @chunk attribute edge cases by setting org.dita.pdf2.chunk.enabled=true. #2479, #3118
• The quote element <q> now generates an equivalent XHTML and HTML5 <q> element, rather than generating quote characters. This improves accessibility of the XHTML and HTML5 output, and defers any internationalization concerns to settings within the browser. #2481, #3032
• In PDF output, the long quote element <lq> is now indented by default, as with other output formats. #3009, #3031
• The previously deprecated dost.jar.path alias has been removed, and the dost.class.path property to which it referred has been deprecated, as the classpath is now defined outside the Ant process. #3011
• HTML5 CSS configuration has been refactored to improve test coverage and simplify property declarations. #3020
• Legacy arguments for the old Java command-line interface that were deprecated in DITA-OT 2.3 have now been removed. #3025
• PDF output now provides generic hazard statement styling based on the ISO 3864 and ANSI Z535 standards, with an SVG icon and XSL variables for the corresponding ISO and ANSI color definitions. #3039
• The XSL import tree for PDF output has been flattened by moving topic-attr.xsl and concept-attr.xsl imports to the topic2fo.xsl shell. In earlier versions, overriding these files required additional modifications to commons-attr.xsl, from which they were imported. #3050
• In all earlier releases, links to topics or other elements with titles would automatically retrieve the title for use as link text, but links to the title would not. With the growing use of WYSIWYG editors, it is easy to set (and link to) IDs directly on titles rather than on the container. Accordingly, output transforms have been updated to pull the same link text when a reference points to a title as for a reference to a container. The same update is made for links to definition list terms and the containing definition list entries. #3056
• An alternative installation method can now be used to install DITA-OT on macOS via the Homebrew package manager. See Installing on macOS via Homebrew for details. #3059
• The topicpull step of DITA-OT preprocessing is used primarily to update link text. This step previously ran on all located topics in the build, but this processing was not useful for resource-only topics that are not published. Accordingly, the topicpull step has been updated to only run on normal-role topics. #3079
• In earlier releases, @conref resolution would fail with an error when the referring document had a constraint that was not also specified on the target document (as when referencing DITA content from an XDITA topic, for example). Based on the DITA specification, this is an error condition but should only fail when the constraint is defined as "strict". Accordingly, the @conref processor has been updated to allow resolution of @conref with an error for ordinary constraints. #3084, #3097
• ARIA role attributes have been extracted from structural HTML5 elements into attribute sets to make it easier to override roles or add custom class attributes as required by popular web frameworks. #3090
• PDF output has been updated so that if change bars are used for revisions and an entire topic is revised, the change bar will also appear alongside the title in the table of contents and the full topic. Previously the bar only appeared alongside the topic body. #3100, #3111
• Unnecessary dependencies for common Java libraries have been removed. #3107
• The command-line help for the dita command has been updated to clarify the list of arguments and options. #3114
• A single NOTICES file is now generated with the license information for all third-party libraries included in the distribution package. #3121

Bugs

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

• When a <shortdesc> element is nested in <abstract> along with other elements and PDF output is generated with the default chapter layout, earlier versions of DITA-OT indented the short description further than its siblings. Processing has been updated to ensure that the correct indentation from the parent is applied for both BASIC and MINITOC layouts. #3063, #3116
• In earlier releases, footnotes defined inside elements with extra styling (such as bold, italic, or centered text) erroneously applied the anchor style to the footnote body in PDF output. These footnotes are now rendered with the same formatting as other footnotes. #3091
• In PDF output generated with earlier releases, <div> elements were rendered with nothing more than a new line. This has been corrected to render logical division elements like other blocks, separated by a bit of space from the previous block (and pick up any standard overrides from the common.block attribute set). #3115
• Default formatting for <xmlpi> elements has been added to all output types (including HTML-based formats, PDF, and troff) to ensure that XML processing instructions are wrapped in question marks and angle brackets. A processing instruction tagged as <xmlpi>test this</xmlpi> is now rendered in the output as <?test this?>. #3117
• In earlier releases, the conref push module did not properly handle namespaced debugging attributes. (It wrote out the attribute but removed the namespace declaration.) The namespaces are now preserved. #3119
• When the same document appeared more than once in a map, cascading metadata was added for every instance of that document. For maps that reference individual topics in a large document (such as a document with 500 small topics), this resulted in OutOfMemory errors from the move-meta preprocessing step. This has been fixed so metadata is handled properly for each reference to a document. #3127
• In earlier releases, input documents that included tables with the @frame attribute set to "none" generated invalid HTML5 markup (border="0"). Processing has been corrected to ensure that the @border attribute is omitted for tables that have no border. #3128, #3139

Contributors

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

1. Jarno Elovirta
2. Robert D Anderson
3. Roger Sheen
4. Stefan Gentz
5. Radu Coravu
6. Lief Erickson
7. Stefan Eike
8. Alexey Mironov
9. Eero Helenius
10. Sean Molenaar

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

• Installing on macOS via Homebrew
• Preview support for Lightweight DITA
• Adding plug-ins via the registry
• Plug-in coding conventions
• Plug-in descriptor file
• Books

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

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

1. Roger Sheen
2. Robert D Anderson
3. Mark Giffin
4. Jarno Elovirta

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