Thread: ALTER TABLE ... CLUSTER ON synopsis
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
Attachment
Josh Kupershmidt <schmiddy@gmail.com> writes:
> 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.
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
On Mon, May 21, 2012 at 9:09 AM, Tom Lane <tgl@sss.pgh.pa.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
On Tue, May 22, 2012 at 12:22:22AM -0700, Josh Kupershmidt wrote: > On Mon, May 21, 2012 at 9:09 AM, Tom Lane <tgl@sss.pgh.pa.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. If anyone comes up with some concrete suggestions or a patch, please let us know. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +