Skip to content

Commit

Permalink
Update the fixed-namespaces PR with additional notes for tutorial pur…
Browse files Browse the repository at this point in the history 
…poses, following review and acceptance
  • Loading branch information
@michaelhkay
michaelhkay committed Nov 28, 2023
1 parent 311d61b commit 01452ae
Showing 1 changed file with 62 additions and 19 deletions.
81 changes: 62 additions & 19 deletions specifications/xslt-40/src/xslt.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2882,8 +2882,11 @@
<p diff="add" at="2023-05-04">Prefixes used in element and attribute names in the stylesheet, because these are interpreted
by the XML parser and not only by the XSLT processor, <rfc2119>must</rfc2119> be bound
using <termref def="dt-native-namespace-bindings"/>.
In particular, this will always apply to the <termref def="dt-xslt-namespace"/> which is
declared in every stylesheet module. But namespace prefixes that are only used within the content of
In particular, the <termref def="dt-xslt-namespace"/> is used in the names of XSLT elements, so it must
be declared in every stylesheet module using a namespace declaration such as
<code>xmlns:xsl="http://www.w3.org/1999/XSL/Transform</code>. (A different prefix can be used:
some users prefer <code>xslt</code>, some favor the default namespace.)
But namespace prefixes that are only used within the content of
attribute and text nodes in the stylesheet (for example, <code>select="math:sin($theta)"</code>)
can be declared in <termref def="dt-fixed-namespace-bindings"/>.</p>

Expand All @@ -2896,6 +2899,20 @@

<p>The effect of declaring fixed namespace bindings is described in more detail in
<specref ref="fixed-namespaces"/>.</p>

<note>
<p>As a general rule:</p>
<ulist>
<item><p>Prefixes used in the names of elements and attributes in the stylesheet
must be declared using <termref def="dt-native-namespace-bindings"/>.</p></item>
<item><p>Prefixes used in QNames appearing in the content of attribute nodes
and text nodes in the stylesheet can usually be declared using
<termref def="dt-fixed-namespace-bindings"/>. There are a small number
of exceptions, notably the standard attributes <code>[xsl:]exclude-result-prefixes</code>
and <code>[xsl:]extension-element-prefixes</code>, and the <code>stylesheet-prefix</code>
and <code>result-prefix</code> attributes of <elcode>xsl:namespace-alias</elcode>.</p></item>
</ulist>
</note>
<div3 id="xslt-namespace">
<head>XSLT Namespace</head>
<p>
Expand Down Expand Up @@ -6660,6 +6677,8 @@ and <code>version="1.0"</code> otherwise.</p>
contain a binding for this prefix.</p>
<note><p>Including <code>xml</code> in the list has no effect, since the XML namespace
will always be in scope anyway.</p></note>
<note><p>If the namespace prefix is explicitly bound to a different namespace, for example
<code>xmlns:math="java:java.util.Math"</code>, then that binding takes precedence.</p></note>
</item>
<item><p>A string in the form <code>prefix=uri</code>, where <code>prefix</code> is an <code>NCName</code>
and <code>uri</code> is a (non-empty) namespace URI: for example,
Expand All @@ -6675,6 +6694,7 @@ and <code>version="1.0"</code> otherwise.</p>
<specref ref="locating-modules"/>. The resource that is retrieved may be any namespace well-formed
XML document. The in-scope namespace bindings of the outermost element of this document are
added to the <termref def="dt-fixed-namespace-bindings"/> of the stylesheet module.</p>
<note><p>Such URIs cannot contain whitespace.</p></note>
</item>
</ulist>

Expand Down Expand Up @@ -6721,18 +6741,13 @@ and <code>version="1.0"</code> otherwise.</p>
of unprefixed names.</p></item>
</ulist>
<note>
<p>The design decision to declare <termref def="dt-fixed-namespace-bindings"/> in an attribute
of the <elcode>xsl:stylesheet</elcode> element, rather than in <termref def="dt-top-level"/>
<termref def="dt-declaration">declarations</termref>, is motivated (a) by the desire to ensure
that the namespace bindings are uniform across the entire stylesheet module, and (b) by the
need for namespace bindings to be declared before they are used, which is necessary (for example) to
allow them to be used in <code>[xsl:]use-when</code> expressions. It is possible to use
<p>It is possible to use
the <termref def="dt-fixed-namespace-bindings"/> in other attributes of the <elcode>xsl:stylesheet</elcode>
element, such as <code>default-mode</code>. It is also possible to use them in
shadow attributes (see <specref ref="shadow-attributes"/>).</p>
<p>It is possible for the <code>fixed-namespaces</code> attribute itself to be supplied as
a shadow attribute (written with an underscore, <code>_fixed-namespaces</code>). Note that
it can then refer to <termref def="dt-static-variable">static variables</termref>
a shadow attribute (written with an underscore, <code>_fixed-namespaces</code>).
It can then refer to <termref def="dt-static-variable">static variables</termref>
declared in an importing or including <termref def="dt-stylesheet-module"/>. This provides an
alternative way of sharing common namespace bindings throughout a <termref def="dt-package"/>.</p>
</note>
Expand Down Expand Up @@ -6765,22 +6780,25 @@ and <code>version="1.0"</code> otherwise.</p>
</ulist>
</note>
<note>
<p>Using the <code>fixed-namespaces</code> attribute rather than <termref def="dt-native-namespace-bindings"/>
to bind namespaces has potential benefits:</p>
<p>Using the <code>fixed-namespaces</code> attribute rather
than <termref def="dt-native-namespace-bindings"/>
to bind namespaces has a number of potential benefits:</p>
<ulist>
<item><p>It reduces repetitive coding across stylesheet module boundaries,
and thus eliminates a source of potential errors.</p></item>
<item><p>It ensures that all expressions in a stylesheet module have the same
namespace bindings in their static context. This can reduce implementation overheads
because it prevents the need to maintain the namespace context at the level of individual
because it reduces the need to maintain the namespace context at the level of individual
expressions through rewrites such as function inlining. With processors that compile
stylesheets to a persistent executable form, it can contribute to a reduction in
the size of compiled code.</p></item>
<item><p>Namespaces bound in this way will never accidentally leak into a result tree.</p></item>
<item><p>Namespaces bound in this way will never accidentally leak into a result tree;
there is no need to exclude them using <code>[xsl:]exclude-result-prefixes</code>.</p></item>
<item><p>Namespaces declared on literal result elements are used purely to define the
namespace of elements and attributes within the result tree; they no longer leak into
the static context used when evaluating XPath expressions.</p></item>
</ulist>
</note>
<note><p>TODO: This is a first step. We hope to propose further changes that reduce the
need to define prefixes on function calls.</p></note>
</div3>


Expand Down Expand Up @@ -20287,6 +20305,9 @@ and <code>version="1.0"</code> otherwise.</p>
no namespace binding in scope for that prefix.</p>
</error>
</p>
<note><p>The prefix must be declared in a
<termref def="dt-native-namespace-bindings">native namespace binding</termref>,
not in a <termref def="dt-fixed-namespace-bindings">fixed namespace binding</termref>.</p></note>
<p>The default namespace of the parent element of the
<code>[xsl:]exclude-result-prefixes</code> attribute (see <xspecref spec="DM30" ref="ElementNode"/>) may be designated as an excluded
namespace by including <code>#default</code> in the list of namespace
Expand Down Expand Up @@ -20325,6 +20346,12 @@ and <code>version="1.0"</code> otherwise.</p>
avoid superfluous namespace declarations in the serialized <termref def="dt-result-tree">result tree</termref>. The attribute is also useful to
prevent namespaces used solely for the naming of stylesheet functions or
extension functions from appearing in the serialized result tree.</p>
<p diff="add" at="2023-11-28">In XSLT 4.0, a simpler approach is to declare such namespaces in a <code>fixed-namespaces</code>
attribute on the <code>xsl:stylesheet</code> element: see <specref ref="fixed-namespaces"/>.
Namespace prefixes declared in that way are not eligible to be used in the names
of literal result elements and their attributes, and they are not copied into the
result tree.
</p>
</note>
<example>
<head>Excluding Namespaces from the Result Tree</head>
Expand Down Expand Up @@ -20440,6 +20467,12 @@ and <code>version="1.0"</code> otherwise.</p>
namespace URI that will appear in the stylesheet, and the
<code>result-prefix</code> attribute specifies the corresponding namespace URI
that will appear in the <termref def="dt-result-tree">result tree</termref>. </p>
<note diff="add" at="2023-05-04"><p>It is the <termref def="dt-native-namespace-bindings"/> that apply,
not the <termref def="dt-fixed-namespace-bindings"/>. More specifically: if a prefix <code>p</code>
appears in the <code>stylesheet-prefix</code> or <code>result-prefix</code> attribute,
there must be an in-scope namespace declaration of the form <code>xmlns:p="...."</code>;
it is not sufficient to declare the namespace in the <code>fixed-namespaces</code>
attribute of the <elcode>xsl:stylesheet</elcode> element.</p></note>
<p>The default namespace (as declared by <code>xmlns</code>) may be specified by
using <code>#default</code> instead of a prefix. If no default namespace is in
force, specifying <code>#default</code> denotes the null namespace URI. This
Expand Down Expand Up @@ -20480,8 +20513,7 @@ and <code>version="1.0"</code> otherwise.</p>
no in-scope binding for that namespace prefix.</p>
</error>
</p>
<note diff="add" at="2023-05-04"><p>It is the <termref def="dt-native-namespace-bindings"/> that apply,
not the <termref def="dt-fixed-namespace-bindings"/>.</p></note>


<p>When a literal result element is processed, its namespace nodes are handled as
follows:</p>
Expand Down Expand Up @@ -20693,6 +20725,9 @@ and <code>version="1.0"</code> otherwise.</p>
<elcode>xsl:element</elcode> instruction.</p>
</error>
</p>
<note><p>If a <code>fixed-namespaces</code> attribute is present on the containing <elcode>xsl:stylesheet</elcode> or
<elcode>xsl:package</elcode> element, then the prefix must be declared in that attribute, not in a
<termref def="dt-native-namespace-bindings">native namespace binding</termref>.</p></note>
<p>If the <code>namespace</code> attribute is not present then the <termref def="dt-lexical-qname">lexical QName</termref> is expanded into an <termref def="dt-expanded-qname">expanded QName</termref> using the namespace
declarations in effect for the <elcode>xsl:element</elcode> element, including any
default namespace declaration.</p>
Expand Down Expand Up @@ -20824,7 +20859,8 @@ and <code>version="1.0"</code> otherwise.</p>
QName</termref>.</p>
<p>
<error spec="XT" type="dynamic" class="DE" code="0850">
<p>It is a <termref def="dt-dynamic-error"> dynamic error</termref> if the <termref def="dt-effective-value">effective value</termref> of the <code>name</code>
<p>It is a <termref def="dt-dynamic-error"> dynamic error</termref> if the <termref def="dt-effective-value">effective value</termref>
of the <code>name</code>
attribute <error.extra>of an <elcode>xsl:attribute</elcode>
instruction</error.extra> is not a <termref def="dt-lexical-qname">lexical
QName</termref>.</p>
Expand All @@ -20850,6 +20886,10 @@ and <code>version="1.0"</code> otherwise.</p>
instruction.</p>
</error>
</p>
<note><p>If a <code>fixed-namespaces</code> attribute is present on the containing <elcode>xsl:stylesheet</elcode> or
<elcode>xsl:package</elcode> element, then the prefix must be declared in that attribute, not in a
<termref def="dt-native-namespace-bindings">native namespace binding</termref>.</p></note>

<p>If the <code>namespace</code> attribute is not present, then the <termref def="dt-lexical-qname">lexical QName</termref> is expanded into an <termref def="dt-expanded-qname">expanded QName</termref> using the namespace declarations
in effect for the <elcode>xsl:attribute</elcode> element, <emph>not</emph> including
any default namespace declaration.</p>
Expand Down Expand Up @@ -36814,6 +36854,9 @@ return ($m?price - $m?discount)</eg>
<code>#default</code> is specified, if there is no default namespace.</p>
</error>
</p>
<note><p>The prefix must be declared in a
<termref def="dt-native-namespace-bindings">native namespace binding</termref>,
not in a <termref def="dt-fixed-namespace-bindings">fixed namespace binding</termref>.</p></note>
<p>The designation of a namespace as an extension namespace is effective for the
element bearing the <code>[xsl:]extension-element-prefixes</code> attribute and
for all descendants of that element within the same stylesheet module.</p>
Expand Down

0 comments on commit 01452ae

Please sign in to comment.