Update GRANT example and discussion to match current sources.

doc/src/sgml/ref/grant.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.22 2002/04/21 00:26:42 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.23 2002/04/22 19:17:40 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -157,11 +157,10 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>CREATE</term>
      <listitem>
       <para>
-       For databases, allows new schemas to be created in the database.
+       For databases, allows new schemas to be created within the database.
       </para>
       <para>
-       For schemas, allows new objects to be created within the specified
+       For schemas, allows new objects to be created within the schema.
-       schema.
       </para>
      </listitem>
     </varlistentry>
@@ -196,9 +195,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
        of privilege that is applicable to procedural languages.
       </para>
       <para>
-       For schemas, allows the use of objects contained in the specified 
+       For schemas, allows access to objects contained in the specified 
        schema (assuming that the objects' own privilege requirements are
-       met).  Essentially this allows the grantee to <quote>look up</>
+       also met).  Essentially this allows the grantee to <quote>look up</>
        objects within the schema.
       </para>
      </listitem>
@@ -226,6 +225,11 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
  <refsect1 id="SQL-GRANT-notes">
   <title>Notes</title>
 
+   <para>
+    The <xref linkend="sql-revoke" endterm="sql-revoke-title"> command is used
+    to revoke access privileges.
+   </para>
+
    <para>
     It should be noted that database <firstterm>superusers</> can access
     all objects regardless of object privilege settings.  This
@@ -243,19 +247,19 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
 
    <para>
     Use <xref linkend="app-psql">'s <command>\z</command> command
-    to obtain information about privileges
+    to obtain information about existing privileges, for example:
-    on existing objects:
 <programlisting>
-          Database    = lusitania
+lusitania=> \z mytable
-   +------------------+---------------------------------------------+
+    Access privileges for database "lusitania"
-   |  Relation        |        Grant/Revoke Permissions             |
+  Table  |           Access privileges
-   +------------------+---------------------------------------------+
+---------+---------------------------------------
-   | mytable          | {"=rw","miriam=arwdRxt","group todos=rw"}   |
+ mytable | {=r,miriam=arwdRxt,"group todos=arw"}
-   +------------------+---------------------------------------------+
+</programlisting>
-   Legend:
+    The entries shown by <command>\z</command> are interpreted thus:
-         uname=arwR -- privileges granted to a user
+<programlisting>
-   group gname=arwR -- privileges granted to a group
+              =xxxx -- privileges granted to PUBLIC
-              =arwR -- privileges granted to PUBLIC
+         uname=xxxx -- privileges granted to a user
+   group gname=xxxx -- privileges granted to a group
 
                   r -- SELECT ("read")
                   w -- UPDATE ("write")
@@ -269,12 +273,25 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
                   C -- CREATE
                   T -- TEMPORARY
             arwdRxt -- ALL PRIVILEGES (for tables)
+</programlisting>
+
+    The above example display would be seen by user <literal>miriam</> after
+    creating table <literal>mytable</> and doing
+
+<programlisting>
+GRANT SELECT ON mytable TO PUBLIC;
+GRANT SELECT,UPDATE,INSERT ON mytable TO GROUP todos;
 </programlisting>
    </para>
 
    <para>
-    The <xref linkend="sql-revoke" endterm="sql-revoke-title"> command is used to revoke access
+   If the <quote>Access privileges</> column is empty for a given object,
-    privileges.
+it means the object has default privileges (that is, its privileges field
+is NULL).  Currently, default privileges are interpreted the same way
+for all object types: all privileges for the owner and no privileges for
+anyone else.  The first <command>GRANT</> on an object will instantiate
+this default (producing, for example, <literal>{=,miriam=arwdRxt}</>)
+and then modify it per the specified request.
    </para>
  </refsect1>