85 lines
No EOL
9.9 KiB
HTML
85 lines
No EOL
9.9 KiB
HTML
<!DOCTYPE html
|
||
SYSTEM "about:legacy-compat">
|
||
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><meta name="description" content="Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these approaches have advantages and shortcomings that should be considered when preparing a customization project."><meta name="keywords" content="PDF, customizing, best practices, upgrading, default plug-ins, PDF"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>PDF customization approaches</title></head><body id="pdf_customization_approaches"><header role="banner"><div class="header">
|
||
<p>DITA Open Toolkit</p>
|
||
<hr>
|
||
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.6</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a><ul><li class="active"><a href="../topics/pdf-customization-approaches.html">Customization approaches</a></li><li><a href="../topics/pdf2-creating-change-bars.html">Generating revision bars</a></li></ul></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
|
||
<h1 class="title topictitle1" id="ariaid-title1">PDF customization approaches</h1>
|
||
|
||
|
||
|
||
|
||
|
||
<div class="body conbody"><p class="shortdesc">Various methods may be used to customize the PDF output that DITA Open Toolkit produces. Each of these
|
||
approaches have advantages and shortcomings that should be considered when preparing a customization
|
||
project.</p>
|
||
<div class="note note note_note"><span class="note__title">Note:</span> 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.</div>
|
||
<section class="section" id="pdf_customization_approaches__why_not_edit_default_files"><h2 class="title sectiontitle">Why not edit default files?</h2>
|
||
|
||
<p class="p">When first experimenting with PDF customization, novice users are often tempted to simply edit the default
|
||
<span class="ph filepath">org.dita.pdf2</span> files in place to see what happens.</p>
|
||
<p class="p">As practical as this approach may seem, the DITA-OT project does not recommend changing any of the files in the
|
||
default plug-ins.</p>
|
||
<p class="p">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.</p>
|
||
<div class="note warning note_warning"><span class="note__title">Warning:</span> Any changes made in this fashion would be overwritten when upgrading to newer versions of
|
||
DITA-OT, so users that have customized their toolkit installation in this way are often “stuck” on older
|
||
versions of the toolkit and unable to take advantage of improvements in recent versions of DITA-OT.</div>
|
||
</section>
|
||
|
||
<section class="section" id="pdf_customization_approaches__the_customization_folder"><h2 class="title sectiontitle">Using the <span class="ph filepath">Customization</span> folder</h2>
|
||
|
||
|
||
|
||
<p class="p">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.</p>
|
||
<p class="p">Files in the <span class="ph filepath">org.dita.pdf2/Customization</span> 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.</p>
|
||
<div class="note important note_important"><span class="note__title">Important:</span> While this approach is slightly better than editing default files in place, it can still
|
||
cause problems when upgrading the toolkit to a new version. Since the <span class="ph filepath">Customization</span> folder
|
||
is located within the <span class="ph filepath">org.dita.pdf2</span> plug-in’s parent directory, users must be take care to
|
||
preserve the contents of this folder when upgrading to new toolkit versions.</div>
|
||
<p class="p">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.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> Users who have used the <span class="ph filepath">Customization</span> folder to modify the default PDF
|
||
output are encouraged to create a custom PDF plug-in instead. In many cases, this may be as simple as copying
|
||
the contents of the <span class="ph filepath">Customization</span> folder to a new subfolder in the
|
||
<span class="ph filepath">plugins</span> folder and creating the necessary <span class="ph filepath">plugin.xml</span> file and an Ant
|
||
script to define the transformation type as described in the following example.</div>
|
||
</section>
|
||
|
||
<section class="section" id="pdf_customization_approaches__external_customization_directories"><h2 class="title sectiontitle">Specifying an external customization directory</h2>
|
||
|
||
<p class="p">To ensure that overrides in customization folders are not overwritten when upgrading DITA-OT to a new release,
|
||
an external customization directory can be specified at build time or in build scripts via the
|
||
<span class="keyword parmname">customization.dir</span> parameter.</p>
|
||
<p class="p">This method is preferable to the use of the <span class="ph filepath">org.dita.pdf2/Customization</span> folder, as the
|
||
contents of external folders are unaffected when upgrading DITA-OT. In distributed environments, users can use
|
||
local installations of DITA-OT, yet still take advantage of common customizations stored in a network location
|
||
available to the entire team, such as a shared drive.</p>
|
||
<p class="p">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.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> Users who specify external customization directories via <span class="keyword parmname">customization.dir</span>
|
||
are encouraged to create a custom PDF plug-in if possible.</div>
|
||
</section>
|
||
|
||
<section class="section" id="pdf_customization_approaches__plug_ins_and_customization_folders"><h2 class="title sectiontitle">Combining custom plug-ins & customization directories</h2>
|
||
|
||
<p class="p">A common custom plug-in may be used to store base overrides that are applicable to all company publications,
|
||
and the <span class="keyword parmname">customization.dir</span> parameter can be passed at build time to override individual
|
||
settings as necessary for a given project or publication.</p>
|
||
<p class="p">In this case, any settings in the customization directory will take precedence over their counterparts in the
|
||
custom plug-in or default <span class="ph filepath">org.dita.pdf2</span> plug-in.</p>
|
||
<p class="p">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.</p>
|
||
<p class="p">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.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> In most scenarios, the use of dedicated PDF customization plug-ins is preferable. Common
|
||
customizations can be bundled in one plug-in, and any project-specific overrides can be maintained in separate
|
||
plug-ins that build on the base branding or other settings in the common custom plug-in.</div>
|
||
</section>
|
||
</div>
|
||
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/pdf-customization.html" title="You can adjust various aspects of PDF output by changing parameter settings. For more complex customizations, you can create custom DITA-OT plug-ins.">Customizing PDF output</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/pdf-customization-plugins.html" title="In most cases, PDF output should be customized by creating custom DITA-OT plug-ins that build on the default DITA to PDF transformation. PDF plug-ins can customize covers and page layouts, modify formatting, override the logic of the default PDF plug-in, and much more.">Custom PDF plug-ins</a></li></ul></div></nav></article></main></body></html> |