public inbox for [email protected]  

help / color / mirror / Atom feed

From: Josh Kupershmidt <[email protected]>
To: Tom Lane <[email protected]>
Cc: pgsql-docs <[email protected]>
Subject: Re: ALTER TABLE ... CLUSTER ON synopsis
Date: Tue, 22 May 2012 00:22:22 -0700
Message-ID: <CAK3UJRELqQhXnP61jy91Vkd6VeQhjaoU2eCdSAqnWGrwGaqP-w@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <CAK3UJRHkjC1PNzu+x+bATT0ku2TRipPUqq60NX4p1eqBw54z9Q@mail.gmail.com>
	<[email protected]>

On Mon, May 21, 2012 at 9:09 AM, Tom Lane <[email protected]> wrote:

> The main inconsistency I notice on that page is that some of the
> subform descriptions repeat the whole syntax while others only show
> the initial keyword(s).  Should we try to be more consistent about
> that, and if so, in which direction?

Well, that's far from the only inconsistency. Some commands are
described in separate lines in the beginning synopsis, and then
clumped together under a single description with vague instructions in
the body (e.g. RENAME COLUMN / RENAME CONSTRAINT / RENAME TO ). Some
commands give you all the syntax you need in the synopsis, and some
punt you to the ref page for CREATE TABLE or elsewhere for the syntax.
As you noted, some commands repeat the whole syntax and some show only
initial keyword(s). Others show only the latter half of the syntax and
hope you know what it's talking about (e.g. SET STATISTICS). Some
commands show up in the Examples section, some don't. Not all of the
possible parameters are documented under the "Parameters" section
(e.g. type_name seems to be missing).

The page is kind of a mess, but I'm a little unsure about how to
attack your issue and most of my gripes. I got the impression that the
intent for the subform descriptions you complained about was to show
the keywords in places where it was needed to distinguish the command
from some other similar one (e.g. RESET attribute_option vs. RESET
storage_parameter or ADD table_constraint vs. ADD
table_constraint_using_index), though of course that's not totally
consistent (e.g. INHERIT and NO INHERIT wouldn't need "parent_table"
under this rule in the Descriptions). Of course, other reference pages
seem to have different rules of thumb about when to list keywords in
the description: CREATE TABLE seems to like the keywords more.

Josh

view thread (4+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: ALTER TABLE ... CLUSTER ON synopsis
  In-Reply-To: <CAK3UJRELqQhXnP61jy91Vkd6VeQhjaoU2eCdSAqnWGrwGaqP-w@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox