Maintenance Release 2.2.5

DITA Open Toolkit Release 2.2.5 includes the following bug fixes.

In earlier toolkit versions, the Word RTF transformation produced invalid RTF output when source
files contained tables with absolute column widths. Processing has been modified to treat all widths as
proportional, including units given in inches, centimeters, millimeters, or points. Absolute units are not
respected, but the toolkit now generates valid RTF output rather than crashing.
#1190,
#2333

References to empty ditamap files threw the DOTX031E error message during the
mapref processing stage. The toolkit no longer checks for subelements in the map and will now continue
processing as long as a root node is available.
#1549,
#2336

Several error messages generated during index processing for PDF output have been clarified to
better explain the cause of the error and provide more helpful information on how to resolve the issue.
#1709,
#2327

Links to <dlentry> elements were broken in PDFs generated via Apache FOP,
as FOP does not support the @id attribute on table rows. To work around this issue, DITA-OT
now moves the ID from the <dlentry> to an <fo:inline> element
in the first term when rendering PDF output via FOP.
#1764,
#2198

The DITA-OT 2.0 HTML5 transformation declared several XSL extension points that were not fully
implemented:

dita.xsl.html5

dita.xsl.html5.toc

dita.xsl.html5.cover

Three new templates now provide the necessary <dita:extension> elements to add
custom XSLT processing to the HTML5 transformation.
#1876,
#2313,
#2342

The OASIS catalogs for DITA 1.3 pointed to a series of non-existent resources. The catalog files
have been updated to remove spurious file references and errata have been submitted to OASIS for inclusion
in the original source catalogs.
#2266,
#2320

Performance of previous toolkit versions suffered substantially if a single warehouse topic was
used to store a large number of blocks for reference instead of multiple smaller warehouse topics with the
same total number of blocks. An expensive XPath expression in the content reference processing phase was
replaced with an optimized expression that dramatically reduces publication time in cases with thousands of
following siblings.
#2307,
#2309

In JavaHelp output, the copy-css task was called too early, before the
user.csspath parameter was evaluated, so CSS files were copied to a folder named
${user.csspath} rather than to the intended location. JavaHelp processing has been
corrected to avoid the duplicate dependency on the copy-css task and ensure that CSS files are handled
correctly.
#2311

Two unimplemented parameter extension points were removed from the HTML5 plug-in:

dita.conductor.html5.param

dita.conductor.html5.toc.param

Implementers who want to add parameters to the HTML5 transformation can instead require the base HTML
plug-in as well as the HTML5 plug-in and extend the base HTML plug-in's parameter extension points
#2312,
#2314

Content reference range processing has been modified to use before << and
after >> expressions rather than following-sibling and check that the conref end
target actually exists.
#2315

When a <topicsetref> element is used to refer to a
<topicset>, previous toolkit versions threw DOTX019W errors,
suggesting that every reference in the original <topicset> also specified
@type="topicset". Map reference processing has been modified to drop the
@type attribute as part of the resolution. This prevents such unintended side effects by
ensuring that the type no longer cascades further down the resolved branch.
#2321,
#2338

Support for flagging in HTML output has been imported (rather than included) and moved before
the extension point to allow custom plug-ins to override flagging behavior.
#2329

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

Maintenance Release 2.2.4

DITA Open Toolkit Release 2.2.4 included the following bug fixes.

The <title> is now used as link text when links are specified using a
<title> element (or specialized variant) as link target. This approach allows the
toolkit to be more lenient when authors link to a <glossterm> rather than to the
parent <glossentry> element, or to figure or table titles instead of the
<fig> or <table> element structure
recommended by the
DITA 1.3 specification.
#2283

The default value for the args.copycss parameter has been explicitly set to
no. Previous toolkit versions never initialized a default value, and only copied the
custom .css file if the parameter was set to yes.
#2278

Hyperlink reference processing has been modified to guard against error conditions caused by
Windows-style path separators in @href attribute values. Any backslashes are converted to
forward slash (“/”) characters to ensure that the attribute values are valid URI references according to
RFC 3986.
#2274

A typo was fixed in the common string logic for the PDF plug-in to retrieve the proper localized
string for the task “Results” label that appears when args.gen.task.lbl is set to
YES.
#2270,
#2216,
#2203

DITA-OT 2.2 introduced a regression in which topics referenced via keys in submaps were not
included in the table of contents. The keyref resolution mechanism has been corrected to ensure that key
references in submaps are correctly resolved.
#2264

A new DOTJ068E error message was added to report cases when a conref "mark"
action is used to mark a target element without a corresponding content reference target (for example, when
the order of the "mark" element and the pushed element is reversed).
#1293

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

Maintenance Release 2.2.3

DITA Open Toolkit Release 2.2.3 included the following bug fixes.

Specifying the source of a long quote with a @keyref attribute on a
<longquoteref> element caused a Null Pointer Exception. The keyref parser has been
modified to ensure that key references on long quote references are correctly resolved.
#2246

The keyscope cascading mechanisms for branch filtering have been modified to comply with the
DITA 1.3 specification. In cases where no @keyscope attribute is specified on a
filtered branch, the prefix and/or suffix values specified in <dvrKeyscopePrefix> /
<dvrKeyscopeSuffix> are now used as the effective key scope names. Key scope
prefixes and suffixes are no longer propagated to descendant key scopes, but only applied to the branch
parent.
#2240

PDF: In DITA-OT 2.2.2, if a <link> element contained both
<linktext> and a description in the <desc> element, the
hyperlink was rendered with the contents of the <desc> element appended to the
contents of the <linktext> element. Link processing has been modified to ensure that
<link> elements with descriptions are rendered correctly.
#2236

PDF: Index term processing has been revised to ensure that indexes in PDF output generated with
Apache FOP correctly include page ranges when @start and @end attributes are
defined on <indexterm> elements and the terms of the index range appear on different
pages. A single page reference is generated in cases where both occurrences of the index term appear on the
same page.
#2214

ODT: The OpenDocument Text transformation has been revised to support SVG images for which image
dimensions are not specified via @height and @width attributes.
#2211

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

Maintenance Release 2.2.2

DITA Open Toolkit Release 2.2.2 included the following bug fixes.

PDF: In earlier DITA-OT 2.x releases, short description content was not rendered when publishing
from a bookmap with the args.chapter.layout parameter set to BASIC.
Short descriptions are now rendered properly.
#2023

Windows: The name of the JAR file for Apache Ant has been corrected to fix the
ANT_HOME is set incorrectly or ant could not be located error that appeared when running
the bundled Ant version on Windows in DITA-OT 2.2.
#2172

The order in which plug-ins are integrated has been revised to guarantee that the base DITA-OT
plug-ins always come first. This ensures that base target code cannot be overridden.
#2180

Content references with relative paths were not properly resolved to the target document in some
cases. The conref base URI resolution mechanism was fixed to ensure that relative references are now
resolved correctly.
#2192

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

Maintenance Release 2.2.1

DITA Open Toolkit Release 2.2.1 included the following bug fixes.

PDF: Several templates in the pr-domain.xsl file used
value-of rather than apply-templates to output the element contents.
This prevented flagging from working as intended in PDF output. This has been corrected to ensure that
elements in the programming domain are properly flagged.
#2170

The name of the JAR file for the Apache Commons library that provides reusable Java components
has been corrected in the integrator Ant script to fix the NoClassDefFoundError error that
appeared when the integrator ran in DITA-OT 2.2.
#2163

PDF title metadata is now generated correctly for DITA maps that set the
@xml:lang attribute. In certain cases, previous versions of DITA-OT displayed the
XMP structure: 1 label in the Document Properties dialog instead of the map title.
#2154

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

Requirements

Release Highlights

DITA 1.3 support

DITA Open Toolkit 2.2 provides processing support for the
OASIS DITA 1.3 specification. Initial preview support for this specification was added in version 2.0 of the
toolkit; version 2.2 extends this foundation to support key scopes and branch filtering along with additional DITA
1.3 features.

Because DITA 1.3 is fully backwards compatible with previous DITA DTDs and schemas, DITA-OT 2.2 provides
the 1.3 materials as the default DTDs for processing. The XML Catalog resolution maps any references for
unversioned DITA doctypes to the 1.3 DTDs. All processing ordinarily dependent on the 1.0, 1.1, or 1.2 definitions
continues to work as usual, and any documents that make use of the newer DITA 1.3 elements or attributes will be
supported with specific new processing.

DITA Open Toolkit Release 2.2 extends DITA 1.3 support with the following
enhancements:

Important: The DITA 1.3 grammars are now used as the default DTDs for processing
#2094

Processing order has been revised to process any same topic fragments used in conrefs before the
conref phase, to enable content references to elements in the same topic using a reference such as
<p conref="#./ID"/> as reported in
#1649.
#1968

New HTML5 output

The HTML5 transformation has been moved to a separate plug-in to facilitate
customization of modern HTML5-based output. The default CSS has been refactored in
Sass as a foundation for further extensions with CSS frameworks, custom plug-ins and
future toolkit versions. (The original XHTML plug-in remains available to support existing legacy HTML-based
output formats such as TocJS, HTML Help and JavaHelp.)
#2099

The HTML5 transformation has been extended with a new
nav-toc parameter that can be used to generate a table of contents in the HTML5
<nav> element of each page. The navigation can then be rendered in a sidebar or
menu via CSS. This parameter is disabled by default (none), but can be enabled by setting
the value to partial (which includes the current topic in the ToC along with its parents,
siblings and children), or full (which generates a ToC for the entire map).
#2103

PDF supports new languages

The PDF transformation has been extended to support additional languages with localized
strings files and index collation.
#2085,
#2089

Resolved issues

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

Features

DITA Open Toolkit Release 2.2 includes the following new features:

The args.artlbl parameter previously provided in HTML-based transformations
to show the source file name along with referenced images has been added to the PDF transformation. For
inline images, the label appears immediately after the image; for standalone images, it appears on a line
following the image.
#2072,
#2062

In PDF output, any index entries that begin with special characters are now moved to a dedicated
section of the index. (Previous toolkit versions issued a warning and dropped any unexpected index terms.)
#2073,
#2071

The plug-in configuration file resources/plugins.xml generated by the
integration process now adds the @xml:base attribute to each plug-in configuration element
so that file paths in the plug-in configuration can be resolved relative to the plug-in folder. This makes
it easier to share a DITA-OT distribution with others via a version control system or bundle it with an
application without re-running the integration process in each installation location.
#2018

The move-meta-entries and mappull steps have been merged. The
mappull step has been moved into move-meta-entries and an empty target
for mappull is retained for backwards compatibility.
#1995

The generation of page masters and page sequence masters in the PDF plug-in has been modularized
to make it easier to extend or override the default set of masters.
#1984

The PDF plug-in has been extended with two new extension points for
flagging-preprocess and i18n-postprocess to alllow plug-ins to customize
these steps of the flagging process.
#1976

The key definition reading process has been moved from the gen-list
preprocessing module to the keyref module to further modularize the code and support
additional DITA 1.3 use cases for keys, such as a map that includes a map that then includes another map
with a key definition.
#1962

The mapref processing stage has been moved to the beginning of the preprocessing pipeline to
simplify keyref processing and support DITA 1.3 branch filtering by allowing all processing to be performed
on a single map.
#1961

The dita-install option can now be used to integrate multiple plug-ins at once. If no
file or url argument is provided, the integration process reloads
plug-ins from the plugins directory, so you can unzip multiple plug-ins to the
plugins directory and run dita-install to integrate them all at once.
#1957

The PDF transformation has been extended with XML catalog support for RenderX XEP. The main
DITA-OT catalog file is now used to ensure that doctypes such as SVG graphics pass validation when
generating PDF output using XEP.
#1955

The Java code has been refactored to use URI-based processing (rather than File objects or
Strings) wherever possible to permit automatic validation of values and support the use of external URIs.
This allows non-file resources to be processed with commands such as dita-i http://example.com/test.ditamap -f html5.
#1544,
#1953

Plug-in folders are now sorted before the integration process runs to ensure predictable results
and consistent order each time plug-ins are reloaded.
#1905

The metadata format in the plugin.xml file for the
org.dita.xhtml plug-in has been refactored with abstract transtypes that group common
parameters used in multiple transformation types. This approach allows common parameters to be defined in
one place and re-used for multiple output formats as necessary.
#1866

The dita command options have been extended to add -t as a
synonym for the -temp option used to specify the location of the temporary directory.
#1836,
#2039

The validation of the table group @cols attribute has been relaxed to support
use cases in which tables containing auto-generated @cols values are reused via content
references.
#1835

The format of the plugin.xml file has been extended to allow plug-ins to
specify the list of public parameters added for each transformation type and announce extensions to a list
of arguments defined in another transtype.
#1757

Enhancements

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

PDF: Table body rows now use the keep-together.within-page attribute to prevent
page breaks within rows.
#2118

PDF: List item numbers are now aligned with the baseline to prevent issues when list items
include icons or other inline elements that affect line spacing.
#2117

PDF: Step section bodies within task topics now honor the $side-col-width value
from basic-settings.xsl, which defines a uniform indent relative to the page margin and
aligns with other body text. (Earlier toolkit versions used a hard-coded 9-mm start-indent
setting.)
#2116

HTML5 and XHTML table border processing has been optimized to match the expected output based on
the table width, column separation, row separation and frame settings in the source files, permit easier
integration of CSS frameworks, and output valid documents.
#2097

The task headings (About this task, Procedure, etc.) and flags for Optional and Required steps
in the PDF transformation have been synchronized with those available in the common string
files, XHTML and ODT transformations. Source files that make use of these
options should now yield more more consistent results when generating output in multiple formats.
#2088

PDF: The index groups for Numerics and Special Characters have been aligned for greater
consistency across languages.
#2080,
#2074

PDF: The “pointing finger” image hand.gif is no longer used to highlight
<note> elements, as it may be considered offensive in some cultures. The image file
is still available for backwards compatibility with any customization that references it, and the "Note
Image Path" variables are still present to permit the use of custom image files, but they are now empty by
default. Text-only note labels appear instead, and the default indentation is reduced by the width of the
empty note image column.

Note: The warning.gif file is still used for Attention,
Caution, Danger and Warning admonitions.

The outer.control parameter description was corrected to clarify how the
DITA-OT handles content files that are not located in or below the directory containing the master DITA map.
#1707#2066

Formatter-specific code for XSL-FO rendering engines has been removed from the PDF plug-in and
split into separate plug-ins for Apache FOP, Antenna House Formatter and RenderX XEP.
#2058

The classpath order is now retained when generating the env.sh and
env.bat environment files to ensure predictable results when a plug-in that uses Java
libraries presupposes a certain classpath order.
#2053

The PDF2 flagging step that converted stage1.xml to
stage1a.xml in the PDF process has been refactored to take advantage of the flagging
information added during the common preprocessing stage.
#2049,
#2047

The dita.bat Windows batch file for the dita command now
sets the DITA_HOME variable to point to the correct location of the DITA-OT.
#2046

PDF: A new axf.opt parameter has been added to specify the user
configuration file for Antenna House Formatter.
#2041

Processing mode coverage has been improved to treat error messages as fatal errors, so the
DITA-OT will now stop processing if any source files are missing when the
processing-mode parameter is set to strict.
#1986

Table columns for which no width is defined in a <colspec> element are no
longer set to 1* per the CALS Table Model. Instead, empty @colwidth
attributes are generated to allow formatter-specific auto-layout. The FO processor can then set the width of
the columns based on the column content.
#1970