- From: Henry Zongaro <zongaro@ca.ibm.com>
- Date: Thu, 19 Feb 2004 11:54:36 -0500
- To: public-qt-comments@w3.org
[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