Chunking customization

Chunking customization
	Chapter 11. HTML customizations

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.

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.

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 chunk.fast parameter) and the onechunk.xsl variation. The following table summarizes the important chunking templates.

Table 11.3. Chunking templates

Template	Location	Function
`<xsl:template match="/">`	chunk-code.xsl	Matches document root to start processing.
<xsl:template match="set\|book\|part\|...	chunk-code.xsl	Matches elements that are always chunks and calls the `process-chunk-element` template.
<xsl:template match="sect1\|sect2\|...	chunk-code.xsl	Matches section elements, calls the `chunk` template to determine if it is to be chunked, and then calls the `process-chunk-element` if it is.
<xsl:template name="chunk">	chunk-common.xsl	Determines if the current element is a chunk. It returns 1 if the element is a chunk, or 0 otherwise.
<xsl:template name="process-chunk-element">	chunk-code.xsl	Applies 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.
<xsl:template name="chunk-all-sections"> and others	chunk-code.xsl	Determines the Next and Previous links for the given chunk element and calls the `process-chunk` template.
<xsl:template name="process-chunk">	chunk-code.xsl	Determines the filename of the chunk and calls the `write-chunk` template.
<xsl:template name="write.chunk">	chunker.xsl	Calls the appropriate extension function for the current processor to write the styled content to a chunk file.


HTML frameset		Separate legalnotice