In writing the PG 16 release notes, I came upon an oddity in our new
createuser syntax, specifically --role and --member. It turns out that
--role matches CREATE ROLE ... ROLE IN (and has prior to PG 16) while
the new --member option matches CREATE ROLE ... ROLE. The PG 16 feature
discussion thread is here:
https://www.postgresql.org/message-id/flat/69a9851035cf0f0477bcc5d742b031a3%40oss.nttdata.com
This seems like it will be forever confusing to people. I frankly don't
know why --role matching CREATE ROLE ... ROLE IN was not already
confusing in pre-PG 16. Any new ideas for improvement?
At a minium I would like to apply the attached doc patch to PG 16 to
improve awkward wording in CREATE ROLE and createuser.
--
Bruce Momjian <br...@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Embrace your flaws. They make you human, rather than perfect,
which you will never be.
diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index 4a84461b28..69ea9060bf 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>
