public inbox for [email protected]
help / color / mirror / Atom feedALTER TABLE ... CLUSTER ON synopsis
4+ messages / 3 participants
[nested] [flat]
* ALTER TABLE ... CLUSTER ON synopsis
@ 2012-05-21 02:12 Josh Kupershmidt <[email protected]>
0 siblings, 1 reply; 4+ messages in thread
From: Josh Kupershmidt @ 2012-05-21 02:12 UTC (permalink / raw)
To: pgsql-docs
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
Attachments:
[application/octet-stream] alter_table_cluster_on.diff (653B, 2-alter_table_cluster_on.diff)
download | inline diff:
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
new file mode 100644
index a39cb8f..04e3e54
*** a/doc/src/sgml/ref/alter_table.sgml
--- b/doc/src/sgml/ref/alter_table.sgml
*************** ALTER TABLE [ IF EXISTS ] <replaceable c
*** 387,393 ****
</varlistentry>
<varlistentry>
! <term><literal>CLUSTER</literal></term>
<listitem>
<para>
This form selects the default index for future
--- 387,393 ----
</varlistentry>
<varlistentry>
! <term><literal>CLUSTER ON</literal></term>
<listitem>
<para>
This form selects the default index for future
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: ALTER TABLE ... CLUSTER ON synopsis
@ 2012-05-21 16:09 Tom Lane <[email protected]>
parent: Josh Kupershmidt <[email protected]>
0 siblings, 1 reply; 4+ messages in thread
From: Tom Lane @ 2012-05-21 16:09 UTC (permalink / raw)
To: Josh Kupershmidt <[email protected]>; +Cc: pgsql-docs
Josh Kupershmidt <[email protected]> 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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: ALTER TABLE ... CLUSTER ON synopsis
@ 2012-05-22 07:22 Josh Kupershmidt <[email protected]>
parent: Tom Lane <[email protected]>
0 siblings, 1 reply; 4+ messages in thread
From: Josh Kupershmidt @ 2012-05-22 07:22 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: pgsql-docs
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.
Josh
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: ALTER TABLE ... CLUSTER ON synopsis
@ 2012-08-30 13:41 Bruce Momjian <[email protected]>
parent: Josh Kupershmidt <[email protected]>
0 siblings, 0 replies; 4+ messages in thread
From: Bruce Momjian @ 2012-08-30 13:41 UTC (permalink / raw)
To: Josh Kupershmidt <[email protected]>; +Cc: Tom Lane <[email protected]>; pgsql-docs
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. +
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2012-08-30 13:41 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2012-05-21 02:12 ALTER TABLE ... CLUSTER ON synopsis Josh Kupershmidt <[email protected]>
2012-05-21 16:09 ` Tom Lane <[email protected]>
2012-05-22 07:22 ` Josh Kupershmidt <[email protected]>
2012-08-30 13:41 ` Bruce Momjian <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox