Minor improvements in alter_table.sgml

Started by Etsuro Fujitaalmost 12 years ago8 messages

Etsuro Fujita

fujita.etsuro@lab.ntt.co.jp

almost 12 years ago

1 attachment(s)

Attached is a patch to improve the manual page for the ALTER TABLE command.

Thanks,

Best regards,
Etsuro Fujita

Attachments:

doc-altertable.patchtext/plain; charset=Shift_JIS; name=doc-altertable.patchDownload

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 0b08f83..ce67c71 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -625,8 +625,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
     <listitem>
      <para>
       The <literal>RENAME</literal> forms change the name of a table
-      (or an index, sequence, or view), the name of an individual column in
-      a table, or the name of a constraint of the table. There is no effect on the stored data.
+      (or an index, sequence, view, materialized view, or foreign table), the name
+      of an individual column in a table, or the name of a constraint of the table.
+      There is no effect on the stored data.
      </para>
     </listitem>
    </varlistentry>
@@ -717,7 +718,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">type</replaceable></term>
+      <term><replaceable class="PARAMETER">data_type</replaceable></term>
       <listitem>
        <para>
         Data type of the new column, or new data type for an existing
@@ -739,7 +740,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
       <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
       <listitem>
        <para>
-        Name of an existing constraint to drop.
+        Name of an existing constraint to alter, validate, or drop.
        </para>
       </listitem>
      </varlistentry>
@@ -836,6 +837,15 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
      </varlistentry>
 
      <varlistentry>
+      <term><replaceable class="PARAMETER">type_name</replaceable></term>
+      <listitem>
+       <para>
+        Name of an existing composite type.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><replaceable class="PARAMETER">new_owner</replaceable></term>
       <listitem>
        <para>

Robert Haas

robertmhaas@gmail.com

almost 12 years ago

In reply to: Etsuro Fujita (#1)

Re: Minor improvements in alter_table.sgml

On Tue, Apr 8, 2014 at 5:05 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is a patch to improve the manual page for the ALTER TABLE command.

Do we really need to add a section for "type_name" when we already
have a section for "OF type_name"?

constraint_name is also used for adding a constraint using an index.
So it could not only be a constraint to alter, validate, or drop, but
also a new constraint name to be added. Honestly, how much value is
there in even having a section for this? Do we really want to
document constraint_name as "name of an existing constraint, or the
name of a new constraint to be added"? It would be accurate, then,
but it also doesn't really tell you anything you didn't know already.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Etsuro Fujita

fujita.etsuro@lab.ntt.co.jp

almost 12 years ago

In reply to: Robert Haas (#2)

Re: Minor improvements in alter_table.sgml

(2014/04/09 1:23), Robert Haas wrote:

On Tue, Apr 8, 2014 at 5:05 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is a patch to improve the manual page for the ALTER TABLE command.

Do we really need to add a section for "type_name" when we already
have a section for "OF type_name"?

I think that the section for "type_name" would be necessary as that in
chapter "Parameters", not in chapter "Description", which includes the
section for "OF type_name".

constraint_name is also used for adding a constraint using an index.
So it could not only be a constraint to alter, validate, or drop, but
also a new constraint name to be added.

I overlooked that.

Honestly, how much value is
there in even having a section for this? Do we really want to
document constraint_name as "name of an existing constraint, or the
name of a new constraint to be added"? It would be accurate, then,
but it also doesn't really tell you anything you didn't know already.

You have a point there, but I feel odd about the documentation as is,
because some are well written (eg, column_name) and some are not (eg,
constraint_name). So, if there are no objections, I'd like to update
the patch.

Thanks,

Best regards,
Etsuro Fujita

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Etsuro Fujita

fujita.etsuro@lab.ntt.co.jp

almost 12 years ago

In reply to: Etsuro Fujita (#3)

1 attachment(s)

Re: Minor improvements in alter_table.sgml

(2014/04/09 12:03), Etsuro Fujita wrote:

(2014/04/09 1:23), Robert Haas wrote:

On Tue, Apr 8, 2014 at 5:05 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is a patch to improve the manual page for the ALTER TABLE
command.

Do we really need to add a section for "type_name" when we already
have a section for "OF type_name"?

I think that the section for "type_name" would be necessary as that in
chapter "Parameters", not in chapter "Description", which includes the
section for "OF type_name".

constraint_name is also used for adding a constraint using an index.
So it could not only be a constraint to alter, validate, or drop, but
also a new constraint name to be added.

I overlooked that.

Honestly, how much value is
there in even having a section for this? Do we really want to
document constraint_name as "name of an existing constraint, or the
name of a new constraint to be added"? It would be accurate, then,
but it also doesn't really tell you anything you didn't know already.

You have a point there, but I feel odd about the documentation as is,
because some are well written (eg, column_name) and some are not (eg,
constraint_name). So, if there are no objections, I'd like to update
the patch.

Attached is an updated version of the patch.

Thanks,

Best regards,
Etsuro Fujita

Attachments:

doc-altertable-v2.patchtext/plain; charset=Shift_JIS; name=doc-altertable-v2.patchDownload

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 0b08f83..c16fc19 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -582,8 +582,8 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
     <term><literal>OWNER</literal></term>
     <listitem>
      <para>
-      This form changes the owner of the table, sequence, or view to the
-      specified user.
+      This form changes the owner of the table, sequence, view, materialized view,
+      or foreign table to the specified user.
      </para>
     </listitem>
    </varlistentry>
@@ -625,8 +625,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
     <listitem>
      <para>
       The <literal>RENAME</literal> forms change the name of a table
-      (or an index, sequence, or view), the name of an individual column in
-      a table, or the name of a constraint of the table. There is no effect on the stored data.
+      (or an index, sequence, view, materialized view, or foreign table), the name
+      of an individual column in a table, or the name of a constraint of the table.
+      There is no effect on the stored data.
      </para>
     </listitem>
    </varlistentry>
@@ -708,38 +709,47 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">new_name</replaceable></term>
+      <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
       <listitem>
        <para>
-        New name for the table.
+        Name of a new or existing constraint.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">type</replaceable></term>
+      <term><replaceable class="PARAMETER">new_constraint_name</replaceable></term>
       <listitem>
        <para>
-        Data type of the new column, or new data type for an existing
-        column.
+        New name for an existing constraint.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">table_constraint</replaceable></term>
+      <term><replaceable class="PARAMETER">new_name</replaceable></term>
       <listitem>
        <para>
-        New table constraint for the table.
+        New name for the table.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
+      <term><replaceable class="PARAMETER">data_type</replaceable></term>
       <listitem>
        <para>
-        Name of an existing constraint to drop.
+        Data type of the new column, or new data type for an existing
+        column.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="PARAMETER">table_constraint</replaceable></term>
+      <listitem>
+       <para>
+        New table constraint for the table.
        </para>
       </listitem>
      </varlistentry>
@@ -799,6 +809,15 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
      </varlistentry>
 
      <varlistentry>
+      <term><replaceable class="PARAMETER">rewrite_rule_name</replaceable></term>
+      <listitem>
+       <para>
+        Name of a single rewrite rule to disable or enable.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><replaceable class="PARAMETER">index_name</replaceable></term>
       <listitem>
        <para>
@@ -836,6 +855,15 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
      </varlistentry>
 
      <varlistentry>
+      <term><replaceable class="PARAMETER">type_name</replaceable></term>
+      <listitem>
+       <para>
+        The name of a composite type.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><replaceable class="PARAMETER">new_owner</replaceable></term>
       <listitem>
        <para>

Robert Haas

robertmhaas@gmail.com

over 11 years ago

In reply to: Etsuro Fujita (#4)

Re: Minor improvements in alter_table.sgml

On Fri, Apr 11, 2014 at 5:00 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is an updated version of the patch.

I applied the first two hunks of this, which seem like clear
oversights; and also the bit fixing the constraint_name language.

I think the other changes deserve to be considered separately, and in
particular I'm still not sure it's a good idea to document both OF
type_name and type_name.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Etsuro Fujita

fujita.etsuro@lab.ntt.co.jp

over 11 years ago

In reply to: Robert Haas (#5)

Re: Minor improvements in alter_table.sgml

(2014/04/14 23:53), Robert Haas wrote:

On Fri, Apr 11, 2014 at 5:00 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is an updated version of the patch.

I applied the first two hunks of this, which seem like clear
oversights; and also the bit fixing the constraint_name language.

I think the other changes deserve to be considered separately, and in
particular I'm still not sure it's a good idea to document both OF
type_name and type_name.

OK, Thanks!

Best regards,
Etsuro Fujita

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Etsuro Fujita

fujita.etsuro@lab.ntt.co.jp

over 11 years ago

In reply to: Etsuro Fujita (#6)

2 attachment(s)

Re: Minor improvements in alter_table.sgml

(2014/04/15 15:27), Etsuro Fujita wrote:

(2014/04/14 23:53), Robert Haas wrote:

On Fri, Apr 11, 2014 at 5:00 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is an updated version of the patch.

I think the other changes deserve to be considered separately, and in
particular I'm still not sure it's a good idea to document both OF
type_name and type_name.

I've agreed on that point, but I think apart from the others, the
trivial typo should be corrected. Patch attached
(doc-altertable-typo.patch).

I noticed the description of index_name should also be corrected,
because it is currently used not only in CLUSTER ON, but in ADD
table_constraint_using_index. (It will also be used in REPLICA IDENTITY
in 9.4.) Patch attached (doc-altertable-indexname.patch).

Thanks,

Best regards,
Etsuro Fujita

Attachments:

doc-altertable-typo.patchtext/plain; charset=Shift_JIS; name=doc-altertable-typo.patchDownload

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 85705e9..42167d8 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -720,7 +720,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="PARAMETER">type</replaceable></term>
+      <term><replaceable class="PARAMETER">data_type</replaceable></term>
       <listitem>
        <para>
         Data type of the new column, or new data type for an existing

doc-altertable-indexname.patchtext/plain; charset=Shift_JIS; name=doc-altertable-indexname.patchDownload

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 85705e9..0354dde 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -805,7 +805,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
       <term><replaceable class="PARAMETER">index_name</replaceable></term>
       <listitem>
        <para>
-        The index name on which the table should be marked for clustering.
+        The name of an existing index.
        </para>
       </listitem>
      </varlistentry>

Robert Haas

robertmhaas@gmail.com

over 11 years ago

In reply to: Etsuro Fujita (#7)

Re: Minor improvements in alter_table.sgml

On Wed, Apr 23, 2014 at 3:46 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

(2014/04/15 15:27), Etsuro Fujita wrote:

(2014/04/14 23:53), Robert Haas wrote:

On Fri, Apr 11, 2014 at 5:00 AM, Etsuro Fujita
<fujita.etsuro@lab.ntt.co.jp> wrote:

Attached is an updated version of the patch.

I think the other changes deserve to be considered separately, and in
particular I'm still not sure it's a good idea to document both OF
type_name and type_name.

I've agreed on that point, but I think apart from the others, the trivial
typo should be corrected. Patch attached (doc-altertable-typo.patch).

I noticed the description of index_name should also be corrected, because it
is currently used not only in CLUSTER ON, but in ADD
table_constraint_using_index. (It will also be used in REPLICA IDENTITY in
9.4.) Patch attached (doc-altertable-indexname.patch).

Agreed. Committed.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers