Received: from magus.postgresql.org ([87.238.57.229]) by malur.postgresql.org with esmtp (Exim 4.72) (envelope-from ) id 1T74zZ-0005rj-FL for pgsql-docs@postgresql.org; Thu, 30 Aug 2012 13:41:05 +0000 Received: from momjian.us ([72.94.173.45]) by magus.postgresql.org with esmtp (Exim 4.72) (envelope-from ) id 1T74zX-00077f-8p for pgsql-docs@postgresql.org; Thu, 30 Aug 2012 13:41:05 +0000 Received: from bruce by momjian.us with local (Exim 4.72) (envelope-from ) id 1T74zV-0000cB-Vf; Thu, 30 Aug 2012 09:41:01 -0400 Date: Thu, 30 Aug 2012 09:41:01 -0400 From: Bruce Momjian To: Josh Kupershmidt Cc: Tom Lane , pgsql-docs Subject: Re: ALTER TABLE ... CLUSTER ON synopsis Message-ID: <20120830134101.GN8753@momjian.us> References: <17585.1337616565@sss.pgh.pa.us> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.5.20 (2009-06-14) X-Pg-Spam-Score: -2.1 (--) X-Archive-Number: 201208/52 X-Sequence-Number: 7445 On Tue, May 22, 2012 at 12:22:22AM -0700, Josh Kupershmidt wrote: > On Mon, May 21, 2012 at 9:09 AM, Tom Lane 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 http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. +