Received: from maia.hub.org (maia-5.hub.org [200.46.204.29])
	by mail.postgresql.org (Postfix) with ESMTP id 44F74B5DBFB
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Thu,  7 Jul 2011 20:17:03 -0300 (ADT)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.29]) (amavisd-maia, port 10024)
	with ESMTP id 30854-08 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Thu,  7 Jul 2011 23:16:57 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.6
Received: from sss.pgh.pa.us (sss.pgh.pa.us [66.207.139.130])
	by mail.postgresql.org (Postfix) with ESMTP id ED719B5DBF4
	for <pgsql-docs@postgresql.org>; Thu,  7 Jul 2011 20:16:56 -0300 (ADT)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.2/8.14.2) with ESMTP id p67NGsUJ006045;
	Thu, 7 Jul 2011 19:16:55 -0400 (EDT)
To: Thom Brown <thom@linux.com>
cc: pgsql-docs <pgsql-docs@postgresql.org>
Subject: Re: Functions example results incorrect 
In-reply-to: <BANLkTikkiorhu6AEDcP8LcTUA+unMnhHeg@mail.gmail.com> 
References: <BANLkTimct3DOjrcXqzV9cCWdzFVF_HFYLw@mail.gmail.com>
	<1830.1309544251@sss.pgh.pa.us>
	<BANLkTikkiorhu6AEDcP8LcTUA+unMnhHeg@mail.gmail.com>
Comments: In-reply-to Thom Brown <thom@linux.com>
	message dated "Fri, 01 Jul 2011 19:33:18 +0100"
Date: Thu, 07 Jul 2011 19:16:54 -0400
Message-ID: <6044.1310080614@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
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/7
X-Sequence-Number: 6874

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>

			regards, tom lane