Re: [xsl] Re: xsl/xslt coding standard

Subject: Re: [xsl] Re: xsl/xslt coding standard
From: Jeni Tennison <jeni@xxxxxxxxxxxxxxxx>
Date: Fri, 16 Aug 2002 11:07:12 +0100
Hi Hans,

> The discussion now get me a little confused.
> Where lays the problem with:
>
>> <xsl:stylesheet version="1.0"
>>                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
>>                 xmlns:doc="doc:documentation"
>>                 extension-element-prefixes="doc">
>> 
>> <doc:module>Here's some documentation of my stylesheet</doc:module>
>> 
>> <xsl:template match="/">
>>   <doc:template name="templateName" match="whatever">
>>      <doc:descr>And I can use it within templates too!</doc:descr>
>>      <doc:result type="tNode-set">result description</doc:result>
>>      <doc:param name="someName">Param description</doc:param>
>>      <doc:param name="someOtherName">Param description</doc:param>
>>      ...............
>>      <xsl:fallback />
>>   </doc:template>
>>   ...
>> </xsl:template>
>
> if i understand correctly, this a good approach, because
>
> 1. i can code a documenting stylesheet to build a resulting
> documentation of my application stylesheet
>
> 2. everything with the namespace doc is not outputted from my
> application stylesheet. Need i for this purpose:
> exclude-result-prefixes="doc" ?

No -- the doc:* elements are labelled as being extension elements
through the extension-element-prefixes attribute. That means that the
namespace is automatically excluded from the result tree. However, it
also means that the processor will try to interpret the elements as
instructions, which leads on to...

> Can anyone explain please for what is <xsl:fallback /> in
> <doc:template> ?

When a processor encounters the doc:template element, because it's
labelled as an extension element, the processor will interpret it as
an instruction. If it doesn't understand the instruction, it will
usually come out with an error. However, if you place an xsl:fallback
element inside, it won't raise an error, but rather will try to
process the content of the xsl:fallback element instead. (If the
xsl:fallback element is empty, then it does nothing, of course.)

To give another, more common, example, say you were using Saxon's
saxon:group extension element:

<xsl:template match="people">
  <saxon:group select="person" group-by="surname">
    ...
  </saxon:group>
</xsl:template>

If you ran that with MSXML, you'd get an error because it doesn't
understand the saxon:group element. To prevent that, you can add an
xsl:fallback which either halts processing with a helpful error
message:

<xsl:template match="people">
  <saxon:group select="person" group-by="surname">
    ...
    <xsl:fallback>
      <xsl:message terminate="yes">
        You must use Saxon to run this stylesheet!
      </xsl:message>
    </xsl:fallback>
  </saxon:group>
</xsl:template>

or provides some alternative XSLT that does the same thing (more or
less) as the saxon:group. For example:

<xsl:template match="people">
  <saxon:group select="person" group-by="surname">
    ...
    <xsl:fallback>
      <xsl:for-each select="person">
        <xsl:sort select="surname" />
        ...
      </xsl:for-each>
    </xsl:fallback>
  </saxon:group>
</xsl:template>

Using xsl:fallback in an element that you're using for documentation
is a hack that enables you to take advantage of the fact that
extension elements don't get output in the result tree, but it's a
nasty hack, and a confusing use of xsl:fallback, which is why I think
that we should have something that's specific for documentation
instead, such as:

<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
                xmlns:doc="doc:documentation"
                documentation-element-prefixes="doc">

<doc:module>Here's some documentation of my stylesheet</doc:module>

<xsl:template match="/">
  <doc:template name="templateName" match="whatever">
     <doc:descr>And I can use it within templates too!</doc:descr>
     <doc:result type="tNode-set">result description</doc:result>
     <doc:param name="someName">Param description</doc:param>
     <doc:param name="someOtherName">Param description</doc:param>
     ...............
  </doc:template>
  ...
</xsl:template>

</xsl:stylesheet>

Cheers,

Jeni

---
Jeni Tennison
http://www.jenitennison.com/


 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list


Current Thread