Home Explore Help
Sign In
bn
/
se
2
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 23a803db8e
Branches Tags
se
/
SE
/
schema
/
WPS_Functions
/
dita-ot
/
dita-ot-3.0.4
/
doc
/
topics
/
pdf-customization-approaches.html

pdf-customization-approaches.html 11 KB
History Raw

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879 
  1. <!DOCTYPE html
    2. 

  2.   SYSTEM "about:legacy-compat">
    3. 

  3. <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 2018"><meta name="DC.rights.owner" content="(C) Copyright 2018"><meta name="DC.Type" content="concept"><meta name="description" content="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."><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.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">
    4. 

  4.   <p>DITA Open Toolkit</p>
    5. 

  5.   <hr>
    6. 

  6. </div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.0</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/extending-the-ot.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/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/custom-plugins.html">Custom 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/rebuilding-the-dita-ot-documentation.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">
    7. 

  7.   <h1 class="title topictitle1" id="ariaid-title1">PDF customization approaches</h1>
    8. 

  8.   
    9. 

  9. 

  10.   <div class="body conbody"><p class="shortdesc">Various methods may be used to customize the PDF output produced by the DITA Open Toolkit. Each of these
    11. 

  11.     approaches have advantages and shortcomings that should be considered when preparing a customization project. Some
    12. 

  12.     of these methods are considered “anti-patterns” with disadvantages that outweigh their apparent appeal. In most
    13. 

  13.     cases, you should create a custom PDF plug-in.</p>
    14. 

  14.     <section class="section" id="pdf_customization_approaches__why_not_edit_default_files"><h2 class="title sectiontitle">Why not edit default files?</h2>
    15. 

  15.       
    16. 

  16.       <p class="p">When first experimenting with PDF customization, novice users are often tempted to simply edit the default
    17. 

  17.           <span class="ph filepath">org.dita.pdf2</span> files in place to see what happens.</p>
    18. 

  18.       <p class="p">As practical as this approach may seem, the DITA-OT project does not recommend changing any of the files in the
    19. 

  19.           default plug-ins.</p>
    20. 

  20.       <p class="p">While this method yields quick results and can help users to determine which files and templates control
    21. 

  21.         various aspects of PDF output, it quickly leads to problems, as any errors may prevent the toolkit from
    22. 

  22.         generating PDF output.</p>
    23. 

  23.       <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
    24. 

  24.         DITA-OT, so users that have customized their toolkit installation in this way are often “stuck” on older
    25. 

  25.         versions of the toolkit and unable to take advantage of improvements in recent versions of DITA-OT.</div>
    26. 

  26.     </section>
    27. 

  27. 

  28.     <section class="section" id="pdf_customization_approaches__the_customization_folder"><h2 class="title sectiontitle">Using the <span class="ph filepath">Customization</span> folder</h2>
    29. 

  29.       
    30. 

  30.       <p class="p">The original Idiom plug-in used its own extension mechanism to provide overrides to the PDF transformation.
    31. 

  31.         With this approach, a dedicated folder within the plug-in is used to store customized files.</p>
    32. 

  32.       <p class="p">Files in the <span class="ph filepath">org.dita.pdf2/Customization</span> folder can override their default counterparts,
    33. 

  33.         allowing users to adjust certain aspects of PDF output without changing any of the plug-in’s default files, or
    34. 

  34.         specifying additional parameters when generating output.</p>
    35. 

  35.       <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
    36. 

  36.         cause problems when upgrading the toolkit to a new version. Since the <span class="ph filepath">Customization</span> folder
    37. 

  37.         is located within the <span class="ph filepath">org.dita.pdf2</span> plug-in’s parent directory, users must be take care to
    38. 

  38.         preserve the contents of this folder when upgrading to new toolkit versions.</div>
    39. 

  39.       <p class="p">Although recent versions of DITA-OT still support this mechanism to ensure backwards compatibility, this
    40. 

  40.         practice is deprecated in favor of custom PDF plug-ins.</p>
    41. 

  41.       <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
    42. 

  42.         output are encouraged to create a custom PDF plug-in instead. In many cases, this may be as simple as copying
    43. 

  43.         the contents of the <span class="ph filepath">Customization</span> folder to a new subfolder in the
    44. 

  44.           <span class="ph filepath">plugins</span> folder and creating the necessary <span class="ph filepath">plugin.xml</span> file and an Ant
    45. 

  45.         script to define the transformation type as described in the following example.</div>
    46. 

  46.     </section>
    47. 

  47. 

  48.     <section class="section" id="pdf_customization_approaches__external_customization_directories"><h2 class="title sectiontitle">Specifying an external customization directory</h2>
    49. 

  49.       
    50. 

  50.       <p class="p">To ensure that overrides in customization folders are not overwritten when upgrading the DITA-OT to a new
    51. 

  51.         release, an external customization directory can be specified at build time or in build scripts via the
    52. 

  52.           <span class="keyword parmname">customization.dir</span> parameter.</p>
    53. 

  53.       <p class="p">This method is preferable to the use of the <span class="ph filepath">org.dita.pdf2/Customization</span> folder, as the
    54. 

  54.         contents of external folders are unaffected when upgrading DITA-OT. In distributed environments, users can use
    55. 

  55.         local installations of the DITA-OT, yet still take advantage of common customizations stored in a network
    56. 

  56.         location available to the entire team, such as a shared drive.</p>
    57. 

  57.       <p class="p">It can also be useful in environments where corporate policy, CMS permissions, or network access rights prevent
    58. 

  58.         changes to the toolkit installation, which may prohibit the installation of custom plug-ins.</p>
    59. 

  59.       <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>
    60. 

  60.         are encouraged to create a custom PDF plug-in if possible.</div>
    61. 

  61.     </section>
    62. 

  62. 

  63.     <section class="section" id="pdf_customization_approaches__plug_ins_and_customization_folders"><h2 class="title sectiontitle">Combining custom plug-ins &amp; customization directories</h2>
    64. 

  64.       
    65. 

  65.       <p class="p">A common custom plug-in may be used to store base overrides that are applicable to all company publications,
    66. 

  66.         and the <span class="keyword parmname">customization.dir</span> parameter can be passed at build time to override individual
    67. 

  67.         settings as necessary for a given project or publication.</p>
    68. 

  68.       <p class="p">In this case, any settings in the customization directory will take precedence over their counterparts in the
    69. 

  69.         custom plug-in or default <span class="ph filepath">org.dita.pdf2</span> plug-in.</p>
    70. 

  70.       <p class="p">This approach allows a single custom plug-in to be shared between multiple publications or the entire company,
    71. 

  71.         without the need to create additional plug-in dependencies per project.</p>
    72. 

  72.       <p class="p">However, the use of multiple customization mechanisms can make it difficult to debug the precedence cascade and
    73. 

  73.         determine the origin of local formatting or processing overrides.</p>
    74. 

  74.       <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
    75. 

  75.         customizations can be bundled in one plug-in, and any project-specific overrides can be maintained in separate
    76. 

  76.         plug-ins that build on the base branding or other settings in the common custom plug-in.</div>
    77. 

  77.     </section>
    78. 

  78.   </div>
    79. 

  79. <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 the DITA Open Toolkit. This will make it easier to you to upgrade to new versions of the DITA-OT when they are released.">Best practices for custom plug-ins</a></li></ul></div></nav></article></main></body></html>
    80.