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.