Re: describe special values in GUC descriptions more consistently

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.

> 4. When there are multiple special values, it seems more natural if
> the values are ordered. Maybe just personal preference.
>
> e.g. "0 means to log all files. -1 disables temporary file logs." =>
> "-1 disables temporary file logs. 0 means log all files."

Seems reasonable to me.

--
nathan