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"/> <c>text</c> </b> </xxx> 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="http://www.w3.org/1999/XSL/Transform" version="1.0" extension-element-prefixes="doc" exclude-result-prefixes="main" xmlns:doc="http://doc.com" xmlns:main="http://a/b/c" xmlns:y="http:/x/y/z"> 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 document 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"/> <main:c>text</main:c> </main:b> </main:xxx> 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 --> </doc:template> <!-- body of the template --> </xsl: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()" />. </doc:template> 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="..."> <doc:template> <!-- documentation on the template --> <xsl:fallback> <!-- body of the template --> </xsl:fallback> </doc:template> </xsl: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 "http://doc.com"), 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... Cheers, Jeni Dr Jeni Tennison Epistemics Ltd, Strelley Hall, Nottingham, NG8 6PE Telephone 0115 9061301 ? Fax 0115 9061304 ? Email jeni.tennison@xxxxxxxxxxxxxxxx XSL-List info and archive: http://www.mulberrytech.com/xsl/xsl-list
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: How is this part of the XSLT sp, David Carlisle | Thread | Re: How is this part of the XSLT sp, Bart Schuller |
Re: Saxon Frustrations, Warren Hedley | Date | Re: Saxon Frustrations, Carlos Araya |
Month |