RE: How is this part of the XSLT specification to be interpreted?

Subject: RE: How is this part of the XSLT specification to be interpreted?
From: Jeni Tennison <Jeni.Tennison@xxxxxxxxxxxxxxxx>
Date: Wed, 21 Jun 2000 18:33:49 +0100
David Pawson wrote:
>Building on David Carlisles stylesheet, to make it a *bit* more
>obvious what's going on :-)

Now I'm confused! :)  I think that David Carlisle's stylesheet was meant to
do two things:

1. demonstrate how extension elements (the ones in the doc namespace) could
be used to hold documentation that would be ignored by the processor, with
an *empty* xsl:fallback being used to stop processors complaining that they
don't recognise the extension element (it gives them something to do instead)

2. demonstrate the effect of exclude-result-prefixes on the appearance of
namespace nodes (and elements within that namespace) within the output
that's generated

I'm going to try to clear up my confusion by going through David's example
step by step.  I'm afraid this is going to be another one of my long emails
- please someone shout at me if I'm using up too much bandwidth here.

David used:

<xxx xmlns="http://a/b/c";>
  <b a="2">
    <x:c xmlns:x="http:/x/y/z"/>

as the example of a fairly complex, but nevertheless short, XML document
that used a couple of namespaces and:

<?xml version="1.0" encoding="utf-8" ?>
<x xmlns:y="http:/x/y/z">[xxx]</x>
<x:c xmlns:x="http:/x/y/z" xmlns="http://a/b/c"/>

as the (non-well-formed) output that he was after.

The stylesheet included:

<xsl:stylesheet xmlns:xsl="";

Here he declared three namespaces (in addition to the standard 'xsl'):

doc  - the documentation namespace
main - the primary namespace, the default namespace throughout the input 
y    - the namespace equivalent to 'x' for the x:c element in the input

Mapping those namespace declarations so that the same prefixes are used in
the input gives helps make the XSLT stylesheet more understandable:

<main:xxx xmlns:main="http://a/b/c";>
  <main:b a="2">
    <y:c xmlns:y="http:/x/y/z"/>

The 'main' namespace is specified as a namespace to be excluded from the
result.  This means that the 'main' namespace will be declared as being the
default namespace in the output (so wherever the result elements are in the
'main' namespace within the stylesheet, they will be included in the output
without a prefix).

The 'doc' namespace is specified as a namespace for extension elements.
You'd normally expect those elements to do something in terms of altering
what the XSLT processor does (like saxon:output).  Here, we're declaring
the 'doc' namespace to be a namespace for extension elements so that the
XSLT processor doesn't treat them as result elements, to be outputted.

David's 'doc' namespace included two elements: 'template' to give
documentation on templates and 'select' to give documentation on select
expressions within templates.  He didn't have any particular structure
within those, though you can easily imagine having structured documentation
within the documentation on a template, commenting on, say, each of the
parameters that it takes.  In fact I'm sure someone will straightway
volunteer an XML dialect for documentation of XSLT stylesheets...

Anyway, within the stylesheet, then, he used the following 'design pattern'
for including documentation within a template:

<xsl:template match="...">
  <doc:template><xsl:fallback />
    <!-- documentation on the template -->
  <!-- body of the template -->

When an extension-element-aware (and XSLT-Recommendation-compliant)
processor comes across this, it knows (because it's been told in the
xsl:stylesheet) that the 'doc:template' element, being in the 'doc'
namespace, is an extension element.  It does a bit of introspection and
finds out that it doesn't know how to support these extensions, so it gets
ready to complain that it can't process the stylesheet, but first checks
whether there is an xsl:fallback element within the extension element.
When it finds one, it operates on the content of the xsl:fallback as if it
were just a normal part of the template (here it's empty, so it does
nothing), and ignores the rest of the content of the extension element.
Hence the documentation is not included in the output.

The fact that an XSLT processor ignores the content of extension elements
like this is important because it means that you can put anything you like
in it and it won't be processed.  This includes any XSLT elements that you
include in it.  There is no point in doing:

  <doc:template><xsl:fallback />
    This template matches <xsl:value-of select="name()" />.

because the xsl:value-of element is never processed (by an XSLT processor
that doesn't understand doc:template).

David points out that the fact that an XSLT processor does process the
content of the xsl:fallback element is important because it means you could
use it to contain the stuff that you're actually commenting on.  So, you
could use:

  <xsl:template match="...">
      <!-- documentation on the template -->
        <!-- body of the template -->

as the design pattern for including documentation instead.  In a previous
email, I've pointed out that this probably isn't a good idea just in case
some XSLT processor comes along that *does* understand the 'doc:template'
extension element, because then the content of the xsl:fallback element
(which is the content of the template) will not be processed, and your
legacy stylesheet won't work. 

The point, of course, of using XML to represent the documentation within
the stylesheet is that you can get at it with things that understand XML,
most importantly XSLT.  So, you can then have another XSLT stylesheet that
takes our documented XSLT stylesheet as input and produces a nice HTML
frameset that explain what the stylesheet does and how it works.  I'm sure
whoever volunteers the XML dialect for documentation will include such a
stylesheet in their contribution...

What the documentation included in this way *doesn't* do, cannot do, and
isn't really designed to do, is perform any run-time evaluation of the
performance of the stylesheet.  To do that, the documentation would need to
be understandable by an XSLT processor.  It would be possible to extend an
XSLT processor so that it understood the extension elements in a particular
namespace that was used for documentation (in this case "";),
and did something clever with them.  I'm not exactly sure what it could do
other than generate messages in a similar way to xsl:message, but I'm sure
there are plenty of ideas out there.  And I'm sure that someone will
volunteer to write extensions for SAXON that will carry them through...



Dr Jeni Tennison
Epistemics Ltd, Strelley Hall, Nottingham, NG8 6PE
Telephone 0115 9061301 ? Fax 0115 9061304 ? Email

 XSL-List info and archive:

Current Thread