Subject: ALTER TABLE ... CLUSTER ON synopsis

From: Josh Kupershmidt <[email-masked]>
Date: Sun, 20 May 2012 19:12:56 -0700

Hi all,

The reference page for ALTER TABLE[1] correctly has the synopsis:

    CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable>

but later leaves off the "ON" keyword:

    <term><literal>CLUSTER</literal></term>

I think the latter description should match the former, especially
since 'ON' is mandatory; small patch attached.

Josh

[1] http://www.postgresql.org/docs/devel/static/sql-altertable.html

---

From: Tom Lane <[email-masked]>
Date: Mon, 21 May 2012 12:09:25 -0400

> since 'ON' is mandatory; small patch attached.

Done, though I'm not sure we've ever tried to be consistent for such
things.

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?

			regards, tom lane

---

From: Josh Kupershmidt <[email-masked]>
Date: Tue, 22 May 2012 00:22:22 -0700

> 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

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 30 Aug 2012 09:41:01 -0400

> the description: CREATE TABLE seems to like the keywords more.

If anyone comes up with some concrete suggestions or a patch, please let
us know.

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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