How to Use XSLT Extension Points for PDF Output from a DITA-OT Plugin

The examples in this section demonstrate how to use XSLT extension points from a DITA-OT plugin.

Instead of directly adding plugins inside the embedded DITA-OT, it is highly recommended to use an external Oxygen Publishing Engine so that you will not lose any of your customizations anytime you upgrade the product in the future.

You just need to follow these steps before starting your custom DITA-OT plugins:

Download the Oxygen Publishing Engine and unzip it inside a folder where you have full write access.
Create your custom plugin(s) inside the DITA-OT-DIR\plugins\ folder.
Go to Options > Preferences > DITA, set the DITA Open Toolkit option to Custom, and specify the path to the unzipped folder.
Warning: The path must end with: oxygen-publishing-engine.

How to Style Codeblocks with a Zebra Effect

Suppose you want your codeblocks to have a particular background color for one line, and another color for the next line. One advantage of this coloring technique is that you can clearly see when text from the codeblock is wrapped.

This effect can be done by altering the HTML5 output, creating a <div> for each line from the code block, then styling them.

To add this functionality using a DITA-OT plugin, follow these steps:

In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.pdf.custom.codeblocks).

Create a plugin.xml file (in the folder you created in step 1) that specifies the extension point and your customization stylesheet. For example:

<plugin id="com.oxygenxml.pdf.custom.codeblocks">
  <feature extension="com.oxygenxml.pdf.css.xsl.merged2html5"
              file="custom_codeblocks.xsl"/>    
</plugin>

Create your customization stylesheet (for example, custom_codeblocks.xsl) with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    exclude-result-prefixes="xs"
    version="3.0">
   
    <xsl:template match="*[contains(@class, ' pr-d/codeblock ')]">
       <div class='zebra'>       
          <xsl:analyze-string regex="\n" select=".">
            <xsl:matching-substring/>
            <xsl:non-matching-substring>
               <div><xsl:value-of select="."/></div>
            </xsl:non-matching-substring>
          </xsl:analyze-string>
       </div>
    </xsl:template>
</xsl:stylesheet>

Use the Integrate/Install DITA-OT Plugins transformation scenario found in the DITA Map section in the Configure Transformation Scenario(s) dialog box.

Create a custom CSS file with rules that style the codeblock structure. For example:

div.zebra {
  font-family:courier, fixed, monospace;        
  white-space:pre-wrap;
}

div.zebra > *:nth-of-type(odd){        
  background-color: silver;
}

Edit a DITA Map PDF - based on HTML5 & CSS transformation scenario and reference your custom CSS file (using the args.css parameter).
Run the transformation scenario.

How to Remove the Related Links Section

Suppose you want the related links sections to be removed from the PDF output.

To add this functionality using a DITA-OT plugin, follow these steps:

In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.pdf.custom.codeblocks).

Create a plugin.xml file (in the folder you created in step 1) that specifies the extension point and your customization stylesheet. For example:

<plugin id="com.oxygenxml.pdf.custom.related.links">
  <feature extension="com.oxygenxml.pdf.css.xsl.merged2merged"
  file="custom_related_links.xsl"/>    
</plugin>

Create your customization stylesheet (for example, custom_related_links.xsl) with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    exclude-result-prefixes="xs"
    version="3.0">

    <xsl:template match="*[contains(@class, ' topic/related-links ')]">
        <!-- Remove. -->
    </xsl:template>
</xsl:stylesheet>

Use the Integrate/Install DITA-OT Plugins transformation scenario found in the DITA Map section in the Configure Transformation Scenario(s) dialog box.
Run the DITA Map PDF - based on HTML5 & CSS transformation scenario.

How to Use Custom Parameters in XSLT Stylesheets

Suppose you want to add an attribute with a custom value inside a <div> element.

To add this functionality using a DITA-OT plugin, follow these steps:

In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.pdf.css.param).
Create a plugin.xml file (in the folder you created in step 1) that specifies the extension points, your parameter file, and your customization stylesheet. For example:
```
<plugin id="com.oxygenxml.pdf.css.param">
  <feature extension="com.oxygenxml.pdf.css.xsl.merged2html5.parameters" file="params.xml"/>
  <feature extension="com.oxygenxml.pdf.css.xsl.merged2html5" file="custom.xsl"/>
</plugin>
```
Note: The com.oxygenxml.pdf.css.xsl.merged2html5 extension point can also be called from a Publishing Template.

Create a params.xml file that specifies the name of the custom attribute with the following content:

<dummy xmlns:if="ant:if">
  <param name="custom-param" expression="${custom.param}" if:set="custom.param"/>
</dummy>

Create your customization stylesheet (for example, custom.xsl) with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  exclude-result-prefixes="xs"
  version="3.0">
  <xsl:param name="custom-param"/>

  <xsl:template match="*[contains(@class, ' topic/div ')]">
    <div>
      <xsl:call-template name="commonattributes"/>
      <xsl:call-template name="setid"/>
      <xsl:if test="$custom-param">
        <xsl:attribute name="custom" select="$custom-param"/>
      </xsl:if>
      <xsl:apply-templates/>
    </div>
  </xsl:template>
</xsl:stylesheet>

Use the Integrate/Install DITA-OT Plugins transformation scenario found in the DITA Map section in the Configure Transformation Scenario(s) dialog box.
Duplicate the DITA Map PDF - based on HTML5 & CSS transformation scenario, then in the Parameters tab click New to create a new parameter (e.g. named custom.param with the value of customValue).
Run the transformation scenario.