Migrating DITA Open Toolkit PDF Customizations

We encounter clients on a daily basis who have PDF customizations created for older DITA Open Toolkit versions and they want to migrate to a new Oxygen version (which includes a newer DITA Open Toolkit publishing engine distribution).

Most XHTML-based customizations are quite easily accomplished just by using a custom CSS. But as the standard PDF publishing obtained with the DITA Open Toolkit is XSL-FO based, it requires XSLT customizations.

As a general rule, when making a customization of any kind you should keep some kind of notes about what you achieved during the customization and through which means. This will help you migrate your customization to a new DITA Open Toolkit version.

Oxygen 18 comes with two DITA Open Toolkit distributions (1.8.5 and 2.x), you can choose which DITA OT distribution to use in the Preferences->DITA page. DITA OT 2.x is newer and it comes with DITA 1.3 support so you should try to update directly to it.

First of all, if you are happy with the output obtained using your current DITA OT distribution, you can continue using that DITA OT as an external DITA OT. You can copy it from inside the old Oxygen installation to an external location and in Oxygen 18, the same Preferences->DITA page allows you to choose an external DITA OT distribution to use:

https://www.oxygenxml.com/doc/ug-editor/topics/use-new-dita-ot.html

If you still want to migrate:

No proper implemented customization should modify the base "org.dita.pdf2" plugin contents. The customization folder should be either kept external to the DITA Open Toolkit distribution:

https://www.oxygenxml.com/doc/ug-editor/topics/dita_pdf_output_customization.html

or it should be provided via a PDF customization plugin:

http://www.dita-ot.org/1.8/readme/dita2pdf-customization.html

In the DITA Open Toolkit documentation, there is also a best practices about PDF customizations:

http://www.dita-ot.org/dev/dev_ref/pdf-customization-best-practices.html

The main idea is to have all your changes in one place.

While the DITA Open Toolkit evolves, various XSLT templates might change, be renamed, or removed completely. There is a migration guide here:

http://www.dita-ot.org/dev/dev_ref/migration.html

Even without reading the guide, you need to determine which XSLT templates are no longer getting called in your customization (you can add xsl:messages for this) and then try to find the templates that need to be overridden in the base PDF plugin instead.

So this is why having some notes about all aspects that your PDF customization should cover is useful in the long run. You can use the notes to see if all aspects of your customization are still applied with a newer DITA OT and for the aspects that no longer work, you can easily locate the places in XSLT where the customization was done.