Code review for escape-strings patch. Sync psql and plpgsql lexers

with main, avoid using a SQL-defined SQLSTATE for what is most definitely
not a SQL-compatible error condition, fix documentation omissions,
adhere to message style guidelines, don't use two GUC_REPORT variables
when one is sufficient.  Nothing done about pg_dump issues.

5 files changed, 48 insertions, 40 deletions

diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml
index ad556d01516..71b4a8cd406 100644
--- a/doc/src/sgml/errcodes.sgml
+++ b/doc/src/sgml/errcodes.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/errcodes.sgml,v 1.12 2005/01/06 01:49:24 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/errcodes.sgml,v 1.13 2005/06/26 19:16:04 tgl Exp $ -->
 
 <appendix id="errcodes-appendix">
  <title><productname>PostgreSQL</productname> Error Codes</title>
@@ -371,6 +371,11 @@
 </row>
 
 <row>
+<entry><literal>22P06</literal></entry>
+<entry>NONSTANDARD USE OF ESCAPE CHARACTER</entry>
+</row>
+
+<row>
 <entry><literal>22010</literal></entry>
 <entry>INVALID INDICATOR PARAMETER VALUE</entry>
 </row>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 9c1b94e2be7..a5bde7fc76e 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.186 2005/06/21 04:02:29 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.187 2005/06/26 19:16:04 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -286,7 +286,7 @@ PGconn *PQconnectdb(const char *conninfo);
        Kerberos service name to use when authenticating with Kerberos 4 or 5.
        This must match the service name specified in the server
        configuration for Kerberos authentication to succeed. (See also
-			 <xref linkend="kerberos-auth">.)
+       <xref linkend="kerberos-auth">.)
       </para>
      </listitem>
     </varlistentry>
@@ -888,10 +888,13 @@ Parameters reported as of the current release include
 <literal>is_superuser</>,
 <literal>session_authorization</>,
 <literal>DateStyle</>,
-<literal>TimeZone</>, and
-<literal>integer_datetimes</>.
+<literal>TimeZone</>,
+<literal>integer_datetimes</>, and
+<literal>standard_compliant_strings</>.
 (<literal>server_encoding</>, <literal>TimeZone</>, and
-<literal>integer_datetimes</> were not reported by releases before 8.0.)
+<literal>integer_datetimes</> were not reported by releases before 8.0;
+<literal>standard_compliant_strings</> was not reported by releases
+before 8.1.)
 Note that
 <literal>server_version</>,
 <literal>server_encoding</> and
@@ -914,6 +917,14 @@ in a numeric form that is much easier to compare against.
 </para>
 
 <para>
+If no value for <literal>standard_compliant_strings</> is reported,
+applications may assume it is <literal>false</>, that is, backslashes
+are treated as escapes in string literals.  Also, the presence of this
+parameter may be taken as an indication that the escape string syntax
+(<literal>E'...'</>) is accepted.
+</para>
+
+<para>
 Although the returned pointer is declared <literal>const</>, it in fact
 points to mutable storage associated with the <literal>PGconn</> structure.
 It is unwise to assume the pointer will remain valid across queries.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index cd6fa0e94f0..7ebcfc63a34 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.59 2005/06/22 15:19:43 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.60 2005/06/26 19:16:04 tgl Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -1072,10 +1072,13 @@
     <literal>is_superuser</>,
     <literal>session_authorization</>,
     <literal>DateStyle</>,
-    <literal>TimeZone</>, and
-    <literal>integer_datetimes</>.
+    <literal>TimeZone</>,
+    <literal>integer_datetimes</>, and
+    <literal>standard_compliant_strings</>.
     (<literal>server_encoding</>, <literal>TimeZone</>, and
-    <literal>integer_datetimes</> were not reported by releases before 8.0.)
+    <literal>integer_datetimes</> were not reported by releases before 8.0;
+    <literal>standard_compliant_strings</> was not reported by releases
+    before 8.1.)
     Note that
     <literal>server_version</>,
     <literal>server_encoding</> and
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 3841b0dee2d..c0b3e65ba78 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.331 2005/06/26 03:03:17 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.332 2005/06/26 19:16:04 tgl Exp $
 -->
 
 <chapter Id="runtime">
@@ -3766,13 +3766,11 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       <listitem>
        <para>
         When <literal>on</>, a warning is issued if a backslash
-        (<literal>\</>) appears in a ordinary, non-escape syntax
-        (<literal>''</>) string. To log the statement that generated the
-        warning, set <varname>log_min_error_statement</> to
-        <literal>error</>.  The default is off.
+        (<literal>\</>) appears in an ordinary string literal
+        (<literal>'...'</> syntax).  The default is <literal>off</>.
        </para>
        <para>
-        Escape string syntax (<literal>E''</>) should be used for
+        Escape string syntax (<literal>E'...'</>) should be used for
         escapes, because in future versions of
         <productname>PostgreSQL</productname> ordinary strings will have
         the standard-compliant behavior of treating backslashes
@@ -3988,22 +3986,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
-     <varlistentry id="guc-escape-string-syntax" xreflabel="escape_string_syntax">
-      <term><varname>escape_string_syntax</varname> (<type>boolean</type>)</term>
-      <indexterm><primary>strings</><secondary>escape</></>
-      <indexterm>
-       <primary><varname>escape_string_syntax</> configuration parameter</primary>
-      </indexterm>
-      <listitem>
-       <para>
-        Reports whether escape string syntax (<literal>E''</>) is
-        supported. This variable is used by applications that need to
-        determine if escape string syntax can be used in their code.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry id="guc-sql-standard-strings" xreflabel="standard_compliant_strings">
+     <varlistentry id="guc-standard-compliant-strings" xreflabel="standard_compliant_strings">
       <term><varname>standard_compliant_strings</varname> (<type>boolean</type>)</term>
       <indexterm><primary>strings</><secondary>escape</></>
       <indexterm>
@@ -4011,10 +3994,16 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </indexterm>
       <listitem>
        <para>
-        Reports whether ordinary, non-escape syntax strings
-        (<literal>''</>) treat backslashes literally, as specified in
-        the SQL standard. This variable is used by applications that
-        need to know how ordinary strings are processed`.
+        Reports whether ordinary string literals
+        (<literal>'...'</>) treat backslashes literally, as specified in
+        the SQL standard.  The value is currently always <literal>false</>,
+        indicating that backslashes are treated as escapes.  It is planned
+        that this will change to <literal>true</> in a future
+        <productname>PostgreSQL</productname> release when string literal
+        syntax changes to meet the standard.  Applications may check this
+        parameter to determine how string literals will be processed.
+        The presence of this parameter can also be taken as an indication
+        that the escape string syntax (<literal>E'...'</>) is supported.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 3d8d457c561..0d3d7f19f18 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.101 2005/06/26 03:03:21 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.102 2005/06/26 19:16:05 tgl Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -249,7 +249,7 @@ UPDATE "my_table" SET "a" = 5;
      <productname>PostgreSQL</productname> also allows single quotes
      to be escaped with a backslash (<literal>\'</literal>).  However,
      future versions of <productname>PostgreSQL</productname> will not
-     support this so applications using this should convert to the 
+     allow this, so applications using backslashes should convert to the 
      standard-compliant method outlined above.
     </para>
 
@@ -276,8 +276,8 @@ UPDATE "my_table" SET "a" = 5;
      eventually treat backslashes as literal characters to be
      standard-compliant. The proper way to specify escape processing is
      to use the escape string syntax to indicate that escape
-     processing is desired. Escape string syntax is specified by placing
-     the the letter <literal>E</literal> (upper or lower case) before
+     processing is desired. Escape string syntax is specified by writing
+     the letter <literal>E</literal> (upper or lower case) just before
      the string, e.g. <literal>E'\041'</>. This method will work in all
      future versions of <productname>PostgreSQL</productname>.
     </para>