DITA Open Toolkit 3.5 Release Notes

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

• In DITA-OT 3.5, certain branch filtering scenarios prevented key references and content key references from resolving correctly in map-first preprocessing, resulting in missing content in PDF output. The Java code for the reader module has been updated to ensure that all filtered and renamed topics contain the correct information. #3549
• In HTML5 output, a new <div> wrapper element has been added to preserve attributes like @outputclass or @id from the <steps> element in single-step tasks. Earlier versions discarded this information when generating output. #3550

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

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

• DITA-OT 3.5 introduced a regression in key scope processing that saved the effective map too early, before all topic references were updated. In certain cases, keys that were intended to point to different reference targets were merged to a single reference. The keyref processing module has been updated to handle these cases correctly. #3524, #3542
• In DITA-OT 3.5.1, generating output from a project file without setting the --output option caused the build to fail with a NullPointerException. The Java code has been updated to properly initialize the output directory. #3526, #3531
• Builds would also fail with a NullPointerException when publishing bookmap chapters with keys to a single file by setting the @chunk attribute to-content. The metadata push process has been updated to properly handle this case. #3533, #3534
• Earlier versions of DITA-OT would sometimes render tables incorrectly when cells were set to span several rows. Processing for <table> and <simpletable> elements has been updated to ensure that cell coordinates are calculated correctly. #3538, #3539
• When processing maps with flagging information, temporary files include <ditaval-startprop> elements that contain <prop> elements without @class attributes, which generated errors in earlier versions. Processing has been updated to ignore foreign content at this stage, allowing Saxon to proceed without errors. #3540
• The documentation includes corrections and new information in the following topics:
  • Markdown content
  • Markdown DITA syntax reference
  • Normalized DITA
  • Preview support for Lightweight DITA

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

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

• In DITA-OT 3.5, Markdown builds failed due to an incompatible plug-in version. The LwDITA plug-in has been updated to version 2.4, which is compatible with DITA-OT 2.4 and newer. #3508, #3512
• On macOS, DITA-OT 3.5 failed to build output if the input file was specified with a relative path based at the current working directory with the ./ notation. Paths specified on the command line are now normalized to support this syntax. #3509
• Several bundled dependencies have been updated to address security vulnerabilities, including:
  • The bundled Jackson data binding library was updated to version 2.11.0 to resolve several vulnerabilities reported in previous versions, including an OWASP false positive for the SnakeYAML library, which has been updated to version 1.27. #3513, #3515
  • The bundled Ant version has been updated to version 1.10.8 to address CVE-2020-1945. #3522
• In DITA-OT 3.5, PDF customizations (and other plug-ins that use <xslt> elements within custom <pipeline> elements) failed to properly compile the custom XSLT code. The XSLT module has been corrected to resolve custom code correctly and apply the customizations. #3517

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

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 RELAX NG 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). These parameters can be passed on the command line, or included in a custom plug-in via <property> elements in an Ant script as described in Adjusting file names in map-first pre-processing. #3413
  • Use result.rewrite-rule.class to rewrite filenames with a Java class that implements the org.dita.dost.module.RewriteRule interface
  • 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
• Earlier versions of DITA-OT stripped namespace declarations from <mathml> and <svg> elements in topics based on RELAX NG syntax. Pre-processing has been corrected to preserve the namespaces. #3499, #3501
• 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.