Creating a Customization Directory for PDF Output

How to Create a Customization Directory for PDF Output

The following procedure explains how to do a basic customization of the PDF output by setting up a customization directory. An example of a common use case is embedding a company logo image in the front matter of the book.

1. Copy the entire directory: DITA_OT_DIR\plugins\org.dita.pdf2\Customization to another location (for instance, C:\Customization).
2. Copy your logo image to: C:\Customization\common\artwork\logo.png.
3. Rename C:\Customization\catalog.xml.orig to: C:\Customization\catalog.xml.
4. Open the catalog.xml in Oxygen XML Editor plugin and uncomment this line:

     <!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->   

   It now looks like this:

   <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/>

5. Rename the file: C:\Customization\fo\xsl\custom.xsl.orig to: C:\Customization\fo\xsl\custom.xsl
6. Open the custom.xsl file in Oxygen XML Editor plugin and create the template called createFrontCoverContents for DITA-OT 2.3.3 (or createFrontMatter_1.0 for DITA-OT 1.8.5).

   Tip

   You can copy the same template from DITA_OT_DIR\plugins\org.dita.pdf2\xsl\fo\front-matter.xsl and modify it in whatever way necessary to achieve your specific goal. This new template in the custom.xsl file will override the same template from DITA_OT_DIR\plugins\org.dita.pdf2\xsl\fo\front-matter.xsl.

   DITA OT 2.3.3 Example:

   For example, if you are using DITA OT 2.3.3, the custom.xsl could look like this:

   <?xml version='1.0'?>
   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
       xmlns:fo="http://www.w3.org/1999/XSL/Format"
       version="2.0">
     
   <xsl:template name="createFrontCoverContents">
    <!-- set the title -->
    <fo:block xsl:use-attribute-sets="__frontmatter__title">
     <xsl:choose>
      <xsl:when test="$map/*[contains(@class,' topic/title ')][1]">
       <xsl:apply-templates select="$map/*[contains(@class,' topic/title ')][1]"/>
         </xsl:when>
         <xsl:when test="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]">
           <xsl:apply-templates select="$map//*[contains
                                          (@class,' bookmap/mainbooktitle ')][1]"/>
         </xsl:when>
         <xsl:when test="//*[contains(@class, ' map/map ')]/@title">
           <xsl:value-of select="//*[contains(@class, ' map/map ')]/@title"/>
         </xsl:when>
         <xsl:otherwise>
           <xsl:value-of select="/descendant::*[contains
              (@class, ' topic/topic ')][1]/*[contains(@class, ' topic/title ')]"/>
      </xsl:otherwise>
     </xsl:choose>
    </fo:block>
       
    <!-- set the subtitle -->
    <xsl:apply-templates select="$map//*[contains
                                             (@class,' bookmap/booktitlealt ')]"/>
    <fo:block xsl:use-attribute-sets="__frontmatter__owner">
     <xsl:apply-templates select="$map//*[contains(@class,' bookmap/bookmeta ')]"/>
    </fo:block>
     
    <!-- Load the image logo -->
     <fo:block text-align="center" width="100%">
      <fo:external-graphic
         src="url({concat($artworkPrefix, 
                             '/Customization/OpenTopic/common/artwork/logo.png')})"
       />
     </fo:block>
    </xsl:template>
   
   </xsl:stylesheet>

   DITA OT 1.8.5 Example:

   For example, if you are using DITA OT 1.8.5, the custom.xsl could look like this:

   <?xml version='1.0'?>
   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
       xmlns:fo="http://www.w3.org/1999/XSL/Format"
       version="1.1">
   
   <xsl:template name="createFrontMatter_1.0">
      <fo:page-sequence master-reference="front-matter" 
                            xsl:use-attribute-sets="__force__page__count">
        <xsl:call-template name="insertFrontMatterStaticContents"/>
          <fo:flow flow-name="xsl-region-body">
            <fo:block xsl:use-attribute-sets="__frontmatter">
        <!-- set the title -->
              <fo:block xsl:use-attribute-sets="__frontmatter__title">
               <xsl:choose>
                <xsl:when test="$map/*[contains(@class,' topic/title ')][1]">
        <xsl:apply-templates select="$map/*[contains(@class,' topic/title ')][1]"/>
                     </xsl:when>
       <xsl:when test="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]">
        <xsl:apply-templates select="$map//*[contains
                                       (@class,' bookmap/mainbooktitle ')][1]"/>
            </xsl:when>
       <xsl:when test="//*[contains(@class, ' map/map ')]/@title">
         <xsl:value-of select="//*[contains(@class, ' map/map ')]/@title"/>
            </xsl:when>
         <xsl:otherwise>
       <xsl:value-of select="/descendant::*[contains
              (@class, ' topic/topic ')][1]/*[contains(@class, ' topic/title ')]"/>
         </xsl:otherwise>
            </xsl:choose>
        </fo:block>
   
     <!-- set the subtitle -->
        <xsl:apply-templates select="$map//*[contains
                                              (@class,' bookmap/booktitlealt ')]"/>
   
           <fo:block xsl:use-attribute-sets="__frontmatter__owner">
               <xsl:apply-templates select="$map//*[contains
                                                  (@class,' bookmap/bookmeta ')]"/>
           </fo:block>
                      
           <fo:block text-align="center" width="100%">
              <fo:external-graphic src="url({concat($artworkPrefix,
                           '/Customization/OpenTopic/common/artwork/logo.png')})"/>
            </fo:block>
   
       </fo:block>
   
      <!--<xsl:call-template name="createPreface"/>-->
   
               </fo:flow>
           </fo:page-sequence>
           <xsl:call-template name="createNotices"/>
       </xsl:template>
   </xsl:stylesheet>

7. Edit the DITA Map PDF transformation scenario and in the Parameters tab, set the customization.dir parameter to C:\Customization.