On Tue, Feb 11, 2025 at 3:22 AM David G. Johnston <david.g.johns...@gmail.com> wrote: > > 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 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
