Feature #6030
closed
in xsl:next-match documentation topic, mention that non-tunneling parameters are not automatically propagated to the next-matching template
0%
Description
Section 6.8 Overriding Template Rules of the XSLT 3.0 spec states the following about how parameters are passed to the next-matching template:
If a matching template rule R is found, then the result of the xsl:next-match or xsl:apply-imports instruction is the result of invoking R, with the values of parameters being set using the child xsl:with-param elements as described in 9.10 Setting Parameter Values.
The Saxonica documentation for xsl:apply-imports has a full paragraph on parameter behavior, but the documentation for xsl:next-match does not say anything about parameters.
At a minimum, I suggest adding something like this (feel free to edit for style):
Non-tunneling parameters that would have reached the next-matching template are not automatically passed; only non-tunneling parameters explicitly declared with
xsl:with-paramare passed.
This aspect is difficult to learn the hard way, especially when using xsl:next-match to implement overrides within someone else's code. I understand the desire not to replicate the XSLT specification in Saxonica's documentation. However, this is an important aspect of template overrides that is not obvious (to me) from the XSLT 3.0 specification without deliberate reading to notice it.
Updated by Michael Kay 11 months ago
You're right that there's an asymmetry between our coverage of xsl:apply-imports and xsl:next-match. However, in both cases we only say a fraction of what could be said. Our target audience is people who want a brief introduction or a quick reminder, and we have to be careful to avoid cramming too much in, because that will defeat the primary purpose.
We also have to beware the natural tendency to add arbitrary sentences here and there because someone tells us that they failed to find the information. You can only create good documentation if you have some kind of feeling for who the target audience is. For this particular material, it's very important to keep it at overview level: the most important thing on each page is the link to the actual spec.
Updated by Michael Kay 10 months ago
- Status changed from New to Resolved
I have copied this paragraph from apply-imports to next-match. I have also added a paragraph emphasising that the documentation in this section makes no attempt to be complete. By all means use it as a quick reference, but the information is very patchy and we have no plans to change this.
Please register to edit this issue
.