Improve privileges discussion (mostly, mention grant options).

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 71bb34d83ce417fc7d22cb828a09f0996b511ff6..af87cabc0c99422f938214ee008a94c5d7aa98d0 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Data Definition
@@ -1378,29 +1378,22 @@ ALTER TABLE products RENAME TO items;
    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,
-   privileges must be granted.  (There are also
-   users that have the superuser privilege.  Those users can always
+   privileges must be granted.  (However,
+   users that have the superuser attribute can always
    access any object.)
   
 
-  
-   
-    To change the owner of a table, index, sequence, or view, use the
-    
-    command.
-   
-  
-
   
    There are several different privileges: SELECT,
    INSERT, UPDATE, DELETE,
    RULE, REFERENCES, TRIGGER,
    CREATE, TEMPORARY, EXECUTE,
-   USAGE, and ALL PRIVILEGES. For complete
+   and USAGE.  The privileges applicable to a particular
+   object vary depending on the object's type (table, function, etc).
+   For complete
    information on the different types of privileges supported by
    PostgreSQL, refer to the
-   
-   reference page.  The following sections
+    reference page.  The following sections
    and chapters will also show you how those privileges are used.
   
 
@@ -1409,23 +1402,30 @@ ALTER TABLE products RENAME TO items;
    the owner only.
   
 
+  
+   
+    To change the owner of a table, index, sequence, or view, use the
+     command.  There are corresponding
+    ALTER commands for other object types.
+   
+  
+
   
    To assign privileges, the GRANT command is
-   used. So, if joe is an existing user, and
+   used. For example, if joe is an existing user, and
    accounts is an existing table, the privilege to
    update the table can be granted with
 
 GRANT UPDATE ON accounts TO joe;
 
-   The user executing this command must be the owner of the table. To
-   grant a privilege to a group, use
+   To grant a privilege to a group, use this syntax:
 
 GRANT SELECT ON accounts TO GROUP staff;
 
    The special user name PUBLIC can
    be used to grant a privilege to every user on the system. Writing
-   ALL in place of a specific privilege specifies that all
-   privileges will be granted.
+   ALL in place of a specific privilege grants all
+   privileges that are relevant for the object type.
   
 
   
@@ -1434,13 +1434,24 @@ GRANT SELECT ON accounts TO GROUP staff;
 
 REVOKE ALL ON accounts FROM PUBLIC;
 
-   The special privileges of the table owner (i.e., the right to do
+   The special privileges of the object owner (i.e., the right to do
    DROP, GRANT, REVOKE, etc.)
    are always implicit in being the owner,
-   and cannot be granted or revoked.  But the table owner can choose
+   and cannot be granted or revoked.  But the object owner can choose
    to revoke his own ordinary privileges, for example to make a
    table read-only for himself as well as others.
   
+
+  
+   Ordinarily, only the object's owner (or a superuser) can grant or revoke
+   privileges on an object.  However, it is possible to grant a privilege
+   with grant option, which gives the recipient the right to
+   grant it in turn to others.  If the grant option is subsequently revoked
+   then all who received the privilege from that recipient (directly or
+   through a chain of grants) will lose the privilege.  For details see
+   the  and  reference
+   pages.
+  
  
 
  
@@ -1544,12 +1555,17 @@ CREATE SCHEMA myschema;
 
 schema.table
 
+    (For brevity we will speak of tables only, but the same ideas apply
+    to other kinds of named objects, such as types and functions.)
+   
+
+   
     Actually, the even more general syntax
 
 database.schema.table
 
     can be used too, but at present this is just for pro-forma compliance
-    with the SQL standard; if you write a database name it must be the
+    with the SQL standard.  If you write a database name, it must be the
     same as the database you are connected to.
    
 
@@ -1862,7 +1878,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
        privileges to allow the other users to access them.  Users can
        then refer to these additional objects by qualifying the names
        with a schema name, or they can put the additional schemas into
-       their path, as they choose.
+       their search path, as they choose.
       
      
     

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index a6a2d4d994e3e5c760e7905994253096ad9e6843..9ea480c57a32aafb783514e025860ecf3d22d43a 100644 (file)
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
 
 
@@ -52,8 +52,8 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
 
   
    The GRANT command gives specific privileges on
-   an object (table, view, sequence, database, function, procedural language,
-   or schema) to
+   an object (table, view, sequence, database, tablespace, function,
+   procedural language, or schema) to
    one or more users or groups of users.  These privileges are added
    to those already granted, if any.