Update documentation for backslashes to mention escape string syntax

more, and standard_conforming_strings less, because in the future non-E
strings will not treat backslashes specially.

Also use E'' strings where backslashes are used in examples. (The
existing examples would have drawn warnings.)

Backpatch to 8.2.X.

9 files changed, 73 insertions, 78 deletions

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 35dbf6e5cf..cdd5529915 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -597,17 +597,17 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
   </para>
 
   <para>
-   As shown previously, when writing an array value you may write double
+   As shown previously, when writing an array value you can write double
    quotes around any individual array element. You <emphasis>must</> do so
    if the element value would otherwise confuse the array-value parser.
    For example, elements containing curly braces, commas (or whatever the
    delimiter character is), double quotes, backslashes, or leading or trailing
    whitespace must be double-quoted.  Empty strings and strings matching the
    word <literal>NULL</> must be quoted, too.  To put a double quote or
-   backslash in a
-   quoted array element value, precede it with a backslash. Alternatively, you
-   can use backslash-escaping to protect all data characters that would
-   otherwise be taken as array syntax.
+   backslash in a quoted array element value, use escape string syntax
+   and precede it with a backslash. Alternatively, you can use
+   backslash-escaping to protect all data characters that would otherwise
+   be taken as array syntax.
   </para>
 
   <para>
@@ -625,16 +625,16 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
    backslashes you need.  For example, to insert a <type>text</> array
    value containing a backslash and a double quote, you'd need to write
 <programlisting>
-INSERT ... VALUES ('{"\\\\","\\""}');
+INSERT ... VALUES (E'{"\\\\","\\""}');
 </programlisting>
-   The string-literal processor removes one level of backslashes, so that
+   The escape string processor removes one level of backslashes, so that
    what arrives at the array-value parser looks like <literal>{"\\","\""}</>.
    In turn, the strings fed to the <type>text</> data type's input routine
    become <literal>\</> and <literal>"</> respectively.  (If we were working
    with a data type whose input routine also treated backslashes specially,
    <type>bytea</> for example, we might need as many as eight backslashes
    in the command to get one backslash into the stored array element.)
-   Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be
+   Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) can be
    used to avoid the need to double backslashes.
   </para>
  </note>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 623a4b34fa..04ba4f8108 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1152,11 +1152,9 @@ SELECT b, char_length(b) FROM test2;
     of a string literal in an <acronym>SQL</acronym> statement. In
     general, to escape an octet, it is converted into the three-digit
     octal number equivalent of its decimal octet value, and preceded
-    by two backslashes (or one backslash if
-    <varname>standard_conforming_strings</> is <literal>off</>).
-    <xref linkend="datatype-binary-sqlesc"> shows the characters
-    that must be escaped, and gives the alternate escape sequences
-    where applicable.
+    by two backslashes.  <xref linkend="datatype-binary-sqlesc">
+    shows the characters that must be escaped, and gives the alternate
+    escape sequences where applicable.
    </para>
 
    <table id="datatype-binary-sqlesc">
@@ -1176,32 +1174,32 @@ SELECT b, char_length(b) FROM test2;
       <row>
        <entry>0</entry>
        <entry>zero octet</entry>
-       <entry><literal>'\\000'</literal></entry>
-       <entry><literal>SELECT '\\000'::bytea;</literal></entry>
+       <entry><literal>E'\\000'</literal></entry>
+       <entry><literal>SELECT E'\\000'::bytea;</literal></entry>
        <entry><literal>\000</literal></entry>
       </row>
 
       <row>
        <entry>39</entry>
        <entry>single quote</entry>
-       <entry><literal>'\''</literal> or <literal>'\\047'</literal></entry>
-       <entry><literal>SELECT '\''::bytea;</literal></entry>
+       <entry><literal>''''</literal> or <literal>E'\\047'</literal></entry>
+       <entry><literal>SELECT E'\''::bytea;</literal></entry>
        <entry><literal>'</literal></entry>
       </row>
 
       <row>
        <entry>92</entry>
        <entry>backslash</entry>
-       <entry><literal>'\\\\'</literal> or <literal>'\\134'</literal></entry>
-       <entry><literal>SELECT '\\\\'::bytea;</literal></entry>
+       <entry><literal>E'\\\\'</literal> or <literal>E'\\134'</literal></entry>
+       <entry><literal>SELECT E'\\\\'::bytea;</literal></entry>
        <entry><literal>\\</literal></entry>
       </row>
 
       <row>
        <entry>0 to 31 and 127 to 255</entry>
        <entry><quote>non-printable</quote> octets</entry>
-       <entry><literal>'\\<replaceable>xxx'</></literal> (octal value)</entry>
-       <entry><literal>SELECT '\\001'::bytea;</literal></entry>
+       <entry><literal>E'\\<replaceable>xxx'</></literal> (octal value)</entry>
+       <entry><literal>SELECT E'\\001'::bytea;</literal></entry>
        <entry><literal>\001</literal></entry>
       </row>
 
@@ -1224,18 +1222,18 @@ SELECT b, char_length(b) FROM test2;
     string written as a string literal must pass through two parse
     phases in the <productname>PostgreSQL</productname> server.
     The first backslash of each pair is interpreted as an escape
-    character by the string-literal parser (assuming
-    <varname>standard_conforming_strings</> is <literal>off</>)
-    and is therefore consumed, leaving the second backslash of the
-    pair.  The remaining backslash is then recognized by the
+    character by the string-literal parser (assuming escape string
+    syntax is used) and is therefore consumed, leaving the second backslash of the
+    pair.  (Dollar-quoted strings can be used to avoid this level
+    of escaping.)  The remaining backslash is then recognized by the
     <type>bytea</type> input function as starting either a three
     digit octal value or escaping another backslash.  For example,
-    a string literal passed to the server as <literal>'\\001'</literal>
+    a string literal passed to the server as <literal>E'\\001'</literal>
     becomes <literal>\001</literal> after passing through the
-    string-literal parser. The <literal>\001</literal> is then sent
+    escape string parser. The <literal>\001</literal> is then sent
     to the <type>bytea</type> input function, where it is converted
     to a single octet with a decimal value of 1.  Note that the
-    apostrophe character is not treated specially by <type>bytea</type>,
+    single-quote character is not treated specially by <type>bytea</type>,
     so it follows the normal rules for string literals.  (See also
     <xref linkend="sql-syntax-strings">.)
    </para>
@@ -1269,7 +1267,7 @@ SELECT b, char_length(b) FROM test2;
        <entry>92</entry>
        <entry>backslash</entry>
        <entry><literal>\\</literal></entry>
-       <entry><literal>SELECT '\\134'::bytea;</literal></entry>
+       <entry><literal>SELECT E'\\134'::bytea;</literal></entry>
        <entry><literal>\\</literal></entry>
       </row>
 
@@ -1277,7 +1275,7 @@ SELECT b, char_length(b) FROM test2;
        <entry>0 to 31 and 127 to 255</entry>
        <entry><quote>non-printable</quote> octets</entry>
        <entry><literal>\<replaceable>xxx</></literal> (octal value)</entry>
-       <entry><literal>SELECT '\\001'::bytea;</literal></entry>
+       <entry><literal>SELECT E'\\001'::bytea;</literal></entry>
        <entry><literal>\001</literal></entry>
       </row>
 
@@ -1285,7 +1283,7 @@ SELECT b, char_length(b) FROM test2;
        <entry>32 to 126</entry>
        <entry><quote>printable</quote> octets</entry>
        <entry>client character set representation</entry>
-       <entry><literal>SELECT '\\176'::bytea;</literal></entry>
+       <entry><literal>SELECT E'\\176'::bytea;</literal></entry>
        <entry><literal>~</literal></entry>
       </row>
 
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6a7682c3f9..5ac4974e56 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1339,7 +1339,7 @@
         Encode binary data to <acronym>ASCII</acronym>-only representation.  Supported
         types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
        </entry>
-       <entry><literal>encode( '123\\000\\001', 'base64')</literal></entry>
+       <entry><literal>encode( E'123\\000\\001', 'base64')</literal></entry>
        <entry><literal>MTIzAAE=</literal></entry>
       </row>       
 
@@ -1439,7 +1439,7 @@
        <entry>
         Return the given string suitably quoted to be used as a string literal
         in an <acronym>SQL</acronym> statement string.
-        Embedded quotes and backslashes are properly doubled.
+        Embedded single-quotes and backslashes are properly doubled.
        </entry>
        <entry><literal>quote_literal( 'O\'Reilly')</literal></entry>
        <entry><literal>'O''Reilly'</literal></entry>
@@ -2393,7 +2393,7 @@
          <secondary>concatenation</secondary>
         </indexterm>
        </entry>
-       <entry><literal>'\\\\Post'::bytea || '\\047gres\\000'::bytea</literal></entry>
+       <entry><literal>E'\\\\Post'::bytea || E'\\047gres\\000'::bytea</literal></entry>
        <entry><literal>\\Post'gres\000</literal></entry>
       </row>
 
@@ -2406,7 +2406,7 @@
          <primary>get_bit</primary>
         </indexterm>
        </entry>
-       <entry><literal>get_bit('Th\\000omas'::bytea, 45)</literal></entry>
+       <entry><literal>get_bit(E'Th\\000omas'::bytea, 45)</literal></entry>
        <entry><literal>1</literal></entry>
       </row>
 
@@ -2419,7 +2419,7 @@
          <primary>get_byte</primary>
         </indexterm>
        </entry>
-       <entry><literal>get_byte('Th\\000omas'::bytea, 4)</literal></entry>
+       <entry><literal>get_byte(E'Th\\000omas'::bytea, 4)</literal></entry>
        <entry><literal>109</literal></entry>
       </row>
 
@@ -2427,7 +2427,7 @@
        <entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry>
        <entry><type>int</type></entry>
        <entry>Number of bytes in binary string</entry>
-       <entry><literal>octet_length( 'jo\\000se'::bytea)</literal></entry>
+       <entry><literal>octet_length( E'jo\\000se'::bytea)</literal></entry>
        <entry><literal>5</literal></entry>
       </row>
 
@@ -2435,7 +2435,7 @@
        <entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry>
        <entry><type>int</type></entry>
        <entry>Location of specified substring</entry>
-      <entry><literal>position('\\000om'::bytea in 'Th\\000omas'::bytea)</literal></entry>
+      <entry><literal>position(E'\\000om'::bytea in E'Th\\000omas'::bytea)</literal></entry>
        <entry><literal>3</literal></entry>
       </row>
 
@@ -2449,7 +2449,7 @@
          <primary>set_bit</primary>
         </indexterm>
        </entry>
-       <entry><literal>set_bit('Th\\000omas'::bytea, 45, 0)</literal></entry>
+       <entry><literal>set_bit(E'Th\\000omas'::bytea, 45, 0)</literal></entry>
        <entry><literal>Th\000omAs</literal></entry>
       </row>
 
@@ -2463,7 +2463,7 @@
          <primary>set_byte</primary>
         </indexterm>
        </entry>
-       <entry><literal>set_byte('Th\\000omas'::bytea, 4, 64)</literal></entry>
+       <entry><literal>set_byte(E'Th\\000omas'::bytea, 4, 64)</literal></entry>
        <entry><literal>Th\000o@as</literal></entry>
       </row>
 
@@ -2476,7 +2476,7 @@
          <primary>substring</primary>
         </indexterm>
        </entry>
-       <entry><literal>substring('Th\\000omas'::bytea from 2 for 3)</literal></entry>
+       <entry><literal>substring(E'Th\\000omas'::bytea from 2 for 3)</literal></entry>
        <entry><literal>h\000o</literal></entry>
       </row>
 
@@ -2492,7 +2492,7 @@
         <parameter>bytes</parameter> from the start
         and end of <parameter>string</parameter>
        </entry>
-       <entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry>
+       <entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry>
        <entry><literal>Tom</literal></entry>
       </row>
      </tbody>
@@ -2530,7 +2530,7 @@
         in <parameter>bytes</parameter> from the start and end of
         <parameter>string</parameter>
       </entry>
-      <entry><literal>btrim('\\000trim\\000'::bytea, '\\000'::bytea)</literal></entry>
+      <entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry>
       <entry><literal>trim</literal></entry>
      </row>
 
@@ -2544,7 +2544,7 @@
        Decode binary string from <parameter>string</parameter> previously 
        encoded with <function>encode</>.  Parameter type is same as in <function>encode</>.
       </entry>
-      <entry><literal>decode('123\\000456', 'escape')</literal></entry>
+      <entry><literal>decode(E'123\\000456', 'escape')</literal></entry>
       <entry><literal>123\000456</literal></entry>
      </row>
 
@@ -2558,7 +2558,7 @@
        Encode binary string to <acronym>ASCII</acronym>-only representation.  Supported
        types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
       </entry>
-      <entry><literal>encode('123\\000456'::bytea, 'escape')</literal></entry>
+      <entry><literal>encode(E'123\\000456'::bytea, 'escape')</literal></entry>
       <entry><literal>123\000456</literal></entry>
      </row>
 
@@ -2577,7 +2577,7 @@
         <see>binary strings, length</see>
        </indexterm>
       </entry>
-      <entry><literal>length('jo\\000se'::bytea)</literal></entry>
+      <entry><literal>length(E'jo\\000se'::bytea)</literal></entry>
       <entry><literal>5</literal></entry>
      </row>
 
@@ -2588,7 +2588,7 @@
        Calculates the MD5 hash of <parameter>string</parameter>,
        returning the result in hexadecimal
       </entry>
-      <entry><literal>md5('Th\\000omas'::bytea)</literal></entry>
+      <entry><literal>md5(E'Th\\000omas'::bytea)</literal></entry>
       <entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry>
      </row>
     </tbody>
@@ -2812,7 +2812,8 @@ cast(-44 as bit(12))           <lineannotation>111111010100</lineannotation>
    <para>
     Note that the backslash already has a special meaning in string
     literals, so to write a pattern constant that contains a backslash
-    you must write two backslashes in an SQL statement.  Thus, writing a pattern
+    you must write two backslashes in an SQL statement (assuming escape
+    string syntax is used).  Thus, writing a pattern
     that actually matches a literal backslash means writing four backslashes
     in the statement.  You can avoid this by selecting a different escape
     character with <literal>ESCAPE</literal>; then a backslash is not special
@@ -3106,7 +3107,7 @@ substring('foobar' from 'o(.)b')   <lineannotation>o</lineannotation>
      substring matching the entire pattern should be inserted.  Write
      <literal>\\</> if you need to put a literal backslash in the replacement
      text.  (As always, remember to double backslashes written in literal
-     constant strings.)
+     constant strings, assuming escape string syntax is used.)
      The <replaceable>flags</> parameter is an optional text
      string containing zero or more single-letter flags that change the
      function's behavior.  Flag <literal>i</> specifies case-insensitive
@@ -3121,7 +3122,7 @@ regexp_replace('foobarbaz', 'b..', 'X')
                                    <lineannotation>fooXbaz</lineannotation>
 regexp_replace('foobarbaz', 'b..', 'X', 'g')
                                    <lineannotation>fooXX</lineannotation>
-regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
+regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
                                    <lineannotation>fooXarYXazY</lineannotation>
 </programlisting>
    </para>
@@ -3283,7 +3284,8 @@ regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
      Remember that the backslash (<literal>\</literal>) already has a special
      meaning in <productname>PostgreSQL</> string literals.
      To write a pattern constant that contains a backslash,
-     you must write two backslashes in the statement.
+     you must write two backslashes in the statement, assuming escape
+     string syntax is used.
     </para>
    </note>
 
@@ -3594,7 +3596,7 @@ regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
      Keep in mind that an escape's leading <literal>\</> will need to be
      doubled when entering the pattern as an SQL string constant.  For example:
 <programlisting>
-'123' ~ '^\\d{3}' <lineannotation>true</lineannotation>
+'123' ~ E'^\\d{3}' <lineannotation>true</lineannotation>
 </programlisting>
     </para>
    </note>
@@ -4756,10 +4758,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
      <listitem>
       <para>
        If you want to have a double quote in the output you must
-       precede it with a backslash, for example <literal>'\\"YYYY
+       precede it with a backslash, for example <literal>E'\\"YYYY
        Month\\"'</literal>. <!-- "" font-lock sanity :-) -->
        (Two backslashes are necessary because the backslash already
-       has a special meaning in a string constant.)
+       has a special meaning when using the escape string syntax.)
       </para>
      </listitem>
 
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index decfb28f4d..28762dcf07 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -916,7 +916,7 @@ in a numeric form that is much easier to compare against.
 
 <para>
 If no value for <literal>standard_conforming_strings</> is reported,
-applications may assume it is <literal>false</>, that is, backslashes
+applications may assume it is <literal>off</>, 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.
@@ -2494,7 +2494,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
    of a <type>bytea</type> literal in an <acronym>SQL</acronym>
    statement. In general, to escape a byte, it is converted into the
    three digit octal number equal to the octet value, and preceded by
-   one or two backslashes. The single quote (<literal>'</>) and backslash
+   usually two backslashes. The single quote (<literal>'</>) and backslash
    (<literal>\</>) characters have special alternative escape
    sequences. See <xref linkend="datatype-binary"> for more
    information. <function>PQescapeByteaConn</function> performs this
diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 198580de87..0436c73150 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -80,10 +80,10 @@ $$ LANGUAGE plperl;
    the function body to be written as a string constant.  It is usually
    most convenient to use dollar quoting (see <xref
    linkend="sql-syntax-dollar-quoting">) for the string constant.
-   If you choose to use regular single-quoted string constant syntax,
-   you must escape single quote marks (<literal>'</>) and backslashes
-   (<literal>\</>) used in the body of the function, typically by
-   doubling them (see <xref linkend="sql-syntax-strings">).
+   If you choose to use escape string syntax <literal>E''</>,
+   you must double the single quote marks (<literal>'</>) and backslashes
+   (<literal>\</>) used in the body of the function 
+   (see <xref linkend="sql-syntax-strings">).
   </para>
 
   <para>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 0387c70142..accaf398db 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -288,7 +288,8 @@ $$ LANGUAGE plpgsql;
     <command>CREATE FUNCTION</command> as a string literal.  If you
     write the string literal in the ordinary way with surrounding
     single quotes, then any single quotes inside the function body
-    must be doubled; likewise any backslashes must be doubled.
+    must be doubled; likewise any backslashes must be doubled (assuming
+    escape string syntax is used).
     Doubling quotes is at best tedious, and in more complicated cases
     the code can become downright incomprehensible, because you can
     easily find yourself needing half a dozen or more adjacent quote marks.
@@ -434,13 +435,6 @@ a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$
    </varlistentry>
   </variablelist>
 
-   <para>
-    A variant approach is to escape quotation marks in the function body
-    with a backslash rather than by doubling them.  With this method
-    you'll find yourself writing things like <literal>\'\'</> instead
-    of <literal>''''</>.  Some find this easier to keep track of, some
-    do not.
-   </para>
   </sect2>
  </sect1>
 
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 4509863cdc..a96c337cd8 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -387,11 +387,11 @@ CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS $$
 $$ LANGUAGE pltcl;
 </programlisting>
 
-    We need backslashes inside the query string given to
-    <function>spi_prepare</> to ensure that the
-    <literal>$<replaceable>n</replaceable></> markers will be passed
-    through to <function>spi_prepare</> as-is, and not replaced by Tcl
-    variable substitution.
+        We need backslashes inside the query string given to
+        <function>spi_prepare</> to ensure that the
+        <literal>$<replaceable>n</replaceable></> markers will be passed
+        through to <function>spi_prepare</> as-is, and not replaced by Tcl
+        variable substitution.
 
        </para>
       </listitem>
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index 1ba5c43faa..349b3e43a2 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -294,11 +294,12 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
   <para>
    Remember that what you write in an SQL command will first be interpreted
    as a string literal, and then as a composite.  This doubles the number of
-   backslashes you need.  For example, to insert a <type>text</> field
+   backslashes you need (assuming escape string syntax is used).
+   For example, to insert a <type>text</> field
    containing a double quote and a backslash in a composite
    value, you'd need to write
 <programlisting>
-INSERT ... VALUES ('("\\"\\\\")');
+INSERT ... VALUES (E'("\\"\\\\")');
 </programlisting>
    The string-literal processor removes one level of backslashes, so that
    what arrives at the composite-value parser looks like
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 8934a10f51..cea8869f06 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -147,9 +147,9 @@ SELECT clean_emp();
     most convenient to use dollar quoting (see <xref
     linkend="sql-syntax-dollar-quoting">) for the string constant.
     If you choose to use regular single-quoted string constant syntax,
-    you must escape single quote marks (<literal>'</>) and backslashes
-    (<literal>\</>) used in the body of the function, typically by
-    doubling them (see <xref linkend="sql-syntax-strings">).
+    you must double single quote marks (<literal>'</>) and backslashes
+    (<literal>\</>) (assuming escape string syntax) in the body of
+    the function (see <xref linkend="sql-syntax-strings">).
    </para>
 
    <para>