Doc: fix thinko in description of how to escape a backslash in bytea.

Also clean up some discussion that had been left in a very confused
state thanks to half-hearted adjustments for the change to
standard_conforming_strings being the default.

Discussion: https://postgr.es/m/154954987367.1297.4358910045409218@wrigleys.postgresql.org

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index ed0ee584c9f1606039e5454604cffe0d6503393c..7807210b3626a73653fb742ef02b33212357fb81 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1335,9 +1335,9 @@ SELECT b, char_length(b) FROM test2;
     per byte, most significant nibble first.  The entire string is
     preceded by the sequence \x (to distinguish it
     from the escape format).  In some contexts, the initial backslash may
-    need to be escaped by doubling it, in the same cases in which backslashes
-    have to be doubled in escape format; details appear below.
-    The hexadecimal digits can
+    need to be escaped by doubling it
+    (see ).
+    For input, the hexadecimal digits can
     be either upper or lower case, and whitespace is permitted between
     digit pairs (but not within a digit pair nor in the starting
     \x sequence).
@@ -1379,9 +1379,7 @@ SELECT '\xDEADBEEF';
     values must be escaped, while all octet
     values can be escaped.  In
     general, to escape an octet, convert it into its three-digit
-    octal value and precede it
-    by a backslash (or two backslashes, if writing the value as a
-    literal using escape string syntax).
+    octal value and precede it by a backslash.
     Backslash itself (octet decimal value 92) can alternatively be represented by
     double backslashes.
     
@@ -1398,7 +1396,7 @@ SELECT '\xDEADBEEF';
        Description
        Escaped Input Representation
        Example
-       Output Representation
+       Hex Representation
       
      
 
@@ -1422,7 +1420,7 @@ SELECT '\xDEADBEEF';
       
        92
        backslash
-       '\' or '\\134'
+       '\\' or '\134'
        SELECT '\\'::bytea;
        \x5c
       
@@ -1442,39 +1440,35 @@ SELECT '\xDEADBEEF';
    
     The requirement to escape non-printable octets
     varies depending on locale settings. In some instances you can get away
-    with leaving them unescaped. Note that the result in each of the examples
-    in  was exactly one octet in
-    length, even though the output representation is sometimes
-    more than one character.
+    with leaving them unescaped.
    
 
    
-    The reason multiple backslashes are required, as shown
-    in , is that an input
-    string written as a string literal must pass through two parse
-    phases in the PostgreSQL server.
-    The first backslash of each pair is interpreted as an escape
-    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
-    bytea input function as starting either a three
-    digit octal value or escaping another backslash.  For example,
-    a string literal passed to the server as '\001'
-    becomes \001 after passing through the
-    escape string parser. The \001 is then sent
-    to the bytea input function, where it is converted
-    to a single octet with a decimal value of 1.  Note that the
-    single-quote character is not treated specially by bytea,
-    so it follows the normal rules for string literals.  (See also
-    .)
+    The reason that single quotes must be doubled, as shown
+    in , is that this
+    is true for any string literal in a SQL command.  The generic
+    string-literal parser consumes the outermost single quotes
+    and reduces any pair of single quotes to one data character.
+    What the bytea input function sees is just one
+    single quote, which it treats as a plain data character.
+    However, the bytea input function treats
+    backslashes as special, and the other behaviors shown in
+     are implemented by
+    that function.
+   
+
+   
+    In some contexts, backslashes must be doubled compared to what is
+    shown above, because the generic string-literal parser will also
+    reduce pairs of backslashes to one data character;
+    see .
    
 
    
     Bytea octets are output in hex
     format by default.  If you change 
     to escape,
-    non-printable octet are converted to
+    non-printable octets are converted to their
     equivalent three-digit octal value and preceded by one backslash.
     Most printable octets are output by their standard
     representation in the client character set, e.g.: