bn
/
se


			
				
					
						
						
							12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485
							<!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 2019"><meta name="DC.rights.owner" content="(C) Copyright 2019"><meta name="DC.type" content="concept"><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. 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."><meta name="DC.subject" content="PDF, customizing, best practices, upgrading, default plug-ins"><meta name="keywords" content="PDF, customizing, best practices, upgrading, default plug-ins"><meta name="DC.relation" scheme="URI" content="../topics/pdf-customization.html"><meta name="DC.relation" scheme="URI" content="../topics/plugin-best-practices.html"><meta name="DC.relation" scheme="URI" content="../topics/plugin-coding-conventions.html"><meta name="DC.format" content="HTML5"><meta name="DC.identifier" content="pdf_customization_approaches"><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.3</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/alternative-input-formats.html">Authoring formats</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../parameters/index.html">Setting parameters</a></li><li><a href="../topics/customizing.html">Customizing DITA-OT</a><ul><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">PDF customization approaches</a></li><li><a href="../topics/pdf-customization-plugin-types.html">Types of custom PDF plug-ins</a></li><li><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a></li><li><a href="../topics/pdf-customization-example.html">Simple PDF plug-in example</a></li><li><a href="../topics/pdf-customization-resources.html">Custom PDF plug-in resources</a></li><li><a href="../topics/pdf2-creating-change-bars.html">Generating revision bars</a></li></ul></li><li><a href="../topics/custom-plugins.html">Working with plug-ins</a></li><li><a href="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../topics/migration.html">Migrating customizations</a></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/rebuilding-docs.html">Rebuilding documentation</a></li></ul></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. 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.</p>
    <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>
      
      <div class="div div-index">
        
        
      </div>
      <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 &amp; 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 create custom DITA-OT plug-ins that build on the default DITA to PDF transformation. Plug-ins can customize covers and page layouts, modify formatting, override logic of the default PDF plug-in, and much more.">Customizing PDF output</a></div></div><div class="linklist relinfo relconcepts"><strong>Related concepts</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/plugin-best-practices.html" title="Adhering to certain development practices will properly isolate your code from that of DITA Open Toolkit. This will make it easier to you to upgrade to new versions of DITA-OT when they are released.">Best practices for custom plug-ins</a></li><li class="linklist"><a class="link" href="../topics/plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a></li></ul></div></nav></article></main></body></html>