Re: Ambiguous index entry for Privileges

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 ----

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

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

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