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.
