From 8c1de5fb0010ae712568f1706b737270c3609bd8 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Thu, 21 Dec 2006 16:05:16 +0000
Subject: Initial SQL/XML support: xml data type and initial set of functions.

---
 doc/src/sgml/datatype.sgml     |  84 ++++++++-----------------------
 doc/src/sgml/func.sgml         | 111 ++++++++++++++++++++++++++++++++++++++++-
 doc/src/sgml/installation.sgml |  11 +++-
 3 files changed, 141 insertions(+), 65 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 4bc950acf0..f68714bd20 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.181 2006/11/23 04:27:33 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.182 2006/12/21 16:05:12 petere Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -233,6 +233,12 @@
        <entry><type>timestamptz</type></entry>
        <entry>date and time, including time zone</entry>
       </row>
+
+      <row>
+       <entry><type>xml</type></entry>
+       <entry></entry>
+       <entry>XML data</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
@@ -248,7 +254,8 @@
     precision</type>, <type>integer</type>, <type>interval</type>,
     <type>numeric</type>, <type>decimal</type>, <type>real</type>,
     <type>smallint</type>, <type>time</type> (with or without time zone),
-    <type>timestamp</type> (with or without time zone).
+    <type>timestamp</type> (with or without time zone),
+    <type>xml</type>.
    </para>
   </note>
 
@@ -3358,12 +3365,21 @@ SELECT * FROM pg_attribute
   </sect1>
 
   <sect1 id="datatype-xml">
-   <title><acronym>XML</> Document Support</title>
+   <title><acronym>XML</> Type</title>
 
-   <indexterm zone="datatype">
-    <primary>xml</primary>
+   <indexterm zone="datatype-xml">
+    <primary>XML</primary>
    </indexterm>
 
+   <para>
+    The data type <type>xml</type> can be used to store XML data.  Its
+    advantage over storing XML data in, say, a text field is that it
+    checks the input values for well-formedness, and there are support
+    functions to perform type-safe operations on it; see <xref
+    linkend="functions-xml">.  Currently, there is no support for
+    validation against a specific <acronym>XML</> schema.
+   </para>
+
    <para>
     <acronym>XML</> (Extensible Markup Language) support is not one
     capability, but a variety of features supported by a database
@@ -3378,22 +3394,6 @@ SELECT * FROM pg_attribute
    </para>
 
    <variablelist>
-
-   <varlistentry>
-    <term>Storage</term>
-    <listitem>
-
-     <para>
-      PostgreSQL does not have a specialized <acronym>XML</> data type.
-      Users should store <acronym>XML</> documents in ordinary
-      <type>TEXT</> fields. If you need the document split apart into
-      its component parts so each element is stored separately, you must
-      use a middle-ware solution to do that, but once done, the data
-      becomes relational and has to be processed accordingly.
-     </para>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term>Import/Export</term>
     <listitem>
@@ -3408,21 +3408,6 @@ SELECT * FROM pg_attribute
     </listitem>
    </varlistentry>
 
-   <varlistentry>
-    <term>Validation</term>
-    <listitem>
-
-     <para>
-      <filename>/contrib/xml2</> has a function called
-      <function>xml_is_well_formed()</> that can be used in a <literal>CHECK</>
-      constraint to enforce that a field contains well-formed <acronym>XML</>.
-      It does not support validation against a specific <acronym>XML</>
-      schema. A server-side language with <acronym>XML</> capabilities
-      could be used to do schema-specific <acronym>XML</> checks.
-     </para>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term>Indexing</term>
     <listitem>
@@ -3438,20 +3423,6 @@ SELECT * FROM pg_attribute
     </listitem>
    </varlistentry>
 
-   <varlistentry>
-    <term>Modification</term>
-    <listitem>
-
-     <para>
-      If an <command>UPDATE</> does not modify an <acronym>XML</> field,
-      the <acronym>XML</> data is shared between the old and new rows.
-      However, if the <command>UPDATE</> modifies an <acronym>XML</>
-      field, a full modified copy of the <acronym>XML</> field must be
-      created internally.
-     </para>
-    </listitem>
-   </varlistentry>
-
    <varlistentry>
     <term>Searching</term>
     <listitem>
@@ -3487,19 +3458,6 @@ SELECT * FROM pg_attribute
      </para>
     </listitem>
    </varlistentry>
-
-   <varlistentry>
-    <term>Missing Features</term>
-    <listitem>
-
-     <para>
-      Missing features include XQuery, SQL/XML syntax (ISO/IEC
-      9075-14), and an <acronym>XML</> data type optimized for
-      <acronym>XML</> storage.
-     </para>
-    </listitem>
-   </varlistentry>
-
    </variablelist>
 
   </sect1>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 1e092c4ce7..c2a3409645 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.347 2006/11/25 00:38:53 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.348 2006/12/21 16:05:12 petere Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -10741,4 +10741,113 @@ SELECT (pg_stat_file('filename')).modification;
    </para>
 
   </sect1>
+
+  <sect1 id="functions-xml">
+   <title>XML Functions</title>
+
+   <para>
+    The functions and function-like expressions described in this
+    section operate on values of type <type>xml</type>.
+   </para>
+
+   <sect2>
+    <title><literal>xmlcomment</literal></title>
+ 
+   <indexterm>
+    <primary>xmlcomment</primary>
+   </indexterm>
+ 
+ <synopsis>
+ <function>xmlcomment</function>(<replaceable>text</replaceable>)
+ </synopsis>
+ 
+    <para>
+     Creates an XML comment.
+    </para>
+    </sect2>
+ 
+   <sect2>
+    <title><literal>xmlconcat</literal></title>
+ 
+   <indexterm>
+    <primary>xmlconcat</primary>
+   </indexterm>
+ 
+ <synopsis>
+ <function>xmlconcat</function>(<replaceable>xml</replaceable><optional>, xml, ...</optional>)
+ </synopsis>
+ 
+    <para>
+     Combines a list of individual XML values to create a
+     single value containing an XML forest.
+    </para>
+    </sect2>
+ 
+   <sect2>
+    <title><literal>xmlelement</literal></title>
+ 
+   <indexterm>
+    <primary>xmlelement</primary>
+   </indexterm>
+ 
+ <synopsis>
+ <function>xmlelement</function>(name <replaceable>name</replaceable><optional>, xmlattribytes(<replaceable>value</replaceable> <optional>AS <replaceable>label</replaceable></optional><optional>, ... </optional>)</optional>
+ <optional><replaceable>, content, ...</replaceable></optional>)
+ </synopsis>
+ 
+    <para>
+     Creates an XML element, allowing the name to be specified.
+    </para>
+    </sect2>
+ 
+   <sect2>
+    <title><literal>xmlforest</literal></title>
+ 
+   <indexterm>
+    <primary>xmlforest</primary>
+   </indexterm>
+ 
+ <synopsis>
+ <function>xmlforest</function>(<replaceable>value</replaceable> <optional>AS <replaceable>label</replaceable></optional><optional>, ...</optional>)
+ </synopsis>
+ 
+    <para>
+     Creates XML elements from columns, using the name of each
+     column as the name of the corresponding element.
+    </para>
+    </sect2>
+ 
+   <sect2>
+    <title><literal>xmlpi</literal></title>
+ 
+   <indexterm>
+    <primary>xmlpi</primary>
+   </indexterm>
+ 
+ <synopsis>
+ <function>xmlpi</function>(name <replaceable>target</replaceable> <optional>, <replaceable>content</replaceable></optional>)
+ </synopsis>
+ 
+    <para>
+     Creates an XML processing instruction.
+    </para>
+    </sect2>
+ 
+   <sect2>
+    <title><literal>xmlroot</literal></title>
+ 
+   <indexterm>
+    <primary>xmlroot</primary>
+   </indexterm>
+ 
+ <synopsis>
+ <function>xmlroot</function>(<replaceable>xml</replaceable>, version <replaceable>text</replaceable> <optional>, standalone yes|no|no value</optional>)
+ </synopsis>
+ 
+    <para>
+     Creates the root node of an XML document.
+    </para>
+  </sect2>
+ 
+ </sect1>
 </chapter>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 5d071586fc..a56ba9ad9b 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.268 2006/12/02 09:29:51 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.269 2006/12/21 16:05:13 petere Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -905,6 +905,15 @@ su - postgres
        </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><option>--with-libxml</option></term>
+       <listitem>
+        <para>
+         Build with libxml, required for SQL/XML support.
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
        <term><option>--enable-integer-datetimes</option></term>
        <listitem>
-- 
cgit v1.2.1