PDF customization approaches
Various methods may be used to customize the PDF output produced by the DITA Open Toolkit. Each of these approaches have advantages and shortcomings that should be considered when preparing a customization project. Some of these methods are considered “anti-patterns” with disadvantages that outweigh their apparent appeal. In most cases, you should create a custom PDF plug-in.
Why not edit default files?
When first experimenting with PDF customization, novice users are often tempted to simply edit the default org.dita.pdf2 files in place to see what happens.
As practical as this approach may seem, the DITA-OT project does not recommend changing any of the files in the default plug-ins.
While this method yields quick results and can help users to determine which files and templates control various aspects of PDF output, it quickly leads to problems, as any errors may prevent the toolkit from generating PDF output.
Using the Customization folder
The original Idiom plug-in used its own extension mechanism to provide overrides to the PDF transformation. With this approach, a dedicated folder within the plug-in is used to store customized files.
Files in the org.dita.pdf2/Customization folder can override their default counterparts, allowing users to adjust certain aspects of PDF output without changing any of the plug-in’s default files, or specifying additional parameters when generating output.
Although recent versions of DITA-OT still support this mechanism to ensure backwards compatibility, this practice is deprecated in favor of custom PDF plug-ins.
Specifying an external customization directory
To ensure that overrides in customization folders are not overwritten when upgrading the DITA-OT to a new release, an external customization directory can be specified at build time or in build scripts via the customization.dir parameter.
This method is preferable to the use of the org.dita.pdf2/Customization folder, as the contents of external folders are unaffected when upgrading DITA-OT. In distributed environments, users can use local installations of the DITA-OT, yet still take advantage of common customizations stored in a network location available to the entire team, such as a shared drive.
It can also be useful in environments where corporate policy, CMS permissions, or network access rights prevent changes to the toolkit installation, which may prohibit the installation of custom plug-ins.
Combining custom plug-ins & customization directories
A common custom plug-in may be used to store base overrides that are applicable to all company publications, and the customization.dir parameter can be passed at build time to override individual settings as necessary for a given project or publication.
In this case, any settings in the customization directory will take precedence over their counterparts in the custom plug-in or default org.dita.pdf2 plug-in.
This approach allows a single custom plug-in to be shared between multiple publications or the entire company, without the need to create additional plug-in dependencies per project.
However, the use of multiple customization mechanisms can make it difficult to debug the precedence cascade and determine the origin of local formatting or processing overrides.