DITA Open Toolkit 3.0.4 Release Notes

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

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

• In previous releases, including a <!DOCTYPE> declaration in a DITAVAL document resulted in a build failure. This is now fixed, and the referenced grammar file will be found using the same catalog that is used to locate other grammar files. #2005, #2922
• DITA-OT 3.0 failed to recognize PDF customizations if the custom plug-in used the same file names as the base PDF plug-in. The default catalog has been removed from the catalog configuration file to ensure that only explicitly configured catalogs are used and customizations take precedence regardless of the file names in the custom plug-in. #2835, #2937
• In DITA-OT 3.0, URI-based links may cause NullPointerExceptions when link targets do not exist until after @copy-to attributes are evaluated. The build failure has been removed, and this type of link will now generate normal build errors as in previous releases. #2841, #2936
• In previous releases, if a key definition specified both @href and @copy-to attributes, references to that key always resolved to the original @href rather than to the new copy specified with @copy-to. Key references to this type of definition will now resolve to the appropriate copy of the resource. #2842, #2935
• In DITA-OT 3.0.1, <coderef> elements that contained references to line ranges in DITA map files were not reliably included in PDF output as the preprocessing routine may change maps. All code references are now resolved from the original files to ensure that code blocks reflect the intended source range. #2901, #2916
• In DITA-OT 3.0, PDF output files were created outside of the specified output directory when the map referenced content outside of the map directory. This has been fixed to ensure that PDFs are always placed in the specified output directory. #2910, #2923
• When generating HTML output with DITA-OT 3.0.2, images referenced indirectly via keys were not copied to the output folder. Processing has been corrected to ensure that the list of images in the job configuration includes those referenced via keys. #2917, #2921
• In earlier releases, @scale attributes on the <fig> element were ignored for PDF output. The @scale attribute is now respected for PDF figures, which may include text content (such as code blocks), inline images inside the text, or block images. #2926
• In earlier releases, topic references to peer DITA content reported “missing navigation title” errors even when the reference included <linktext>. As with all other peer, external, and non-DITA references, the <linktext> for peer topics will now be used as a fallback title when no navigation title is available. #2927
• The Lightweight DITA plug-in has been updated to the latest version (2.0.3) to prevent errors when processing Markdown input that contains typographic quotation marks with the @format attribute set to markdown #2929, #2956
• When generating PDF output for tables that specified row headers, DITA-OT failed to honor vertical spans defined via the @morerows attribute on an <entry> (cell). Row headers are now properly applied when cells span additional rows. #2942, #2946
• When <fragref> elements were used to reference a syntax diagram fragment, earlier versions of DITA-OT displayed an error. Processing has been updated to use the latest designs from the topicpull module and fix the error. #2945

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

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

• In some scenarios on Windows, the version of Saxon shipped in DITA-OT 3.0 caches one copy of the toolkit module functions.xsl and then uses that copy in place of a second (different) module with the same name. This causes problems when using the ant command to run HTML5 builds. Adding an explicit path to one of the imports works around the problem. #2892
• If an XSLT message is declared to be fatal, throwing that message should halt the build. This stopped working with a refactored message process several releases ago, but was missed because the default toolkit does not declare any fatal messages for XSLT modules. #2894
• When a DITAVAL document contains a typo in the @action attribute (which should be set to one of include, exclude, flag, or passthrough), the build ends with a message that is difficult to diagnose. The message has been updated to be more explicit and to use the toolkit’s standard message format. #2896
• When the <navtitle> element is used in a map, it should be ignored by default (for the purposes of TOC titles, PDF bookmarks or generated links), except in cases where the @locktitle attribute on the containing topic reference is set to yes. This has always worked when using the @navtitle attribute on topic references, but previously the <navtitle> element in maps was used even if it was not locked. #2897
• When a DITA document contains more than one <glossentry> element, and keys are defined for those entries using the file name but without including the entry ID, XHTML and HTML5 builds would fail to process topics that reference the key. This error has been corrected so that terms linking to glossary entries will go to the correct file, and no error will be generated. #2900
• In PDF builds, the <navtitle> element inside of a topic was ignored when creating bookmarks and the table of contents. The <navtitle> element in topics is now used for each of those cases except when a map overrides the navigation title. #2904, #2906
• When the <choicetable> element does not specify a table header, it should generate default values for the "Option" and "Description" fields. In PDF, the "Description" column was not generating the correct header. This has been fixed so that each column gets the proper header. #2908, #2909
• In HTML5, the default output process generates a Dublin Core metadata tag that specifies the content format as XHTML. This is left over from earlier releases when the two formats shared the same code. The format value is now correctly set to HTML5. #2912

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

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

• If a map or branch of a map was chunked to create a single document, but that portion of the map also contained a <topicref> reference to a non-DITA resource, earlier versions of DITA-OT attempted to read and chunk the non-DITA file. This resulted in build errors and a broken reference. The non-DITA references are no longer read or renamed when chunking. #1550, #2883
• Several issues related to relationship table column headings have been resolved: #2432, #2873.
  • If a relationship table heading uses a @navtitle without a topic, earlier versions of DITA-OT would fail with an XSLT error. If the @href attribute is not present, the navigation title will now be used as expected.
  • You can now set a heading on any relationship table column to apply that heading to the group of links generated by cells in that column. For example, if you create a column for <glossentry> topics and set a title of “Related terms”, the generated links will appear in a group titled “Related terms” (rather than the default “Related concepts”). In earlier releases, these headings were ignored unless every column specified its own heading.
• If a bookmap is referenced from within another map or topic reference, earlier versions of DITA-OT generated an invalid <fo:page-sequence> within an <fo:block>, which caused FO processing to fail. DITA-OT now checks the bookmap elements at the root level to determine whether page sequences and static content should be generated. This allows processing to complete without errors. #2596, #2859
• The bundled DITA grammar files have been updated to reflect the latest changes from the OASIS DITA Technical Committee (Errata 02, 16 January 2018). These changes allow XML Schema-based validators like Saxon EE to resolve schema references based on URI mappings, and replace declarations of the @domains attribute in modules with domains-att references to facilitate domain attribute substitution. #2725, #2818, #2860
• In DITA-OT 3.0, image references in bookmap bookmeta data caused builds to fail. Processing has been corrected to ignore images when reading topics from the map, allowing builds to complete successfully. #2828
• Earlier versions of DITA-OT failed to process resources where the filename includes the percent % character. The URI parser has been corrected to escape these characters correctly and rewrite references in valid URI syntax. #2829
• The Lightweight DITA plug-in has been updated to the latest version (2.0.2) to prevent errors when processing Markdown input that contains typographic quotation marks. #2837, #2866
• In DITA-OT 3.0, cross-references to external resources caused problems if the @scope attribute was not explicitly set to external. The preprocess validation filter has been revised to implicitly treat such references as external in lax processing mode per the DITA specification and issue a warning. #2862, #2877
• The German translation for danger note labels has been changed from VORSICHT to GEFAHR to align with recommendations in ANSI Z535.4 Annex D. #2864, #2871
• DITA-OT 3.0 would fail with an error when generating HTML output with non-DITA resource references such as MathML, which were treated as html. The @format tracking has been corrected to use the correct format in the job configuration instead of html. #2867, #2889
• The DITA 1.2 schemas have been corrected to use DITA 1.2 version-specific identifiers in all @schemaLocation references. Previously one module was referenced with an unversioned identifier, causing DITA 1.3 rules to be pulled into the DITA 1.2 task schema. #2874, #2878
• The bundled Saxon-HE library was updated to version 9.8.0.7, which restores the ability to run XSLT 1.0–based stylesheets. This change will allow existing plug-ins that still use XSLT 1.0 syntax to work in DITA-OT 3.0.2 without migration. #2887, #2888

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

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

• Microsoft Compiled HTML Help requires a Windows codepage rather than UTF-8, so many characters are converted to HTML entities to ensure they are preserved during the codepage conversion. In earlier versions of DITA-OT, these entities were not rendered correctly in index terms or in topic titles on the Contents tab of the .chm file. This is now fixed; characters that exist in the target codepage are not converted to entities, so they will appear properly in the compiled help file. #1151, #1271, #2852
• When unordered lists nest greater than 4 levels, PDF processing generates a warning about a missing variable, and deeply nested lists use text such as Unordered List bullet 5 instead of a bullet character. Characters for levels 1 through 4 now repeat in deeply nested lists. #2824, #2853
• Map-first processing in 3.0 uses generated file names in the temp directory for HTML Help, but this breaks any existing context-sensitive help projects that call topics directly by file name rather than by aliased constants (topic IDs) or help context numbers. Topics in the compiled help file are now restored to their original names to support external applications that to link to topics within a CHM by file name. #2830
• Simplified common variable definitions in 3.0 could not be overridden using the traditional customization approach; the override process now checks for common variables to ensure those in the configuration directory are used. #2833, #2838
• Generating Markdown output with DITA-OT 3.0 failed with references to a missing stylesheet. The Lightweight DITA plug-in has been updated to the latest version (2.0.1), which corrects the plug-in directory path in the stylesheet reference, so Markdown output is now generated as expected. #2836, #2846
• In 3.0, HTML Help project files would not compile to CHM files because a property definition was not properly initialized. This has been fixed and CHM files are generated using the original map name. #2851
• In 3.0, the args.output.base property to name output files does not work properly for HTML Help. The property is now used to produce a CHM file with the correct name and contents. #2854
• In 3.0, content references to warehouse topics that contain unresolved cross-references would cause PDF builds to fail, even if the invalid reference was not explicitly included in the content reference. DITA-OT now checks to make sure such files exist and only parses them if available. #2856

• 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.

DITA-OT 3.0 adds support for Markdown, normalized DITA output, and the alternative authoring formats proposed for Lightweight DITA. The map-first preprocessing approach provides a modern alternative to the default preprocess operation.

Markdown support

The Markdown implementation previously provided by the external dita-ot-markdown plug-in has been updated to support additional edge cases and bundled into the DITA-OT 3.0 release. #2774

Markdown topics can be added to DITA publications by setting the @format attribute to markdown so the toolkit will recognize the source file as Markdown and convert it to DITA:

<map>
  <topicref href="markdown-dita-topic.md" format="markdown"/>
</map>

Along with Markdown input, DITA-OT now provides three new output formats to convert DITA content to Markdown, including the original markdown syntax, markdown_github for GitHub-Flavored Markdown, and markdown_gitbook for publishing via GitBook.

Markdown output can be generated by passing one of these keywords to the dita command with the --format option:

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

The new output formats can be used to feed DITA content into Markdown-based publishing systems or other workflows that lack the ability to process DITA XML.

Preview support for Lightweight DITA

The new org.lwdita plug-in replaces the earlier dita-ot-markdown plug-in and provides preview support for the MDITA and HDITA authoring formats proposed for Lightweight DITA.

The @format attribute can be set to mdita to apply LwDITA-specific processing to Markdown topics:

<map>
  <topicref href="mdita-topic.md" format="mdita"/>
</map>

In this case, the first paragraph in the topic will be treated as a short description, for example, and additional metadata can be specified for the topic via a YAML front matter block.

Normalized DITA output

The new dita transformation generates normalized topics and maps from DITA input. The normalized output includes the results of the DITA Open Toolkit pre-processing operations, which resolve map references, keys, content references, code references and push metadata back and forth between maps and topics.

In comparison to the source DITA files, the normalized DITA files are modified in the following ways:

• References from one DITA map to another are resolved
• Map-based links, such as those generated by map hierarchy and relationship tables, are added to the topics.
• Link text is resolved.
• Map attributes that cascade are made explicit on child elements.
• Map metadata such as index entries and copyrights are pushed into topics.
• Topic metadata such as navigation titles, link text and short descriptions are pulled from topics into the map.
• XML comments are removed.

Normalized output can be used during plug-in development to troubleshoot the results of preprocessing routines, or in situations where post-processing of DITA content is required, but the downstream systems are limited in their ability to resolve DITA references. #2775

Map-first preprocessing

DITA-OT 3.0 provides a map-first preprocessing option as an alternative to the default preprocess operation. The method, which was introduced in DITA-OT 2.5 as an experimental feature, has been improved and is ready for use in many production scenarios. Map-first-preprocessing provides the same functionality as the default preprocess, but takes a different approach. #2763

Whereas the default preprocessing routine handles both maps and topics at the same time, often switching back and forth between map operations and topic operations, the map-first approach only begins processing topics after nearly all map processing is complete. This simplifies the processing logic and creates cleaner module responsibilities, which makes it easier to process only those topics that are actually referenced after filtering, for example, or to only process the map to validate the map structure.

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

Features

DITA Open Toolkit Release 3.0 includes the following new features:

• A new property named args.output.base can be used to control the name of the output file for transformation types that produce a single output file. The value of the property is the base file name of the output file, without file extension. The file extension is defined by the transformation type. #1200
• The custom logging implementation used by earlier toolkit versions has been replaced with the Simple Logging Facade for Java (SLF4J) and the Logback logging framework to better support parameterized log messages and reduce dependencies on the underlying logging mechanisms. #1471
• HTML Help project files are now generated in a temporary directory, so that only the Compiled HTML Help (.chm) file is returned. #1551
• The Map-first preprocessing routine has been extended to support subject schemes #2626
• A new ant.import extension point has been added to make it easier to add new targets to the Ant processing pipeline. #2766
  Tip: See Adding a new target to the Ant build process for details.

Enhancements and changes

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

• Legacy plug-ins that were removed from the distribution package in earlier releases have been moved to their own repositories. The following plug-ins have been moved: DocBook, Eclipse Content, Eclipse map specialization, RTF, ODT, and support for pre-OASIS DITA document types. #2121
• Use XMLUnit 2 #2232, #2723
• Generated link groups in XHTML and HTML5 now use list markup rather than <div>, as required to comply with WCAG 2.0 accessibility guidelines. #2447
• Upgrade Gradle to version 3.5 #2713
• When building PDF from files that do not use .dita or .ditamap extensions, the input file extension (such as .xml) is no longer included in the generated PDF file name. #2718
• Upgrade Saxon-HE to version 9.8 #2721, #2727, #2822
• Upgrade Apache™ FOP to version 2.2 #2736
• When merging submaps for processing, preserve titles and metadata from the referenced submap so that they may be used in later processing stages. #2739
• Add flagging information from DITAVAL during the same step that handles DITAVAL filtering. #2748
• Allow plug-ins to specify custom parameters of type url #2755
• Move or rename Java classes #2765
• Make it easier for PDF plug-ins or overrides to customize how processing handles the DITA @outputclass attribute, such as by mapping it to corresponding XSL:FO attributes. #2770
• Topics exploded by chunk should be written to the topic folder #2780
• Move configuration files to a dedicated config/ directory, which ensures that configuration files and generated files like messages.xml will not be bundled into the compiled dost.jar #2781, #2783
• Allow any attribute to be used for profiling #2784
• Support language-independent variable files. For variables common to all (or nearly all) languages, this means we no longer need to maintain an individual copy of the variable for every language. Plugins may also now define variables that are used by all languages. #2789
• Use double-hyphen syntax for CLI options in error messages #2808
• Refactor HTML5 <simpletable> accessibility to use more modern attributes to associate table entries with header cells. #2811, #2448

Bugs

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

• Email links without a scope or format previously generated a NullPointerException. The mailto: syntax is now recognized as an email link and will not be read as a file reference. #2654
• The wrong language code was previously set when documents set @xml:lang to the value zh-Hans #2742
• According to the DITA 1.3 specification, when key definitions refer to images, text that would otherwise become link text should be placed in the images @alt element as alternative text. Previously the text was placed directly into the <image>, which was not valid and ignored by later processing. #2752, #2814
• In earlier releases, when a <table> element included too many entries in a row, FOP would crash during PDF processing. The extra entries are now ignored with an error message. #2782
• A Java method for generating relative paths failed on Windows when comparing two paths from different drives. The method has been fixed so that it does not try to construct a relative path between drives. #2797
• In HTML5, a DITA <stepsction> that contained paragraphs resulted in HTML5 <p> elements that contained <p>. The <stepsection> now generates a <div> to ensure valid HTML5 output regardless of what it contains. #2807
• An updated errata has been approved for DITA 1.3 that removes default values for @rowheader on <colspec>. The relevant grammar file modules from OASIS have been updated to include this errata. #2810

Contributors

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

1. Jarno Elovirta
2. Robert D. Anderson
3. Roger Sheen
4. Alexey Mironov

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

• The top-level documentation structure has been revised to replace book-based paradigms (User Guide, Developer Reference) with more task-oriented groupings #121
  • Installing the DITA Open Toolkit
  • Building output
  • Customizing the DITA Open Toolkit
  • Error messages and troubleshooting
• New input formats #150 #151
  • Markdown content
  • Preview support for Lightweight DITA
• New output formats #152
  • Markdown
  • Normalized DITA
• Map-first preprocessing
• Migrating to release 3.0

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

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

1. Roger Sheen
2. Robert D. Anderson
3. Jarno Elovirta
4. Shane Taylor
5. Misti Pinter
6. Garrett Guillotte
7. Lionel Moizeau
8. Stefan Eike

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