From b6d10403ef191499f151dd5dec4fb37b25978144 Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Tue, 30 Jan 2024 13:21:29 -0700
Subject: [PATCH] description addition and tweaks

grant tweaks
---
 doc/src/sgml/ref/create_role.sgml | 22 +++++++++++++++-------
 doc/src/sgml/ref/grant.sgml       | 11 ++++++-----
 2 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index d0d3d7ed64..f3b89e7239 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -66,6 +66,17 @@ in sync when changing the above synopsis!
    Note that roles are defined at the database cluster
    level, and so are valid in all databases in the cluster.
   </para>
+
+  <para>
+   During role creation it is possible to immediately assign the newly created
+   role to be a member of an existing role, and also assign existing roles
+   to be members of the newly created role.  The rules for which initial
+   role membership options are enabled described below in the
+   <literal>IN ROLE</literal>, <literal>ROLE</literal>, and
+   <literal>ADMIN</literal> clauses.  The <xref linkend="sql-grant"/>
+   command has fine-grained option control during membership creation,
+   and the ability to modify these options after the new role is created.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -285,10 +296,7 @@ in sync when changing the above synopsis!
         roles. The new membership will have the <literal>SET</literal>
         option enabled and the <literal>ADMIN</literal> option disabled.
         The <literal>INHERIT</literal> option will be enabled unless the
-        <literal>NOINHERIT</literal> option is specified.  See the <xref
-        linkend="sql-grant"/> command, which has additional option
-        control during membership creation and to modify these options
-        after the new role is created.
+        <literal>NOINHERIT</literal> option is specified.
        </para>
       </listitem>
      </varlistentry>
@@ -301,9 +309,9 @@ in sync when changing the above synopsis!
         existing roles to be automatically added as members, with the
         <literal>SET</literal> option enabled. This in effect makes the
         new role a <quote>group</quote>.  Roles named in this clause
-        with role-level <literal>INHERIT</literal> options will have
-        <literal>INHERIT</literal> enabled in the new membership.  New
-        memberships will have the <literal>ADMIN</literal> option disabled.
+        with role-level the <literal>INHERIT</literal> attribute will have
+        the <literal>INHERIT</literal> option enabled in the new membership.
+        New memberships will have the <literal>ADMIN</literal> option disabled.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index ee53871713..9d27b7fcde 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -266,7 +266,9 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
    <literal>TRUE</literal> or <literal>FALSE</literal>. The keyword
    <literal>OPTION</literal> is accepted as a synonym for
    <literal>TRUE</literal>, so that <literal>WITH ADMIN OPTION</literal>
-   is a synonym for <literal>WITH ADMIN TRUE</literal>.
+   is a synonym for <literal>WITH ADMIN TRUE</literal>.  When altering
+   an existing membership the omission of an option results in the current
+   value being retained.
   </para>
 
   <para>
@@ -280,14 +282,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
   </para>
 
   <para>
-   The <literal>INHERIT</literal> attribute controls the inheritance status
+   The <literal>INHERIT</literal> option controls the inheritance status
    of the new membership;  see <xref linkend="role-membership"/> for
    details on inheritance.  If it is set to <literal>TRUE</literal>,
    it causes the new member to inherit from the granted role. If
    set to <literal>FALSE</literal>, the new member does not inherit.
-   If unspecified, new role membership defaults to the inheritance status
-   of the role being added.  If an existing membership, the inheritance
-   option is unchanged.
+   If unspecified when create a new role membership this defaults to
+   the inheritance attribute of the role being added.
   </para>
 
   <para>
-- 
2.34.1