public inbox for [email protected]  

help / color / mirror / Atom feed

From: Bruce Momjian <[email protected]>
To: Josh Kupershmidt <[email protected]>
Cc: Tom Lane <[email protected]>
Cc: pgsql-docs <[email protected]>
Subject: Re: ALTER TABLE ... CLUSTER ON synopsis
Date: Thu, 30 Aug 2012 09:41:01 -0400
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAK3UJRELqQhXnP61jy91Vkd6VeQhjaoU2eCdSAqnWGrwGaqP-w@mail.gmail.com>
References: <CAK3UJRHkjC1PNzu+x+bATT0ku2TRipPUqq60NX4p1eqBw54z9Q@mail.gmail.com>
	<[email protected]>
	<CAK3UJRELqQhXnP61jy91Vkd6VeQhjaoU2eCdSAqnWGrwGaqP-w@mail.gmail.com>

On Tue, May 22, 2012 at 12:22:22AM -0700, Josh Kupershmidt wrote:
> On Mon, May 21, 2012 at 9:09 AM, Tom Lane <[email protected]> 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  <[email protected]>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

view thread (4+ messages)

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: ALTER TABLE ... CLUSTER ON synopsis
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox