-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
cc070bf
commit d70047e
Showing
2 changed files
with
135 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.--> | ||
|
|
||
| <concept id="pdf-plugin-structure"> | ||
| <title>PDF plug-in structure</title> | ||
| <shortdesc>PDF customization plug-ins typically organize files in a folder structure that mimics the hierarchy of the | ||
| default PDF plug-in. This method facilitates comparisons with the default settings in the base PDF plug-in.</shortdesc> | ||
|
|
||
| <conbody> | ||
| <section id="the_customization_folder"> | ||
| <title>The Customization folder</title> | ||
| <p>This customization approach was introduced with the Idiom plug-in, which provided a dedicated Customization | ||
| folder to store overrides to the PDF transformation. While this method is deprecated in recent toolkit versions, | ||
| the same organization principles can be used in custom PDF plug-ins.</p> | ||
| <note type="tip">If you follow the recommended <xref href="pdf-customization-best-practices.dita"/> and create a | ||
| custom PDF plug-in, the following information on the <codeph>Customization</codeph> folder will apply to the | ||
| root folder of your custom plug-in.</note> | ||
| <p>The Customization directory is used to store customized versions of the default PDF plug-in files. DITA-OT will | ||
| look for certain files here to override the standard ones when publishing PDF output. </p> | ||
| <p>Things you can currently override include:</p> | ||
| <ul> | ||
| <li>Custom XSL via <codeph>xsl/custom.xsl</codeph> and <codeph>attrs/custom.xsl</codeph></li> | ||
| <li>Layout overrides via <codeph>layout-masters.xsl</codeph></li> | ||
| <li>Font overrides via <codeph>font-mappings.xml</codeph></li> | ||
| <li>Per-locale variable overrides via <codeph>common/vars/[language].xml</codeph></li> | ||
| <li>I18N configuration via <codeph>i18n/[language].xml</codeph></li> | ||
| <li>Index configuration via <codeph>index/[language].xml</codeph></li> | ||
| </ul> | ||
| <p>When customizing any of these areas, modify the relevant file(s) in the <codeph>Customization</codeph> folder. | ||
| Then, to enable the changes in the publishing process, you find the corresponding entry for each file you | ||
| modified in the <codeph>catalog.xml</codeph> file.</p> | ||
| <p>It should look like this:</p> | ||
| <codeblock><!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/--></codeblock> | ||
| <p>Remove the comment markers <codeph>!--</codeph> and <codeph>--</codeph> to enable the change:</p> | ||
| <codeblock><uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/></codeblock> | ||
| <p>Your customization should now be enabled as part of the publishing process.</p> | ||
| <p>DITA-OT provides template files that you can start with throughout the <codeph>Customization</codeph> directory | ||
| structure. These files end in the suffix <codeph>.orig</codeph> (for example, | ||
| <codeph>catalog.xml.orig</codeph>). To enable these files, make a copy of them and remove the | ||
| <codeph>.orig</codeph> suffix. For example, copy <codeph>catalog.xml.orig</codeph> to | ||
| <codeph>catalog.xml</codeph>. You can then make modifications to the copy.</p> | ||
| <p>The files in this directory and its subfolders will override the out-of-the-box settings from their | ||
| counterparts in <codeph>cfg/fo/attrs</codeph> and <codeph>xsl/fo</codeph>.</p> | ||
| </section> | ||
|
|
||
| <section id="custom_artwork_the_common_artwork_folder"> | ||
| <title>Custom artwork: the common/artwork folder</title> | ||
| <p>This folder houses custom artwork files that override the standard ones in <codeph>cfg/common/artwork</codeph>. | ||
| These files are used to graphically identify different types of DITA <codeph><note></codeph> element.</p> | ||
| <p>The mapping between <codeph><note></codeph> type and graphic is contained in a subset of the | ||
| locale-dependent variable files, such as</p> | ||
| <codeblock>cfg/common/vars</codeblock> | ||
| <p>The variables that control <codeph><note></codeph> graphics all follow the form</p> | ||
| <codeblock> <variable id="{type} Note Image Path"> {Path to image file} </variable></codeblock> | ||
| <p>where {type} contains a possible value for the <codeph><note></codeph> | ||
| <codeph>@type</codeph> attribute.</p> | ||
| </section> | ||
|
|
||
| <section id="index_configuration_the_common_index_folder"> | ||
| <title>Index configuration: the common/index folder</title> | ||
| <p>This folder houses custom index definition files that override the standard ones in | ||
| <codeph>cfg/common/index</codeph>. Each file contains data for a single language, and should take that | ||
| language’s ISO 639-1 language designator as its name (for example, <codeph>pt.xml</codeph> for Portuguese). If | ||
| necessary, locale-specific customizations can be provided by adding a region designator to the file name (for | ||
| example, <codeph>pt_BR.xml</codeph> for Brazilian Portuguese).</p> | ||
| <p>The index files consist of <codeph><index.group></codeph> elements which contain sorting information on | ||
| one or more characters. Index groups are listed in sort order (“specials“ before numbers, numbers before the | ||
| letter ‘A‘, etc), and the <codeph><char.set></codeph> entries they contain are also listed in sort order | ||
| (uppercase before lowercase).</p> | ||
| <p>The best way to start editing a custom index file is by making a copy of the original from | ||
| <codeph>cfg/common/index</codeph> and making changes as desired.</p> | ||
| <p>In order to apply a custom index definition to your publishing outputs, edit | ||
| <codeph>Customization/catalog.xml</codeph> and uncomment the appropriate entry in the “Index configuration | ||
| override entries“ section.</p> | ||
| </section> | ||
|
|
||
| <section id="variable_overrides_the_common_vars_folder"> | ||
| <title>Variable overrides: the common/vars folder</title> | ||
| <p>This folder houses custom variable definitions that override the standard ones in | ||
| <codeph>cfg/common/vars</codeph>. As with index configuration, Each file contains data for a single language, | ||
| and should take that language’s ISO 639-1 language designator as its name.</p> | ||
| <p>Variable files contain a set of <codeph><variable></codeph> elements, identified by their | ||
| <codeph>id</codeph> attribute. The variable definitions are used to store static text that is used as part of | ||
| the published outputs. For example, page headers, hyperlinks, etc. The id attribute for each variable should | ||
| make it clear how the variable text is being used.</p> | ||
| <p>Some variables contain <codeph><param></codeph> elements which indicate parameter values that are | ||
| substituted at publish time by the XSL. For example, a page number that is being generated as part of the | ||
| publishing process might be identified by <param ref-name="number"/> When editing or translating a | ||
| variable file, these should be included in the translation, though they can be moved and rearranged within the | ||
| <codeph><variable></codeph> content as needed.</p> | ||
| <p>The best way to start editing a custom variables file is by making a copy of the original from | ||
| <codeph>cfg/common/vars</codeph> and making changes as desired. When adding a new language, start from an | ||
| existing language’s list of variables and translate each entry as needed.</p> | ||
| <p>Note that unchanged <codeph><variable></codeph> elements can be omitted: the custom variables file need | ||
| only include those <variable> elements which you have modified. Variables not found in the custom file | ||
| will are taken from the standard variable files.</p> | ||
| <p>Applying a custom variable does not require modifying the <codeph>Customization/catalog.xml</codeph> file. The | ||
| publishing process will automatically use any custom variables definitions in place of the original ones.</p> | ||
| </section> | ||
|
|
||
| <section id="custom_attributes_the_fo_attrs_folder"> | ||
| <title>Custom attributes: the fo/attrs folder</title> | ||
| <p>This folder houses custom attribute configuration files that override the standard ones in | ||
| <codeph>cfg/fo/attrs</codeph>. These files define the appearance of different elements in XML assets when they | ||
| are rendered to PDF output. The different DITA elements are organized into files by element type – index-related | ||
| definitions in <codeph>index-attr.xsl</codeph>, table-related definitions in <codeph>tables-attr.xsl</codeph>, | ||
| etc.</p> | ||
| <p>The XSL attribute sets defined in these files can be used to override the presentation of DITA elements, | ||
| including font size, color, spacing, etc.</p> | ||
| </section> | ||
|
|
||
| <section id="internationalization_configuration_the_fo_i18n_folder"> | ||
| <title>Internationalization configuration: the fo/i18n folder</title> | ||
| <p>This folder houses custom configuration files that override the standard ones in <codeph>cfg/fo/i18n</codeph>. | ||
| As with index configuration and variable overrides, each file contains data for a single language, and should | ||
| take that language’s ISO 639-1 language designator as its name. </p> | ||
| <p>Each configuration file contains mappings of certain symbols to the Unicode codepoint which should be used to | ||
| represent them in the given locale.</p> | ||
| <p>The best way to start editing a custom configuration is by making a copy of the original from | ||
| <codeph>cfg/fo/i18n</codeph> and making changes as desired.</p> | ||
| <p>In order to apply a custom configuration to your publishing outputs, edit <codeph>catalog.xml</codeph> and | ||
| uncomment the appropriate entry in the “I18N configuration override entries“ section.</p> | ||
| </section> | ||
|
|
||
| <section id="custom_stylesheets_the_fo_xsl_folder"> | ||
| <title>Custom stylesheets: the fo/xsl folder</title> | ||
| <p>This folder houses custom stylesheet files that override the default stylesheets in | ||
| <codeph>cfg/fo/xsl</codeph>. </p> | ||
| <p>You can use custom stylesheets to implement additional processing routines or adjust the output generated by | ||
| the default toolkit processing.</p> | ||
| </section> | ||
| </conbody> | ||
| </concept> |