DITA Open Toolkit 4.1 Release Notes

DITA Open Toolkit Release 4.1 includes a new version of the Lightweight DITA plug-in with significant enhancements to Markdown processing, and updates for the latest DITA 2.0 draft standard.

Plug-in development features

• Since DITA-OT 3.5, the dita plugins subcommand shows a list of the currently installed plug-ins by plug-in ID. To make it easier to determine which version of each plug-in is installed, the output now includes the version number for each plug-in as specified in the plugin.xml file. #4137, #4141
• Previously only files referenced from the start map could be parsed using a custom parser. The start map itself was always processed as DITA XML. As of DITA-OT 4.1, processing has been updated to also allow the start map to use a custom parser. This change allows recent versions of the LwDITA plug-in to process Markdown maps. #4159
• Plug-in developers can now configure custom parsers via SAX properties that provide a list of formats and processing mode. The LwDITA plug-in uses this mechanism to configure the options supported for Markdown and MDITA. #4205

Lightweight DITA and Markdown updates

The org.lwdita plug-in has been updated to version 5.5, which includes performance improvements and updates to Markdown processing to reflect recent changes to the latest LwDITA drafts from OASIS.

• Markdown output

  • When generating Markdown output, the less-than “<” and greater-than “>” characters are now added to <xmlelement> content as in HTML and PDF output.
  • Markdown output now treats programming and software domain elements as code spans and wraps the content in backtick quotes (`) for better correspondence with HTML5 output, which wraps these elements in <code>.

• Markdown input

  • Standard Markdown syntax can now be used to indicate a span of code by wrapping it with backtick quotes (`). In Markdown DITA input, these constructs are converted to DITA <codeph> elements on import, and rendered as <code> elements in HTML output. In MDITA input, backtick code spans are parsed as teletype <tt> elements to align with LwDITA, which supports teletype highlighting in XDITA.
  • The LwDITA plug-in supports a new $schema key in the YAML front matter block. This key can be used to define parsing options in topic files for more control over how Markdown content is converted to DITA. For more information, see Markdown schemas.
  • Earlier versions of the plug-in failed to parse certain Markdown tables correctly. Table parsing has been improved to ensure these cases are properly processed.
  • The MDITA core profile can now be specified via the new schema key in the YAML front matter block.
  • Any <?linefeed?> processing instructions in Markdown input are now converted to line feeds in HTML5 and PDF output.
  • Markdown DITA supports both loose and tight list spacing (with no blank lines between list items). MDITA treats all lists as loose, and wraps each list item in a paragraph: <li><p>item</p></li>.
  • DITA maps can now be written in Markdown using standard Markdown syntax for links and lists.
    • In Markdown DITA, the schema key in the YAML front matter block is used to define the file as a map. Unordered list items create <topicref> elements, and ordered list items create <topicref> elements with @collection-type=sequence. List items without a link are treated as topic heads.
    • In MDITA, maps use the file name extension mditamap to define the file as a map. Both ordered and unordered list items create <topicref>, and any unlinked topic heads are ignored.

• The flexmark Markdown parsing library has been updated to version 0.64.

• The XDITA plug-in has been updated to version 0.3.0, which includes recent changes to the grammar files from OASIS (as of June 18, 2023). #4214

Updated DITA 2.0 preview

In addition to the DITA 2.0 preview support provided in DITA-OT 3.5 – 4.0, this release includes updated processing for the latest draft versions of the DITA 2.0 grammar files from OASIS (as of April 26, 2023).

• DITA 2.0 splits the programming and syntax domains (so you can use one without the other).

  The syntax diagram elements move from the programming domain to a new syntax diagram domain, which results in new class attribute tokens. All elements and content models remain the same.

  HTML5 and PDF processing has been updated for DITA-OT 4.1 to support syntax diagram elements from DITA 2.0, so that processing matches what those elements did in DITA 1.3. #4082

• DITA 2.0 removes the xNAL domain and classification domains. #4177

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.

Enhancements and changes

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

• When publishing to HTML and PDF, email links no longer include the mailto: prefix in the default link text. #4020, #4089
• When filtering profiled content with DITAVAL files that exclude content by default, the DOTJ031I message no longer appears when no rule is specified for a certain attribute. #4048, #4073
• The Java code has been refactored to use new language and library features from recent Java versions. These changes make the code more future-proof and easier to maintain. #4090, #4091, #4092, #4121
• The following bundled plug-ins have been upgraded to the latest versions:
  • The Normalized DITA plug-in version 1.1 now removes unnecessary key artefacts like @keys, @keyref or <keydef> after key resolution, and <ditavalref> elements after branch filter resolution. #4140
  • The Lightweight DITA plug-in version 5.5 includes the Lightweight DITA and Markdown updates described above. #4167, #4178, #4210
  • The PDF Theme plug-in version 0.7.0 adds support for tasks, and the hazard, highlight, markup, UI, and XML domains, so you can now style these elements in a YAML theme file without building a custom PDF plug-in. #4194
• Several bundled dependencies have been upgraded to the latest versions:
  • Ant 1.10.13 #4182
  • FOP 2.8 #4183, #4011
  • Gradle wrapper 7.6.1 #4197
  • Saxon 12.2 #4130

Bug fixes

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

• Earlier versions of Map-first preprocessing (preprocess2) failed to copy non-DITA files to the output directory. Processing has been updated to copy media files and other linked assets. #3242, #3966, #4132
• When a map contained references to nested subtopics within the same topic file, earlier versions would process the file multiple times during branch filtering. The output was correct but runtime was increased. This issue has been fixed so that the topic file is only filtered once. #3903, #4152
• In earlier versions, cross-references to <fn> footnote elements without target text were rendered with two levels of <sup> superscript formatting in XHTML and HTML5 output. Now, these links are only superscripted once. #3967, #3968
• When generating PDF output, earlier versions failed with the PDFX005F error when topic references targeted external resources with the @scope attribute set to external. Processing has been updated to properly recognize external resources and allow builds to complete. #4131
• Earlier versions included DITA 2.0 grammar files from OASIS that referenced non-public URNs. The files have been updated to the latest versions (as of April 26, 2023), which include updated references in the RELAX NG files. #4144, #4177
• Earlier versions reported errors when processing DITA 2.0 content with empty @specializations attribute values. Processing has been updated to handle these cases correctly. #4165
• When generating HTMLHelp with DITA-OT 4.0, builds failed with the DOTA015F error. HTMLHelp has been updated to replace the outdated preprocess.copy-image.skip property with the corresponding DITA 4.0 build-step.copy-image property for compatibility with recent toolkit versions. #4181, #4186
• When topic short descriptions contain cross-reference links that point to one another in circular references across topics, earlier versions would fail with an infinite-recursion stylesheet loop. Now, <shortdesc> descriptions in referenced elements are processed only one level deep. #4184, #4185
• In earlier versions, setting the processing-mode parameter to strict would only stop processing if errors were reported from the Java code. Any XSLT errors were logged to the console, but processing continued. Now, XSLT errors will also stop processing, so strict mode is a bit … stricter. #4187

Contributors

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

1. Jarno Elovirta
2. Robert D Anderson
3. Radu Coravu
4. Chris Papademetrious
5. Roger Sheen
6. Duna Marius Cosmin
7. Josh Johnson
8. Toshihiko Makita

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

Documentation updates

The documentation for DITA Open Toolkit Release 4.1 provides corrections and improvements to existing topics, along with new information in the following topics:

• Publishing with project files
• Markdown input
• Generating Markdown output
• Extension point reference
• Markdown formats
  • Markdown DITA syntax
  • MDITA syntax
  • Format comparison
  • Markdown schemas
  • Custom schemas

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

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

1. Roger Sheen
2. Jarno Elovirta
3. Lief Erickson
4. Darrenn Jackson
5. Mark Giffin

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