Re: DOCBOOK-APPS: Overriding <para> template creates invalid HTML

[Alex Lancaster <alexl at users dot sourceforge dot net>]

>>>>> "-" == Bob Stayton <bobs@caldera.com> writes:

[...]

>> https://sourceforge.net/tracker/index.php?func=detail&aid=583335&group_id=21935&atid=373747
>> 
>> Here is the test case, "test.xml":

[...]

-> Actually, this isn't a bug, it is an expression of the behavior of
-> XSLT import precedence that shows up when you use formalpara/para.

-> Here is what is going on.  The stock <xsl:template match="para">
-> template wraps its content in <p> </p>, except when its unwrap
-> process kicks in to avoid <p> tags where HTML doesn't like them.

-> But the block.xsl file also has a template <xsl:template
-> match="formalpara/para">.  This template does not output <p> </p>
-> at all, because it knows the wrapper formalpara element's template
-> has already done that, so that the title and para are inside the
-> <p> </p>.  Because this template's match pattern is more specific,
-> it has a higher priority that the "para" template.

-> Now copy the "para" template to your customization layer and import
-> docbook.xsl.  The rules of import precedence state that the
-> importing file's templates take precedence over the imported file's
-> templates.  In general, that's how customized templates override
-> the stock ones.

-> But what isn't obvious is that import precedence is stronger than
-> priority selection.  So your custom "para" template is used inside
-> formalpara.  The "formalpara/para" template has higher priority
-> inside the stock docbook stylesheet, but not in the importing
-> stylesheet.  So you end up with nested <p> elements, which is not
-> legal HTML.

-> The solution is to add another template to your customization
-> layer:

-> <xsl:template match="formalpara/para"> <xsl:apply-imports/>
-> </xsl:template>

-> Now this template has higher priority than your custom "para"
-> template in the importing stylesheet. Its effect is to use the
-> imported stock "formalpara/para" template, which is what you want
-> in order to avoid the extra <p> elements.

-> A quick scan of the stylesheets also shows a template in
-> footnote.xsl: <xsl:template
-> match=""footnote/para[1]|footnote/simpara[1]" priority="2"> To
-> avoid problems with footnote paras, you should probably add an
-> apply-imports template for this one too.

Bob,

Thanks for the illuminating explanation.  I tried it, it works, and
with your clear explanation, it all makes sense now.  I thought that
might be some import/precedence/priority issue with templates going
on, but I somehow got fixated on the idea that it was somehow related
to the 'unwrap.p' named template.

I didn't think to look at overriding other elements, but you're right,
it's subtle, because I didn't realize that in XSLT import precedence
trumps priority (or what you might term 'specializedness') of a
template, because I assumed that if the wasn't overriden, it would
simply use the imported one.  So I learned something.

Since overriding <para> is possibly a common task, and has subtle
ramifications if not done correctly, perhaps it's one for either the
DocBook FAQ (the "Customizing DocBook section") or the XSLT FAQ (under
"Priorities" or "Precedence" or somesuch).  DaveP?

Alex