Received: from maia.hub.org (maia-3.hub.org [200.46.204.243])
	by mail.postgresql.org (Postfix) with ESMTP id 3FBCA133798E
	for <pgsql-docs-postgresql.org@mail.postgresql.org>;
	Fri, 18 Feb 2011 14:48:56 -0400 (AST)
Received: from mail.postgresql.org ([200.46.204.86])
	by maia.hub.org (mx1.hub.org [200.46.204.243]) (amavisd-maia,
	port 10024) with ESMTP id 09266-09 for
	<pgsql-docs-postgresql.org@mail.postgresql.org>;
	Fri, 18 Feb 2011 18:48:48 +0000 (UTC)
X-Greylist: from auto-whitelisted by SQLgrey-1.7.6
Received: from momjian.us (momjian.us [70.90.9.53])
	by mail.postgresql.org (Postfix) with ESMTP id 290481336FA7
	for <pgsql-docs@postgresql.org>; Fri, 18 Feb 2011 14:48:47 -0400 (AST)
Received: (from bruce@localhost) by momjian.us (8.11.6/8.11.6) id
 p1IImdR13411;
	Fri, 18 Feb 2011 13:48:39 -0500 (EST)
From: Bruce Momjian <bruce@momjian.us>
Message-Id: <201102181848.p1IImdR13411@momjian.us>
Subject: Re: Ambiguous index entry for Privileges
In-Reply-To: <4C68FE080200002500034660@gw.wicourts.gov>
To: Kevin Grittner <Kevin.Grittner@wicourts.gov>
Date: Fri, 18 Feb 2011 13:48:39 -0500 (EST)
CC: Thom Brown <thom@linux.com>, pgsql-docs <pgsql-docs@postgresql.org>
X-Mailer: ELM [version 2.4ME+ PL124 (25)]
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="ELM1298054919-11851-0_"
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: Maia Mailguard 1.0.1
X-Spam-Status: No, hits=-1.91 tagged_above=-5 required=5 tests=BAYES_00=-1.9,
	T_RP_MATCHES_RCVD=-0.01
X-Spam-Level: 
X-Archive-Number: 201102/59
X-Sequence-Number: 6407


--ELM1298054919-11851-0_
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset="US-ASCII"

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

--ELM1298054919-11851-0_
Content-Transfer-Encoding: 7bit
Content-Type: text/x-diff
Content-Disposition: inline; filename="/rtmp/privs.diff"

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

--ELM1298054919-11851-0_--