Re: ALTER TABLE ... CLUSTER ON synopsis

On Mon, May 21, 2012 at 9:09 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> 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