proposed-docs-changes.patch

From 464e8f16386c0fbfb8b5c6fdee66402c95c6ae9f Mon Sep 17 00:00:00 2001
From: Craig Ringer <craig@2ndquadrant.com>
Date: Mon, 12 Sep 2016 12:26:14 +0800
Subject: [PATCH] Proposed docs changes

---
 doc/src/sgml/func.sgml | 103 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 82 insertions(+), 21 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ca861d2..3ba492e 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10099,7 +10099,7 @@ SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
     </para>
    </sect3>
 
-   <sect3>
+   <sect3 id="functions-xmltable" xreflabel="XMLTABLE">
     <title><literal>xmltable</literal></title>
 
    <indexterm>
@@ -10111,7 +10111,9 @@ SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
 </synopsis>
 
     <para>
-      The <function>xmltable</function> produces table based on passed XML value.
+      The <function>xmltable</function> produces a table based on the
+      passed XML value, an xpath filter to extract rows, and an
+      optional set of column definitions.
     </para>
 
     <para>
@@ -10140,11 +10142,11 @@ SELECT  xmltable.*
     </para>
 
    <para>
-     The optional <literal>xmlnamespaces</literal> clause allow to specify a list
-     of namespaces specified by <replaceable>namespace URI</replaceable> and
-     <replaceable>namespace name</replaceable> (alias>. The default namespace is
-     specified by <replaceable>namespace URI</replaceable> after keyword
-     <literal>DEFAULT</literal>.
+     The optional <literal>xmlnamespaces</> clause is a comma-separated list of
+     namespaces of the form <replaceable>namespace-URI</> <literal>AS</>
+     <replaceable>namespace-name</>. It specifies the XML namespaces used in
+     the document and their aliases. The default namespace is specified with
+     <literal>DEFAULT</> <replaceable>namespace-URI</>.
 
 <screen><![CDATA[
 SELECT *
@@ -10159,25 +10161,84 @@ SELECT *
    </para>
 
     <para>
+     The required <replaceable>rowexpr</> argument is an xpath
+     expression that is evaluated against the supplied XML document to
+     obtain an ordered sequence of XML nodes. This sequence is what
+     <function>xmltable</> transforms into output rows.
+    </para>
+
+    <note>
+     <para>
+      The SQL/XML standard specifies the the
+      <function>xmltable</function> construct should take an XQuery
+      expression as the first argument, but PostgreSQL currently only
+      supports XPath, which is a subset of XQuery.
+     </para>
+    </note>
+
+    <para>
+     The <literal>PASSING</> <replaceable>xml</> clause provides the
+     XML document to operate on.
      The <literal>BY REF</literal> clauses have no effect in
      PostgreSQL, but are allowed for SQL conformance and compatibility
-     with other implementations.  Per SQL standard, the
-     first <literal>BY REF</literal> is required, the second is
-     optional.  Also note that the SQL standard specifies
-     the <function>xmlexists</function> construct to take an XQuery
-     expression as first argument, but PostgreSQL currently only
-     supports XPath, which is a subset of XQuery.
+     with other implementations. Per the SQL/XML standard, the first
+     <literal>BY REF</literal> is required, the second is optional.
+     Passing <literal>BY VALUE</> is not supported. Multiple
+     comma-separated terms in the PASSING clause are not supported.
+     <literal>AS</> aliases are not supported.
     </para>
 
    <para>
-     The optional <literal>COLUMNS</literal> clause allow to specify a list
-     of colums of generated table. The column with special mark
-     <literal>FOR ORDINALITY</literal> ensures row numbers in this column.
-     When <literal>PATH</literal> is not defined, then the name of column is
-     used as implicit path. Only one column should be marked <literal>FOR ORDINALITY</literal>.
-     When path expression is empty, then possible <literal>DEFAULT</literal> value
-     is used.
-<screen><![CDATA[
+     The optional <literal>COLUMNS</literal> clause specifies the list
+     of colums in the generated table. If the whole
+     <literal>COLUMNS</> list is omitted, then the result set is a
+     single column where each row is a field of <literal>xml</> type
+     containing the data matched by the <replaceable>rowexpr</>.
+     Otherwise each entry describes a single column. See the syntax
+     summary above for the format. The column name and type are
+     required; the path and not-null specifier are optional. 
+    </para>
+
+    <note>
+     <para>
+      Column names and types are identifiers so unlike normal
+      function arguments they may not be specified as bind parameters,
+      column references, or expressions. The path and default are
+      ordinary values.
+     </para>
+    </note>
+
+    <para>
+     The <literal>PATH</> for a column is an xpath expression that is
+     evaluated for each row, relative to the result of the
+     <replaceable>rowexpr</>, to find the value of the column. If no
+     <literal>PATH</> is given then the column name is used as an
+     implicit path.
+    </para>
+
+    <para>
+     If the path expression does not match for a given row but a
+     <literal>DEFAULT</> xpath expression is specified, the resulting
+     default value is used. If no <literal>DEFAULT</> is given the
+     field will be <literal>NULL</>.  Note that unlike
+     <literal>PATH</>, the <literal>DEFAULT</> for a column is
+     evaluated only once, relative to the root of the
+     <replaceable>xml</> argument, when processing begins.
+    </para>
+
+    <para>
+     Columns may be marked <literal>NOT NULL</>. If the xpath expression
+     for a <literal>NOT NULL</> column does not match anything and there
+     is no <literal>DEFAULT</> or the <literal>DEFAULT</> also evaluated
+     to null then the function terminates with an ERROR.
+    </para>
+     
+    <para>
+     A column marked with the
+     <literal>FOR ORDINALITY</literal> keyword will be populated with
+     row numbers that match the order in which the the output rows appeared
+     in the original input XML document.  Only one column should be
+     marked <literal>FOR ORDINALITY</literal>. <screen><![CDATA[
 SELECT *
   FROM XMLTABLE(XMLNAMESPACES(DEFAULT 'http://x.y')
                 '/rows/row' PASSING '<rows xmlns="http://x.y"><row><a>10</a></row></rows>');
-- 
2.5.5