Chunking customization

Although the chunk stylesheet provides many parameters that control the chunking of your document into multiple HTML files, you may have a need for further customization. In earlier versions of the stylesheet, modification of the chunking behavior was difficult because the code for styling elements and the code for chunking was mixed together. Starting with version 1.61, these templates are cleanly separated, so customization is easier.

If you examine the html/chunk.xsl file from version 1.61 or above, you will see that all it does is load other stylesheet modules.

<xsl:import href="docbook.xsl"/>
<xsl:import href="chunk-common.xsl"/>
<xsl:include href="manifest.xsl"/>
<xsl:include href="chunk-code.xsl"/>

The use of both xsl:import and xsl:include, and the order in which they are used, are important for allowing clean customization. It also allows you to create a customized version of the single-page stylesheet as well as the chunking stylesheet using modular files.

Here are the steps for creating customizations of both chunking and single-page stylesheets.

  1. Create a customization file for single-page output as described in the section “Customization layer”. Let's say you name that file mydocbook.xsl. It should contain:

    • An xsl:import of the stock html/docbook.xsl stylesheet.

    • Followed by any parameter settings and customizations of how elements should be styled. Don't include any parameters that control chunking.

  2. Copy the html/chunk.xsl file to another customization file, such as mychunk.xsl. Edit that file as follows:

    Import your single-page customization file, which imports docbook.xsl:
    <xsl:import href="mydocbook.xsl"/>
    <xsl:import href="chunk-common.xsl"/>
    <xsl:include href="manifest.xsl"/>
    <xsl:include href="chunk-code.xsl"/>
    Add your parameter settings and customizations that affect chunking behavior here.

With this arrangement, you can put all customizations of style into your mydocbook.xsl customization file, and they will be used in both the single-page and chunked output. Then the mychunk.xsl customization file only needs to contain chunking-specific changes.

Even with this arrangement, customization of the chunking behavior will require you to understand the templates that perform the chunking process. The behavior is further complicated by options such as fast chunking (turned on by the parameter) and the onechunk.xsl variation. The following table summarizes the important chunking templates.

Table 11.3. Chunking templates

<xsl:template match="/">chunk-code.xslMatches document root to start processing.
chunk-code.xslMatches elements that are always chunks and calls the process-chunk-element template.
chunk-code.xslMatches section elements, calls the chunk template to determine if it is to be chunked, and then calls the process-chunk-element if it is.
chunk-common.xslDetermines if the current element is a chunk. It returns 1 if the element is a chunk, or 0 otherwise.
chunk-code.xslApplies templates to style the element content and saves the styled result in a variable. Routes the content to the appropriate template based on chunking options that are set.
and others
chunk-code.xslDetermines the Next and Previous links for the given chunk element and calls the process-chunk template.
chunk-code.xslDetermines the filename of the chunk and calls the write-chunk template.
chunker.xslCalls the appropriate extension function for the current processor to write the styled content to a chunk file.