Re: describe special values in GUC descriptions more consistently

On Mon, Feb 10, 2025 at 9:02 AM Nathan Bossart <nathandbossart(at)gmail(dot)com>
wrote:

> On Mon, Feb 10, 2025 at 09:13:26AM +1100, Peter Smith wrote:
> > +1 for improving consistency.
>
> Thanks for reviewing.
>
> > 1. IMO all places wording as "XXX means to YYY" should be just "XXX
> > means YYY" (e.g. remove the "to")
> >
> > e.g. "-1 means to wait forever." => "-1 means wait forever."
> > e.g. ""-1 means to log values in full." => "-1 means log values in full."
>
> I think this works in some cases, but IMHO it sounds awkward with the
> "means to use" ones (e.g., "0 means use the system default"). So I would
> probably leave the "to" in those.
>
> > 2. GUC names in messages should always be double quoted.
>
> Will fix.
>
> > 3. Wording for the automatic selections.
> >
> > Some of the special values get calculated and assigned *automatically*
> > on your behalf. The patch currently seems to be using "means to use"
> > for these:
> >
> > I felt all these should be written as:
> > "XXX means to use YYY" => "XXX means YYY is used."
> >
> > e.g. "0 means to use a suitable default value." => "0 means a suitable
> > default value is used."
> > e.g. "0 means to use a fraction of \"shared_buffers\"." => "0 means a
> > fraction of \"shared_buffers\" is used".
> > e.g. "-1 means to use vacuum_cost_limit" => "-1 means
> > \"vacuum_cost_limit\" is used."
>
> I'm also not tremendously happy with "means to use," but I'd like to avoid
> passive voice if possible.
>
>
For most of these "is used" is just noise anyway and we can simplify things
to:

X means [no "to"] <verb: log, compute, sample, disable> thing

-1 means log values in full
0 means sample all statements
-1 means disable sampling
-1 means wait forever

-1 means use vacuum_cost_limit
0 means compute a fraction of "shared_buffers" (0 means use a fraction of
"shared_buffers" also works)

I get the argument for avoiding saying what the fraction used is; but at
the same time it seems like it should be documented.

David J.