doc: restructure ALTER DEFAULT PRIVILEGES

Clarify that default privileges are not inherited and reorder
paragraphs.  This is a follow up to a recent ALTER DEFAULT PRIVILEGES
doc patch.

Reported-by: Sanjay Minni
Diagnosed-by: AMpxBo=M35hcH1g4Vg=KRJ0-77FOJcvdrdiVF5KSOAdOG-LvKQ@mail.gmail.com
Co-authored-by: Laurenz Albe
Backpatch-through: 16

diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml
index 8a6006188d3b694224569de39ab09d7e16639574..78744470c8d15f7f5ee1ea8f72d483f14519d42b 100644 (file)
--- a/doc/src/sgml/ref/alter_default_privileges.sgml
+++ b/doc/src/sgml/ref/alter_default_privileges.sgml
@@ -88,25 +88,19 @@ REVOKE [ GRANT OPTION FOR ]
   Description
 
   
-   ALTER DEFAULT PRIVILEGES allows you to set the privileges
-   that will be applied to objects created in the future.  (It does not
-   affect privileges assigned to already-existing objects.)  Currently,
-   only the privileges for schemas, tables (including views and foreign
-   tables), sequences, functions, and types (including domains) can be
-   altered.  For this command, functions include aggregates and procedures.
-   The words FUNCTIONS and ROUTINES are
-   equivalent in this command.  (ROUTINES is preferred
-   going forward as the standard term for functions and procedures taken
-   together.  In earlier PostgreSQL releases, only the
-   word FUNCTIONS was allowed.  It is not possible to set
-   default privileges for functions and procedures separately.)
+   ALTER DEFAULT PRIVILEGES allows you to set the
+   privileges that will be applied to objects created in the future.
+   (It does not affect privileges assigned to already-existing objects.)
+   Privileges can be set globally (i.e., for all objects created in the
+   current database), or just for objects created in specified schemas.
   
 
   
-   You can change default privileges only for objects that will be created by
-   yourself or by roles that you are a member of.  The privileges can be set
-   globally (i.e., for all objects created in the current database),
-   or just for objects created in specified schemas.
+   While you can change your own default privileges and the defaults of
+   roles that you are a member of, at object creation time, new object
+   permissions are only affected by the default privileges of the current
+   role, and are not inherited from any roles in which the current role
+   is a member.
   
 
   
@@ -118,6 +112,19 @@ REVOKE [ GRANT OPTION FOR ]
    ALTER DEFAULT PRIVILEGES.
   
 
+  
+   Currently,
+   only the privileges for schemas, tables (including views and foreign
+   tables), sequences, functions, and types (including domains) can be
+   altered.  For this command, functions include aggregates and procedures.
+   The words FUNCTIONS and ROUTINES are
+   equivalent in this command.  (ROUTINES is preferred
+   going forward as the standard term for functions and procedures taken
+   together.  In earlier PostgreSQL releases, only the
+   word FUNCTIONS was allowed.  It is not possible to set
+   default privileges for functions and procedures separately.)
+  
+
   
    Default privileges that are specified per-schema are added to whatever
    the global default privileges are for the particular object type.
@@ -136,12 +143,9 @@ REVOKE [ GRANT OPTION FOR ]
     target_role
     
      
-      The name of an existing role of which the current role is a member.
-      Default access privileges are not inherited, so member roles
-      must use SET ROLE to access these privileges,
-      or ALTER DEFAULT PRIVILEGES must be run for
-      each member role.  If FOR ROLE is omitted,
-      the current role is assumed.
+      Change default privileges for objects created by the
+      target_role, or the current
+      role if unspecified.