Re: CREATE ROLE inheritance details

Almost there I think. The comment regarding seeing GRANT really applies to
IN ROLE, ROLE, and ADMIN. Repeating it seemed a poor choice and upon
thinking further it really makes sense to consider how this command and
GRANT work together part of the description of create role. So I moved
that commentary to a new description paragraph.

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 are described below in the
+ <literal>IN ROLE</literal>, <literal>ROLE</literal>, and
+ <literal>ADMIN</literal> clauses. Alternatively, the <xref
linkend="sql-grant"/>
+ command has fine-grained option control during membership creation,
+ and also 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>

And then fixed up one last instance of attribute/option specification. I
left the term " membership inheritance status" alone in the attribute
description since that really does refer to the concept and neither the
specific attribute here nor the membership option. All of the other
references seemed better of being specific to the feature and not the
behavior.

@@ -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>

The omission of an option during membership modification results in no
change, not applying the default, applies to all three, not just inherit.
Again, instead of documenting all three with this it seemed preferable to
add it once somewhere - in this case the paragraph that talks about the
option mode values seems appropriate.

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>

And some final touch-ups; including removing the now redundant omission
sentence for inherit.

@@ -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 creating a new role membership this defaults to
+ the inheritance attribute of the role being added.
</para>

<para>

I've attached a revised role.diff patch as well as just the changes from
the original.

David J.