Search code examples
htmlxmlxsltdocbookdocbook-xsl

Extend an XSLT template to not effect stock templates during processing?

Instead of modifying the stock templates that come with many suites, I'd like to extend the stock templates so when the stock template gets upgraded/updated with a new version, I can keep my own XSLT extension/modification of the stock XSLT and use to process with as well. Similar in function to a source code patch file or CSS inheritance.

For example, if the stock XSLT doesn't have enough spaces in the separation between footnotes when processing to HTML, I'd like to add my own XSLT for that footnote that adds a space.

Solution

  • In DocBook XSL stylesheets terms want you want to create is called a “customization layer”.

    The basic idea is, put your customizations in a customizations.xsl or whatever file and then use your XSLT engine of choice to call that instead of the stock DocBook XSL driver file; like this:

    xsltproc customizations.xsl my-docbook-source.xml

    As far what exactly you put into the customizations.xsl file, if all you want to change is some of the user-configurable DocBook XSL params, it’s as easy as:

    <xsl:stylesheet  
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:import href="html/docbook.xsl"/>

<xsl:param name="html.stylesheet" select="'corpstyle.css'"/>
<xsl:param name="admon.graphics" select="1"/>

</xsl:stylesheet>

    And if you need to replace a whole template:

    <xsl:stylesheet  
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    version="1.0"> 

<xsl:import href="fo/docbook.xsl"/> 

<xsl:template match="lineannotation">
  <fo:inline font-style="italic">
    <xsl:call-template name="inline.charseq"/>
  </fo:inline>
</xsl:template>
</xsl:stylesheet>

    So because instead of you directly calling the DocBook XSL driver file from the command line, you call your customization.xsl file and it needs to call the right DocBook XSL driver, then for the href values in, e.g., the <xsl:import href="html/docbook.xsl"/> elements, you just need to put the path to wherever the stock DocBook XSL stylesheets+driver are on your system.

    For example, on a Debian system:

    <xsl:import href="/usr/share/xml/docbook/stylesheet/docbook-xsl/html/docbook.xsl"/>

    Caveats

    If you need to make any changes to one of the templates in the stock stylesheets, you copy-paste the entire template into your customization layer and make your changes to the template there.

    XSLT doesn’t give any more change-making granularity than that—e.g., you can’t have your layer contain just a two-line patch for part of a template. You have to copy in the whole template.

    A consequence of that is, if the upstream maintainers change/fix some other part of original template you made a copy of, your customization layer is not going to pick up that change unless you re-copy the new upstream template in again and make your tweaks to it again.

    But that’s probably not going to cause you any problems in practice because these days I think the upstream DocBook XSL templates don’t change very often.

    Also note that some of the templates in the DocBook XSL stylesheets are huge—so your layer can end up being a relatively big file even if you only need to make a single-line patch