[DM] comments on WD-xpath-datamodel-20031112

(I sent all these comments about half an hour ago, but neglected to include
the [DM] in the subject header as instructed by the WD, so I'm resending in
case some automated process uses the [DM] to route the e-mail.)
 
Overall, it looks good, and it's clearly tough work that someone had to do.
I just have editorial comments. Some are bigger (suggested structural
changes) and some smaller (picky copy editing things).
 
General note: Search through the WD for the word "kind" and note that
sometimes the WD uses it in the traditional sense ("an instance of that kind
of item", "the data model supports some kinds of items") but usually uses it
in what appears to be a more technical sense ("node kind") which I suppose
is some alternative to saying "node type" or "node class." The XPath 1.0 Rec
used the term "node type", and if some decision was made that "type" is not
the right way to refer to a particular, uhh, breed of nodes, and that "kind"
should be used as a technical term instead, document this distinction and
the apparently specific meaning of "kind" as used in the document (or point
to documentation). The term "node type" does come up twice, so if this isn't
a mistake, the document should make distinction between node types and node
"kinds" clear.  
 
Numbers beginning each note are section numbers.
 
1 no need to hyphenate "programming languages"
 
2.1 ("Every node is one of...") The term "accessor" should be defined before
it's used. The second half of the first paragraph of 2.2, "Notation", is not
about notation, but about the role of accessors, and that text would be
better off in an "accessor" entry under "Terminology" before the Nodes entry
that uses the term. I would put Notation before Terminology anyway, since
Terminology uses some namespace prefixes that are explained in Notation.
 
"Definition... as a document." Congratulations! I believe this is the first
time in the history of XML that a W3C TR has defined the term "document".
 
2.2 "cannot be used, it only means" Comma splice. You can just replace the
comma with a semicolon. 
 
2.6.1 "For anonymous types... and the name of every other anonymous type."
Add a few words about why.
 
"The semantics of other operations... schema type is defined in [Formal
Semantics]." Add comma after "type" and change "is" to "are".
 
3.3.4 "When qualified exist as" add "names" after "qualified"
 
"contains a local-name" no need for hyphen
 
4 These four sentences don't deserve an entire section of their own; they
should be somewhere more structurally relevant to the parts of the spec that
describe infoset mapping. Perhaps the introduction to section 6 could say
"Information on each node kind in this section includes a description of how
to map each kind of node to the corresponding [and so on with the other text
from section 4]."
 
5 First sentence needs some fixing. "is defined nodes"? I can't figure out
what it's trying to say--for nodes? Over nodes? 
 
The second paragraph, which describes the whole point of having accessor
functions, should be the first paragraph in the section, not the second.
Some of this material could be in the definition of "accessor" that I
suggested be added to the Terminology section. The current first paragraph
is much too technical to open the section, although I do like the phrase
"constant empty sequence"--it's like an engineering version of Gertrude
Stein's "there's no there there".
 
5.2 There are seven node kinds, and node-kind() returns one of six values,
but can't return a value of "namespace". Mention why.
 
5.11 (and throughout): 'The prefix for the default namespace is "" .' I
understand that it's the empty string, but written like this, it looks like
someone forgot to fill in the value. How about 'The prefix for the default
namespace is the empty string ("").'  This comes up many other times in the
document; search for "". Also search for () starting at section 6.1.2
because of the same problem: don't say that an accessor function returns a
pair of parentheses if it doesn't return anything; say that it returns null,
or the empty string, or something more descriptive than (). As these are
now, they look more like engineering shorthand, and a revision will help the
document be understandable to a wider audience.
 
5.12 'if the node is "nilled", see 3.3.2 Mapping..." Comma splice.
 
5.14 "if the node is an XML IDREF or IDREFS" change to "if the node is an
XML attribute of type IDREF or IDREFS"
 
6.1.1(and 6.2.1, 6.3.1, etc.) "Document Nodes encapsulate XML documents." Is
this really a proper use of the word "encapsulate", or is there a more
appropriate word? 
 
6.1.3 "Construction from an Infoset" of an XQuery/XPath data model, right?
This could be made clearer to someone who isn't reading the WD from cover to
cover, and when it's not clear, defining base-uri entirely as "The value of
the [base-uri] property" (and many other similar definitions) doesn't tell
us very much. Something like "The value of the [base-uri] property of the
corresponding node of the Infoset version of the data model", if correct,
would get the point across better.
 
"and comment found in the [children] property" of the corresponding node in
the Infoset version of the data model, right? 
 
6.2.1 (and 6.3.1, 6.4.1, etc.) "Element Nodes must satisfy the following
constraints." Because this is introducing a list, it should end with a colon
and not a period. Compare the second sentence of 6.2.1 (and 6.3.1, and
6.4.1...)
 
6.4.1 "without parents, see below"  Comma splice.
 
"accessible by applications, by means of"  Delete comma.
 
"for the element (including the xml prefix"  No corresponding ")". 
 
6.7.3 "the content of the Text Node is the empty string." Saying this, and
not 'the content of the Text Node is "" ', is much clearer than all those
references to "" in the document. 
 
D Glossary
 
"is an implementation defined, unique type" "implementation defined" should
be hyphenated as with the rest of the document. (Also in definition of
"implementation defined" and "implementation dependent".) Search throughout
the document for both to make them consistent.
 
"instance of the data model ... Node... primitive simple type" I don't
understand why Node is initial capped where it is and why it's not initial
capped where it isn't. It looks inconsistent to me. It's the term being
defined here, but so are "instance of the data model" and "primitive simple
type". 
 
E "Graphic representation of the data model" If this diagram was 50% bigger
it would fit on the page just fine, and if you stretched the lengths of the
ovals in the diagrams even more, all the text within the diagram could be
almost 100% larger than it is now, making the diagram readable. Yes, I see
the links to larger versions, but the one shown in the spec, by not being
readable on my screen or in a printout while still taking up nearly a third
of a page, is the largest thumbnail I've ever seen.
 
F 'Document Nodes Returns "document" ', 'Element Nodes Returns "element" '
etc.  Change to 'Document Nodes Returns the string "document" ', 'Element
Nodes Returns the string "element" ', etc.
 
G "General notes <a>occur elsewhere</a>" Not much of a link anchor... how
about "General notes occur in the section <a>Construction from a PSVI</a>",
which is where it links to.
 

Again, great job.
 
Bob DuCharme