From ce3673daded3fe3a101b0c008235dcf8bfe9ffec Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 18 May 2023 22:22:17 -0400
Subject: [PATCH] doc:  improve description of adding roles as members

Discussion: https://postgr.es/m/ZFvVZvQDliIWmOwg@momjian.us
---
 doc/src/sgml/ref/create_role.sgml | 15 ++++++++-------
 doc/src/sgml/ref/createuser.sgml  | 22 ++++++++++------------
 2 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 4a84461b28..7249fc7432 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -285,10 +285,11 @@ in sync when changing the above synopsis!
       <term><literal>IN ROLE</literal> <replaceable class="parameter">role_name</replaceable></term>
       <listitem>
        <para>
-        The <literal>IN ROLE</literal> clause lists one or more existing
-        roles to which the new role will be immediately added as a new
-        member.  (Note that there is no option to add the new role as an
-        administrator; use a separate <command>GRANT</command> command to do that.)
+        The <literal>IN ROLE</literal> clause causes the new role to
+        be automatically added as a member of the specified existing
+        roles. (Note that there is no option to add the new role as an
+        administrator; use a separate <command>GRANT</command> command
+        to do that.)
        </para>
       </listitem>
      </varlistentry>
@@ -306,9 +307,9 @@ in sync when changing the above synopsis!
       <term><literal>ROLE</literal> <replaceable class="parameter">role_name</replaceable></term>
       <listitem>
        <para>
-        The <literal>ROLE</literal> clause lists one or more existing
-        roles which are automatically added as members of the new role.
-        (This in effect makes the new role a <quote>group</quote>.)
+        The <literal>ROLE</literal> clause causes one or more specified
+        existing roles to be automatically added as members of the new
+        role.  This in effect makes the new role a <quote>group</quote>.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index c5c74b86a2..58ed111642 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -85,11 +85,10 @@ PostgreSQL documentation
       <term><option>--admin=<replaceable class="parameter">role</replaceable></option></term>
       <listitem>
        <para>
-        Indicates a role that will be immediately added as a member of the new
+        Indicates an existing role that will be automatically added as a member of the new
         role with admin option, giving it the right to grant membership in the
-        new role to others.  Multiple roles to add as members (with admin
-        option) of the new role can be specified by writing multiple
-        <option>-a</option> switches.
+        new role to others.  Multiple existing roles can be specified by
+        writing multiple <option>-a</option> switches.
        </para>
       </listitem>
      </varlistentry>
@@ -153,11 +152,10 @@ PostgreSQL documentation
       <term><option>--role=<replaceable class="parameter">role</replaceable></option></term>
       <listitem>
        <para>
-         Indicates a role to which this role will be added immediately as a new
-         member. Multiple roles to which this role will be added as a member
-         can be specified by writing multiple
-         <option>-g</option> switches.
-         </para>
+        Indicates the new role should be automatically added as a member
+        of the specified existing role. Multiple existing roles can be
+        specified by writing multiple <option>-g</option> switches.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -227,9 +225,9 @@ PostgreSQL documentation
       <term><option>--member=<replaceable class="parameter">role</replaceable></option></term>
       <listitem>
        <para>
-        Indicates role that will be immediately added as a member of the new
-        role.  Multiple roles to add as members of the new role can be specified
-        by writing multiple <option>-m</option> switches.
+        Indicates the specified existing role should be automatically
+        added as a member of the new role. Multiple existing roles can
+        be specified by writing multiple <option>-m</option> switches.
        </para>
       </listitem>
      </varlistentry>