Обсуждение: Ambiguous index entry for Privileges

I noticed that there are 2 linked entries for "Privileges":
http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982

While they both go to different pages (with admittedly very similar
content), those pages are both entitled "Privileges" so it's unclear
from the index which page you'll end up at.  Can we rename one of
those pages to clarify as it looks weird in the index.

Thanks

Thom
--
Thom Brown
Registered Linux user: #516935

On 12 August 2010 00:05, Thom Brown <thom@linux.com> wrote:
> I noticed that there are 2 linked entries for "Privileges":
> http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982
>
> While they both go to different pages (with admittedly very similar
> content), those pages are both entitled "Privileges" so it's unclear
> from the index which page you'll end up at.  Can we rename one of
> those pages to clarify as it looks weird in the index.
>

Does anyone have an opinion on this?

--
Thom Brown
Registered Linux user: #516935

Thom Brown <thom@linux.com> wrote:
> On 12 August 2010 00:05, Thom Brown <thom@linux.com> wrote:
>> I noticed that there are 2 linked entries for "Privileges":
>> http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982
>>
>> While they both go to different pages (with admittedly very
>> similar content), those pages are both entitled "Privileges" so
>> it's unclear from the index which page you'll end up at.  Can we
>> rename one of those pages to clarify as it looks weird in the
>> index.
>
> Does anyone have an opinion on this?

Sure -- I think the page at
http://www.postgresql.org/docs/9.0/static/privileges.html (in
"Chapter 20. Database Roles and Privileges" should be more
conceptual rather than a subset of the other page.  Rather than
explaining how to use GRANT and REVOKE to change privileges, it
should give an overview of privileges and discuss what is allowed by
each particular privilege.  It could link to the other page, so
there would be one place to keep up-to-date on how to grant and
revoke privileges.

I think the page at
http://www.postgresql.org/docs/9.0/static/ddl-priv.html (in "Chapter
5. Data Definition") should be renamed to something more like
"Modifying Privileges" or "Granting and Revoking Privileges" (or
something to that effect).  It might make sense to have its entry in
the index be a secondary entry under privilege, with some similar
qualification.

-Kevin

On tor, 2010-08-12 at 00:05 +0100, Thom Brown wrote:
> I noticed that there are 2 linked entries for "Privileges":
> http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982
>
> While they both go to different pages (with admittedly very similar
> content), those pages are both entitled "Privileges" so it's unclear
> from the index which page you'll end up at.  Can we rename one of
> those pages to clarify as it looks weird in the index.

In general, you could also make one of the indexterms
significance="preferred", which will make it italic.  Not sure if that
is appropriate here.

Kevin Grittner wrote:
> Thom Brown <thom@linux.com> wrote:
> > On 12 August 2010 00:05, Thom Brown <thom@linux.com> wrote:
> >> I noticed that there are 2 linked entries for "Privileges":
> >> http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982
> >>
> >> While they both go to different pages (with admittedly very
> >> similar content), those pages are both entitled "Privileges" so
> >> it's unclear from the index which page you'll end up at.  Can we
> >> rename one of those pages to clarify as it looks weird in the
> >> index.
> >
> > Does anyone have an opinion on this?
>
> Sure -- I think the page at
> http://www.postgresql.org/docs/9.0/static/privileges.html (in
> "Chapter 20. Database Roles and Privileges" should be more
> conceptual rather than a subset of the other page.  Rather than
> explaining how to use GRANT and REVOKE to change privileges, it
> should give an overview of privileges and discuss what is allowed by
> each particular privilege.  It could link to the other page, so
> there would be one place to keep up-to-date on how to grant and
> revoke privileges.
>
> I think the page at
> http://www.postgresql.org/docs/9.0/static/ddl-priv.html (in "Chapter
> 5. Data Definition") should be renamed to something more like
> "Modifying Privileges" or "Granting and Revoking Privileges" (or
> something to that effect).  It might make sense to have its entry in
> the index be a secondary entry under privilege, with some similar
> qualification.

I went even farther.  I think there is no need to discuss object
permissions in the database roles chapter.  We already link to the DDL
section, so I just changed that to link specifically to the DDL
privileges section, and made that DDL privileges section be a
super-set of the two old sections.

Patch attached.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

  + It's impossible for everything to be true. +
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index a65b4bc..519afd6 100644
*** a/doc/src/sgml/ddl.sgml
--- b/doc/src/sgml/ddl.sgml
*************** ALTER TABLE products RENAME TO items;
*** 1400,1412 ****
     <see>privilege</see>
    </indexterm>

    <para>
!    When you create a database object, you become its owner.  By
!    default, only the owner of an object can do anything with the
!    object. In order to allow other users to use it,
!    <firstterm>privileges</firstterm> must be granted.  (However,
!    users that have the superuser attribute can always
!    access any object.)
    </para>

    <para>
--- 1400,1432 ----
     <see>privilege</see>
    </indexterm>

+   <indexterm zone="ddl-priv">
+    <primary>owner</primary>
+   </indexterm>
+
+   <indexterm zone="ddl-priv">
+    <primary>GRANT</primary>
+   </indexterm>
+
+   <indexterm zone="ddl-priv">
+    <primary>REVOKE</primary>
+   </indexterm>
+
    <para>
!    When an object is created, it is assigned an owner. The
!    owner is normally the role that executed the creation statement.
!    For most kinds of objects, the initial state is that only the owner
!    (or a superuser) can do anything with the object. To allow
!    other roles to use it, <firstterm>privileges</firstterm> must be
!    granted.
!    There are several different kinds of privilege: <literal>SELECT</>,
!    <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
!    <literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
!    <literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
!    <literal>EXECUTE</>, and <literal>USAGE</>.
!    For more information on the different types of privileges supported by
!    <productname>PostgreSQL</productname>, see the
!    <xref linkend="sql-grant"> reference page.
    </para>

    <para>
*************** ALTER TABLE products RENAME TO items;
*** 1429,1442 ****
     the owner only.
    </para>

!   <note>
!    <para>
!     To change the owner of a table, index, sequence, or view, use the
!     <xref linkend="sql-altertable">
!     command.  There are corresponding <literal>ALTER</> commands for
!     other object types.
!    </para>
!   </note>

    <para>
     To assign privileges, the <command>GRANT</command> command is
--- 1449,1462 ----
     the owner only.
    </para>

!   <para>
!    An object can be assigned to a new owner with an <command>ALTER</command>
!    command of the appropriate kind for the object, e.g. <xref
!    linkend="sql-altertable">.  Superusers can always do
!    this; ordinary roles can only do it if they are both the current owner
!    of the object (or a member of the owning role) and a member of the new
!    owning role.
!   </para>

    <para>
     To assign privileges, the <command>GRANT</command> command is
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 2830aec..6a52827 100644
*** a/doc/src/sgml/user-manag.sgml
--- b/doc/src/sgml/user-manag.sgml
***************
*** 1,7 ****
  <!-- doc/src/sgml/user-manag.sgml -->

  <chapter id="user-manag">
!  <title>Database Roles and Privileges</title>

   <para>
    <productname>PostgreSQL</productname> manages database access permissions
--- 1,7 ----
  <!-- doc/src/sgml/user-manag.sgml -->

  <chapter id="user-manag">
!  <title>Database Roles</title>

   <para>
    <productname>PostgreSQL</productname> manages database access permissions
***************
*** 22,31 ****
   </para>

   <para>
!   This chapter describes how to create and manage roles and introduces
!   the privilege system.  More information about the various types of
!   database objects and the effects of privileges can be found in
!   <xref linkend="ddl">.
   </para>

   <sect1 id="database-roles">
--- 22,30 ----
   </para>

   <para>
!   This chapter describes how to create and manage roles.
!   More information about the effects of privileges on various database
!   objects can be found in <xref linkend="ddl-priv">.
   </para>

   <sect1 id="database-roles">
*************** ALTER ROLE myname SET enable_indexscan T
*** 282,362 ****
    </para>
   </sect1>

-  <sect1 id="privileges">
-   <title>Privileges</title>
-
-   <indexterm zone="privileges">
-    <primary>privilege</primary>
-   </indexterm>
-
-   <indexterm zone="privileges">
-    <primary>owner</primary>
-   </indexterm>
-
-   <indexterm zone="privileges">
-    <primary>GRANT</primary>
-   </indexterm>
-
-   <indexterm zone="privileges">
-    <primary>REVOKE</primary>
-   </indexterm>
-
-   <para>
-    When an object is created, it is assigned an owner. The
-    owner is normally the role that executed the creation statement.
-    For most kinds of objects, the initial state is that only the owner
-    (or a superuser) can do anything with the object. To allow
-    other roles to use it, <firstterm>privileges</firstterm> must be
-    granted.
-    There are several different kinds of privilege: <literal>SELECT</>,
-    <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
-    <literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
-    <literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
-    <literal>EXECUTE</>, and <literal>USAGE</>.
-    For more information on the different types of privileges supported by
-    <productname>PostgreSQL</productname>, see the
-    <xref linkend="sql-grant"> reference page.
-   </para>
-
-   <para>
-    To assign privileges, the <command>GRANT</command> command is
-    used. So, if <literal>joe</literal> is an existing role, and
-    <literal>accounts</literal> is an existing table, the privilege to
-    update the table can be granted with:
- <programlisting>
- GRANT UPDATE ON accounts TO joe;
- </programlisting>
-    The special name <literal>PUBLIC</literal> can
-    be used to grant a privilege to every role on the system. Writing
-    <literal>ALL</literal> in place of a specific privilege specifies that all
-    privileges that apply to the object will be granted.
-   </para>
-
-   <para>
-    To revoke a privilege, use the fittingly named
-    <xref linkend="sql-revoke"> command:
- <programlisting>
- REVOKE ALL ON accounts FROM PUBLIC;
- </programlisting>
-   </para>
-
-   <para>
-    The special privileges of an object's owner (i.e., the right to modify
-    or destroy the object) are always implicit in being the owner,
-    and cannot be granted or revoked.  But the owner can choose
-    to revoke his own ordinary privileges, for example to make a
-    table read-only for himself as well as others.
-   </para>
-
-   <para>
-    An object can be assigned to a new owner with an <command>ALTER</command>
-    command of the appropriate kind for the object.  Superusers can always do
-    this; ordinary roles can only do it if they are both the current owner
-    of the object (or a member of the owning role) and a member of the new
-    owning role.
-   </para>
-  </sect1>
-
   <sect1 id="role-membership">
    <title>Role Membership</title>

--- 281,286 ----

Applied.

---------------------------------------------------------------------------

Bruce Momjian wrote:
> Kevin Grittner wrote:
> > Thom Brown <thom@linux.com> wrote:
> > > On 12 August 2010 00:05, Thom Brown <thom@linux.com> wrote:
> > >> I noticed that there are 2 linked entries for "Privileges":
> > >> http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982
> > >>
> > >> While they both go to different pages (with admittedly very
> > >> similar content), those pages are both entitled "Privileges" so
> > >> it's unclear from the index which page you'll end up at.  Can we
> > >> rename one of those pages to clarify as it looks weird in the
> > >> index.
> > >
> > > Does anyone have an opinion on this?
> >
> > Sure -- I think the page at
> > http://www.postgresql.org/docs/9.0/static/privileges.html (in
> > "Chapter 20. Database Roles and Privileges" should be more
> > conceptual rather than a subset of the other page.  Rather than
> > explaining how to use GRANT and REVOKE to change privileges, it
> > should give an overview of privileges and discuss what is allowed by
> > each particular privilege.  It could link to the other page, so
> > there would be one place to keep up-to-date on how to grant and
> > revoke privileges.
> >
> > I think the page at
> > http://www.postgresql.org/docs/9.0/static/ddl-priv.html (in "Chapter
> > 5. Data Definition") should be renamed to something more like
> > "Modifying Privileges" or "Granting and Revoking Privileges" (or
> > something to that effect).  It might make sense to have its entry in
> > the index be a secondary entry under privilege, with some similar
> > qualification.
>
> I went even farther.  I think there is no need to discuss object
> permissions in the database roles chapter.  We already link to the DDL
> section, so I just changed that to link specifically to the DDL
> privileges section, and made that DDL privileges section be a
> super-set of the two old sections.
>
> Patch attached.
>
> --
>   Bruce Momjian  <bruce@momjian.us>        http://momjian.us
>   EnterpriseDB                             http://enterprisedb.com
>
>   + It's impossible for everything to be true. +

[ text/x-diff is unsupported, treating like TEXT/PLAIN ]

> diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
> index a65b4bc..519afd6 100644
> *** a/doc/src/sgml/ddl.sgml
> --- b/doc/src/sgml/ddl.sgml
> *************** ALTER TABLE products RENAME TO items;
> *** 1400,1412 ****
>      <see>privilege</see>
>     </indexterm>
>
>     <para>
> !    When you create a database object, you become its owner.  By
> !    default, only the owner of an object can do anything with the
> !    object. In order to allow other users to use it,
> !    <firstterm>privileges</firstterm> must be granted.  (However,
> !    users that have the superuser attribute can always
> !    access any object.)
>     </para>
>
>     <para>
> --- 1400,1432 ----
>      <see>privilege</see>
>     </indexterm>
>
> +   <indexterm zone="ddl-priv">
> +    <primary>owner</primary>
> +   </indexterm>
> +
> +   <indexterm zone="ddl-priv">
> +    <primary>GRANT</primary>
> +   </indexterm>
> +
> +   <indexterm zone="ddl-priv">
> +    <primary>REVOKE</primary>
> +   </indexterm>
> +
>     <para>
> !    When an object is created, it is assigned an owner. The
> !    owner is normally the role that executed the creation statement.
> !    For most kinds of objects, the initial state is that only the owner
> !    (or a superuser) can do anything with the object. To allow
> !    other roles to use it, <firstterm>privileges</firstterm> must be
> !    granted.
> !    There are several different kinds of privilege: <literal>SELECT</>,
> !    <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
> !    <literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
> !    <literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
> !    <literal>EXECUTE</>, and <literal>USAGE</>.
> !    For more information on the different types of privileges supported by
> !    <productname>PostgreSQL</productname>, see the
> !    <xref linkend="sql-grant"> reference page.
>     </para>
>
>     <para>
> *************** ALTER TABLE products RENAME TO items;
> *** 1429,1442 ****
>      the owner only.
>     </para>
>
> !   <note>
> !    <para>
> !     To change the owner of a table, index, sequence, or view, use the
> !     <xref linkend="sql-altertable">
> !     command.  There are corresponding <literal>ALTER</> commands for
> !     other object types.
> !    </para>
> !   </note>
>
>     <para>
>      To assign privileges, the <command>GRANT</command> command is
> --- 1449,1462 ----
>      the owner only.
>     </para>
>
> !   <para>
> !    An object can be assigned to a new owner with an <command>ALTER</command>
> !    command of the appropriate kind for the object, e.g. <xref
> !    linkend="sql-altertable">.  Superusers can always do
> !    this; ordinary roles can only do it if they are both the current owner
> !    of the object (or a member of the owning role) and a member of the new
> !    owning role.
> !   </para>
>
>     <para>
>      To assign privileges, the <command>GRANT</command> command is
> diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
> index 2830aec..6a52827 100644
> *** a/doc/src/sgml/user-manag.sgml
> --- b/doc/src/sgml/user-manag.sgml
> ***************
> *** 1,7 ****
>   <!-- doc/src/sgml/user-manag.sgml -->
>
>   <chapter id="user-manag">
> !  <title>Database Roles and Privileges</title>
>
>    <para>
>     <productname>PostgreSQL</productname> manages database access permissions
> --- 1,7 ----
>   <!-- doc/src/sgml/user-manag.sgml -->
>
>   <chapter id="user-manag">
> !  <title>Database Roles</title>
>
>    <para>
>     <productname>PostgreSQL</productname> manages database access permissions
> ***************
> *** 22,31 ****
>    </para>
>
>    <para>
> !   This chapter describes how to create and manage roles and introduces
> !   the privilege system.  More information about the various types of
> !   database objects and the effects of privileges can be found in
> !   <xref linkend="ddl">.
>    </para>
>
>    <sect1 id="database-roles">
> --- 22,30 ----
>    </para>
>
>    <para>
> !   This chapter describes how to create and manage roles.
> !   More information about the effects of privileges on various database
> !   objects can be found in <xref linkend="ddl-priv">.
>    </para>
>
>    <sect1 id="database-roles">
> *************** ALTER ROLE myname SET enable_indexscan T
> *** 282,362 ****
>     </para>
>    </sect1>
>
> -  <sect1 id="privileges">
> -   <title>Privileges</title>
> -
> -   <indexterm zone="privileges">
> -    <primary>privilege</primary>
> -   </indexterm>
> -
> -   <indexterm zone="privileges">
> -    <primary>owner</primary>
> -   </indexterm>
> -
> -   <indexterm zone="privileges">
> -    <primary>GRANT</primary>
> -   </indexterm>
> -
> -   <indexterm zone="privileges">
> -    <primary>REVOKE</primary>
> -   </indexterm>
> -
> -   <para>
> -    When an object is created, it is assigned an owner. The
> -    owner is normally the role that executed the creation statement.
> -    For most kinds of objects, the initial state is that only the owner
> -    (or a superuser) can do anything with the object. To allow
> -    other roles to use it, <firstterm>privileges</firstterm> must be
> -    granted.
> -    There are several different kinds of privilege: <literal>SELECT</>,
> -    <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
> -    <literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
> -    <literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
> -    <literal>EXECUTE</>, and <literal>USAGE</>.
> -    For more information on the different types of privileges supported by
> -    <productname>PostgreSQL</productname>, see the
> -    <xref linkend="sql-grant"> reference page.
> -   </para>
> -
> -   <para>
> -    To assign privileges, the <command>GRANT</command> command is
> -    used. So, if <literal>joe</literal> is an existing role, and
> -    <literal>accounts</literal> is an existing table, the privilege to
> -    update the table can be granted with:
> - <programlisting>
> - GRANT UPDATE ON accounts TO joe;
> - </programlisting>
> -    The special name <literal>PUBLIC</literal> can
> -    be used to grant a privilege to every role on the system. Writing
> -    <literal>ALL</literal> in place of a specific privilege specifies that all
> -    privileges that apply to the object will be granted.
> -   </para>
> -
> -   <para>
> -    To revoke a privilege, use the fittingly named
> -    <xref linkend="sql-revoke"> command:
> - <programlisting>
> - REVOKE ALL ON accounts FROM PUBLIC;
> - </programlisting>
> -   </para>
> -
> -   <para>
> -    The special privileges of an object's owner (i.e., the right to modify
> -    or destroy the object) are always implicit in being the owner,
> -    and cannot be granted or revoked.  But the owner can choose
> -    to revoke his own ordinary privileges, for example to make a
> -    table read-only for himself as well as others.
> -   </para>
> -
> -   <para>
> -    An object can be assigned to a new owner with an <command>ALTER</command>
> -    command of the appropriate kind for the object.  Superusers can always do
> -    this; ordinary roles can only do it if they are both the current owner
> -    of the object (or a member of the owning role) and a member of the new
> -    owning role.
> -   </para>
> -  </sect1>
> -
>    <sect1 id="role-membership">
>     <title>Role Membership</title>
>
> --- 281,286 ----

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

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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

On 21 February 2011 03:21, Bruce Momjian <bruce@momjian.us> wrote:
>
> Applied.
>
> ---------------------------------------------------------------------------
>
> Bruce Momjian wrote:
>> Kevin Grittner wrote:
>> > Thom Brown <thom@linux.com> wrote:
>> > > On 12 August 2010 00:05, Thom Brown <thom@linux.com> wrote:
>> > >> I noticed that there are 2 linked entries for "Privileges":
>> > >> http://www.postgresql.org/docs/9.0/static/bookindex.html#AEN128982
>> > >>
>> > >> While they both go to different pages (with admittedly very
>> > >> similar content), those pages are both entitled "Privileges" so
>> > >> it's unclear from the index which page you'll end up at.  Can we
>> > >> rename one of those pages to clarify as it looks weird in the
>> > >> index.
>> > >
>> > > Does anyone have an opinion on this?
>> >
>> > Sure -- I think the page at
>> > http://www.postgresql.org/docs/9.0/static/privileges.html (in
>> > "Chapter 20. Database Roles and Privileges" should be more
>> > conceptual rather than a subset of the other page.  Rather than
>> > explaining how to use GRANT and REVOKE to change privileges, it
>> > should give an overview of privileges and discuss what is allowed by
>> > each particular privilege.  It could link to the other page, so
>> > there would be one place to keep up-to-date on how to grant and
>> > revoke privileges.
>> >
>> > I think the page at
>> > http://www.postgresql.org/docs/9.0/static/ddl-priv.html (in "Chapter
>> > 5. Data Definition") should be renamed to something more like
>> > "Modifying Privileges" or "Granting and Revoking Privileges" (or
>> > something to that effect).  It might make sense to have its entry in
>> > the index be a secondary entry under privilege, with some similar
>> > qualification.
>>
>> I went even farther.  I think there is no need to discuss object
>> permissions in the database roles chapter.  We already link to the DDL
>> section, so I just changed that to link specifically to the DDL
>> privileges section, and made that DDL privileges section be a
>> super-set of the two old sections.
>>
>> Patch attached.
>>
>> --
>>   Bruce Momjian  <bruce@momjian.us>        http://momjian.us
>>   EnterpriseDB                             http://enterprisedb.com
>>
>>   + It's impossible for everything to be true. +
>
> [ text/x-diff is unsupported, treating like TEXT/PLAIN ]
>
>> diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
>> index a65b4bc..519afd6 100644
>> *** a/doc/src/sgml/ddl.sgml
>> --- b/doc/src/sgml/ddl.sgml
>> *************** ALTER TABLE products RENAME TO items;
>> *** 1400,1412 ****
>>      <see>privilege</see>
>>     </indexterm>
>>
>>     <para>
>> !    When you create a database object, you become its owner.  By
>> !    default, only the owner of an object can do anything with the
>> !    object. In order to allow other users to use it,
>> !    <firstterm>privileges</firstterm> must be granted.  (However,
>> !    users that have the superuser attribute can always
>> !    access any object.)
>>     </para>
>>
>>     <para>
>> --- 1400,1432 ----
>>      <see>privilege</see>
>>     </indexterm>
>>
>> +   <indexterm zone="ddl-priv">
>> +    <primary>owner</primary>
>> +   </indexterm>
>> +
>> +   <indexterm zone="ddl-priv">
>> +    <primary>GRANT</primary>
>> +   </indexterm>
>> +
>> +   <indexterm zone="ddl-priv">
>> +    <primary>REVOKE</primary>
>> +   </indexterm>
>> +
>>     <para>
>> !    When an object is created, it is assigned an owner. The
>> !    owner is normally the role that executed the creation statement.
>> !    For most kinds of objects, the initial state is that only the owner
>> !    (or a superuser) can do anything with the object. To allow
>> !    other roles to use it, <firstterm>privileges</firstterm> must be
>> !    granted.
>> !    There are several different kinds of privilege: <literal>SELECT</>,
>> !    <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
>> !    <literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
>> !    <literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
>> !    <literal>EXECUTE</>, and <literal>USAGE</>.
>> !    For more information on the different types of privileges supported by
>> !    <productname>PostgreSQL</productname>, see the
>> !    <xref linkend="sql-grant"> reference page.
>>     </para>
>>
>>     <para>
>> *************** ALTER TABLE products RENAME TO items;
>> *** 1429,1442 ****
>>      the owner only.
>>     </para>
>>
>> !   <note>
>> !    <para>
>> !     To change the owner of a table, index, sequence, or view, use the
>> !     <xref linkend="sql-altertable">
>> !     command.  There are corresponding <literal>ALTER</> commands for
>> !     other object types.
>> !    </para>
>> !   </note>
>>
>>     <para>
>>      To assign privileges, the <command>GRANT</command> command is
>> --- 1449,1462 ----
>>      the owner only.
>>     </para>
>>
>> !   <para>
>> !    An object can be assigned to a new owner with an <command>ALTER</command>
>> !    command of the appropriate kind for the object, e.g. <xref
>> !    linkend="sql-altertable">.  Superusers can always do
>> !    this; ordinary roles can only do it if they are both the current owner
>> !    of the object (or a member of the owning role) and a member of the new
>> !    owning role.
>> !   </para>
>>
>>     <para>
>>      To assign privileges, the <command>GRANT</command> command is
>> diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
>> index 2830aec..6a52827 100644
>> *** a/doc/src/sgml/user-manag.sgml
>> --- b/doc/src/sgml/user-manag.sgml
>> ***************
>> *** 1,7 ****
>>   <!-- doc/src/sgml/user-manag.sgml -->
>>
>>   <chapter id="user-manag">
>> !  <title>Database Roles and Privileges</title>
>>
>>    <para>
>>     <productname>PostgreSQL</productname> manages database access permissions
>> --- 1,7 ----
>>   <!-- doc/src/sgml/user-manag.sgml -->
>>
>>   <chapter id="user-manag">
>> !  <title>Database Roles</title>
>>
>>    <para>
>>     <productname>PostgreSQL</productname> manages database access permissions
>> ***************
>> *** 22,31 ****
>>    </para>
>>
>>    <para>
>> !   This chapter describes how to create and manage roles and introduces
>> !   the privilege system.  More information about the various types of
>> !   database objects and the effects of privileges can be found in
>> !   <xref linkend="ddl">.
>>    </para>
>>
>>    <sect1 id="database-roles">
>> --- 22,30 ----
>>    </para>
>>
>>    <para>
>> !   This chapter describes how to create and manage roles.
>> !   More information about the effects of privileges on various database
>> !   objects can be found in <xref linkend="ddl-priv">.
>>    </para>
>>
>>    <sect1 id="database-roles">
>> *************** ALTER ROLE myname SET enable_indexscan T
>> *** 282,362 ****
>>     </para>
>>    </sect1>
>>
>> -  <sect1 id="privileges">
>> -   <title>Privileges</title>
>> -
>> -   <indexterm zone="privileges">
>> -    <primary>privilege</primary>
>> -   </indexterm>
>> -
>> -   <indexterm zone="privileges">
>> -    <primary>owner</primary>
>> -   </indexterm>
>> -
>> -   <indexterm zone="privileges">
>> -    <primary>GRANT</primary>
>> -   </indexterm>
>> -
>> -   <indexterm zone="privileges">
>> -    <primary>REVOKE</primary>
>> -   </indexterm>
>> -
>> -   <para>
>> -    When an object is created, it is assigned an owner. The
>> -    owner is normally the role that executed the creation statement.
>> -    For most kinds of objects, the initial state is that only the owner
>> -    (or a superuser) can do anything with the object. To allow
>> -    other roles to use it, <firstterm>privileges</firstterm> must be
>> -    granted.
>> -    There are several different kinds of privilege: <literal>SELECT</>,
>> -    <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>,
>> -    <literal>TRUNCATE</>, <literal>REFERENCES</>, <literal>TRIGGER</>,
>> -    <literal>CREATE</>, <literal>CONNECT</>, <literal>TEMPORARY</>,
>> -    <literal>EXECUTE</>, and <literal>USAGE</>.
>> -    For more information on the different types of privileges supported by
>> -    <productname>PostgreSQL</productname>, see the
>> -    <xref linkend="sql-grant"> reference page.
>> -   </para>
>> -
>> -   <para>
>> -    To assign privileges, the <command>GRANT</command> command is
>> -    used. So, if <literal>joe</literal> is an existing role, and
>> -    <literal>accounts</literal> is an existing table, the privilege to
>> -    update the table can be granted with:
>> - <programlisting>
>> - GRANT UPDATE ON accounts TO joe;
>> - </programlisting>
>> -    The special name <literal>PUBLIC</literal> can
>> -    be used to grant a privilege to every role on the system. Writing
>> -    <literal>ALL</literal> in place of a specific privilege specifies that all
>> -    privileges that apply to the object will be granted.
>> -   </para>
>> -
>> -   <para>
>> -    To revoke a privilege, use the fittingly named
>> -    <xref linkend="sql-revoke"> command:
>> - <programlisting>
>> - REVOKE ALL ON accounts FROM PUBLIC;
>> - </programlisting>
>> -   </para>
>> -
>> -   <para>
>> -    The special privileges of an object's owner (i.e., the right to modify
>> -    or destroy the object) are always implicit in being the owner,
>> -    and cannot be granted or revoked.  But the owner can choose
>> -    to revoke his own ordinary privileges, for example to make a
>> -    table read-only for himself as well as others.
>> -   </para>
>> -
>> -   <para>
>> -    An object can be assigned to a new owner with an <command>ALTER</command>
>> -    command of the appropriate kind for the object.  Superusers can always do
>> -    this; ordinary roles can only do it if they are both the current owner
>> -    of the object (or a member of the owning role) and a member of the new
>> -    owning role.
>> -   </para>
>> -  </sect1>
>> -
>>    <sect1 id="role-membership">
>>     <title>Role Membership</title>
>>
>> --- 281,286 ----

Thanks Bruce. :)

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Excerpts from Bruce Momjian's message of lun feb 21 00:21:37 -0300 2011:
>
> Applied.

I think this paragraph is a bit strange:

+  This chapter describes how to create and manage roles.
+  More information about the effects of privileges on various database
+  objects can be found in <xref linkend="ddl-priv">.

Note that it says it's going to talk about roles and suddenly talks
about privileges, without saying how those two concepts are linked.  I
think an extra phrase is missing in the middle of those two; not sure
exactly what.

--
Álvaro Herrera <alvherre@commandprompt.com>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:
> Excerpts from Bruce Momjian's message of lun feb 21 00:21:37 -0300 2011:
> >
> > Applied.
>
> I think this paragraph is a bit strange:
>
> +  This chapter describes how to create and manage roles.
> +  More information about the effects of privileges on various database
> +  objects can be found in <xref linkend="ddl-priv">.
>
> Note that it says it's going to talk about roles and suddenly talks
> about privileges, without saying how those two concepts are linked.  I
> think an extra phrase is missing in the middle of those two; not sure
> exactly what.

Good point.  I think it was missing the word "role", which I have added:

  This chapter describes how to create and manage roles.
  More information about the effects of role privileges on various
                                        ----
  database objects can be found in <xref linkend="ddl-priv">.

--
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

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