How to Override a WebHelp Classic XSLT Stylesheet from an Ant Build File
Edit online

To create a WebHelp XSLT customization that is only available for a certain DITA OT transformation, the extension plugin should declare a custom transtype. The WebHelp XSLT stylesheets can be overridden from an ANT file provided by the DITA-OT extension plugin. From the Ant target associated with the plugin, you will specify a custom XSLT stylesheet that imports the original WebHelp stylesheet and add some customization templates.

The following procedure explains how to create a DITA-OT extension plugin that uses this extension method:

  1. In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.webhelp.classic.custom).
  2. Create a plugin.xml file (in the folder you created in step 1) that specifies a new DITA-OT transtype and the build file associated with the plugin. For example:
    <plugin id="com.oxygenxml.webhelp.classic.custom">
    <feature extension="dita.conductor.target.relative" file="integrator.xml"/>
    <transtype name="webhelp-classic-custom" extends="webhelp" 
      desc="WebHelp Classic Customization"/>
</plugin>
  3. Create the integrator.xml file that will import the actual plugin Ant build file.
    <project basedir="." name="Webhelp Classic Customization">    
    <import file="build.xml"/>
</project>
  4. Create the build.xml file that overrides the value of properties associated with the XSLT stylesheets used to produce HTML files. The following Ant properties can be overridden to specify your customization stylesheets:
    args.wh.classic.topic.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce an HTML file for each topic.
    args.wh.classic.create.main.files.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the main HTML files.
    args.wh.classic.createTocXML.xsl
    Specify this property if you want to customize the XSLT stylesheet used to produce the toc.xml file. The toc.xml file contains information extracted from DITA map and it is mainly used to create the WebHelp TOC.

    For example, to customize a WebHelp Classic transformation type, the build file should look like:

    <project basedir="." name="Webhelp Classic Customization">  
 <target name="dita2webhelp-classic-custom">    
   <!-- 
     Override this property if you want to customize the XSLT stylesheet 
     used to produce an HTML file for each topic 
   -->    
   <property 
     name="args.wh.classic.topic.xsl" 
     value="${dita.plugin.com.oxygenxml.webhelp.classic.custom.dir}
                                                 /xsl/dita2webhelpCustom.xsl"/>
   <!-- 
     Override this property if you want to customize the XSLT stylesheet 
     used to produce the main HTML file.
   -->    
   <property 
     name="args.wh.classic.create.main.files.xsl" 
     value="${dita.plugin.com.oxygenxml.webhelp.classic.custom.dir}
                                              /xsl/createMainFilesCustom.xsl"/>
   <!-- 
     Override this property if you want to customize the XSLT stylesheet 
     used to produce the toc.xml file.
   -->    
   <property 
     name="args.wh.classic.createTocXML.xsl" 
     value="${dita.plugin.com.oxygenxml.webhelp.classic.custom.dir}
                                              /xsl/createTocXMLCustom.xsl"/>
   <!--
     You need to delegate the build target:
     * dita2webhelp - for WebHelp Classic
   -->
   <antcall target="dita2webhelp"/>
 </target>  
</project>
  5. Create an xsl directory in the plugin customization directory (that you created in step 1) to store the customized XSLT stylesheets.
  6. Now that the extension plugin is created, install it in the DITA Open Toolkit.

Referencing the WebHelp XSLT Stylesheets from Your Customizations

Note that your customization stylesheets should import the original stylesheets that they override. To reference the WebHelp stylesheets, you can use the plugin:com.oxygenxml.dita-ot.plugin.webhelp prefix. This prefix is rewritten by an XML catalog to the WebHelp root directory.

Customizing the dita2webhelp.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp dita2webhelp.xsl stylesheet should look like:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:math="http://www.w3.org/2005/xpath-functions/math"
   exclude-result-prefixes="xs math"
   version="2.0">    
   <!--
     Import the original stylesheet used to produce an HTML file for each topic.
   -->
   <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/
                                             dita/classic/dita2webhelp.xsl"/>
   <!--
     Add your customization templates here.
   -->
</xsl:stylesheet>

You need to import the following XSLT stylesheet:

<xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/desktop/dita2webhelp.xsl"/>

Customizing the createMainFiles.xsl Stylesheet
The XSLT stylesheet that customizes the WebHelp createMainFiles.xsl stylesheet should look like:
<?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"
    xmlns:math="http://www.w3.org/2005/xpath-functions/math"
    exclude-result-prefixes="xs math"
    version="2.0">    
    <!--
        Import the original stylesheet used to produce the main HTML file.
    -->
    <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/
                                               desktop/createMainFiles.xsl"/>
    <!--
        Add your customization templates here.
    -->
        
</xsl:stylesheet>

You need to import the following XSLT stylesheet:

<xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/desktop/createMainFiles.xsl"/>

Customizing the tocDita.xsl File
The XSLT stylesheet that customizes the WebHelp tocDita.xsl stylesheet should look like:
<?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"
    xmlns:math="http://www.w3.org/2005/xpath-functions/math"
    exclude-result-prefixes="xs math"
    version="2.0">    
    <!--
        Import the original stylesheet used to produce the toc.xml file.
    -->
    <xsl:import href="plugin:com.oxygenxml.webhelp.classic:xsl/dita/tocDita.xsl"/>
    <!--
        Add your customization templates here.
    -->        
</xsl:stylesheet>