Refactor documentation about privileges to centralize the info.

Expand section 5.6 "Privileges" to include the full definition of
each privilege type, and an explanation of aclitem privilege displays,
along with some helpful summary tables.  Most of this material came
out of the GRANT reference page, although some of it is new.
Adjust a bunch of links that were pointing to GRANT to point to 5.6.

Fabien Coelho and Tom Lane, reviewed by Bradley DeJong

Discussion: https://postgr.es/m/alpine.DEB.2.21.1807311735200.20743@lancre

doc/src/sgml/catalogs.sgml

@@ -1973,10 +1973,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
 
@@ -2679,10 +2676,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
     </tbody>
@@ -3491,10 +3485,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
 
@@ -3587,10 +3578,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
 
@@ -4052,9 +4040,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry></entry>
       <entry>
        The initial access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
 
@@ -4179,10 +4165,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
     </tbody>
@@ -4319,10 +4302,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
 
@@ -4386,10 +4366,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
     </tbody>
@@ -5396,10 +5373,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
     </tbody>
@@ -6810,10 +6784,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
 
@@ -7923,10 +7894,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <entry><type>aclitem[]</type></entry>
       <entry></entry>
       <entry>
-       Access privileges; see
-       <xref linkend="sql-grant"/> and
-       <xref linkend="sql-revoke"/>
-       for details
+       Access privileges; see <xref linkend="ddl-priv"/> for details
       </entry>
      </row>
     </tbody>

doc/src/sgml/func.sgml

@@ -16932,21 +16932,11 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
 
   <para>
    <xref linkend="functions-aclitem-fn-table"/> shows the operators
-   available for the <type>aclitem</type> type, which is the internal
-   representation of access privileges. An <type>aclitem</type> entry
-   describes the permissions of a grantee, whether they are grantable
-   or not, and which grantor granted them. For instance,
-   <literal>calvin=r*w/hobbes</literal> specifies that the role
-   <literal>calvin</literal> has the grantable privilege
-   <literal>SELECT</literal> (<literal>r*</literal>) and the non-grantable
-   privilege <literal>UPDATE</literal> (<literal>w</literal>), granted by
-   the role <literal>hobbes</literal>. An empty grantee stands for
-   <literal>PUBLIC</literal>.
+   available for the <type>aclitem</type> type, which is the catalog
+   representation of access privileges.  See <xref linkend="ddl-priv"/>
+   for information about how to read access privilege values.
   </para>
 
-   <indexterm>
-    <primary>aclitem</primary>
-   </indexterm>
    <indexterm>
     <primary>acldefault</primary>
    </indexterm>
@@ -17015,9 +17005,9 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
      <tbody>
       <row>
        <entry><literal><function>acldefault</function>(<parameter>type</parameter>,
-                                  <parameter>ownerId</parameter>)</literal></entry>
+        <parameter>ownerId</parameter>)</literal></entry>
        <entry><type>aclitem[]</type></entry>
-       <entry>get the hardcoded default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
+       <entry>get the default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
       </row>
       <row>
        <entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry>
@@ -17034,16 +17024,14 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
    </table>
 
    <para>
-    <function>acldefault</function> returns the hardcoded default access privileges
-    for an object of <parameter>type</parameter> belonging to role <parameter>ownerId</parameter>.
-    Notice that these are used in the absence of any pg_default_acl
-    (<xref linkend="catalog-pg-default-acl"/>) entry. Default access privileges are described in
-    <xref linkend="sql-grant"/> and can be overwritten with
-    <xref linkend="sql-alterdefaultprivileges"/>. In other words, this function will return
-    results which may be misleading when the defaults have been overridden.
-    Type is a <type>CHAR</type>, use
+    <function>acldefault</function> returns the built-in default access
+    privileges for an object of type <parameter>type</parameter> belonging to
+    role <parameter>ownerId</parameter>.  These represent the access
+    privileges that will be assumed when an object's ACL entry is null.
+    (The default access privileges are described in <xref linkend="ddl-priv"/>.)
+    The <parameter>type</parameter> parameter is a <type>CHAR</type>: write
     'c' for <literal>COLUMN</literal>,
-    'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
+    'r' for <literal>TABLE</literal> and table-like objects,
     's' for <literal>SEQUENCE</literal>,
     'd' for <literal>DATABASE</literal>,
     'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
@@ -17053,15 +17041,16 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
     't' for <literal>TABLESPACE</literal>,
     'F' for <literal>FOREIGN DATA WRAPPER</literal>,
     'S' for <literal>FOREIGN SERVER</literal>,
+    or
     'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
    </para>
 
    <para>
     <function>aclexplode</function> returns an <type>aclitem</type> array
-    as a set rows. Output columns are grantor <type>oid</type>,
+    as a set of rows. Output columns are grantor <type>oid</type>,
     grantee <type>oid</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
     granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
-    and whether the prilivege is grantable as <type>boolean</type>.
+    and whether the privilege is grantable as <type>boolean</type>.
     <function>makeaclitem</function> performs the inverse operation.
    </para>
 

doc/src/sgml/ref/alter_default_privileges.sgml

@@ -112,7 +112,7 @@ REVOKE [ GRANT OPTION FOR ]
   </para>
 
   <para>
-   As explained under <xref linkend="sql-grant"/>,
+   As explained in <xref linkend="ddl-priv"/>,
    the default privileges for any object type normally grant all grantable
    permissions to the object owner, and may grant some privileges to
    <literal>PUBLIC</literal> as well.  However, this behavior can be changed by
@@ -173,9 +173,8 @@ REVOKE [ GRANT OPTION FOR ]
   <para>
    Use <xref linkend="app-psql"/>'s <command>\ddp</command> command
    to obtain information about existing assignments of default privileges.
-   The meaning of the privilege values is the same as explained for
-   <command>\dp</command> under
-   <xref linkend="sql-grant"/>.
+   The meaning of the privilege display is the same as explained for
+   <command>\dp</command> in <xref linkend="ddl-priv"/>.
   </para>
 
   <para>

doc/src/sgml/ref/create_function.sgml

@@ -761,7 +761,7 @@ $$  LANGUAGE plpgsql
    <para>
     Another point to keep in mind is that by default, execute privilege
     is granted to <literal>PUBLIC</literal> for newly created functions
-    (see <xref linkend="sql-grant"/> for more
+    (see <xref linkend="ddl-priv"/> for more
     information).  Frequently you will wish to restrict use of a security
     definer function to only some users.  To do that, you must revoke
     the default <literal>PUBLIC</literal> privileges and then grant execute

doc/src/sgml/ref/psql-ref.sgml

@@ -1324,8 +1324,8 @@ testdb=>
         <para>
         The <xref linkend="sql-alterdefaultprivileges"/> command is used to set
         default access privileges.  The meaning of the
-        privilege display is explained under
-        <xref linkend="sql-grant"/>.
+        privilege display is explained in
+        <xref linkend="ddl-priv"/>.
         </para>
         </listitem>
       </varlistentry>
@@ -1372,7 +1372,7 @@ testdb=&gt;
         specified, only those servers whose name matches the pattern
         are listed.  If the form <literal>\des+</literal> is used, a
         full description of each server is shown, including the
-        server's ACL, type, version, options, and description.
+        server's access privileges, type, version, options, and description.
         </para>
         </listitem>
       </varlistentry>
@@ -1425,8 +1425,8 @@ testdb=&gt;
         If <replaceable class="parameter">pattern</replaceable> is
         specified, only those foreign-data wrappers whose name matches
         the pattern are listed.  If the form <literal>\dew+</literal>
-        is used, the ACL, options, and description of the foreign-data
-        wrapper are also shown.
+        is used, the access privileges, options, and description of the
+        foreign-data wrapper are also shown.
         </para>
         </listitem>
       </varlistentry>
@@ -1639,8 +1639,8 @@ testdb=&gt;
         The <xref linkend="sql-grant"/> and
         <xref linkend="sql-revoke"/>
         commands are used to set access privileges.  The meaning of the
-        privilege display is explained under
-        <xref linkend="sql-grant"/>.
+        privilege display is explained in
+        <xref linkend="ddl-priv"/>.
         </para>
         </listitem>
       </varlistentry>

doc/src/sgml/ref/revoke.sgml

@@ -177,14 +177,6 @@ REVOKE [ ADMIN OPTION FOR ]
  <refsect1 id="sql-revoke-notes">
   <title>Notes</title>
 
-  <para>
-   Use <xref linkend="app-psql"/>'s <command>\dp</command> command to
-   display the privileges granted on existing tables and columns.  See <xref
-   linkend="sql-grant"/> for information about the
-   format.  For non-table objects there are other <command>\d</command> commands
-   that can display their privileges.
-  </para>
-
   <para>
    A user can only revoke privileges that were granted directly by
    that user.  If, for example, user A has granted a privilege with
@@ -244,6 +236,11 @@ REVOKE [ ADMIN OPTION FOR ]
     lead to revoking privileges other than the ones you intended, or not
     revoking anything at all.
    </para>
+
+   <para>
+    See <xref linkend="ddl-priv"/> for more information about specific
+    privilege types, as well as how to inspect objects' privileges.
+   </para>
  </refsect1>
 
  <refsect1 id="sql-revoke-examples">
@@ -293,9 +290,10 @@ REVOKE admins FROM joe;
  <refsect1>
   <title>See Also</title>
 
-  <simpara>
-   <xref linkend="sql-grant"/>
-  </simpara>
+  <simplelist type="inline">
+   <member><xref linkend="sql-grant"/></member>
+   <member><xref linkend="sql-alterdefaultprivileges"/></member>
+  </simplelist>
  </refsect1>
 
 </refentry>