Received: from maia.hub.org (maia-5.hub.org [200.46.204.29])
	by mail.postgresql.org (Postfix) with ESMTP id 9FD561337B39
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Mon,  7 Feb 2011 11:59:55 -0400 (AST)
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 91979-04 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Mon,  7 Feb 2011 15:59:48 +0000 (UTC)
X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6
Received: from mail-iw0-f174.google.com (mail-iw0-f174.google.com
	[209.85.214.174])
	by mail.postgresql.org (Postfix) with ESMTP id DABB21336971
	for <pgsql-docs@postgresql.org>; Mon,  7 Feb 2011 11:59:47 -0400 (AST)
Received: by iwn9 with SMTP id 9so4719794iwn.19
	for <pgsql-docs@postgresql.org>; Mon, 07 Feb 2011 07:59:47 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=domainkey-signature:mime-version:in-reply-to:references:date
	:message-id:subject:from:to:cc:content-type
	:content-transfer-encoding;
	bh=gjxWCq8eABO1py3AtB+CXbuE7wuy0iEP/13YNJ2s0cM=;
	b=RrfsRdkE3/CP4VksS+9o8Tlk/mcT7lWYZRIVYdhTtNzRVcZtEUhiU/Lx4xF6aL43O6
	kTPVWAm2Apyha/lq8hPumZ21hIJ8zZg4Mq0D0FCQd7gCRNsFUROe0cY/hbfWnJDMZ4s7
	WqhARM/kvuIjrWZ5wMmYo2S1MBlf/gt4pt7k4=
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;
	h=mime-version:in-reply-to:references:date:message-id:subject:from:to
	:cc:content-type:content-transfer-encoding;
	b=WY7G3jLiPOuDk3St2c53J4yZ0M9we40TFzLzGPtqT+rcXtOp1qZb82bWiGsbVoIS/V
	qjKsX4WYNAPmOBrrOHd0G/2QfOTD2FOn1h6ksuZ2CrO2Lpm5/9icbR3Hi6YAJJdj0/AA
	g5XAs7rGWX915PmUn+1xoPNSd8d4bRHRfJZ+E=
MIME-Version: 1.0
Received: by 10.42.169.9 with SMTP id z9mr3189299icy.457.1297094387022; Mon,
	07 Feb 2011 07:59:47 -0800 (PST)
Received: by 10.42.164.74 with HTTP; Mon, 7 Feb 2011 07:59:47 -0800 (PST)
In-Reply-To: <15595.1297091285@sss.pgh.pa.us>
References: <AANLkTi=ytYtfkYYcb+_=JR=sByAwXNHD-J4-+T_EefaC@mail.gmail.com>
	<201102071454.p17EskV22239@momjian.us>
	<AANLkTim7FZvuqRB7r7yxcxFKgD0F241ue6o6BcxRUoX-@mail.gmail.com>
	<15595.1297091285@sss.pgh.pa.us>
Date: Mon, 7 Feb 2011 10:59:47 -0500
Message-ID: <AANLkTinvGSO2RXpmKvjQoA-6Ux7AxQB-T24GrsUBorcs@mail.gmail.com>
Subject: Re: [COMMITTERS] pgsql: remove tags.
From: Robert Haas <robertmhaas@gmail.com>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Bruce Momjian <bruce@momjian.us>,
	PostgreSQL-documentation <pgsql-docs@postgresql.org>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-2.599 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7
X-Spam-Level: 
X-Archive-Number: 201102/33
X-Sequence-Number: 6381

On Mon, Feb 7, 2011 at 10:08 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Robert Haas <robertmhaas@gmail.com> writes:
>> Which way did we more commonly do it before you applied this patch?
>
> We don't have a standard for this, and an undocumented patch applied
> without any discussion doesn't create one. =A0It's hopeless to imagine
> that you'll ever achieve any uniformity that way. =A0It won't last long
> if you do, since you're outnumbered by committers who won't be following
> whatever you think the convention is.
>
> I'm not even sure why you're trying --- I don't think it even makes
> sense to try to have a standard about this. =A0I can easily imagine that
> integer constants might read better with <literal> in some contexts
> and better without in others.

*reads patch more carefully*

Here are my verdicts:

advanced.sgml: good
array.sgml: good
backup.sgml: unsure
catalogs.sgml: bad
client-auth.sgml: bad
config.sgml: bad
func.sgml: bad
high-availability.sgml: bad
libpq.sgml: bad
runtime.sgml: bad
spi.sgml: unsure
tsearch2.sgml: good

So I guess I'm back agreeing with you.  Basically, it seems like we
ought to use <literal> if it's being used as a value that the user
might want to supply (e.g. "if you set this parameter to 0, then no
statements will be logged).  It shouldn't use <literal> if it's just
being used as a number (e.g. "this query will return all airplanes
with a height of less than 30,000 feet").  The cases I'm unsure about
are the ones where we're talking about a return value (e.g. in the
event of an error, this function will return -1).

--=20
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company