DITA Open Toolkit 3.7 Release Notes
DITA Open Toolkit 3.7.4 is a maintenance release that fixes issues
reported in DITA-OT 3.7, which includes stable IDs in re-used
content, a common variable format for generated text strings, and an updated preview of features for the
latest draft of the upcoming DITA 2.0 standard, such as the new “combine” chunk action, the
<titlealt>
element, and the alternative titles domain.
DITA-OT releases follow
semantic versioning guidelines. Version numbers use the
major.minor.patch
syntax, where
major versions may include incompatible API changes, minor versions add
functionality in a backwards-compatible manner and patch versions are maintenance releases
that include backwards-compatible bug fixes.
Requirements
- You can download the Oracle JRE or JDK from oracle.com/java under commercial license.
- Eclipse Temurin is the free OpenJDK distribution available from adoptium.net.
- Free OpenJDK distributions are also provided by Amazon Corretto, Azul Zulu, and Red Hat.
DITA-OT 3.7.4
DITA Open Toolkit 3.7.4 is a maintenance release that includes the following bug fixes.
- In PDF output generated with DITA-OT 3.3 and newer,
<abbreviated-form>
references did not work correctly when both<topicref>
elements and<glossentry>
elements used the same@id
value. Processing has been updated to filter any topic references and handle only glossary entries. #3937, #4002 - When processing maps, the
@processing-role
and@scope
attributes were not cascading downward in the map. Processing has been updated to correctly apply these attributes to any elements that are children of the element where the attributes are specified. #3940, #4003 - In earlier versions, builds failed when filtering removed content that was referenced elsewhere. The XSLT matcher functions have been updated to handle cases when the class argument is an empty sequence, which allows builds to continue. #3814, #4028
- In the Map-based linking (maplink) preprocessing step, related link processing has been updated to consider references to topics duplicated by branch filtering. #3989, #3993
- In earlier versions, builds failed with a NullPointerException when a peer mapref and local mapref used the same keyscope. Processing has been updated to allow builds to continue in these cases. #4007, #4010
- When files were parsed with a custom parser, earlier versions categorized the file as the
original file format. (For example, when the LwDITA parser was used to parse Markdown, the file was
treated as
@format
=markdown
). The map-first preprocessing routines in thepreprocess2
target have been updated to align with the defaultpreprocess
target, which ensures that files parsed with a custom parser are categorized asdita
. #4027
For additional information on the issues resolved since the previous release, see the 3.7.4 milestone and changelog on GitHub.
DITA-OT 3.7.3 released September 6, 2022
DITA Open Toolkit 3.7.3 is a maintenance release that includes the following bug fixes.
- In earlier versions, links to non-DITA resources were broken in branch filtering scenarios that
used the
<dvrResourcePrefix>
or<dvrResourceSuffix>
elements to adjust the names of filtered topic files. Processing has been corrected to only rename DITA resources, and preserve the original names of non-DITA resources like images or other assets. #2704, #3947 - The image metadata processing failed to determine the height and width of images referenced via
keyrefs. The
@format
attribute value is now set toimage
in the temporary .job.xml file, so the image dimensions can be read from the file metadata. #3353, #3963 - In earlier versions, builds failed with a NullPointerException when projects contained references with absolute paths pointing outside the folder where the DITA map is located. A new guard has been added to handle these cases more gracefully. #3366, #3977
- In DITA-OT 3.5.4 and later, builds failed with a NullPointerException when parsing specialized topics containing only table rows or cells. The table normalization filter has been updated to process these cases correctly. #3597, #3962
- When passing DITA maps as --resource files with absolute paths on Windows, the temporary files folder path was added to the map path, resulting in invalid references. Processing has been updated to properly compute the file path for map resources with absolute paths. #3724, #3964
- DITA-OT 3.6 always used the bundled open-source Saxon Home Edition (HE), even when a license for Saxon Professional Edition (PE) or Enterprise Edition (EE) was available in the DITA-OT classpath. The configuration has been updated to allow DITA-OT to use a licensed Saxon XSLT processor if present. #3727, #3949
- Earlier versions generated incorrect links to nested topics when the parent topic contained a key reference and was re-used in different key scopes. Processing has been updated to preserve the fragment identifiers and ensure that links are generated correctly when topics are duplicated for each key scope. #3867, #3874, #3945
- On Windows, publishing speed was slower when running DITA-OT with recent Java versions, because the file canonicalization cache is no longer enabled by default in Java 12 and newer (see JDK-8207005). The Java commands in the dita.bat and ant.bat wrapper scripts have been updated to re-enable caching. #3932, #3933
- On Windows, DITA-OT 3.6 failed to build output when input file paths contained non-ASCII characters. The encoding of the .job.xml file in the temporary directory has been explicitly set to UTF-8 to ensure that builds complete regardless of the operating system locale and input file path encoding. #3934, #3943
- In earlier versions, builds failed with a NullPointerException when custom plug-ins referenced missing stylesheets. A new guard has been added to handle these cases more gracefully. #3959, #3960
- When writing messages to the console in DITA-OT 3.6,
<xsl:message>
references to an XML element recursively printed its descendants. The logging code has been updated to properly serialize the nodes in XSL messages. #3969, #3978 - The DOTJ085E error message has been aligned for consistency with other messages. #3972
- In DITA-OT 3.7, content references to topic elements were not resolved when publishing to HTML. Processing has been corrected to ensure that topic conrefs are handled correctly. #3976, #3979
- In earlier verions, builds failed with a NullPointerException when processing maps that
contained elements without
@class
attributes, such as inside<foreign>
elements. Processing has been updated to handle these situations correctly. #3980, #3981 - In earlier versions, builds would fail with XSLT errors when named templates returned an empty sequence. Processing has been relaxed to allow processing to continue under these circumstances. #3991, #3992
- The bundled Jackson data format dependency was updated to resolve a security vulnerability in the SnakeYAML library, which has been updated to version 1.31. #3999 #4000
For additional information on the issues resolved since the previous release, see the 3.7.3 milestone and changelog on GitHub.
DITA-OT 3.7.2 released May 17, 2022
DITA Open Toolkit 3.7.2 is a maintenance release that includes the following bug fixes.
- In version 3.7.1, processing failed when link targets contained unexpected syntax. The URL
processing and validation filters in the Java code have been updated to support
mailto:
links and additional URI schemes. #3730, #3912 - The DITA 1.3 grammar files have been updated to allow the
@outputclass
attribute on the<change-historylist>
element. #3905, #3911 - Processing will now report an error when a project file
param
is used to define a parameter that should be set with a dedicated key instead. #3913, #3915 - When parallel processing was enabled with parallel=true, some files were occasionally skipped with “folder could not be created” errors when different processes tried to create the same directory. Processing has been updated to handle concurrent directory creation. If the directory already exists, processing will now continue without errors. #3917, #3925
- The
jackson-databind
library has been updated to the latest patch version 2.13.2.2 to address a reported security vulnerability: CVE-2020-36518. #3923
For additional information on the issues resolved since the previous release, see the 3.7.2 milestone and changelog on GitHub.
DITA-OT 3.7.1 released March 23, 2022
DITA Open Toolkit 3.7.1 is a maintenance release that includes the following bug fixes.
- In earlier versions, paths or filenames with typewriter apostrophes “
'
” or tilde “~
” characters caused HTML builds to fail. Processing has been updated to ensure that these characters are handled correctly. #2844, #3880 - On Windows, referencing images on another disk drive caused builds to fail. Resources with different drive letter paths are now handled correctly. #3635, #3885
- As of version 3.6, XSL messages with serialized XML elements included only the text content. Processing has been revised to include the original XML element structure as in DITA-OT 3.5.4 and earlier releases. #3662, #3893
- When publishing documents with nested topics or multiple glossary entries in the same file,
generating
@copy-to
attributes with force-unique=true caused earlier versions of DITA-OT to create redundant copies of each file. TheForceUniqueFilter
has been updated to properly handle references to separate topics within the same file. #3750, #3894 - Earlier versions failed with errors when generating HTML5 output for chunked topics that include
links between inner topics. Chunk processing has been updated to ensure that links between nested topics are
generated correctly when the
@chunk
attribute is defined withto-content select-topic
. #3846, #3881 - The bundled Apache Xerces™ XML parser has been upgraded to version 2.12.2, which includes security updates to mitigate the vulnerability described in CVE-2022-23437 when handling specially crafted XML document payloads. #3857, #3860
- Strict processing mode has been updated to stop processing when images are missing. Earlier versions reported errors in this case, but allowed processing to continue. #3858, #3871
- In earlier versions, the PDF2
dita.xsl.xslfo.i18n-postprocess
extension point did not work, because the extension point and the XSLT templates were defined in the same place. The templates have been moved to a new file to ensure that templates in custom plug-ins take precedence when using the extension point. #3861, #3862 - The DITA-OT 3.7 distribution package contained a spurious fop.jar file with an empty manifest in the root folder. The unnecessary Java archive has been removed. #3864
- In earlier versions, the branch filtering routine did not handle nested subtopics correctly. Processing has been corrected to properly re-write topic references with ditavalrefs and inner topics. #3875, #3887
- Messages in build logs now contain location information when available.
#3877,
#3884
The following error messages now include the name of the file where the issue was found:
- DOTJ041E
- DOTJ045I
- DOTJ046E
- DOTJ052E
- DOTJ060W
- DOTJ074W
- DOTJ077F
- DOTX008E
- DOTX065W
- The German and French translations for Caution, Notice, and Remember note labels have been updated to align with the signal words defined in ANSI Z535. #3882, #3883
- When publishing to HTML, builds would fail when image paths contained a
?
query component or#
fragment identifier. Processing has been updated to handle these references correctly. #3886, #3892 - The “Notice” strings added to PDF2 in DITA-OT 1.7.1 have been moved to the base plugin to ensure that all signal words for safety levels are defined in the same location. #3888, #3899
For additional information on the issues resolved since the previous release, see the 3.7.1 milestone and changelog on GitHub.
DITA-OT 3.7 released January 17, 2022
DITA Open Toolkit Release 3.7 includes stable IDs in re-used
content, a common variable format for generated text strings, and an updated preview of features for the
latest draft of the upcoming DITA 2.0 standard, such as the new “combine” chunk action, the
<titlealt>
element, and the alternative titles domain.
Common format for generated text
Prior to DITA-OT 3.7, there were two different XML structures for adding or modifying generated text
(gentext). The base plug-in org.dita.base and any custom overrides defined via the
dita.strings.xsl extension point used a root element <strings>
,
with individual strings in <str>
elements with @name
attributes. This
format was previously used for HTML, and all other output formats except PDF.
<?xml version="1.0" encoding="utf-8"?>
<strings xml:lang="en-US">
<str name="String1">English generated text</str>
</strings>
The PDF plug-in org.dita.pdf2 used a root element <vars>
with an XML namespace,
and strings in <variable>
elements with @id
attributes.
<?xml version="1.0" encoding="UTF-8"?>
<vars xmlns="http://www.idiominc.com/opentopic/vars">
<variable id="String1">English generated text</variable>
</vars>
Starting with DITA-OT 3.7, these structures have been deprecated and replaced with a new unified format. All
files now use <variables>
as the root element, with the
<variable>
elements previously used in PDF strings. The new format supports the XSL
parameters used by the earlier PDF strings format to pass dynamic information such as chapter numbers or
figure titles.
<?xml version="1.0" encoding="UTF-8"?>
<variables>
<variable id="String1">English generated text</variable>
</variables>
The old formats are still supported, but plug-in developers should update any generated text files to reflect the new structure, as support for the old formats may be removed in a future release. #3817
Updated DITA 2.0 preview
In addition to the DITA 2.0 preview support provided in DITA-OT 3.5 and 3.6, this release adds support for the DITA 2.0 “combine” chunk action, and updated processing for the latest DRAFT versions of the DITA 2.0 DTD and RELAX NG grammar files from OASIS (as of January 2022). #3674, #3760, #3809, #3833, #3847
- The new “combine” chunk action can be used to merge content into new output documents.
When the
@chunk
attribute is set tocombine
on a map, branch, or map reference, all source DITA documents grouped by that reference will be combined into a single document in the output.(Support for the DITA 2.0 “split” chunk action has not yet been implemented.)
Note: The new chunk action is only applied if the root map has a DITA 2.0 doctype, such as:<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA 2.0 Map//EN" "map.dtd">
If the root map uses an unversioned (or 1.x) doctype, DITA 1.3 processing will be applied, and 2.0 chunk actions will be ignored. With a 2.0 root map, any 1.3 chunk actions are ignored.
- The new
<keytext>
element can be used to define variable text referenced by@keyref
. Although the DITA 2.0 grammar files in this release support the use of<keytext>
in authored files, DITA-OT 3.7 does not yet have processing support for the element. - The new alternative titles domain and
<titlealt>
element (separate from the<titlealts>
element in DITA 1.3) may be used when you need to use an alternate title, such as for a navigation title, search title, link title, subtitle, or title hint. - The new
@appid-role
attribute is available on<resourceid>
. The default iscontext-sensitive-help
. - The
@keyref
attribute was added to all elements in the highlighting domain and the new emphasis domain. - The
@href
,@format
, and@scope
attributes are now used consistently for linking elements. - Several obsolete elements and attributes have been removed from DITA 2.0, including:
<anchor>
<anchorref>
<data-about>
<hasInstance>
<hasKind>
<hasNarrower>
<hasPart>
<hasRelated>
<longquoteref>
<relatedSubjects>
<sectiondiv>
<subjectRel>
<subjectRelHeader>
<subjectRelTable>
<subjectRole>
@anchorref
from<map>
@copy-to
@href
,@format
,@type
,@scope
,@reftitle
from<lq>
(@keyref
remains)@locktitle
@longdescref
@mapkeyref
@print
@query
@specentry
from<stentry>
@spectitle
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 3.7 includes the following enhancements and changes to existing features:
- The
Dockerfile has been updated to better support the official
dita-ot-action that was introduced in 3.6.1 to publish documentation via
GitHub Actions whenever your source files are changed. The Dockerfile
adds the SHELL command and installs the
locales
andtzdata
packages as part of the base image, so custom actions can be simplified to a series of scripting hooks. #3665 - In earlier versions, IDs defined on elements in reusable components were not
preserved when the parent element was included in other topics via content reference. In this case, element
IDs were always randomized to prevent duplicate IDs, but this made it difficult to cross-reference reused
content. The
conref
preprocessing module has been updated to retain the original IDs whenever possible, and only generate a randomized ID if the original would not be unique in the new context. This ensures that content references produce stable anchors in HTML and named destinations in PDF output. #3736, #3739 - Additional support for Ant
<style>
was added to make custom<pipeline>
configurations more consistent with XSLT tasks in Ant. A stylesheet can be passed as an Ant resource, providing support for classpath-based plug-in resources. #3780 - The mappull processing step has changed how related links are generated with
args.rellinks. Starting in 3.7, noparent will not generate any
ancestor links and nofamily will not generate sibling, cousin, ancestor, or descendant
links. Prior to 3.7, args.rellinks=all did not actually include all
links. Now it will. As in previous versions, the default value for PDF output is nofamily,
and other output formats include all link roles except
ancestor
links. #3792, #3850 - Mapref processing was improved to remove any duplicate
@keyscope
values. Prior to 3.7 it was possible that<mapref>
and<map>
would contribute the same@keyscope
value when the value was defined on both. #3796 - A
commonattributes
mode was added to the HTML5, PDF, and XHTML plug-ins to allow for easier extension. This is a backwards compatible change, however, existing plug-ins should be changed to use the newcommonattributes
mode. #3806Figure 4. Named template prior to version 3.7 <xsl:template name="commonattributes"> <!-- whole copy of commonattributes named template with customizations --> </xsl:template>
Figure 5. Template mode as of version 3.7 <xsl:template match="@* | node()" mode="commonattributes"> <xsl:param name="default-output-class" as="xs:string*"/> <xsl:next-match> <xsl:with-param name="default-output-class" select="$default-output-class"/> </xsl:next-match> <!-- customizations --> </xsl:template>
-
The
copy-to
preprocessing module has been updated to preserve fragment-only links. This ensures that any local anchors do not change when original topic resources are copied to new resources defined by the@copy-to
attribute. #3811, #3832 - HTML5
- The order of elements in the
<head>
element of the HTML template files was changed to facilitate overrides. The common CSS stylesheets and any custom CSS files specified via args.css now come after the contents of the custom header file specified via args.hdf. This change better supports use cases in which the custom header file is used to insert references to external CSS stylesheets for frameworks like Bootstrap. In previous versions of DITA-OT, framework styles took precedence over any equivalent rules in the user’s custom stylesheet. This change allows rules in custom CSS files specified via args.css to override any of the framework styles as necessary. #3770 - The legacy
gen-user
templates that were originally used to add content to the<head>
element have been deprecated and will be removed in a future release. For each of these templates, parameter-based customizations are available that can be used to specify files that contain content that extends the default processing. #3835, #3849gen-user-head
→ use args.hdf insteadgen-user-header
→ use args.hdrgen-user-footer
→ use args.ftrgen-user-scripts
→ use args.hdfgen-user-styles
→ use args.css
- Support for the legacy media format Adobe Flash has been removed. All major browser vendors block Flash Player in recent versions, making it difficult to view Shockwave Flash content. #3791
- The HTML5 stylesheets were updated to use XSL modes instead of named templates.
#3794
This is a backwards compatible change, however, existing plug-ins should be changed to use modes instead of named templates for:
copyright
gen-endnotes
generateDefaultMeta
generateCssLinks
generateChapterTitle
processHDF
generateBreadcrumbs
processHDR
processFTR
generateCharset
- The order of elements in the
- PDF
- The new
@note__image
attribute set was added to combine attributes for images or icons for notes. #3529 #3660 - Japanese font mappings have been updated to ensure characters are rendered correctly.
#3768,
#3769
- The logical font
Sans
now prefers MS-Gothic, Hiragino Kaku Gothic Pro, HiraKakuProN-W3, or YuGothic over Arial Unicode MS. - For
Serif
text, MS-Mincho, Hiragino Mincho Pro, HiraMinProN-W3, or YuMincho are preferred to Arial Unicode MS. - For
Monospaced
text, MS-Gothic, Hiragino Kaku Gothic Pro, HiraKakuProN-W3, YuGothic, or Arial Unicode MS are used.
- The logical font
- The source code for the renderer-specific PDF plug-ins for Antenna House Formatter (AXF) and
RenderX XEP have been extracted to dedicated code repositories. The renderer-specific plug-ins are still
distributed with DITA-OT. Only the source code location changed, allowing for easier maintenance.
#3807,
#3813
This allows the plug-ins to be updated separately by commercial software vendors or open source contributors independent of the DITA-OT release cycle:
- The new
- Several bundled dependencies have been upgraded to new versions:
- Up until DITA-OT 2.4, the
log4j
logging library was bundled as a dependency of the Apache™ Formatting Objects Processor (FOP). DITA-OT 2.4 upgraded FOP to version 2.1, and removed thelog4j
library, but left the corresponding configuration files behind. The obsolete log4j.properties files have now been removed from the distribution package. #3841
Bugs
DITA Open Toolkit Release 3.7 provides fixes for the following bugs:
- In PDF output generated with previous versions, “Warning” note labels used the same attribute set as “Danger” note labels. Processing has been corrected to apply the dedicated attribute set defined for warning note labels. Both attribute sets are empty by default, but this change makes it easier for custom plug-ins to define separate styling for danger and warning notes. #3709
- HTML5 output generated by earlier versions defined the character set twice in the
<head>
element, which certain HTML validation services reported as an error. The legacy<meta>
element that specified the content type with an@http-equiv
attribute has been removed in favor of the simpler version, which defines only the character set:<meta charset="UTF-8">
. #3715, #3738 - Key references were not properly expanded within content references when using key scopes. Processing has been updated to create unique topics for all resources, including resource-only topics. #3733, #3775
- The command line interface now respects the convention to disable colored output when either the
TERM=dumb
orNO_COLOR
environment variables are set, or the --no-color option is passed to the dita command. #3741 - The German localization of the PDF Preface header strings included the page numbers twice, and the prodname parameter was missing. The default German strings have been aligned to include the product name and page numbers in the same pattern as other languages. #3742
- Column and row separators defined via the
<tgroup>
element were ignored. HTML processing has been corrected to ensure separators are applied as expected in HTML5 and XHTML table groups. #3751, #3752 - The PDF2 internationalization configuration for the service mark character used an incorrect
decimal code
ࡈ
, which corresponds to theU+0848 MANDAIC LETTER ATT
character: ࡈ. The language files have been updated to use the correct hexadecimal code℠
for theU+2120 SERVICE MARK
character: ℠. #3754 - When plug-ins were installed on Windows systems, the integration process wrote Windows-style backslash “\” characters as path separators to the generated properties files, which caused errors if the same DITA-OT installation was used on other operating systems. All resources generated by the integrator now use UNIX-style slashes “/” as path separators, which work on Linux, macOS, and Windows. This ensures DITA-OT installations remain portable for use in continuous integration systems and other cross-platform publishing scenarios. #3755, #3759
- Project files that included empty values in
<param>
elements failed with errors. Processing has been updated to allow processing to continue. #3761, #3824 - In PDF output, figure descriptions were rendered before the image and title. Processing has been updated to correct the order of elements within figures. The image now appears first, followed by title and description. #3765, #3766
- When processing simple tables such as parameter tables with no explicit header elements, earlier versions failed to assign IDs to generated elements. IDs are now generated correctly in these cases. #3778
- XHTML processing has been refined to correct the order of contents within
<object>
elements. Any<desc>
or<longdesc>
content is now generated after any<param>
element to ensure the resulting XHTML files pass EPUBCheck validation. #3779 - HTML output generated from SVG files that specified height or width values in centimeters or inches were not scaled properly. Length values are now converted to pixels to ensure images are scaled correctly. #3785, #3786
- When publishing documents with peer map references, spurious errors were reported for missing files, link text, and navigation titles when the peer maps were not available at processing time. Processing has been updated to relax these requirements for peer maps, and allow processing to complete without errors. #3790
- Table of contents navigation in HTML5 output used a
<nav>
element with the ARIA@role
attribute set totoc
. Certain accessibility tools flagged this as an error. The invalid role has been replaced with thenavigation
landmark role. A newtoc
class allows custom CSS styles to target the ToC navigation. CSS rules that use thenav[role='toc']
selector can be simplified tonav.toc
. #3800, #3801 - A 17-year-old bug in the content reference implementation has been resolved. When the original conref code was updated to XSLT 2.0 years ago, the syntax was not adjusted to account for the differences between XSLT 1.0 and 2.0, which caused errors in the selection of the first topic in a document. #3842
- DITA 1.3 grammar files have been updated to include hotfixes from the latest OASIS errata
branch, which resolve issues with the available attributes on
<change-historylist>
and<colspec>
elements. #3843
Contributors
DITA Open Toolkit Release 3.7 includes code contributions by the following people:
- Jarno Elovirta
- Roger Sheen
- Radu Coravu
- Eric Sirois
- Robert D Anderson
- Eliot Kimber
- Chris Papademetrious
- Julien Lacour
- Toshihiko Makita
- Dmitriy Krasilnikov
- David Bertalan
- Jake Bourne
- Jason Fox
- Joe D. Williams
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.7 provides corrections and improvements to existing topics, along with new information in the following topics:
- Migrating to release 3.7
- DITA 2.0 preview support
- Customizing generated text
- Installing DITA-OT via Homebrew
For additional information on documentation issues resolved in DITA Open Toolkit Release 3.7, see the 3.7 milestone in the documentation repository.
DITA Open Toolkit Release 3.7 includes documentation contributions by the following people:
- Roger Sheen
- Jarno Elovirta
- Lief Erickson
- Jason Fox
- Nicolas Delobel
- Stefan Eike
For the complete list of documentation changes since the previous release, see the changelog.