Rename xml_valid() to xml_is_well_formed(), but provide a temporary

alias with the old name for backwards compatibility.  Per discussion,
the old name is actively wrong because validity and well-formedness
have different meanings in XML.

diff --git a/contrib/xml2/README.xml2 b/contrib/xml2/README.xml2
index f5335c38b56aa16aa90763987e6d057ec1467e84..c2e71703860f7bb7a1e2d2c4231370a2781324f8 100644 (file)
--- a/contrib/xml2/README.xml2
+++ b/contrib/xml2/README.xml2
@@ -21,17 +21,24 @@ you can place it in a different directory in a PostgreSQL tree).
 Before you begin, just check the Makefile, and then just 'make' and
 'make install'.
 
-This code requires libxml to be previously installed.
+By default, this module requires both libxml2 and libxslt to be installed
+on your system.  If you do not have libxslt or do not want to use XSLT
+functions, you must edit the Makefile to not build the XSLT functions,
+as directed in its comments; and edit pgxml.sql.in to remove the XSLT
+function declarations, as directed in its comments.
 
 Description of functions
 ------------------------
 
 The first set of functions are straightforward XML parsing and XPath queries:
 
-xml_valid(document) RETURNS bool
+xml_is_well_formed(document) RETURNS bool
 
 This parses the document text in its parameter and returns true if the
-document is well-formed XML.
+document is well-formed XML.  (Note: before PostgreSQL 8.2, this function
+was called xml_valid().  That is the wrong name since validity and
+well-formedness have different meanings in XML.  The old name is still
+available, but is deprecated and will be removed in 8.3.)
 
 xpath_string(document,query) RETURNS text
 xpath_number(document,query) RETURNS float4

diff --git a/contrib/xml2/pgxml.sql.in b/contrib/xml2/pgxml.sql.in
index 006f3f7f53cc1a5ef0f1923ec5ae8bffd5bb44df..4555cc833111c4ed64794913ebc0d3f4914e1c9e 100644 (file)
--- a/contrib/xml2/pgxml.sql.in
+++ b/contrib/xml2/pgxml.sql.in
@@ -1,8 +1,12 @@
 --SQL for XML parser
 
-CREATE OR REPLACE FUNCTION xml_valid(text) RETURNS bool
+CREATE OR REPLACE FUNCTION xml_is_well_formed(text) RETURNS bool
        AS 'MODULE_PATHNAME' LANGUAGE C STRICT IMMUTABLE;
 
+-- deprecated old name for xml_is_well_formed
+CREATE OR REPLACE FUNCTION xml_valid(text) RETURNS bool
+       AS 'MODULE_PATHNAME', 'xml_is_well_formed' LANGUAGE C STRICT IMMUTABLE;
+
 CREATE OR REPLACE FUNCTION xml_encode_special_chars(text) RETURNS text
        AS 'MODULE_PATHNAME' LANGUAGE C STRICT IMMUTABLE;
 

diff --git a/contrib/xml2/uninstall_pgxml.sql b/contrib/xml2/uninstall_pgxml.sql
index b055ce85a5f2b996d75cc3ca40ed36d1f0cdb4db..f375f59724a643e8c6ea33eaad094d401aef9448 100644 (file)
--- a/contrib/xml2/uninstall_pgxml.sql
+++ b/contrib/xml2/uninstall_pgxml.sql
@@ -24,4 +24,7 @@ DROP FUNCTION xpath_string(text,text);
 
 DROP FUNCTION xml_encode_special_chars(text);
 
+-- deprecated old name for xml_is_well_formed
 DROP FUNCTION xml_valid(text);
+
+DROP FUNCTION xml_is_well_formed(text);

diff --git a/contrib/xml2/xpath.c b/contrib/xml2/xpath.c
index 01f1976ab610d676c82a0746e31b8b403f439edf..cc830322193ce34ebe2ec6bfa47e1ef26491eec4 100644 (file)
--- a/contrib/xml2/xpath.c
+++ b/contrib/xml2/xpath.c
@@ -42,7 +42,7 @@ xmlChar    *pgxml_texttoxmlchar(text *textstring);
 static xmlXPathObjectPtr pgxml_xpath(text *document, xmlChar * xpath);
 
 
-Datum          xml_valid(PG_FUNCTION_ARGS);
+Datum          xml_is_well_formed(PG_FUNCTION_ARGS);
 Datum          xml_encode_special_chars(PG_FUNCTION_ARGS);
 Datum          xpath_nodeset(PG_FUNCTION_ARGS);
 Datum          xpath_string(PG_FUNCTION_ARGS);
@@ -166,12 +166,12 @@ pgxml_parser_init()
 
 /* Returns true if document is well-formed */
 
-PG_FUNCTION_INFO_V1(xml_valid);
+PG_FUNCTION_INFO_V1(xml_is_well_formed);
 
 Datum
-xml_valid(PG_FUNCTION_ARGS)
+xml_is_well_formed(PG_FUNCTION_ARGS)
 {
-       /* called as xml_valid(document) */
+       /* called as xml_is_well_formed(document) */
        xmlDocPtr       doctree;
        text       *t = PG_GETARG_TEXT_P(0);            /* document buffer */
        int32           docsize = VARSIZE(t) - VARHDRSZ;

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index ac632ee37785bfcc7d71763e38db9efc23dfe1e9..5bca7c418f3ea91b849d22542ff0775bda9d9ff8 100644 (file)
--- 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.174 2006/09/16 00:30:12 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.175 2006/09/16 16:18:11 tgl Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -3345,8 +3345,8 @@ SELECT * FROM pg_attribute
 
      <para>
       <filename>/contrib/xml2</> has a function called
-      <function>xml_valid()</> that can be used in a <literal>CHECK</>
-      constraint to enforce that a field contains valid <acronym>XML</>.
+      <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.