Re-usable components

Upgrade stylesheets to XSLT 2.0

The Saxon project has announced plans to remove XSLT 1.0 support from the Saxon-HE library that ships with DITA-OT:

…we’re dropping XSLT 1.0 backwards compatibility mode from Saxon-HE, and hope to eliminate it entirely in due course.
https://www.xml.com/news/release-saxon-98/

DITA-OT 3.0 and 3.0.1 included Saxon-HE 9.8.0.5, which rejects XSLT stylesheets that specify version="1.0". Plug-ins with XSLT templates specifying version 1.0 will fail with the message “XSLT 1.0 compatibility mode is not available in this configuration.”

To resolve this issue, change any occurrences of <xsl:stylesheet version="1.0"> in custom plug-in stylesheets to at least <xsl:stylesheet version="2.0">.

Tip: DITA-OT 3.0.2 includes Saxon-HE 9.8.0.7, which restores XSLT 1.0 backwards-compatibility mode, but the DITA Open Toolkit project recommends upgrading all stylesheets to XSLT 2.0 to ensure plug-ins remain compatible with future versions of DITA-OT and Saxon-HE.

Validating plug-ins

DITA-OT includes a RELAX NG schema file that can be used to validate the plugin.xml files that define the capabilities of each plug-in.

To ensure the syntax of your custom plug-in is correct, include an <?xml-model?> processing instruction at the beginning of the plugin.xml file, immediately after the XML prolog:

<?xml-model href="dita-ot/plugin.rnc" type="application/relax-ng-compact-syntax"?>

If your authoring environment does not apply this schema automatically, point your editor to dita-ot-dir/resources/plugin.rnc to associate the schema with your plug-in file.

DITA for Print: A DITA Open Toolkit Workbook (Second Edition, 2017)

Authored by Leigh W. White, DITA Specialist at IXIASOFT, and published by XML Press, DITA for Print walks readers through developing a PDF customization from scratch.

Here is an excerpt from the back cover:

DITA for Print is for anyone who wants to learn how to create PDFs using the DITA Open Toolkit without learning everything there is to know about XSL-FO, XSLT, or XPath, or even about the DITA Open Toolkit itself. DITA for Print is written for non-programmers, by a non-programmer, and although it is written for people who have a good understanding of the DITA standard, you don’t need a technical background to get custom PDFs up and running quickly.

This is an excellent, long-needed resource that was initially developed in 2013 for DITA-OT 1.8.

The second edition has been revised to cover DITA Open Toolkit Version 2, including customizing the DITA 1.3 troubleshooting topic type, localization strings, bookmarks, and the new back-cover functionality.

Important:

The first edition of DITA for Print recommended copying entire files from the PDF2 plug-in to your custom plug-in. The DITA-OT project — and the second edition of the book — do not recommend this practice.

Instead, you should copy only the specific attribute sets and templates that you want to override. Following this practice will more cleanly isolate your customizations from the DITA-OT code, which will make it easier for you to update your plug-ins to work with future versions of DITA-OT.

DITA for Practitioners: Volume 1, Architecture and Technology (2012)

Authored by Eliot Kimber and published by XML Press, this seminal resource contains a chapter dedicated to DITA Open Toolkit: “Running, Configuring, and Customizing the Open Toolkit”. In addition to a robust overview of DITA-OT customization and extension, the chapter contains a detailed example of customizing a PDF plug-in to specify 7" × 10" paper size and custom fonts for body text and headers.

The DITA-OT chapter in DITA for Practitioners: Volume 1 was written for DITA-OT 1.5.4, which was the latest stable version at the time it was written.

Supported Java versions

DITA-OT is designed to run on Java version 8u101 or later. Compatible Java distributions are available from multiple sources:

You can download the Oracle JRE or JDK from oracle.com/technetwork/java.
OpenJDK is an open-source implementation of Java available from adoptopenjdk.net.
Amazon Corretto is an OpenJDK distribution with no-cost long-term support from aws.amazon.com/corretto.

Limitations of map-first pre-processing

The internal extension points that run before or after individual steps in the original preprocess pipeline (preprocess.*.pre/preprocess.*.post) are not available in the newer map-first preprocessing pipeline (preprocess2), which is used in the PDF and HTML Help transformations as of DITA-OT 3.0.