2.3. Custom transform stylesheets

The transform phase is implemented by the means of XSLT 1.0 stylesheets. The -t engine option specifies which XSLT stylesheet is to be used to implement the transform phase. Therefore a custom transform phase is implemented as follows:

  1. Create your XSLT 1.0 stylesheet. Let's call this file custom_docbook5.xslt. This file is found in the folder containing your DocBook 5 customization.

    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
                    xmlns:h="http://www.w3.org/1999/xhtml"
                    xmlns="http://docbook.org/ns/docbook"
                    exclude-result-prefixes="h">
    
      <xsl:import href="paste-from-word:xslt/docbook5.xslt"/>
    
    ...YOUR CUSTOMIZATION HERE...
  2. Use property configuration_name.pasteFromWord.parameter to run it.

    <property name="$c.pasteFromWord.parameter">
      ...
      -t custom_docbook5.xslt
      ...
    </property>
  3. As is, option -t custom_docbook5.xslt will not work because a relative filename is resolved against the current working directory. For this -t option to work, your DocBook 5 customization file must additionally define property configuration_name.pasteFromWord.parameter.base as follows:

    <property name="$c.pasteFromWord.parameter.base" url="true">.</property>

    When this property is defined, command pasteFromWord uses it to resolve any relative URL found in its parameters.

2.3.1. A real world example

The problem to be solved is transforming XHTML pre elements having attribute class="programlisting" to DocBook 5 programlisting elements. (The stock XSLT stylesheet addon_install_dir/xslt/docbook5.xslt generates literallayout elements.)

In order to solve this problem, it is recommended to proceed as follows:

  1. Use MS-Word to save a sample document making use of your user-defined styles as non-filtered HTML. Example: samples/custom_docbook5/program_listing.docx saved as samples/custom_docbook5/program_listing.htm.

  2. Write your XSLT stylesheet. Example: samples/custom_docbook5/custom_docbook5.xslt.

  3. Test it using the toxml command-line utility, and not in XMLmind XML Editor. Example:

    C:\...\custom_docbook5> toxml -i prune program_listing.xed¬
     -t custom_docbook5.xslt program_listing.htm program_listing.xml

    In the above toxml command, option "-i prune program_listing.xed" is used to generate XHTML pre elements having attribute class="programlisting". See Section 2.2, “Custom edit steps”.

  4. After your XSLT stylesheet passes all tests, integrate it into your DocBook 5 customization. Example: samples/custom_docbook5/0docbook5.xxe.

XSLT stylesheet samples/custom_docbook5/custom_docbook5.xslt contains:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
                xmlns:h="http://www.w3.org/1999/xhtml"
                xmlns="http://docbook.org/ns/docbook"
                exclude-result-prefixes="h">

  <xsl:import href="paste-from-word:xslt/docbook5.xslt"/>

  <xsl:template match="h:pre[@class='programlisting']">
    <programlisting>
      <xsl:call-template name="processCommonAttributes"/>
      <xsl:apply-templates/>
    </programlisting>
  </xsl:template>

</xsl:stylesheet>

When the above toxml command is applied to samples/custom_docbook5/program_listing.htm, this gives DocBook 5 document samples/custom_docbook5/program_listing.xml.