Subject: Re: PostgreSQL vs SQL/XML Standards
To: Pavel Stehule <pavel.stehule@gmail.com>,
 Markus Winand <markus.winand@winand.at>
References: 
 <CAFj8pRDFQJMoKf-X+3p1ASwU02nnXfAXrg83Z3fHUBd-Gwuuxw@mail.gmail.com>
 <20181025194720.ylmw64xqlnjr5wja@alvherre.pgsql>
 <CAFj8pRB10LxRcYYKWb5omjtAQq_bEVWiQ9B6V=kRZYMvM0B-_w@mail.gmail.com>
 <CAFj8pRBr5tY5b=8gKptwOyuPf8f3fvyHbXNbSCU03guNh-johw@mail.gmail.com>
 <CAFj8pRA6J25CtAZ2TuRvxK3gat7-bBUYh0rfE2yM7Hj9GD14Dg@mail.gmail.com>
 <FB592C2F-E2F3-42FD-A342-EE41BECD3771@winand.at>
 <CAFj8pRC_bi4uzE3Z-XXuGnLFPP-7cZ-zr2JhGauWm3E8K2MqEg@mail.gmail.com>
 <45C74339-3531-46BD-A595-37183C6730A1@winand.at>
 <CAFj8pRB4NHismecE-SnezKz9OektP2H8t_684TbqQ4Ax3swZwQ@mail.gmail.com>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>, Tom Lane <tgl@sss.pgh.pa.us>,
 PostgreSQL Hackers <pgsql-hackers@postgresql.org>
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <5C283168.8060001@anastigmatix.net>
Date: Sat, 29 Dec 2018 21:46:00 -0500
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
MIME-Version: 1.0
In-Reply-To: 
 <CAFj8pRB4NHismecE-SnezKz9OektP2H8t_684TbqQ4Ax3swZwQ@mail.gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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