How to Customize Attributes in the DITA Open Toolkit PDF Plugin

This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example! We will be working in the demo/fo/Customization directory of the open toolkit as shown in the image below.

1. In this example, we are going to customize the <codeblock> element by increasing the font size, changing the font color and weight, and modifying the background color.  Our default code block looks like the following before any changes:

and the dita xml content looks like:

<codeblock>/* I should have green text and a red background */

&lt;xsl:template match="dita"&gt;

   &lt;output&gt;DITA IS COOL&lt;/output&gt;

&lt;/xsl:template&gt;

</codeblock>

2. In order to modify the <codeblock>, we first need to figure out which attributes to change.   The method I find most useful is to run a full-text search the demo/fo directory.  Searching for the term "codeblock" yields a few results, one of which is demo/fo/xsl/pr-domain.xsl and the template is found on line 46: <xsl:template match="*[contains(@class,' pr-d/codeblock ')]">.  Examining this template shows us that we want to modify the "codeblock" attribute set as shown on line 48: <fo:block xsl:use-attribute-sets="codeblock" id="{@id}">. Looking at the text search again, we can see that the "codeblock" attribute set is found in demo/fo/cfg/fo/attrs/pr-domain-attr.xsl on line 41: <xsl:attribute-set name="codeblock">.  The next step is to customize this attribute set.

3. In order to customize this attribute set, copy demo/fo/Customization/fo/attrs/custom.xsl.orig to custom.xsl and copy the codeblock attribute set into the new XSL.  We are going to modify the background color, font color, font size, and make the font bold.  In order to do this, we only need to specify the attributes that we are going to change, so the resulting block of code to add looks like:

    <xsl:attribute-set name="codeblock">

        <xsl:attribute name="background-color">#dc7f72</xsl:attribute>

        <xsl:attribute name="font-size">12pt</xsl:attribute>

        <xsl:attribute name="color">#005511</xsl:attribute>

        <xsl:attribute name="font-weight">bold</xsl:attribute>

    </xsl:attribute-set>

Note, that we could also copy over the entire codeblock attribute set and modify that, which would results in the code below.  Both of these should produce the same output.

     <xsl:attribute-set name="codeblock">

        <xsl:attribute name="space-before">0.4em</xsl:attribute>

        <xsl:attribute name="space-after">0.8em</xsl:attribute>

        <xsl:attribute name="white-space-treatment">preserve</xsl:attribute>

        <xsl:attribute name="white-space-collapse">false</xsl:attribute>

        <xsl:attribute name="linefeed-treatment">preserve</xsl:attribute>

        <xsl:attribute name="wrap-option">wrap</xsl:attribute>

        <xsl:attribute name="background-color">#dc7f72</xsl:attribute>

        <xsl:attribute name="font-family">Monospaced</xsl:attribute>

        <xsl:attribute name="line-height">106%</xsl:attribute>

        <xsl:attribute name="font-size">12pt</xsl:attribute>

        <xsl:attribute name="keep-with-previous.within-page">always</xsl:attribute>

        <!--        <xsl:attribute name="keep-together.within-page">always</xsl:attribute&gt;-->

        <!-- Additional attributes -->

        <xsl:attribute name="color">#005511</xsl:attribute>

        <xsl:attribute name="font-weight">bold</xsl:attribute>

     </xsl:attribute-set>

4. The last step is to tell the plugin that we have made customizations.  In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and then open the copied file and edit the 6th row to uncomment the code from:

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

to:

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

and save the file.

5. This should create the output below for the <codeblock> element.  There are many different ways the attributes can be customized and this is just one small example.  If you have some ideas for other examples you would like to see, contact us!