Re: CREATE ROLE inheritance details

On Wed, Jan 17, 2024 at 9:38 AM Bruce Momjian <bruce(at)momjian(dot)us> wrote:

> On Wed, Jan 17, 2024 at 09:28:38AM +0100, Laurenz Albe wrote:
> > On Tue, 2024-01-16 at 17:03 -0500, Bruce Momjian wrote:
> > > I am unhappy with the documentation adjustments made to CREATE ROLE in
> > > Postgres 16 by this commit:
> > >
> > > commit e3ce2de09d
> > >
> > > I have attached a patch to re-add this information, and clarify it. I
> > > would like to apply this to PG 16 and master.
> >
> > I had to read the text twice before I understood it, but I cannot think
> > of a simpler way to write it.
>
> Yeah, I had the same feeling. A bullet list would be nice but overkill
> for a manual page.
>
>
I had a go at this.

I went with a more "bullet item" approach with my wording for
INHERIT/NOINHERIT.

The entire paragraph regarding how the INHERIT "option" works, as opposed
to the attribute, seems out of place where it was and the material is
already covered in the GRANT page. We should either improve that page or
extract this level of detail somewhere else, not try to clutter up the
CREATE ROLE page with it.

We consistently say what the default is for these attribute pairs, do so
here as well.

Turn the parenthetical in the IN ROLE section into actual assertive
documentation of what the clause does. Tweak ROLE and ADMIN as well to fit
in better.

Reword the discussion regarding non-inheritance to be more direct.

I added mention of the grantee aspect of privileges as a soft way of
further pointing out that the IN ROLE, ROLE, ADMIN clauses are limited in
what they can control in the resulting membership grants.

I choose to use the phrasing "giving ... roles" for both parts of the
sentence instead of switching to "... roles are given" for the second
half. More of a style choice but I didn't think switching really added
much and just makes it a bit wordier and possibly a bit more effort to
mentally parse.

Patch built on top of Bruce's role.diff, not HEAD

David J.