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 13:55:32 +0100
Hi Hans,

> <snip>
> (And that it uses documentation-element-prefixes rather than
> extension-element-prefixes.)
>
> I think it would be much less confusing if elements that are
> intended as documentation were clearly marked as such to both the
> author/reader and to the processor.
> </snip>
>
> Okay, i got it hopefully, it´s a proposition. Not yet realized. I am
> looking for a solution with xslt 1.0. recommendation standard.

Yes, it's a proposition for XSLT 2.0.

> <snip>
> However, it would be rather pointless having a template in your
> stylesheet that never got called or applied. In the example we're
> using the template matches the root node, so its content is always
> processed...
> </snip>
>
> So if a named template <doc:template> is embedded in a template rule
> which is matched <xsl:template match="/"> the processor look out for
> instructions in a named template without calling it becuase of its
> declaration as extension-element-prefixes?

I don't really understand the question, but let me go through it step
by step and see if that answers it anyway. Let's rename doc:template
in the sample:

<xsl:template match="/">
  <doc:template-documentation 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-documentation>
  ...
</xsl:template>

The doc:template-documentation element isn't a template definition.

Templates are defined with xsl:template elements (elements that are
called 'template' and that are in the XSLT namespace) which live at
the top level of the stylesheet.

Anything inside a template is either an *instruction* (e.g. xsl:if,
xsl:for-each), which the processor tries to follow, or a *literal
result element* (e.g. HTML elements), which a processor copies to the
result tree.

A subset of instructions are *extension elements*. Extension elements
are elements that are recognised as being instructions not because
they're XSLT elements but because they're in a namespace that has been
designated an extension element namespace.

If you take the above example, the doc:template-documentation element
is in a template, so it must be either an instruction (an extension
element, since it's not in the XSLT namespace) or a literal result
element. If the prefix 'doc' is listed in the
extension-element-prefixes attribute of the stylesheet, then it's an
extension element, otherwise it's a literal result element.

If the processor finds that it's an extension element, it will try to
process it, to do something other than just copy it across to the
result tree. If it doesn't recognise it, and there's no xsl:fallback
element inside, it will raise an error.

If the processor finds that it's a literal result element, it will
copy the element across into the result tree and you'll see it in the
output.

> If it is not an extension-element-prefixes type it would look out
> either as simple xml ?

If the 'doc' namespace hasn't been declared as an extension element
namespace then yes, it will be output just like normal XML would.

> If yes, why not declare in this way the documentation without
> <xsl:fallback />?

If the 'doc' namespace hasn't been declared as an extension element
then it will be output just like normal XML would, and you don't need
xsl:fallback. Usually you don't want documentation from your
stylesheet to appear in the result of the transformation, however.

If the 'doc' namespace *has* been declared as an extension element
then the processor will try to process it. It will raise an error if
you don't have an xsl:fallback element inside, unless you're dealing
with a processor that recognises the 'doc' namespace and knows what to
do with it.

> And extracting in a second documenting stylesheet the documentation
> and avoiding in this way that the documentating code of the first
> stylesheet are outputted?

Whatever method you use, you can process the stylesheet with XSLT to
extract the documentation. If the documentation contains xsl:fallback
elements, you can simply ignore them.

Whatever method you use, you can process the stylesheet with XSLT to
remove the documentation and thus get a running stylesheet. If you're
prepared to pre-process your stylesheet before using it, then you can
add documentation wherever you want, and don't have to worry about
xsl:fallback (or even marking the documentation elements as extension
elements) because the documentation elements will never be included in
a stylesheet that is actually run.

Cheers,

Jeni

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


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


Current Thread