Re: Ambiguous index entry for Privileges

On 21 February 2011 03:21, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
>
> Applied.
>
> ---------------------------------------------------------------------------
>
> Bruce Momjian wrote:
>> Kevin Grittner wrote:
>> > Thom Brown <thom(at)linux(dot)com> wrote:
>> > > On 12 August 2010 00:05, Thom Brown <thom(at)linux(dot)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(at)momjian(dot)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