On Mon, Feb 10, 2025 at 9:02 AM Nathan Bossart <nathandboss...@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 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.
