Re: describe special values in GUC descriptions more consistently

On Mon, Feb 10, 2025 at 4:53 PM Peter Smith <smithpb2250(at)gmail(dot)com> wrote:

> On Tue, Feb 11, 2025 at 9:25 AM Nathan Bossart <nathandbossart(at)gmail(dot)com>
> wrote:
> >
> > On Tue, Feb 11, 2025 at 08:29:28AM +1100, Peter Smith wrote:
> > > +1 for this. Your wording examples below look good to me..
> >
> > Okay, how does this look?
> >
> > --
>
> v2 mostly looked good to me. Just a couple of questions.
>
> ~~~
>
> 1.
> {"shared_memory_size_in_huge_pages", PGC_INTERNAL, PRESET_OPTIONS,
> gettext_noop("Shows the number of huge pages needed for the main
> shared memory area."),
> - gettext_noop("-1 indicates that the value could not be determined."),
> + gettext_noop("-1 means the value could not be determined."),
>
> I didn't know what that meant. And the docs seem worded differently. More
> like:
> "-1 means huge pages are not supported."
>

Agreed

> ~~~
>
> 2.
> - gettext_noop("An empty string indicates that \"archive_command\"
> should be used.")
> + gettext_noop("An empty string means \"archive_command\" should be used.")
>
> Should that be worded more like other ones that delegate to other GUCs:
>
> "An empty string means use \"archive_command\"."
>

Agreed

> ~~~
>
> 3.
>
> What is the difference between "system setting" and "system default",
> or should those be made the same?
>
>
Looking at the documentation it seems to be communicating the difference
between a PostgreSQL default (system default) and a value taken from the
operating environment (system setting). Maybe making that more clear by
saying "operating system setting" is warranted.

A couple of more items.

Minor typo, trailing whitespace in message:

"lost before a connection is considered dead. "

And then these two don't seem worded symmetrically enough:

"An empty string means don't load CRL file unless \"ssl_crl_dir\" is set."
"An empty string means don't use CRLs unless \"ssl_crl_file\" is set."

The first one also needs to be "the CRL file".

But I'm thinking something more like:

"An empty string disables the directory-based CRL auto-load mechanism."
(ssl_crl_dir)
"An empty string disables the fixed-file CRL reload mechanism."
(ssl_crl_file)

I don't see much benefit trying to shoe-horn a cross-reference to the other
setting in these brief usage messages. Though if we wanted to a simple
(see also ssr_crl_<file|dir>) would suffice. It seems unworthy of the
limited space to try and communicate the fact that if both are empty
strings no CRL files will be loaded (or that both can be used at the same
time). Even trying to fit in the "auto-load versus reload" dynamic of
these two choices seems awkward.

David J.