DITA Open Toolkit 3.5 Release Notes

DITA Open Toolkit Release 3.5 includes support for additional input resources, an alternative subcommand syntax for the dita command, and an initial preview of features for the latest draft of the upcoming DITA 2.0 standard.

DITA 2.0 preview

DITA-OT 3.5 includes processing support for the latest DRAFT versions of the DITA 2.0 DTD and RelaxNG grammar files from OASIS (as of April 2020). #3449

DITA documents that reference the draft grammar files can be parsed, and where features overlap with DITA 1.3, those features will work as expected.

• The new <include> element can be used to reference text or XML content from other files. In addition to the processing mandated by the specification, DITA-OT also supports the character set definition and line range extraction options previously provided for <coderef> elements (see Extended codeblock processing). #3453

• The new @specializations attribute, which replaces the DITA 1.x @domains attribute, can now be used as an alternative method of declaring specialized attributes. #3440, #3462

• The @outputclass attribute can now be specified as a flagging behavior in DITAVAL files. This allows you to flag an element with a CSS class keyword that will be added to the @class attribute value in the generated HTML. Output classes allow you to pick up pre-defined styles from existing web frameworks, and are more easily overridden with custom CSS files than the inline @style attributes generated by DITA 1.x flagging options such as @color and @backcolor. #3463, #3482

• Titles can now be specified on simple tables, and <simpletable> entries now support row and column spanning attributes. #3464, #3465, #3479

• Where DITA 1.x defined conflicting @class values for <linktext>, <shortdesc>, and <searchtitle> in maps and topics, the new draft of DITA 2.0 uses the topic-based @class value in all cases. Processing is updated to recognize the updated value when these elements are used in maps. #3483

New features

DITA-OT 3.5 also includes the following new features:

• You can now pass additional input resources to the dita command with the --resource option. #3412

  For example, to process a single topic file with a map that contains key definitions, use a command like this:

  dita --input=topic.dita --resource=keys.ditamap --format=html5

• Two new parameters can be used to dynamically adjust the names and locations of output files in transformations that use the map-first pre-processing routine (preprocess2). #3413
  • Use result.rewrite-rule.class to rewrite filenames with a Java class
  • Use result.rewrite-rule.xsl to rewrite via an XSLT stylesheet

• The dita command line interface has been refactored to support subcommands for common operations. #3437, #3492, #3494

  dita deliverables

  Prints the list of deliverables in a project file

  dita install

  Installs or reloads plug-ins (replaces dita --install)

  dita plugins

  Prints a list of installed plug-ins (replaces dita --plugins)

  dita transtypes

  Prints a list of installed transformation types, or output formats (replaces dita --transtypes)

  dita uninstall

  Removes and deletes a plug-in (replaces dita --uninstall)

  dita version

  Prints version information and exits (replaces dita --version)

  For syntax details, see Arguments and options for the dita command.

  Note: The double-hyphen option syntax has been retained for backwards compatibility, so if you use dita --install in scripts (or out of habit), it will still work.
  Tip: Each subcommand has its own --help option, so you can run dita install --help for details on the available arguments and options.

• DITAVAL @style tokens are now also generated as CSS classes that are added to the @class attribute values in the generated HTML. #3489

  Rules with corresponding class selectors have been added to the default stylesheets to implement the same appearance that previous versions of DITA-OT achieved with inline styles. You can override these flagging styles if necessary using the following classes:

  • .flag__style--bold
  • .flag__style--italics
  • .flag__style--overline
  • .flag__style--underline
  • .flag__style--double-underline

Enhancements and changes

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

• The Java code has been refactored to generate xsl:message output using methods that are compatible with Saxon Enterprise Edition. #3383, #3452
• Handling for UncheckedXPathException errors has been improved to provide more details on the source of the error including line and column information. #3395
• The integration tests for the map-first preprocessing routine (preprocess2) have been separated from the previous preprocessing tests, with dedicated results defined to evaluate the compliance of map-first preprocessing with the expected output. #3425
• The HTML5 plug-in includes new attribute sets for link lists that make it easier for custom plug-ins to add supplementary classes or other customizations without overriding entire templates. The default output includes the same CSS classes as previous versions of DITA-OT (relconcepts, relinfo, relref, reltasks), so existing customizations that rely on these classes will behave as expected. #3430
• Various unused and deprecated Ant properties, list files, and targets have been removed from the preprocessing configuration. Recent DITA-OT versions provide alternative mechanisms to achieve the same results, such as the <ditafileset> element to select resources in the temporary directory. #3434
• The org.dita.eclipsehelp plugin, which is still bundled with DITA-OT, is now installed from a separate repository. #3442
• XSLT processing has been adjusted to use Saxon’s preferred Java API for XSLT, XQuery, XPath, and XML Schema processing (S9API) directly instead of the JAXP wrapper used by previous versions of DITA-OT. #3471
• Java code has been refactored to use a single instance of XML utilities during processing. This approach allows other XML-related resources to be shared, including Saxon processors and name pools. #3473

Bugs

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

• The DITA 1.x specification defines cascade behaviors for maps such that <othermeta> and <source> do not cascade to child <topicref> elements. In earlier releases the mappull stage of processing pushed these to nested elements; that behavior is now corrected to match the specification. #1899, #3326
• When <coderef> elements imported code samples with key references via the @keyref attribute, earlier versions of DITA-OT appended the (temporary) file name of the referenced code sample to the last line of the parent <codeblock> element. Processing has been corrected to ensure that code blocks contain only the referenced code samples. #3232, #3496
• To support additional resources, the mapref preprocessing stage now runs even if the input file is not a map. DITA-OT now checks whether maps with additional resources are available, even if they are not specified as input files. #3429
• In some earlier releases, a call to an empty stub template for table @summary attributes was dropped. Calls to that template have been restored, making it available for easy overrides. #3484
• When key definitions with external scope were defined in maps in subdirectories, earlier versions treated absolute paths beginning with slashes as relative paths, and prefixed the name of the enclosing directory to the output path, resulting in broken links. Map reference processing has been corrected to ensure that absolute paths are recognized as such and passed to the output as intended. #3497
• If <term> elements pointed to missing topics using the @keyref attribute, earlier versions of DITA-OT would crash during the build process. An additional check has been implemented to catch these cases, allowing the build to finish and report errors for any unresolved term references. #3498
• In HTML5 output, earlier versions of DITA-OT displayed the “Note” label when the @type attribute of a <note> element was set to notice. Processing has been updated to ensure that the “Notice” label is correctly applied. #3502, #3503
• In previous releases, when <chunk> was used to combine a branch of content, and a file within that branch was missing or invalid, processing within the chunk module could fail with a NullPointerException. This condition has been fixed, and processing will continue without the missing file. #3505

Contributors

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

1. Jarno Elovirta
2. Robert D Anderson
3. Radu Coravu
4. Roger Sheen
5. Lionel Moizeau
6. Stefan Weil

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

• Arguments and options for the dita command
• Installing plug-ins
• Removing plug-ins
• Migrating to release 3.5
• DITA 2.0 preview support

The topic hierarchy has been revised to promote information on common customization scenarios, including Customizing HTML output and Customizing PDF output, and how to extend the toolkit by Adding and removing plug-ins and Creating custom plug-ins.

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

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

1. Roger Sheen
2. Robert D Anderson
3. Jarno Elovirta
4. Shane Taylor
5. Lief Erickson
6. Heston Hoffman

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