Re: improve predefined roles documentation

On Mon, Jun 17, 2024 at 02:10:22PM -0400, Robert Haas wrote:
> On Thu, Jun 13, 2024 at 3:48 PM Nathan Bossart <nathandbossart(at)gmail(dot)com> wrote:
>> I think we could improve matters by abandoning the table and instead
>> documenting these roles more like we document GUCs, i.e., each one has a
>> section below it where we can document it in as much detail as we want.
>> Some of these roles should probably be documented together (e.g.,
>> pg_read_all_data and pg_write_all_data), so the ordering is unlikely to be
>> perfect, but I'm hoping it would still be a net improvement.
>
> +1. I'm not sure about all of the details, but I like the general idea.

Here is a first try. I did pretty much exactly what I proposed in the
quoted text, so I don't have much else to say about it. I didn't see an
easy way to specify multiple ids and xreflabels for a given entry, so the
entries that describe multiple roles just use the name of the first role
listed. In practice, I think this just means you need to do a little extra
work when linking to one of the other roles from elsewhere in the docs,
which doesn't seem too terrible.

--
nathan