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

[Alex Lancaster <alexl@users.sourceforge.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