Rewrite discussion of string constant syntax to bring it into line with

the politically correct view that backslash escapes are deprecated.

diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 8fd54089e31c78fca0e63d1970f80f64da008efa..3a7b5d9ea11c03d12d9746deedd4a2d3b18dafb1 100644 (file)
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  SQL Syntax
@@ -240,49 +240,12 @@ UPDATE "my_table" SET "a" = 5;
      
      A string constant in SQL is an arbitrary sequence of characters
      bounded by single quotes ('), for example
-     'This is a string'.  The standard-compliant way of
-     writing a single-quote character within a string constant is to
+     'This is a string'.  To include
+     a single-quote character within a string constant,
      write two adjacent single quotes, e.g.
      'Dianne''s horse'.
-     PostgreSQL also allows single quotes
-     to be escaped with a backslash (\').  However,
-     future versions of PostgreSQL will not
-     allow this, so applications using backslashes should convert to the 
-     standard-compliant method outlined above.
-    
-
-    
-     Another PostgreSQL extension is that
-     C-style backslash escapes are available: \b is a
-     backspace, \f is a form feed,
-     \n is a newline, \r is a
-     carriage return, \t is a tab. Also supported is
-     \digits, where
-     digits represents an octal byte value, and
-     \xhexdigits, where
-     hexdigits represents a hexadecimal byte value.
-     (It is your responsibility that the byte sequences you create are
-     valid characters in the server character set encoding.) Any other
-     character following a backslash is taken literally. Thus, to
-     include a backslash in a string constant, write two backslashes.
-    
-
-    
-    
-     While ordinary strings now support C-style backslash escapes,
-     future versions will generate warnings for such usage and
-     eventually treat backslashes as literal characters to be
-     standard-conforming. 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 writing
-     the letter E (upper or lower case) just before
-     the string, e.g. E'\041'. This method will work in all
-     future versions of PostgreSQL.
-    
-    
-
-    
-     The character with the code zero cannot be in a string constant.
+     Note that this is not the same as a double-quote
+     character (").
     
 
     
@@ -306,6 +269,70 @@ SELECT 'foo'      'bar';
      by SQL; PostgreSQL is
      following the standard.)
     
+
+    
+     
+      escape string syntax
+     
+     
+      backslash escapes
+     
+     PostgreSQL also accepts escape
+     string constants, which are an extension to the SQL standard.
+     An escape string constant is specified by writing the letter
+     E (upper or lower case) just before the opening single
+     quote, e.g. E'foo'.  (When continuing an escape string
+     constant across lines, write E only before the first opening
+     quote.)
+     Within an escape string, a backslash character (\) begins a
+     C-like backslash escape sequence, in which the combination
+     of backslash and following character(s) represents a special byte value.
+     \b is a backspace,
+     \f is a form feed,
+     \n is a newline,
+     \r is a carriage return,
+     \t is a tab.
+     Also supported are
+     \digits, where
+     digits represents an octal byte value, and
+     \xhexdigits, where
+     hexdigits represents a hexadecimal byte value.
+     (It is your responsibility that the byte sequences you create are
+     valid characters in the server character set encoding.) Any other
+     character following a backslash is taken literally. Thus, to
+     include a backslash character, write two backslashes (\\).
+     Also, a single quote can be included in an escape string by writing
+     \', in addition to the normal way of ''.
+    
+
+    
+    
+     If the configuration parameter
+      is off,
+     then PostgreSQL recognizes backslash escapes
+     in both regular and escape string constants.  This is for backward
+     compatibility with the historical behavior, in which backslash escapes
+     were always recognized.
+     Although standard_conforming_strings currently defaults to
+     off, the default will change to on in a future
+     release for improved standards compliance.  Applications are therefore
+     encouraged to migrate away from using backslash escapes.  If you need
+     to use a backslash escape to represent a special character, write the
+     constant with an E to be sure it will be handled the same
+     way in future releases.
+    
+
+    
+     In addition to standard_conforming_strings, the configuration
+     parameters  and
+      govern treatment of backslashes
+     in string constants.
+    
+    
+
+    
+     The character with the code zero cannot be in a string constant.
+