[XSLT2.0] IBM-XSLT-127: XSLT 2.0 last call editorial comments

[With apologies that these comments are coming in after the end of the 
Last Call comment period.]

Hello,

     Following are comments on XSLT 2.0 that we believe to be editorial in 
nature.

------------------------------------------------------------------

Global Editorial

Different elements exhibit different behaviour with respect to import 
precedence.  These differences are frequent sources of confusion. 
Rationale for the particular behaviour of each element should be provided 
in order to aide readers.

------------------------------------------------------------------

Section 1.1

The fourth paragraph states that "XSLT is used for a wide range of 
XML-to-XML transformation tasks, not exclusively for formatting and 
presentation applications."

Although this is introductory, it might be worth noting that it is also 
used for a range of XML-to-non-XML transformation tasks as well.  For 
example, DOM3 test generation.

------------------------------------------------------------------

Section 2.3

The fifth bullet in the bulleted list refers to the "default mode".  This 
term should be defined somewhere with a termdef.

------------------------------------------------------------------

Section 2.4

The bulleted list of instruction elements should include xsl:param 
(probably with "Instructions that declare variables").  If the list isn't 
intended to be exhaustive, that should be stated or it should be removed 
competely.

------------------------------------------------------------------

Section 2.5.1

The paragraph that precedes the definition of singleton focus ("Sometimes 
the focus is based on a single node.") doesn't flow very well from the 
paragraph that precedes it.  As it doesn't add anything, it should be 
removed.

------------------------------------------------------------------

Section 2.9

In the paragraph before "Example: Errors in Constant Subexpressions", the 
scope of the "constant expression evaluation" subphase must be 
sufficiently well-defined.  A proper specref in place of "XPath 
specification states" is required, and should consider making "evaluate" 
into a termref.
------------------------------------------------------------------

Section 2.9

The paragraph before "Example: Errors in Constant Subexpressions" 
indicates that "any error occurs during [constant subexpression] 
evaluation. . .  must be held back until the evaluation phase, and 
signaled only if the XPath expression is actually evaluated."

It needs to be made clear that if the implementation can determine that 
the error would always be reported, that it can do so, as described in the 
preceding paragraph.  The wording of the last paragraph might be taken to 
override the permission provided by the preceding paragraph.

------------------------------------------------------------------

Section 3.3

In the first paragraph, it needs to be made clear that although the 
presence of the extension attribute does not affect the result tree, the 
namespace declaration for that extension will affect the result - in 
particular, the namespace declaration might be present in the result.

------------------------------------------------------------------

Section 3.6

The second paragraph of the note in this section introduces the concept of 
"entry modules".  Define "entry module" or add a good example.  The 
meaning isn't necessarily immediately clear.

------------------------------------------------------------------

Section 3.8

The second sentence of the third paragraph contains a link to XPath with 
the label "Section".  This appears to be a documentation build error of 
some sort.

------------------------------------------------------------------

Section 4.2

It would probably be helpful to point out to users here the potential 
pitfall of using xml:space='preserve' in the presence of xsl:attribute 
elements - it might result in a whitespace text node being created as a 
child of an element before an attribute node is generated.

------------------------------------------------------------------

Section 4.3

The second paragraph reads, "The stripping process takes as input a set of 
element names whose child whitespace text nodes are to be preserved."  How 
that set is constructed is only described further on, beneath the syntax 
diagrams for xsl:strip-space and xsl:preserve-space.

That separation makes the quoted sentence seem confusing.  One easily 
makes the mistake that this is actually referring to the pair of 
whitespace-separated lists of NameTests that appear as the values of the 
elements attributes in xsl:strip-space and xsl:preserve-space.

------------------------------------------------------------------

Section 4.4

The title "Attributes Types and DTD Validation" should be "Attribute Types 
and DTD Validation" or "Attributes' Types and DTD Validation".

------------------------------------------------------------------

Section 4.4

In the second paragraph, it would be helpful to provide a little more 
detail about how the equality comparison works.

------------------------------------------------------------------

Section 5.6.1

The second item in the numbered list, indicates that "Special 
considerations apply to two atomic types for which casting to xs:string is 
not possible. . . ."  However, there is only one such type.

------------------------------------------------------------------

Section 6.4

The first item in the numbered list states "First, all matching template 
rules that have lower import precedence than the matching template rule or 
rules with the highest import precedence are eliminated from 
consideration."

The wording of this is ambiguous.  It can be read as "First, (all matching 
template rules that have lower import precedence than the matching 
template rule) or (rules with the highest import precedence) are 
eliminated from consideration."

A better wording might be "First, only the matching template rule or rules 
with the highest import precedence are considered. Other matching template 
rules with lower precedence are eliminated from consideration."  The 
second item could then be reworded as "Next, of the remaining matching 
rules, only those with the highest priority are considered. Other matching 
template rules with lower priority are eliminated from consideration."

------------------------------------------------------------------

Section 7

In the second paragraph, the use of the term "sorted sequence" is 
potentially confusing, as it might refer to a sequence that hasn't been 
sorted at all.

We would suggest changing " the input sequence is sorted to produce a 
sorted sequence" to "is sorted before being used", and using the term 
"input sequence" instead of "sorted sequence" everywhere else.

------------------------------------------------------------------

Section 7

The lead-in to the bulleted list reads "The sequence constructor is 
evaluated with the focus set as follows".

This might read better reworded as "For each item in the sorted sequence, 
the sequence constructor is evaluated with the focus is set as follows:"

------------------------------------------------------------------

Section 9.4

The fourth sentence of the first paragraph uses the term "owned by".  This 
term is not defined nor is it used anywhere else.

Suggest changing "evaluating the sequence constructor owned by the 
variable-binding element" to "evaluating the contents of the 
variable-binding elment as a sequence constructor".

------------------------------------------------------------------

Section 9.4

In the first sentence of the second paragraph, there is a reference to 
Data Model, but it's not clear what one is being directed to see there. 
The reference should be placed after the words "The base URI of a node".

------------------------------------------------------------------

Section 9.4

In the example "Example: Two-Phase Transformation", it probably will not 
be clear to a novice reader that the imported stylesheets in the example 
will define templates only for the particular modes.

------------------------------------------------------------------

Section 9.4

The note suggests it is a good idea to use modes when transforming 
temporary trees.  It should be clarified that that's only necessary if 
different templates actually need to be applied.

------------------------------------------------------------------

Section 10.1.2

In the xsl:number instruction in "Example: Using Tunnel Parameters", 
'format="{$format}"' should be 'format="{$equation-format}"'.

------------------------------------------------------------------

Section 10.3

It is easy for a reader to make the mistake that the override attribute 
can be used to prevent a stylesheet function from overriding another 
stylesheet function with the same expanded QName with lower import 
precedence.  It should be made very clear that it can only override 
"built-in" functions.  That could include renaming the attribute to 
something like "override-builtin-functions".  An example illustrating the 
behaviour would also be appropriate.

------------------------------------------------------------------

Section 10.3

The bulleted list describing which stylesheet functions are included in 
the in-scope functions is somewhat confusing.

It would probably be easier to read if reworded to describe the intended 
effect - for example, "A stylesheet function definition suppresses any 
other stylesheet function defintions with the same name and arity that has 
lower import precedence.  It is added to the in-scope functions, unless 
the override attribute has the value "no" and there is a 
processor-provided function of the same name and arity, in which case that 
function will be included in the in-scope functions."

------------------------------------------------------------------

Section 10.3

In the second note, which describes the override attribute, it might not 
be clear that the attribute can override extension functions that might be 
provided by the user, not just functions that are provided by the 
implementation.

------------------------------------------------------------------

Section 11.1.2

The fifth sentence of the third note states, "One consequence of this is 
that these attributes should not be written as attribute value templates: 
although an XSLT processor will understand this notation, the XML parser 
will not."

Making a normative statement with the RFC term "should not" isn't 
appropriate in a note.  Either this needs to be stated normatively or use 
of the RFC "should not" should be avoided.

------------------------------------------------------------------

Section 11.1.2

The third paragraph of the third note states "None of these attributes 
will be generated in the result tree unless the stylesheet writes them to 
the result tree explicitly, in the same way as any other attribute."

It might not be clear to a user why he or she might have thought these 
attributes would have been generated automatically.  It might be helpful 
to describe the fallacious reasoning that this sentence is trying to 
correct.

------------------------------------------------------------------

Section 11.1.2

Error XT0805 is "It is a static error if an attribute on a literal result 
element is in the XSLT namespace, unless it is one of the attributes 
explicitly defined in this specification."

It would be helpful to point out to readers that they might need to use 
namespace aliasing or xsl:element/xsl:attribute if they really need to 
create such attributes in the XSLT namespace.

------------------------------------------------------------------

Section 11.1.3

It is odd that a feature like exclude-result-prefixes is defined here, 
rather than in its own section.  It might be better as a subsection in the 
Namespace fixup section.

------------------------------------------------------------------

Section 11.1.3

A sentence in the third bullet states "It is a static error if there is no 
namespace bound to the prefix on the element bearing the 
[xsl:]exclude-result-prefixes attribute."

The words "prefix on the element" make it sound like this is talking about 
the prefix of the element.  We suggest changing "on the element" to "by 
the element".

------------------------------------------------------------------

Section 11.1.3

The third bullet makes reference the "The default namespace (as declared 
by xmlns)".  It might be unclear to some readers whether default namespace 
refers to a namespace declared using xmlns="uri" or the default - no 
namespace.  It would be worthwhile defining the term in one place, and 
including termref's to it.

This same comment applies to the second paragraph after the first bulleted 
list in 11.1.4, and in the paragraph in Section 11.2 that defines error 
XT0830.

------------------------------------------------------------------

Section 11.1.3

The last paragraph of the example "Example: Excluding Namespaces from the 
Result Tree" begins "If the stylesheet is changed so that the literal 
result element has an attribute b:bar="3", then the element in the result 
tree will typically have a namespace declaration xmlns:b="b.uri", although 
the processor is free to choose a different namespace prefix if it 
wishes."

This should be reworded to indicate that some namespace declaration for 
the namespace must be available, rather than appealing to the typical 
behaviour.
------------------------------------------------------------------

Section 11.1.3

The material that appears in the last paragraph of the example "Example: 
Excluding Namespaces from the Result Tree" would be better placed in 
Section 5.6.3.
------------------------------------------------------------------

Section 11.1.4

The second note in this section states, "The processor still has a free 
choice of prefixes when generating element and attribute names in the 
result tree, but it will normally use the result-prefix since that prefix 
will already be declared in the result tree."

As this is implementation dependent, the note shouldn't refer to the 
"normal" behaviour.  If we want to make a normative statement, that can't 
be handled editorially.

------------------------------------------------------------------

Section 11.1.4

In the example box, the paragraph before the second stylesheet states in 
part, "however, the rules guarantee that there will be a namespace node 
that binds the prefix xsl to the URI http://www.w3.org/1999/XSL/Transform, 
which makes it safe to use the QName xsl:version in the content of the 
generated stylesheet."

It might not be clear to the reader which rules guarantee this.  That 
should be explicitly stated.

------------------------------------------------------------------

Section 11.1.4

It might be worthwhile to add a note that describes the merits of using 
xsl:attribute and xsl:element over using namespace aliasing.  For example, 
"xsl:element and xsl:attribute (see following sections) can also be 
practical solutions for the tasks commonly addressed via namespace 
aliasing. They have the advantages of being more direct and of permitting 
more explicit "hinting" about the desired prefix, at the expense of being 
more verbose. Users may wish to consider both approaches and select the 
one which best suits their needs."

------------------------------------------------------------------

Section 11.2

In the description of the recovery action for Error XT0820, it might be 
worthwhile to add that the xsl:element is replaced by its children, in 
case the effect of the recovery isn't clear to all readers.

------------------------------------------------------------------

Section 11.2

The recovery action for Error XT0820 is potentially surprising.  Some 
rationale for the recovery action might be appropriate.

------------------------------------------------------------------

Section 11.2

The recovery action for XT0830 is "to ignore the prefix part of the 
lexical QName, with the effect that the new element will be in the default 
namespace."  It is not clear whether the element is in the default 
namespace of the result or the default namespace of the stylesheet.

------------------------------------------------------------------

Section 11.3

Error XT0840 states "It is a static error if the select attribute of the 
xsl:attribute element is present unless the element has empty content." 
Section 5.6 deals with stripping of whitespace nodes in this situation, 
but it might make things more clear to say "unless the element has empty 
content after whitespace nodes have been stripped from the stylesheet."

------------------------------------------------------------------

Section 11.4.2

In the second paragraph, the phrase "either a single node, the newly 
constructed text node, or an empty sequence" might be taken to present 
three choices rather than two.  It should be rephrased as "either the 
newly constructed text node or an empty sequence."

------------------------------------------------------------------

Sections 11.4.2 and 11.4.3

These sections should state that the text created by xsl:text or 
xsl:value-of instructions might be merged with other adjacent text into a 
single text node.  This is only stated explicitly in the case of literal 
text nodes in 11.4.1.

------------------------------------------------------------------

Section 11.5

The note begins "This means that xsl:processing-instruction cannot be used 
to output an XML declaration."  It is not clear what the antecedent of 
"this" is.  Is it the rule in XT0890 or the fact that xsl:attribute cannot 
be used to construct the pseudo-attributes of a processing instruction?

------------------------------------------------------------------

Section 11.6

The sections on xsl:element and xsl:attribute state "The effective value 
[of the namespace attribute] should be a URI reference.  It is not an 
error if the string is not a syntactically legal URI reference."  A 
similar statement is required for xsl:namespace.

------------------------------------------------------------------

Section 11.6

The second paragraph of the first note in this section states that adding 
a namespace node to the result tree "does, however, constrain the choice 
of prefixes when namespace fixup is performed."

The word "does" should be changed to "might" - adding such a namespace 
node could also increase the number of choices available or have no effect 
on the choice.

------------------------------------------------------------------

Section 11.8.1

The second note states "but if namespaces are used in the content of the 
attribute. . . then it is the responsibility of the stylesheet author to 
ensure that suitable namespace declarations are added to the result tree."

This should really begin "but if namespace prefixes are used. . . ."  A 
namespace URI could be used inside of an attribute without requiring any 
namespace declaration.

------------------------------------------------------------------

Section 13.1.2

The second paragraph uses the term "converted" twice.  This should be 
"cast" to avoid any confusion about the meaning of the term.

------------------------------------------------------------------

Section 13.1.3

The paragraph after the second note indicates that the lang and case-order 
attributes "identify a suitable collation".  It should be noted that for 
any particular combination of lang and case-order, there may be more than 
one suitable collation.

------------------------------------------------------------------

Section 14.3

The last sentence in the second paragraph states that "A group is never 
empty."  The fifth paragraph begins with the sentence "If the population 
is empty, the number of groups will be zero."  These two related sentences 
should probably appear closer to one another.

------------------------------------------------------------------

Section 14.3

In the definition following XT1090, there is no term that is in bold type 
that is being defined.  Is this defining "grouping key"?

------------------------------------------------------------------

Section 14.3

The definition of "processing order" ends prematurely.  To complete the 
definition, the two sentences that follow should probably be included in 
the definition.  Otherwise, the definition should be reworded in order to 
stand alone.

------------------------------------------------------------------

Section 14.3

The title of the example box "Example: Sorting Groups in order of their 
Grouping Key" isn't accurate - it includes two examples, only one of which 
uses a grouping key.

------------------------------------------------------------------

Section 15.1

The paragraph following XT1150 begins "The xsl:analyze-string instruction 
starts at the beginning of the input string and attempts to find the first 
substring that matches the regular expression."

It doesn't seem appropriate to talk about this particular complexity of 
regular expression matching, out of all the other complexities discussed 
in the F&O. A reference to F&O would probably be more appropriate.

------------------------------------------------------------------

Section 15.2

In the definition of "current captured substrings", "parenthized" should 
be "parenthesized".

------------------------------------------------------------------

Section 15.2

The behaviour of the regex-group function is not sufficiently specified 
when it is used within xsl:non-matching-substring and outside of 
xsl:analyze-string - in particular, how is an argument value of zero 
handled in those situations?  It's not clear whether the matching string 
is considered to be considered to be a one of the current captured 
substrings, and so, part of the sequence, which would imply that 
regex-group(0) should return the zero-length string in those situations, 
or whether it is still "the same as the value of . (dot)" in those 
situations.

------------------------------------------------------------------

Section 16.1

The last rule in this section begins "The effect of these rules. . . ." 
These rules have more than one effect; this should be "One effect of these 
rules. . . ."

------------------------------------------------------------------

Section 16.2

The second paragraph indicates that "The URI must contain no fragment 
identifier. . . ."  Presumably this is because the text has no known 
structure.  It would be helpful to state the rationale behind the 
restriction.

------------------------------------------------------------------

Section 16.2

The paragraph following the first note, states "This encoding is used to 
translate the contents of the file into a string."  More accurately, it 
specifies a default unless file-specific information is available as 
described further on.

------------------------------------------------------------------

Section 16.3.2

The paragraph following the bulleted list describes the interpretation of 
the current function when it appears in match or use in xsl:key.  This 
really belongs in 16.3.1 - though the wording might be complicated by the 
fact that it can't refer to the node N that is being considered.

------------------------------------------------------------------

Section 16.5.2

The seventh paragraph reads as follows:

<<
The choice of the names and abbreviations used in any given language is 
implementation-defined. For example, one implementation might abbreviate 
July as Jul while another uses Jly. In German, one implementation might 
represent Saturday as Samstag while another uses Sonnabend. 
Implementations may provide mechanisms allowing users to control such 
choices.
>>

It should be explicitly stated that mechanisms that allow users to control 
such choices must not be in the form of additional, implementation-defined 
presentation modifiers.

------------------------------------------------------------------

Section 16.6.5

The sentences before and after the note in this section are related, and 
should probably be placed in a single paragraph, rather than being 
separated by a note.

------------------------------------------------------------------

Section 18.1

The first paragraph of this section needs to deal with the fact that the 
stylesheet function with highest import precedence might have specified 
the override attribute with a value of "no".  We understand that the 
reference would be to the extension function in this case.

------------------------------------------------------------------

Section 18.2.2

The first paragraph states, "The element-available function can be used 
with the xsl:choose and xsl:if instructions to explicitly control how a 
stylesheet behaves if a particular extension instruction is not 
available."

The element-available function applies to instructions in the XSLT 
namespace as well as to extension instructions.  The quoted sentence needs 
to be reworded.

Given that the function applies to more than just extension instructions, 
perhaps it should be moved to another section.

------------------------------------------------------------------

Section 19

In the second paragraph, suggest changing "may be created" to "can be 
created", to avoid confusion with the RFC term.

------------------------------------------------------------------

Section 19

The fourth paragraph begins "A result tree has a URI."  We would suggest 
this be changed to "A result tree is assigned a URI when it is created" or 
perhaps "A result tree is assigned an absolute URI when it is created."

------------------------------------------------------------------

Section 19

The first note begins "The URI of the result tree is not the same thing as 
the URI of its serialized representation. . . ."  The words "is not the 
same thing" are too strong; perhaps, it should be "is not necessarily the 
same thing"

------------------------------------------------------------------

Section 19

The last sentence of the first note begins "As long as it satisfies 
requests. . . ."  It is not clear what the antecedent of "it" is in this 
case.  Perhaps this should be "As long as the API satisfies requests. . . 
."

------------------------------------------------------------------

Section 19

All this description of how the URI that is associated with the result 
tree might be utilized by an API seems like it belongs with the 
description of the href attribute in section 19.1, as it specifies the 
URI.

------------------------------------------------------------------

Section 19

In the last note, the phrase "is unrelated" is too strong.  We would 
suggest "may differ from"

------------------------------------------------------------------

Section 19.1

The fourth paragraph following XT1460 states that "An implementation that 
does not support the serialization of result trees. . . must provide the 
application with some means of access to the (un-serialized) result tree, 
optionally using its URI to identify it."  However, the fourth paragraph 
of Section 19 states that "If the implementation provides an API to access 
result trees, then it must allow a final result tree to be identified by 
means of this URI."

The two statements differ as to whether an API must allow result trees to 
be identified by URI.

------------------------------------------------------------------

Section 19.2

A brief summary of the distinction between the validity and type 
attributes -- validity tests for any valid type, while type insists on 
validating against a specified type, if I'm reading this correctly -- 
would tremendously improve readability of this section, by setting context 
and giving the reader some guidance as to the differences in syntax and 
semantics.

------------------------------------------------------------------

Section 19.2.1

The first and second subbullets of the third bullet in the first bulleted 
list indicate that in certains circumstances the "transformation fails."

It would be helpful to provide a link to the error that is reported in 
each case, because the definitions of the definitions of those errors are 
so far-removed.

------------------------------------------------------------------

Section 19.2.1

The third subbullet of the the third bullet in the first bulleted list 
states that "The schema components used to validate an element or 
attribute may be located in any way permitted by [XML Schema]."  The word 
"permitted" is too strong; the section of XML Schema that is cited just 
describes a number of possibilities, without any restrictions.  Perhaps 
"described" would be a better word.

Where the remainder of the bullet indicates that the processor might have 
implicit knowledge of a namespace or may use a schemaLocation to locate 
schema components, it should be made clear that those are just two 
possibilities - not an exhaustive list.

------------------------------------------------------------------

Section 19.2.1

The third bullet of the second bulleted list states, "If the element or 
attribute is not considered valid, the transformation fails."  For 
clarity, the word "valid" should be changed to "a valid instance of the 
specified type".

------------------------------------------------------------------

Section 19.2.1

The first part of this section is specific to [xsl:]validation; the second 
part is specific to [xsl:]type.  It is not clear whether the paragraphs 
and bulleted lists following the last note in this section only apply if 
the [xsl:]type attribute is specified.

------------------------------------------------------------------

Section 20

The paragraph following XT1560 states that "The values of attributes are 
defaulted after the xsl:output elements have been merged. . . ."  However, 
if no method attribute is specified, not all of the default attribute 
values are necessarily known after merging.

------------------------------------------------------------------

Section 20

The third bullet from the end of the list states, "The 
undeclare-namespaces attribute is relevant only when producing output with 
method="xml" and version="1.1"."  This should probably be rephrased to 
allow for future versions of XML.

------------------------------------------------------------------

Section 21

The note in this section refers to the static typing feature.  Some 
normative statement about this feature should be provided - perhaps in 
section 2.8

------------------------------------------------------------------

Section 21.1

The second note indicates that a processor might ignore non-trivial type 
annotations from PSVI in order to construct a data model that conforms to 
the requirements of a basic XSLT processor.  It should also be noted that 
the data model cannot be constructed from Infoset as described in the Data 
Model document, as that can result in attributes with types that aren't 
permitted for a basic XSLT processor - such types would similarly have to 
suppressed in order to construct a data model that conforms to the 
requirements of a basic XSLT processor.

------------------------------------------------------------------

Appendix F

Whether a processor supports the XML 1.0 or 1.1 definitions of the Char 
and NCName productions should be an implementation-defined feature. 
Section 4.1 does not currently describe this as implementation-defined, 
but it ought to.

------------------------------------------------------------------

Appendix F

Items 20 and 23 in this list appear to be subsets of the 
implementation-defined feature in item 21.

------------------------------------------------------------------

Thanks,

Henry
[Speaking on behalf of reviewers from IBM.]
------------------------------------------------------------------
Henry Zongaro      Xalan development
IBM SWS Toronto Lab   T/L 969-6044;  Phone +1 905 413-6044
mailto:zongaro@ca.ibm.com

Received on Thursday, 19 February 2004 11:54:40 UTC