Re: bytea vs standard_conforming_strings

Tom Lane wrote:
> The discussion of bytea in section 8.4,
> http://developer.postgresql.org/pgdocs/postgres/datatype-binary.html
> is obsolete because it assumes that standard_conforming_strings is
> always OFF.  It could be very much simpler and shorter if
> standard_conforming_strings were always ON, but that's not reality
> either.  Anyone have an idea on how to rewrite it in a way that
> isn't awkward, incomprehensible, or both?

I added two "(assuming <varname>standard_conforming_strings</> is
<literal>off</>)" clauses in the bytea docs.  Patch attached, sorry for
the new wrapping.

--
  Bruce Momjian   bruce@momjian.us
  EnterpriseDB    http://www.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/datatype.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v
retrieving revision 1.180
diff -c -c -r1.180 datatype.sgml
*** doc/src/sgml/datatype.sgml    23 Oct 2006 18:10:30 -0000    1.180
--- doc/src/sgml/datatype.sgml    23 Nov 2006 04:21:46 -0000
***************
*** 1097,1111 ****
     </para>

     <para>
!     When entering <type>bytea</type> values, octets of certain values
!     <emphasis>must</emphasis> be escaped (but all octet values
!     <emphasis>can</emphasis> be escaped) when used as part 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. <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">
--- 1097,1113 ----
     </para>

     <para>
!     When entering <type>bytea</type> values, octets of certain
!     values <emphasis>must</emphasis> be escaped (but all octet
!     values <emphasis>can</emphasis> be escaped) when used as part
!     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.
     </para>

     <table id="datatype-binary-sqlesc">
***************
*** 1168,1191 ****
     </para>

     <para>
!     The reason that you have to write so many backslashes, as shown in
!     <xref linkend="datatype-binary-sqlesc">, is that an input 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 and is therefore consumed, leaving the
!     second backslash of the pair.  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> becomes <literal>\001</literal> after
!     passing through the string-literal 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>, so it follows the normal
!     rules for string literals.  (See also <xref
!     linkend="sql-syntax-strings">.)
     </para>

     <para>
--- 1170,1194 ----
     </para>

     <para>
!     The reason that you have to write so many backslashes, as shown
!     in <xref linkend="datatype-binary-sqlesc">, is that an input
!     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
!     <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>
!     becomes <literal>\001</literal> after passing through the
!     string-literal 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>,
!     so it follows the normal rules for string literals.  (See also
!     <xref linkend="sql-syntax-strings">.)
     </para>

     <para>