I've rearranged the templates in the chunking stylesheet files, and I'm
hoping some people will try out the latest DocBook XSL snapshot and report
any problems.
I've been trying to solve a long standing problem with the chunking
stylesheets: how do you customize both the element formats and the chunking
behavior, without creating conflicts between templates. The chunking
templates make extensive use of import precedence, but sometimes when
another import layer is added for a customization, things would break.
The basic idea is that the chunking stylesheet imports the non-chunking
stylesheet to get the templates that format elements. The chunking
stylesheet also defines templates that match on the same elements, but
instead perform the chunking process to contain the formatted content. The
chunking version has import precedence over the non-chunking version, so it
acts first. Inside the chunking template, the xsl:apply-imports element is
used to apply the non-chunking version to format the content. So far so
good.
The problem arises when a customization layer imports the chunking
templates and then customizes the chunking behavior. If the customized
chunking template does xsl:apply-imports, it applies the most recent
import, which is the original chunking template, not the element formatting
template. Oops, broken output, most visibly noticed as chunks with header
and footer but no content.
The chunking customization process tries to work around this by using
xsl:include instead of xsl:import for the chunking templates. That way you
don't add another layer of import, so xsl:apply-imports will find the
element formatting version. The problem with xsl:include is that any
templates that you copy and customize then come into conflict with the
xsl:included templates, because they are at the same import level.
The solution seems to be to handle named templates and "match" templates
differently. Only match templates serve as the basis for an
xsl:apply-imports. A named template may contain xsl:apply-imports, but the
import selection is based on the match template that called the named
template. So only the match templates need to be kept at only one higher
level of import precedence. Named templates don't have that restriction.
In addition, match templates can use a priority attribute to resolve any
conflicts.
So I rearranged the templates so that chunk-common.xsl now contains all the
named chunking templates, and chunk-code.xsl now contains all the match
templates. The chunk.xsl stylesheet does xsl:import on chunk-common.xsl
(named templates are imported), and it does xsl:include on chunk-code.xsl
(match templates are included). The manifest.xsl templates were moved into
one or the other as well, leaving an empty module at this point.
Now a chunking customization will look a lot like the old way of doing it
(minus manifest.xsl):
<xsl:import href="mydocbook.xsl"/>
<xsl:import href="/path/to/chunk-common.xsl"/>
<xsl:include href="/path/to/chunk-code.xsl"/>
- If you customize a named chunking template, then your custom template
has a higher import precedence than the original imported one in
chunk-common.xsl.
- If you customize a chunking template with a match attribute, you have to
do one thing to avoid conflict: add a priority="1" attribute. That's
because the original chunk match templates in chunk-code.xsl are
xsl:included, so they are at the same import precedence level as your
custom template.
Adding the priority attribute resolves the conflict in your favor, but
*doesn't add another level of import*. That is the key improvement here.
If your custom match template does xsl:apply-imports, it goes back one
import level and finds the element formatting version, not the stock
chunking version. So you get new chunking behavior, and each chunk
contains the formatted element content.
I think the new arrangement won't break existing chunking customizations,
but I would like others to test it and confirm that or report problems. If
it doesn't work, I'll back it out before the 1.72.1 release.
The new chunk.xsl stylesheet file has comments that describe how to create
a customization. The new arrangement enables more extensive customization
without generating empty chunks or error messages about template conflicts.
Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net