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

[Jeni Tennison <Jeni.Tennison@xxxxxxxxxxxxxxxx>]

David Carlisle wrote:
>   So, you can just do:
>
>   <xsl:stylesheet exclude-result-prefixes="doc" ... >
>
>   and all elements in the 'doc' namespace will be ignored, and you can have
>   structured documentation within that namespace to your heart's content.
>
>No, exclude-result-prefixes just means that namespace declarations will
>not be copied if they are not used, it never changes the
>element/attribute structure of the output.

Shoot.  I'd tried it out and thought it worked, but I must have been
looking at the wrong output file.  Sorry for the misinformation.

To summarise some ways of putting documentation in a stylesheet that
currently work, then:

1. using 'extension elements'

a. declare the namespace for the documentation elements (e.g. doc)
b. identify them as extension elements using:
     <xsl:stylesheet extension-element-prefixes="doc" ... >
c. insert the documentation elements wherever you want them; always include
an (empty) xsl:fallback child within them if you put them within templates
- outside templates (at the top level) you don't have to [1], but inside
them you must

----

2. using structured comments

Use normal XML comments (<!-- ... -->) but include a structure within them,
which you can then parse using XSLT if you wish (Warren Hedley provides a
stylesheet for doing so).

----

3. using xsl:if

a. declare the namespace for the documentation elements (e.g. doc)
b. exclude the namespace from the result using:
     <xsl:stylesheet exclude-result-prefixes="doc" ... >
c. define a parameter to indicate whether documentation should be outputted
(default false):
     <xsl:param name="documentation" />
d. place any documentation within xsl:if elements testing on the value of
the $documentation parameter, e.g.:
     <xsl:if test="$documentation">
       <doc:p>My documentation here...</doc:p>
     </xsl:if>

----

Of these ways, the first is the purest, probably (though it's a bit
annoying having to use xsl:fallback).

Cheers,

Jeni

[1] "Thus, an XSLT processor is always free to ignore such top-level
elements, and must ignore a top-level element without giving an error if it
does not recognize the namespace URI." from
http://www.w3.org/TR/xslt#stylesheet-element

[2] http://www.mulberrytech.com/xsl/xsl-list/archive/msg14060.html

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