Re: ALTER TABLE ... CLUSTER ON synopsis

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(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.

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

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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