Re: describe special values in GUC descriptions more consistently

On Tue, Feb 11, 2025 at 3:22 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Mon, Feb 10, 2025 at 9:02 AM Nathan Bossart <nathandbossart@gmail.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 for this. Your wording examples below look good to me..

> -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.
>

======
Kind Regards,
Peter Smith.
Fujitsu Australia