On Wed, Jan 17, 2024 at 02:32:47PM -0700, David G. Johnston wrote:
> I had a go at this.
>
> I went with a more "bullet item" approach with my wording for INHERIT/
> NOINHERIT.
I tried to address that.
> 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.
Because the CREATE ROLE is the way to create roles, and GRANT does much
more than just grant membership, I ended up moving the details from the
GRANT page to the CREATE ROLE page.
> We consistently say what the default is for these attribute pairs, do so here
> as well.
I added that, I hope in all the right places.
> 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.
Yes, that needed help.
> 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.
I adjusted that working, but in a different way. Patch attached.
I also found we didn't document that GRANT can be used to modify a
membership's attributes even after it is created; I added that.
Just a reminder, this is for PG 16 and master.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Only you can decide what is important to you.