On 11/12/18 04:58, Pavel Stehule wrote:
> It is assigned to January commitfest.
When I build this patch against master (4203842), it builds, but breaks
make check. The diffs seem only incidental (loss of some error context
output), but there are no make check errors building 4203842 unmodified,
so the patch has introduced them. Example:
*** ../postgresql/src/test/regress/expected/xml.out Sat Dec 29 19:58:41 2018
--- src/test/regress/results/xml.out Sat Dec 29 19:59:11 2018
***************
*** 9,16 ****
LINE 1: INSERT INTO xmltest VALUES (3, '<wrong');
^
DETAIL: line 1: Couldn't find end of Start Tag wrong line 1
- <wrong
- ^
=== ABOUT THE DOCUMENTATION ===
While this patch fixes bugs in the embedding of XPath 1.0 into PostgreSQL,
and that is good, I still think there is an elephant in the room, namely
that XPath 1.0 isn't the right language to embed. Clearly, that can't be
fixed as long as we rely on libxml, but I think our documentation could
(should) do a better job of warning users of the surprises that result.
My ideas for improving the documentation are not yet so finished as to
offer a patch, but here are some thoughts:
Of the 13 mentions in func.sgml of XPath (not counting its appearances
in function and parameter names), only one specifically says XPath 1.0,
and it is buried down at functions-xml-processing, not somewhere common
to all of them, like the introduction to functions-xml.
Really, all of our functions that refer to "XPath" mean XPath 1.0,
and because that version was essentially thrown away to produce the 2.0
and later versions, and that happened a dozen years ago, the documentation
needs to make that clear. Users who have learned XQuery, or XPath in the
last dozen years, need to know this is something very different, to avoid
walking into the traps.
I think:
1) Every reference to "XPath" or an "XPath expression" (that is the first
in the description of a function or parameter) should be spelled out as
"XPath 1.0".
2) There should be a section in one central place (clearly applying to
all of the XML functions), perhaps in the functions-xml introduction,
or a <footnote> to a paragraph there, or in an appendix (new section
under SQL Conformance?) that summarizes the gulf between XPath 1.0
and the later, XQuery-compatible versions. There should be cross-
reference links to this section from the "XPath 1.0" mentions in
individual function descriptions. The section could be a condensation
of [1] (and perhaps contain a link to [1], if links out to the wiki
are allowed), and link to the W3C compatibility notes at [2] and [3].
3) Currently, the description of XMLEXISTS notes that "the SQL standard
specifies ... the construct to take an XQuery expression ... but
PostgreSQL currently only supports XPath, which is a subset of XQuery".
The description of XMLTABLE does not have such a note, and needs one.
In both cases, the note should probably be nearer the top of the
description (for XMLEXISTS, it is currently at the bottom, after the
examples).
4) That note currently says "only supports XPath, which is a subset
of XQuery". That would be a fair claim if we meant XPath 2.0
or later, but not XPath 1.0 (which was not a subset of any version
of XQuery, and has fundamental incompatibilities with it). The note,
for both XMLEXISTS and XMLTABLE, should simply say "only supports
XPath 1.0", with a link to the section summarizing the incompatibilities.
Those are my thoughts on how a patch to the documentation could be
organized. Do they seem reasonable?
-Chap
[1]
https://wiki.postgresql.org/wiki/PostgreSQL_vs_SQL/XML_Standards#Related_to_version_of_XPath
[2] https://www.w3.org/TR/xpath20/#id-backwards-compatibility
[3]
https://www.w3.org/TR/2010/REC-xpath-functions-20101214/#xpath1-compatibility
