More comments on XPointer CR

Further Comments on "XML Pointer Language (XPointer) Version 1.0"
W3C Candidate Recommendation 7 June 2000

[It's still September 7 in *some* time zone!
Yeah, that's it, I'm sending this from Hawaii. Aloha! :)]

5.3.1 Definition of Point Location

"A location of type point":
    Maybe put "point" within <CODE>.

"the location preceding any individual character ... in an XML document":
    Might as well say "preceding or following", as with nodes.
    
    Actually, a point can't represent *any* such location, in particular
    it can't represent locations between markup characters.

para containing defn of character-point:
"index n indicates an point":
    Change "an" to "the".

"Point locations do not have an expanded-name."
    Change subject and verb to singular, to agree with object:
    "A point location does not have an expanded-name."

"The axes of a point location..."
    It would be better to refer explicitly to XPath axes.
    E.g., instead of saying
        "A point location has no children"
    say
        "The <CODE>child</CODE> axis is empty."

    Similarly for the `preceding-sibling' and `following-sibling' axes.

    We can deduce that the `descendant' axis is empty, but it wouldn't
    hurt to say so.

    Presumably, the `attribute', and `namespace' axes are also empty,
    but again, it wouldn't hurt to say so.

    What about the `parent' axis? Does a point location have a parent?

    What about the `preceding' and `following' axes?

    What about the `self' axis? One guesses that it would contain just
    the point itself.

    The `ancestor', `descendant-or-self', and `ancestor-or-self' axes
    could be deduced from other axes, but it would be nice to mention
    them, just to show that you haven't forgotten any.

5.3.2 Definition of Range Location

"A location of type range":
    Maybe put "range" within <CODE>.

    Can the start and end points be in different entities?

"Range locations do not have an expanded-name."
    Change to "A range location does not have an expanded-name."

"The axes of a range location are the axes of its start point."
    So if the `self' axis of a point contains just the point,
    then the `self' axis of a range contains just its start point,
    which is probably not what people would expect.

    Some of the other axes (e.g., `parent' and `following') are also a bit
    odd under this definition. Not that that's wrong, but it might be
    worth a note saying, "yes this is intentional".

5.3.3 Covering Ranges for All Location Types

Definition:
    The sentence within the Definition brackets does not actually define
    "covering range", since it relies on an intuitive understanding of
    "wholly emcompasses". It's just a gloss for the real definition, which
    is given by the bulleted points.

last bullet:
    Change "starting point" to "start point".

"This definition ensures that for a range location, [various axes] do not
intersect and that they together contain all locations in the document
(other than attribute, namespace, and range locations)."
    I think this paragraph is misplaced. I don't see how the definition of
    "covering range" has anything to do with establishing how a range's
    axes partition the document. In fact, the only use I see of the term
    "covering range" is in the definition of the "range" function. Maybe
    the content of this section should be moved there.

    And I think you'll have to add point locations to the "other than"
    list. As far as I can tell, no axis contains a point location except
    for the self axis of a point (or range, see above).

5.3.5 Document Order

"The relative order...":
    Change "starting" to "start".

"One range node is before another range node..."
    Delete both "node"s.

Last two bullets:
    Change all "starting" to "start".
    Change all "ending" to "end".

5.4.1 range-to Function

prototype:
    Change "expression" to "location". (Every argument is an expression.
    The prototype must give the expected type of the value of the
    argument.)

"the start of the context location", "the end of the location":
    You haven't defined what the "start" and "end" of a location are.
    If you mean the definitions that appear in 5.4.3 under "start-point"
    and "end-point", it might be good to extract those definitions (not
    the whole function descriptions, just the embedded definitions) and
    put them in a new section somewhere in 5.3.

"found by evaluating the expression argument with respect to that context
location":
    This is redundant, given XPath's semantics of FunctionCall. You could
    maybe relegate it to a note.

"For example..."
    Insert "the start of" and "the end of" before the two "the elements",
    respectively.

"As another example..."
    Delete space between open paren and "such".

"XPath does not permit functions immediately following the slash":
    I agree with Michael Kay: you can't just toss this off in a note.

5.4.2 string-range() Function

prototype:
    Delete space between "location-set" and comma.

Definition:
    There's a lot of non-definition stuff in this definition. Presumably
    the real definition (which should be disentangled from the other
    stuff) is just:
        "A <B>string range</B> is a substring of a string."
    or perhaps
        "... is a range whose start and end points are character points."
    I prefer the second.

the resulting range:
    What happens if third and/or fourth arguments specify positions that
    lie outside the string-value of the location?

3rd para:
"the string in the second argument":
    Change to "the <I>string</I> argument".

"a value in the third or fourth argument":
    Change to "the third or fourth argument".

"indicates a string that is beyond":
    You mean wholly beyond, or even just partly beyond?

"the expression fails":
    Change to "no range location is added to the resulting location-set
    for that location, or that match, respectively."  I suggest separating
    the two cases. (And actually, the first case is covered by the "for
    each match" phrase in the first para, but I'd keep it in.)

4th para ("The points of the range-locations...")
    This is redundant if you use my second definition of "string range"
    above.

para after 1st box ("As another example..."):
    Change "third" to "17th".

para after 3rd box ("String-values are `views'..."):
"a string-range match is on the range":
    Change "is on the range" to "is a range".
"not necessarily on a contiguous string":
    Delete "on".

5.4.3 Additional Range-Related Functions

range-inside:
    The definition seems to ignore the possibility that x might be a point
    location: a point can't be a container.

    Change "location children" to just "children", I think.

start-point & end-point:
prototype:
    Change both argument and return types to "location-set".

"of type point":
    Put "point" in <CODE>?

"the function must signal a syntax error":
    Change to "no point is added to the resulting location-set".

end-point:
    Put "x" in italics.
    Change "location children" to "children".

5.4.4 here Function

"syntax error":
    I think "resource error" would make more sense.

5.4.6 unique Predicate Function

6th para ("Note that different XPointers...") to end of section:
    I think this belongs somewhere in 5.3.

"following-sibling(item)":
    I don't think XPath lets you use an AxisName as a FunctionName.
    Change to "following-sibling::item", I think.

-Michael Dyck

Received on Friday, 8 September 2000 03:43:26 UTC