Would you believe there are one hundred and forty-eight definitions embedded in XPath 3.1?
What strikes me as odd is that the same one hundred and forty-eight definitions appear in a non-normative glossary, sans what looks like the note material that follows some definitions in the normative prose.
The first issue is why have definitions in both normative and non-normative prose? Particularly when the versions in non-normative prose lack the note type material found in the main text.
Speaking of normative, did you now that normatively, document order is defined as:
Informally, document order is the order in which nodes appear in the XML serialization of a document.
So we have formal definitions that are giving us informal definitions.
That may sound like being picky but haven’t we seen definitions of “document order” before?
Grepping the current XML specifications from the W3C, I found 147 mentions of “document order” outside of the current drafts.
I really don’t think we have gotten this far with XML without a definition of “document order.”
Or “node,” “implementation defined,” “implementation dependent,” “type,” “digit,” “literal,” “map,” “item,” “axis step,” in those words or ones very close to them.
- My first puzzle is why redefine terms that already exist in XML?
- My second puzzle is the one I mentioned above, why repeat shorter versions of the definitions in an explicitly non-normative appendix to the text?
For a concrete example of the second puzzle:
For example:
[Definition: The built-in functions
supported by XPath 3.1 are defined in [XQuery and XPath Functions and Operators
3.1].] Additional functions may be provided
in the static
context. XPath per se does not provide a way to declare named
functions, but a host language may provide such a
mechanism.
First, you are never told what section of XQuery and XPath Functions and Operators 3.1 has this definition so we are back to the 5,000 x N problem.
Second, what part of:
XPath per se does not provide a way to declare named functions, but a host language may provide such a mechanism.
Does not look like a note to you?
Does it announce some normative requirement for XPath?
Proofing is made more difficult because of the overlap of these definitions, verbatim, in XQuery 3.1. Whether it is a complete overlap or not I can’t say because I haven’t extracted all the definitions from XQuery 3.1. The XQuery draft reports one hundred and sixty-five (165) definitions, so it introduces additional definitions. Just spot checking, the overlap looks substantial. Add to that the same repetition of terms as shorter entries in the glossary.
There is the accomplice XQuery and XPath Data Model 3.1, which is alleged to be the source of many definitions but not well known enough to specify particular sections. In truth, many of the things it defines have no identifiers so precise reference (read hyperlinking to a particular entry) may not even be possible.
I make that to be at least six sets of definitions, mostly repeated because one draft won’t or can’t refer to prior XML definitions of the same terms or the lack of anchors in these drafts, prevents cross-referencing by section number for the convenience of the reader.
I can ease your burden to some extent, I have created an HTML file with all the definitions in XPath 3.1, the full definitions, for your use in proofing these drafts.
I make no warranty about the quality of the text as I am a solo shop so have no one to proof copy other than myself. If you spot errors, please give a shout.
I will see what I can do about extracting other material for your review.
What we actually need is a concordance of all these materials, sans the digrams and syntax productions. KWIC concordances don’t do so well with syntax productions. Or tables. Still, it might be worth the effort.