+
+ The Customization folder
+ 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.
+ If you follow the recommended and create a
+ custom PDF plug-in, the following information on the Customization folder will apply to the
+ root folder of your custom plug-in.
+ 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.
+ Things you can currently override include:
+
+ - Custom XSL via xsl/custom.xsl and attrs/custom.xsl
+ - Layout overrides via layout-masters.xsl
+ - Font overrides via font-mappings.xml
+ - Per-locale variable overrides via common/vars/[language].xml
+ - I18N configuration via i18n/[language].xml
+ - Index configuration via index/[language].xml
+
+ When customizing any of these areas, modify the relevant file(s) in the Customization folder.
+ Then, to enable the changes in the publishing process, you find the corresponding entry for each file you
+ modified in the catalog.xml file.
+ It should look like this:
+ <!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->
+ Remove the comment markers !-- and -- to enable the change:
+ <uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/>
+ Your customization should now be enabled as part of the publishing process.
+ DITA-OT provides template files that you can start with throughout the Customization directory
+ structure. These files end in the suffix .orig (for example,
+ catalog.xml.orig). To enable these files, make a copy of them and remove the
+ .orig suffix. For example, copy catalog.xml.orig to
+ catalog.xml. You can then make modifications to the copy.
+ The files in this directory and its subfolders will override the out-of-the-box settings from their
+ counterparts in cfg/fo/attrs and xsl/fo.
+
+
+
+ Custom artwork: the common/artwork folder
+ This folder houses custom artwork files that override the standard ones in cfg/common/artwork.
+ These files are used to graphically identify different types of DITA <note> element.
+ The mapping between <note> type and graphic is contained in a subset of the
+ locale-dependent variable files, such as
+ cfg/common/vars
+ The variables that control <note> graphics all follow the form
+ <variable id="{type} Note Image Path"> {Path to image file} </variable>
+ where {type} contains a possible value for the <note>
+ @type attribute.
+
+
+
+ Index configuration: the common/index folder
+ This folder houses custom index definition files that override the standard ones in
+ cfg/common/index. Each file contains data for a single language, and should take that
+ language’s ISO 639-1 language designator as its name (for example, pt.xml for Portuguese). If
+ necessary, locale-specific customizations can be provided by adding a region designator to the file name (for
+ example, pt_BR.xml for Brazilian Portuguese).
+ The index files consist of <index.group> 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 <char.set> entries they contain are also listed in sort order
+ (uppercase before lowercase).
+ The best way to start editing a custom index file is by making a copy of the original from
+ cfg/common/index and making changes as desired.
+ In order to apply a custom index definition to your publishing outputs, edit
+ Customization/catalog.xml and uncomment the appropriate entry in the “Index configuration
+ override entries“ section.
+
+
+
+ Variable overrides: the common/vars folder
+ This folder houses custom variable definitions that override the standard ones in
+ cfg/common/vars. 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.
+ Variable files contain a set of <variable> elements, identified by their
+ id 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.
+ Some variables contain <param> 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
+ <variable> content as needed.
+ The best way to start editing a custom variables file is by making a copy of the original from
+ cfg/common/vars 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.
+ Note that unchanged <variable> 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.
+ Applying a custom variable does not require modifying the Customization/catalog.xml file. The
+ publishing process will automatically use any custom variables definitions in place of the original ones.
+
+
+
+ Custom attributes: the fo/attrs folder
+ This folder houses custom attribute configuration files that override the standard ones in
+ cfg/fo/attrs. 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 index-attr.xsl, table-related definitions in tables-attr.xsl,
+ etc.
+ The XSL attribute sets defined in these files can be used to override the presentation of DITA elements,
+ including font size, color, spacing, etc.
+
+
+
+ Internationalization configuration: the fo/i18n folder
+ This folder houses custom configuration files that override the standard ones in cfg/fo/i18n.
+ 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.
+ Each configuration file contains mappings of certain symbols to the Unicode codepoint which should be used to
+ represent them in the given locale.
+ The best way to start editing a custom configuration is by making a copy of the original from
+ cfg/fo/i18n and making changes as desired.
+ In order to apply a custom configuration to your publishing outputs, edit catalog.xml and
+ uncomment the appropriate entry in the “I18N configuration override entries“ section.
+
+
+
+ Custom stylesheets: the fo/xsl folder
+ This folder houses custom stylesheet files that override the default stylesheets in
+ cfg/fo/xsl.
+ You can use custom stylesheets to implement additional processing routines or adjust the output generated by
+ the default toolkit processing.
+
+
+