Received: from maia.hub.org (maia-2.hub.org [200.46.204.251])
	by mail.postgresql.org (Postfix) with ESMTP id 6A1F9B5DD14
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Mon, 11 Jul 2011 19:25:11 -0300 (ADT)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.251]) (amavisd-maia,
	port 10024) with ESMTP id 36489-04 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Mon, 11 Jul 2011 22:25:04 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.6
Received: from momjian.us (momjian.us [70.90.9.53])
	by mail.postgresql.org (Postfix) with ESMTP id 87B01B5DD0D
	for <pgsql-docs@postgresql.org>; Mon, 11 Jul 2011 19:25:04 -0300 (ADT)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 p6BMP3M08188;
	Mon, 11 Jul 2011 18:25:03 -0400 (EDT)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201107112225.p6BMP3M08188@momjian.us>
Subject: Re: Functions example results incorrect
In-Reply-To: <6044.1310080614@sss.pgh.pa.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 11 Jul 2011 18:25:03 -0400 (EDT)
CC: Thom Brown <thom@linux.com>, pgsql-docs <pgsql-docs@postgresql.org>
X-Mailer: ELM [version 2.4ME+ PL124 (25)]
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset="UNKNOWN-8BIT"
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.91 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	T_RP_MATCHES_RCVD=-0.01
X-Spam-Level: 
X-Archive-Number: 201107/10
X-Sequence-Number: 6877

Tom Lane wrote:
> Thom Brown <thom@linux.com> writes:
> > On 1 July 2011 19:17, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >> Thom Brown <thom@linux.com> writes:
> >>> The quote literal example of quote_literal('O\'Reilly') doesn't work
> >>> on my installation by default.
> 
> >> Hmm, should we use an E'' literal there, or change the input to be
> >> 'O''Reilly'?  The former would confuse people who didn't understand E''
> >> literals, while the latter would make it look like quote_literal wasn't
> >> doing anything at all, so neither alternative seems to offer much
> >> clarity.
> 
> > My concern is that people copying the example as a way to quote their
> > string literal will find that, by default, it doesn't work.  I'll
> > leave it to your better judgement though as I can see that the E''
> > notation could potentially confuse.   It is possible, either way, to
> > add a footnote to the example?
> 
> On further study, I notice that somebody already E-ified all the other
> examples where it was important; the quote_literal example simply got
> overlooked, I think.  It seems better to use E'' there than make the
> example potentially confusing as to what the function accomplishes.
> 
> Also, I looked at the examples for binary strings, and decided that
> converting the sample outputs to hex format would render the examples
> a lot less readable (since the inputs are not shown in that format).
> So instead I'm going to add this:
> 
>    <note>
>     <para>
>      The sample results shown on this page assume that the server parameter
>      <link linkend="guc-bytea-output"><varname>bytea_output</></link> is set
>      to <literal>escape</literal> (the traditional PostgreSQL format).
>     </para>
>    </note>

Please consider that the "traditional PostgreSQL format" is now not the
_default_ bytea_output format.  I think a lot of people equate
"traditional" with "default".

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

  + It's impossible for everything to be true. +