chunking templates rearranged in snapshot

["Bob Stayton" <bobs@sagehill.net>]

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"/> <!-- contains any element format 
customizations -->
<xsl:import href="/path/to/chunk-common.xsl"/>
<xsl:include href="/path/to/chunk-code.xsl"/>
<!-- Add any customized chunking templates here -->

-  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