- From: Michael Dyck <jmdyck@netcom.ca>
- Date: Sat, 31 Jul 1999 13:08:10 -0700
- To: www-xml-linking-comments@w3.org
Comments on "XML Pointer Language (XPointer): W3C Working Draft 9 July 1999" Submitted to www-xml-linking-comments@w3.org by Michael Dyck (jmdyck@netcom.ca) on July 31, 1999. Most of my comments are piddly typographical/editorial details, but some are more serious, tending to deal with inconsistencies within the spec and between it and the XPath spec (especially in the sections on `range' and `string'). Rather than attempt to sort my comments by severity, I'll just give you them all in document order. I use "A -> B" as a shorthand for "Change A to B". XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX The "previous version" points to "TR/WD-xml-link-970731". Shouldn't that be "TR/1998/WD-xptr-19980303"? ------------ 1.1 Language Design Goals title: De-capitalize "Design Goals". (Most of the section titles capitalize only the first word.) ------------ 1.2 Relationship to Other Documents title: De-capitalize "Other Documents". 4th para: Put "XML 1.0 specification" in italics? 5th para: Put "Namespaces in XML" in italics. 7th para: Insert "The" before "XHTML". 9th para: Insert "The" before "draft". ------------ 2. XPointer Usage title: De-capitalize "Usage". ------------ 3. The XPointer model and language 1st bullet: "The semantic .. is" -> "The semantics ... are"? grammar: Change "XFragment" to "XFragmentIdentifier"? (It seems to me that the XML Fragment WG should be the ones to define a symbol named "XFragment".) "when scheme is xptr": Capitalize "scheme". Put "xptr" in quotes? ------------ 3.1 Character sets and escaping last para: "SchemSpecificExpr" -> "SchemeSpecificExpr" (insert "e") Insert comma after "i.e.". ------------ 3.2 Schemes 3rd para: "GenLocationPath" -> "GenlLocationPath" (insert "l") Editor's Note: Talking about "multiple LocationSpecs in an XPointer" is not consistent with the grammar given in Section 3. For that, you should change the grammar to: XFragment ::= BareName | Tumbler | ( LocationSpec )+ LocationSpec ::= Scheme '(' SchemeSpecificExpr ')' etc (You could then go back to the 2nd para and change "scheme, along with its arguments," to "LocationSpec" if you liked.) "attribtues" -> "attributes" "An XPointer like #...": The "#" sign is not part of the XPointer. "would work": Optimistic. Maybe "could work". "the second <par> in the <body>": The convention in the rest of the spec is to put "par" and "body" within a <CODE> element. The same goes for the two fragment identifiers and the URI also in the Editor's Note. ------------ 4. Summary of XPath 2nd para: Surely the definition of an XPointer belongs in a normative section. ------------ 4.1 XPath basics 1st box: For consistency with the XPath grammar: "axis-name" -> "AxisName" "node-test" -> "NodeTest" XPath also includes the square brackets within "Predicate" -- I don't know if you want to follow the XPath grammar that closely. Editor's Note: "descendents" -> "descendant" 3rd para: "axis-name" -> "AxisName" "The context node is initially the document root": In the XPath spec, I believe this is only stated for an absolute location path, and left undefined for a relative location path. "A context in XPointer is the same thing as a context in XPath": Well, that isn't really true. As section 5 points out, here() and origin() "in effect add information to the context of evaluation". "as described below..": delete a period. "The curly braces": What curly braces? 5th para: "the first following siblings": "siblings" -> "sibling" The second clause of this sentence might be clearer as: 'and then for each of those nodes, find the first following sibling of type "list".' 6th para: "portions (for ...)." -> "portions. (For ....)" 7th para: "SEC", "MYNOTE", "SEC": put within <CODE>. ------------ 4.3 XPath Relative Axes title: XPath does not use the term "relative axis". Delete "relative". De-capitalize "Relative Axes". 3rd para: "relative axes" -> "axes" (3 times) child & descendant: "pi" -> "processing instruction" descendant-or-self: "constraint" -> "constraints" "summay" -> "summary" parent: "nodes" -> "node" ancestor-or-self: "of the SEC itself" -> "or the SEC itself" ";" -> "," (twice) "and then taking the last one": Shouldn't you take the first one? That is, the innermost definition takes precedence. (If the outermost one takes precedence, what's the point of having inner definitions?) box: I don't think that this path does what you want. Note that the predicate belongs to the last step. That is, the last step is attribute::lang[position()=last()] which selects the last attribute named "lang" from the context node, which is presumably not what you want. Instead, I think you need to take everything before the predicate and put it within parentheses. (Note that this makes the whole expression a FilterExpr rather than a LocationPath.) self: "nodelist" -> "node list" "This is useful for applying multiple predicates to a single axis": But that's what every location step does: apply multiple predicates to a single axis. "particular" -> "particularly" "particular when predicates other than the first one must test a context node's position among all those context nodes that were selected by the prior predicates": But again, that's what always happens: a predicate tests a node with respect to the list of nodes that were selected by the previous predicates in the step. An example would help convey the intent. The `namespace' axis is missing. ------------ 4.4 XPath node-tests title: "node-tests" -> "node tests" or "NodeTests" 1st box: 'if the element type is "x:para"': This is not quite correct. I think it actually locates child elements whose type is of the form "y:para" where the NCName "y" expands (in the element's namespace context) to the same URI as "x" does (in the expression evaluation context). Still, for a non-normative summary, perhaps it's good enough. 3rd para: The node test "node()" is not mentioned. 4th para: "Nodetest" -> "NodeTest" The principal type of the "namespace" axis is namespace. ------------ 4.5 XPath Predicates title: De-capitalize "Predicates". 1st para: "relative axes": Delete "relative". (see above) "node-test" -> "node test" "variable binding" -> "variable reference" "and defines XPointer's additions": No, it doesn't. ------------ 4.5.1 Introduction to Predicates title: De-capitalize "Predicates". 1st para: "node-test" -> "node test" "special-case" -> "special case" point 1: "candidate nodes, such as ... all substrings of the content": As is pointed out elsewhere, these are not nodes. "the axes are applied" -> "the axis is applied" "and the results are unioned together": No, the union does not happen here. What gets unioned are the results of applying the whole step (points 1,2,3) to each node in the step's context node list. point 2: "node-test" -> "node test" (twice) 2nd para: "node-test" -> "node test" How can no node test be specified? Even an AbbreviatedBasis must have a NodeTest. 3rd para: "node-test" -> "node test" 'is a name or "*".': This omits NodeType '(' ')' | 'processing-instruction' '(' Literal ')' Shouldn't this whole para be in section 4.4? 1st bullet: XPath does not define functions named "text" or "processing- instruction" (although it does define NodeTests that use those identifiers). 2nd bullet, Comparisons: Add "!=". 7th bullet, Numeric...: "and quo (quotient)": delete. ------------ 4.5.2 Positional tests 1st, 5th, 7th paras: "predicate function" -> "boolean function"? (XPath doesn't use the term "predicate function", but it does use the term "boolean function".) 4th para: "locates the first <item> element": Don't need angle brackets. ------------ 4.5.3 Local structure tests 1st para: "attribute-values" -> "attribute names"? (It's possible to test for attribute value, but that hasn't been "described above".) 2nd para: "document contexts": add "or contents"? (An embedded location path can look outside or inside the context node.) ------------ 4.6 Examples of axis usage child:: "of whose" -> "whose" "and parentheses": Delete. (I wouldn't have guessed that "axis identifier" includes the double-colon, but that's how it's used elsewhere. Note that XPath's AxisName does not include the double-colon.) descendant:: "the descendents axis" -> "the <CODE>descendant</CODE> axis" (Note two spelling changes in addition to the font change.) "This is expected" -> "This axis is expected" "The XPathLocationPath": Insert space after "XPath", or delete "XPath". ancestor:: "typically used to obtain the parent node" Wouldn't one use the "parent" axis for that? ------------ 5. Xpointer extensions to XPath title: "Xpointer" -> "XPointer" 1st para: Append period. 1st bullet: Append period. 3rd bullet: Put "here()" and "origin()" within <CODE>? 4th bullet: "predicate function" -> "boolean function"? Put "unique()" within <CODE>? ------------ 5.1.1 Initialization of the context node 1st para: "document elements": Delete "s" Append period. ------------ 5.1.5 Initialization of the namespace declarations box: "Xpointer" -> "XPointer" (4 times). ------------ 5.2 XPointer axes 1st para: "relative axes": Delete "relative". ------------ 5.2.1 The range axis 1st para: "location source": This term is no longer defined. You'll need to replace the sentence with something like: "For each node X in the result of the first argument, the second argument is evaluated in a context whose context node is X, and whose context node list is a singleton list consisting of X." Also, you should really say that the evaluation context of the first argument is that of the Range. What happens if the second argument selects (perhaps among other things) a location that is before the location selected by the first argument? Is it an error, or does the Range simply not locate anything (for that particular result of the second argument)? 2nd para: "range::": Put within <CODE>. "It selects ...": Delete. (It's redundant.) 1st box: It would be helpful to point out that the `LocationPath' symbol comes from the XPath grammar. Not all of the example XPointers given so far match the GenlLocationPath production. For instance id("MYNOTE")/ancestor::SEC is not a GenlLocationPath, because it's not a LocationPath, because id("MYNOTE") is not a Basis. Instead, it's a PrimaryExpr and a FilterExpr, and id("MYNOTE")/ancestor::SEC is a PathExpr. You should probably change "LocationPath" to "PathExpr" (which includes LocationPath) in the GenlLocationPath production. And similarly in the Range production. You might want to change the name of the symbol "Range" to "RangeIdentifier" or "RangeLocator" or something like that, otherwise it becomes unclear, when speaking of "a range", whether one means the expression or its result. (And I think it should mean the latter.) 2nd box: This expression does not conform to the grammar, because 'range' is not the outermost construct. Presumably you mean range::id("a23")/child[1],following-sibling[2] which conforms if you make the change from `LocationPath' to `PathExpr' suggested above. ------------ 5.2.2 The string axis (If XPath *does* take on the functionality of this section, please convey the following comments to the XPath WG.) 1st para: "point positions": This term is not defined or used elsewhere in the spec. "location source" -> "value [in the XPath sense] of the context node" Either do that throughout this section, or say something like: "In this section, we will use the term `location source' to mean `the value of the context node'." 2nd box: Why are only *these* productions numbered? "StringTerm": Something should say how `StringTerm' fits into the XPath grammar. It appears to be another alternative for `Step', so perhaps it should be called `StringStep' instead. "SkipLit" + "Digit": It would be helpful to point out that these symbols come from the XML specification. Maybe you could give (non-normative) reminders of their definitions. "predicate" -> "Predicate" (if you're referring to the XPath symbol) "Digit": Note that the XML definition for `Digit' is a lot broader than just [0-9]. Thus, it is incongruous that the first digit in a Position or Length must be [1-9]. 2nd para: "Matches ... are non-overlapping" Is this a requirement on matches to the SkipLit, or is it a requirement on the results of the whole term? For instance, if the location source is "banana", then string::"an" locates two substrings: b[an]ana and ban[an]a They're non-overlapping, so there's no problem. But consider string::"an",1,3 This would seem to locate two substrings: b[ana]na and ban[ana] However, these overlap, so is the second one disallowed? Conversely, consider string::"ana",1,2 The SkipLit-match yields the substrings b[ana]na and ban[ana] (which overlap) but the Length reduces the yield to b[an]ana and ban[an]a which *don't* overlap, so do both count? To me, "matches" suggests "matches against the SkipLit": when you add the modifications with respect to Position and Length, it doesn't feel like "matching" any more. On the other hand, the blurb for "predicate" suggests that the whole SkipLit, Position,Length construct must yield non-overlapping strings. So it's unclear. SkipLit: "null SkipLit string": I don't think XML defines this sense of "null". You could maybe say "a SkipLit with no characters between the delimiting quotes". 'contains the character string "Thomas"': For the example to work, it is not enough that the element contains (somewhere) "Thomas" -- it must *begin* with "Thomas". box: This example does not conform to the given grammar, because the Position (3) precedes the SkipLit (""). (In fact, this is true of all the examples in this section!) This one should presumably be id("x37")/string::"",3 Position: "specified string" -> "candidate string" (for consistency) "reserved position value": Delete "reserved"? (It's unclear what it adds to the sentence.) Length: "A length of zero": How can this happen, given that Length must begin with a non-zero? predicate: This should have a capital "P" and be within a <CODE> element. "Selects among the resulting list": XPath says: "A predicate filters a list of nodes to produce a new list of nodes." The PredicateExpr is evaluated with respect to a context, including a context node and a context node list. Therefore, it's not immediately clear how a Predicate (in general) can be used to filter a list of substrings. Does *anything* other than a position test have an obvious re-interpretation? "non-overlapping": delete? See discussion above. "occurrences of the specified string" -> "located strings" ("the specified string" is unclear. One easy interpretation would be "the SkipLit", but this would be wrong in general. The modifications of Position and Length yield strings that aren't really "occurrences" of anything.) 3rd para ("When the context node"): This para should be moved earlier in this section, because the content that the StringTerm operates on is an important part of its semantics. "PI" -> "processing instruction" (twice) 5th box: This example doesn't conform to the grammar. You could change it to string::"Thomas Pynchon",8,0,[position()=3] but only if you change the grammar to allow a Length of zero. 6th box: Doesn't conform to the grammar. Change to: string::'!',1,2,[position()=5] 6th para ("For purposes..."): Move this para earlier as well. "in the element(s) in" -> "in" (Otherwise, you exclude the character data in the context node itself.) "current location source" -> "context node" 7th box: Doesn't conform. Change to: string::'affect',1,6,[position()=1] or some prefix of that, depending on what you want. 9th box: Doesn't conform. Change to: string::"hello world" ... nth para ("No case-folding ..."): Presumably, there should be a space in "ThomasPynchon", otherwise there *would* be a match. Editor's Note: "add" -> "adding" ------------ 5.3.1 / (root) This section is covered by XPath, so it should be deleted or moved to Section 4, Summary of XPath. 1st para: "which is over it" -> "which contains it" "RelPath" -> "RelativeLocationPath" ------------ 5.3.2 id This too is covered by XPath. 1st para: "containing resource" -> "document containing the context node" 4th para: "along" -> "alone" ------------- 5.3.3 here 1st para: Maybe here() should locate the text or attribute node that contains the XPointer, rather than the element that contains/bears that node. "reusable relative links when the links reside directly at one of their endpoints": This isn't really meaningful to someone who hasn't read the XLink spec. ------------ 5.3.4 origin 1st para: The second occurrence of "origin()" should be within <CODE>. ------------ 5.4 XPointer predicate functions title: "predicate" -> "boolean" 1st para: "predicate" -> "boolean" "Unique()": Use lower-case "u". Put within <CODE>. "current context node list": Delete "current". 3rd para: "unique()": Put within <CODE>. "an XPath expression that counts the number of items in the context node list and compares it to 1": That is, "count()=1". (So "unique()", as a shorthand, is only 1 character shorter!) ------------ 5.5 Locations That Are Not Simply Nodes title: De-capitalize "That Are Not Simply Nodes". 1st para: "let the user select": Select what? We need a referent for "it" later in the sentence. "it; perhaps" -> "it (perhaps" 3rd para: "construct. axes": It appears that something is missing here. ------------ 5.5.1 String axis semantics Maybe this discussion should be moved to section 5.2.2, "The string axis". 2nd para: "at the c below": Put "c" in quotes. 3rd para: "Even if characters are considered individual nodes, the EMPH node itself remains an issue: it is only *partly* included in the located data portion." Why does that make it an issue? The (non-spanning!) XPointer child::CHAPTER/child::SECTION locates a set of nodes that is only *partly* included by any particular CHAPTER element. So what? Do the CHAPTER nodes "remain an issue"? ------------ 5.5.2 Range axis semantics Maybe this discussion should be moved to section 5.2.1, "The range axis". 1st para: "chapter; and the" -> "chapter. The" 2nd para: "Like string, range": Put "string" and "range" within <CODE>. "Also like string": Ditto. ------------ 5.5.3 Multiple spanning locations This also belongs in section 5.2.1, The range axis. 2nd para: "[The Range is] simply evaluated for each member of the context node list independently" But a Range must be the outermost construct, and as such its context node list is defined to be a singleton list. 3rd para: "span" -> "range" "element to" -> "elements to" 4th para: "Multiple locations ..." This sentence would be clearer as: "It is prohibited for the second argument of the range axis to produce multiple locations from a single result of the first argument, on grounds of simplicity." If an XPointer violates this prohibition, what kind of error does it have? ------------ 5.6 Link Persistence title: De-capitalize "Persistence". Is this section normative? It seems like it should be informative. 3rd para: "where relative axes are used" -> "in node tests" ------------ 6. Conformance 2nd para: "syntactic requirements": append "for an XFragment"? ------------ A. Glossary 1st para: "This appendix is normative." All of the terms in this glossary are (or should be) defined by other specs. Shouldn't *those* be normative and *these* be informative? axis: "reserved name": It's not clear what this means. "Other axes define a sequence that does not depend on context, such as the element with a particular ID, or the abolute root of the document." Delete. (This is talking about `id()' and `/', which are not axes.) Context node list: De-capitalize "Context" "A context node list can be the final result of evaluating an XPointer": XPath doesn't support this usage of the term. element tree: This only use of this term in the spec is in the subsequent definition of "root", which could live without it. Moreover, it is incongruous to call it an "element tree" when it includes many things that are not elements. linking element: This term is not used in the spec. locator: "primarily": Delete? (Is this spec secondarily concerned with anything?) predicate: "given a sub-resource location" -> "given an evaluation context" "in documents" -> "in the context" root: "an abstract node" -> "a node" (All nodes are abstract.) "The root() function (see below) gives direct access to this node.": Delete. ------------ B. References Other specs put the name of the reference in italics. That would be helpful. XLINK: The editors have changed. IETF RFC 1808: "/rfc 1808.txt": Delete space. TEI: Add "(See http://www.uic.edu/orgs/tei/p3.)". DOM: The `range' construct is defined in DOM Level 2. Also, the convention seems to be to put the author/org first. So change to: World Wide Web Consortium. Document Object Model (DOM) Level 2 Specification. W3C Working Draft, 1999. (See http://www.w3.org/TR/WD-DOM-Level-2.) CHUM: "Và(c)ronis" -> "Véronis" (I think) No reference to the XML spec? XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Received on Saturday, 31 July 1999 16:11:56 UTC