93 lines
No EOL
12 KiB
HTML
93 lines
No EOL
12 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="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="keywords" content="languages, adding support for, I18N, plug-in, PDF, font-mappings.xml, fonts, PDF, fonts, index, Customization directory"><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.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></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a><ul><li><a href="../topics/plugin-benefits.html">Plug-in benefits</a></li><li><a href="../topics/plugin-configfile.html">Plug-in descriptor file</a></li><li><a href="../topics/plugin-coding-conventions.html">Coding conventions</a></li><li><a href="../topics/plugin-dependencies.html">Plug-in dependencies</a></li><li><a href="../topics/plugin-use-cases.html">Plug-in use cases</a></li><li><a href="../topics/html-customization-plugins.html">Custom HTML plug-ins</a></li><li><a href="../topics/pdf-customization-plugins.html">Custom PDF plug-ins</a><ul><li><a href="../topics/pdf-customization-plugin-types.html">Types of 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</a></li><li><a href="../topics/pdf-customization-resources.html">PDF plug-in resources</a></li></ul></li><li><a href="../topics/globalization.html">Globalizing DITA content</a></li><li><a href="../topics/migration.html">Migrating customizations</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-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>.</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-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></div></div></nav></article></main></body></html> |