Try to be a little bit clearer about the implications of GRANT TO PUBLIC

and REVOKE FROM PUBLIC: the latter is not the same as 'revoke from all
users', but the ref page blurred the difference.

2 files changed, 34 insertions, 12 deletions

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index fab1c758d00..a4ff54b5794 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.15 2001/11/18 20:35:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.16 2001/11/19 19:03:56 tgl Exp $
 Postgres documentation
 -->
 
@@ -27,18 +27,30 @@ GRANT { { SELECT | INSERT | UPDATE | DELETE | RULE | REFERENCES | TRIGGER } [,..
 
   <para>
    The <command>GRANT</command> command gives specific permissions on
-   an object (table, view, sequence) to a user or a group of users.
-   The special key word <literal>PUBLIC</literal> indicates that the
+   an object (table, view, sequence) to one or more users or groups of users.
+   These permissions are added to those already granted, if any.
+  </para>
+
+  <para>
+   The key word <literal>PUBLIC</literal> indicates that the
    privileges are to be granted to all users, including those that may
-   be created later.
+   be created later.  <literal>PUBLIC</literal> may be thought of as an
+   implicitly defined group that always includes all users.
+   Note that any particular user will have the sum
+   of privileges granted directly to him, privileges granted to any group he
+   is presently a member of, and privileges granted to
+   <literal>PUBLIC</literal>.
   </para>
 
   <para>
    Users other than the creator do not have any access privileges
-   unless the creator grants permissions, after the object is created.
+   to an object unless the creator grants permissions.
    There is no need to grant privileges to the creator of an object,
    as the creator automatically holds all privileges, and can also
-   drop the object.
+   drop the object.  (The creator could, however, choose to revoke
+   some of his own privileges for safety.  Note that the ability to
+   grant and revoke privileges is inherent in the creator and cannot
+   be lost.)
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml
index afa75d851ee..7c00c36115b 100644
--- a/doc/src/sgml/ref/revoke.sgml
+++ b/doc/src/sgml/ref/revoke.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/revoke.sgml,v 1.17 2001/11/18 20:35:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/revoke.sgml,v 1.18 2001/11/19 19:03:56 tgl Exp $
 Postgres documentation
 -->
 
@@ -27,9 +27,19 @@ REVOKE { { SELECT | INSERT | UPDATE | DELETE | RULE | REFERENCES | TRIGGER } [,.
 
   <para>
    <command>REVOKE</command> allows the creator of an object to revoke
-   permissions granted before, from a users or a group of users.  The
-   key word <literal>PUBLIC</literal> means to revoke this privilege
-   from all users.
+   previously granted permissions from one or more users or groups of users.
+   The key word <literal>PUBLIC</literal> refers to the implicitly defined
+   group of all users.
+  </para>
+
+  <para>
+   Note that any particular user will have the sum
+   of privileges granted directly to him, privileges granted to any group he
+   is presently a member of, and privileges granted to
+   <literal>PUBLIC</literal>.  Thus, for example, revoking SELECT privilege
+   from <literal>PUBLIC</literal> does not necessarily mean that all users
+   have lost SELECT privilege on the object: those who have it granted
+   directly or via a group will still have it.
   </para>
 
   <para>
@@ -52,7 +62,7 @@ REVOKE { { SELECT | INSERT | UPDATE | DELETE | RULE | REFERENCES | TRIGGER } [,.
   <title>Examples</title>
 
   <para>
-   Revoke insert privilege from all users on table
+   Revoke insert privilege for the public on table
    <literal>films</literal>:
 
 <programlisting>
@@ -93,7 +103,7 @@ REVOKE [ GRANT OPTION FOR ] { SELECT | INSERT | UPDATE | DELETE | REFERENCES }
     this privilege in cascade using the CASCADE keyword.
     If user1 gives a privilege WITH GRANT OPTION to user2,
     and user2 gives it to user3, then if user1 tries to revoke
-    this privilege it fails if he specify the RESTRICT
+    this privilege it fails if he specifies the RESTRICT
     keyword.
    </para>
   </refsect2>