| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293 |
- <!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="In cases that require substantial customizations, it is often useful to organize the files in a folder structure that mimics the hierarchy of the default PDF plug-in."><meta name="DC.subject" content="languages, adding support for, I18N, plug-in, PDF, font-mappings.xml, fonts, index, Customization directory"><meta name="keywords" content="languages, adding support for, I18N, plug-in, PDF, font-mappings.xml, fonts, index, Customization directory"><meta name="DC.relation" scheme="URI" content="../topics/pdf-customization.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-plugin-structure_common-artwork.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-plugin-structure_common-index.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-plugin-structure_common-vars.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-plugin-structure_fo-attrs.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-plugin-structure_fo-i18n.html"><meta name="DC.relation" scheme="URI" content="../topics/pdf-plugin-structure_fo-xsl.html"><meta name="DC.format" content="HTML5"><meta name="DC.identifier" content="pdf-plugin-structure"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>PDF plug-in structure</title></head><body id="pdf-plugin-structure"><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><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 class="active"><a href="../topics/pdf-plugin-structure.html">PDF plug-in structure</a><ul><li><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></li><li><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></li><li><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></li><li><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></li><li><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization</a></li><li><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></li></ul></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 plug-in structure</h1>
-
-
- <div class="body conbody"><p class="shortdesc">In cases that require substantial customizations, it is often useful to organize the files in a folder
- structure that mimics the hierarchy of the default PDF plug-in.</p>
- <div class="note note note_note"><span class="note__title">Note:</span> For simpler customizations, you may want to structure your plug-in differently, but the information in this
- topic may help you to locate the files you need to customize.</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 <span class="ph filepath">Customization</span> folder within the plug-in was used as a
- customization layer to store files that override the default behavior.</p>
- <p class="p">While this method is no longer recommended, the same organization principles can be used in custom PDF plug-ins
- to facilitate comparisons with the default settings in the base PDF plug-in and make it easier to migrate
- customizations to new toolkit versions.</p>
- <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 1. </span>Default <span class="ph filepath">Customization</span> folder content</figcaption>
-
- <pre class="pre codeblock"><code>.
- ├── build.properties.orig
- ├── catalog.xml.orig
- └── fo/
- ├── attrs/
- │ └── custom.xsl.orig
- └── xsl/
- └── custom.xsl.orig</code></pre>
- </figure>
- <p class="p">To begin creating a new custom plug-in, you can copy the contents of the customization layer template in
- <span class="ph filepath">plugins/org.dita.pdf2/Customization</span> to a new folder that will serve as your new custom
- plug-in folder, such as <span class="ph filepath">plugins/com.company.pdf</span>.</p>
- <p class="p">To mimic the hierarchy of the default PDF plug-in, you may want to add a <span class="ph filepath">cfg/</span> subfolder and
- move the contents of the <span class="ph filepath">fo/</span> folder to <span class="ph filepath">cfg/fo/</span>.</p>
- <p class="p">DITA-OT provides template files that you can start with throughout the <span class="ph filepath">Customization</span>
- directory structure. These files end in the suffix <code class="ph codeph">.orig</code> (for example,
- <span class="ph filepath">catalog.xml.orig</span>). To enable these files, remove the <code class="ph codeph">.orig</code> suffix from the
- copies in your new custom plug-in folder. (For example, rename <span class="ph filepath">catalog.xml.orig</span> to
- <span class="ph filepath">catalog.xml</span>).</p>
- <p class="p">You can then make modifications to the copy in your custom plug-in folder, and copy any other files from the
- default PDF plug-in that you need to override, such as the page layouts in
- <span class="ph filepath">layout-masters.xsl</span>, or the <span class="ph filepath">font-mappings.xml</span> file that tells your PDF
- renderer which fonts to use and where to find them.</p>
- <div class="note important note_important"><span class="note__title">Important:</span> Wherever possible, avoid copying entire XSL files from the PDF2 plug-in to your custom
- plug-in. Instead, copy only the specific attribute sets and templates that you want to override. For details, see
- <a class="xref" href="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>.</div>
- <p class="p">Things you can currently override include:</p>
- <ul class="ul">
- <li class="li">Custom XSL via <span class="ph filepath">xsl/custom.xsl</span> and <span class="ph filepath">attrs/custom.xsl</span></li>
- <li class="li">Layout overrides via <span class="ph filepath">layout-masters.xsl</span></li>
- <li class="li">Font overrides via <span class="ph filepath">font-mappings.xml</span></li>
- <li class="li">Per-locale variable overrides via <span class="ph filepath">common/vars/[language].xml</span></li>
- <li class="li">I18N configuration via <span class="ph filepath">i18n/[language].xml</span></li>
- <li class="li">Index configuration via <span class="ph filepath">index/[language].xml</span></li>
- </ul>
- <p class="p">When customizing any of these areas, modify the relevant file(s) in your custom plug-in folder. Then, to enable
- the changes in the publishing process, you find the corresponding entry for each file you modified in the
- <span class="ph filepath">catalog.xml</span> file.</p>
- <p class="p">It should look like this:</p>
- <pre class="pre codeblock language-xml"><code><!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/--></code></pre>
- <p class="p">Remove the comment markers <code class="ph codeph">!--</code> and <code class="ph codeph">--</code> to enable the change:</p>
- <pre class="pre codeblock language-xml"><code><uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/></code></pre>
- <p class="p">Your customization should now be enabled as part of the publishing process.</p>
- <figure class="fig fignone"><figcaption><span class="fig--title-label">Figure 2. </span>Sample custom plug-in structure</figcaption>
-
- <pre class="pre codeblock"><code>.
- ├── plugin.xml
- ├── ant-include.xml
- └── cfg/
- ├── catalog.xml
- ├── common/
- │ ├── artwork/
- │ │ ├── logo.svg
- │ └── vars/
- │ ├── strings.xml
- │ ├── en.xml
- └── fo/
- ├── attrs/
- │ ├── custom.xsl
- ├── font-mappings.xml
- ├── layout-masters.xsl
- └── xsl/
- └── custom.xsl</code></pre>
- </figure>
- <p class="p">When your custom plug-in is installed, the files in its subfolders will override the out-of-the-box settings from
- their counterparts in <span class="ph filepath">org.dita.pdf2/cfg/fo/attrs</span> and
- <span class="ph filepath">org.dita.pdf2/xsl/fo</span>.</p>
- <p class="p">The following topics describe the contents of the base PDF plug-in subfolders and provide additional information
- on customizing various aspects of the default PDF output.</p>
- </div>
- <nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_common-artwork.html">Custom artwork</a></strong><br>The <span class="ph filepath">common/artwork</span> folder houses custom artwork files that override the standard icons in <span class="ph filepath">org.dita.pdf2/cfg/common/artwork</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_common-index.html">Index configuration</a></strong><br>The <span class="ph filepath">common/index</span> folder houses custom index definition files that override the standard definitions in <span class="ph filepath">org.dita.pdf2/cfg/common/index</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_common-vars.html">Variable overrides</a></strong><br>The <span class="ph filepath">common/vars</span> folder houses custom variable definitions that override the standard definitions in <span class="ph filepath">org.dita.pdf2/cfg/common/vars</span>. </li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_fo-attrs.html">Custom attributes</a></strong><br>The <span class="ph filepath">fo/attrs</span> folder houses custom attribute configuration files that override the standard attributes in <span class="ph filepath">org.dita.pdf2/cfg/fo/attrs</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_fo-i18n.html">Internationalization configuration</a></strong><br>The <span class="ph filepath">fo/i18n</span> folder houses custom internationalization files that override the standard configurations in <span class="ph filepath">org.dita.pdf2/cfg/fo/i18n</span>.</li><li class="link ulchildlink"><strong><a href="../topics/pdf-plugin-structure_fo-xsl.html">Custom stylesheets</a></strong><br>The <span class="ph filepath">fo/xsl</span> folder houses custom stylesheet files that override the default stylesheets in <span class="ph filepath">org.dita.pdf2/xsl/fo</span>.</li></ul><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></nav></article></main></body></html>
|
