From: Nathan Bossart <nathandbossart@gmail.com>
To: Peter Smith <smithpb2250@gmail.com>
Cc: pgsql-hackers@postgresql.org
Subject: Re: describe special values in GUC descriptions more consistently
Date: Mon, 10 Feb 2025 10:02:10 -0600
Message-ID: <Z6ojAoZPfjGo0qP8@nathan> (raw)
In-Reply-To: <CAHut+Ptw+z=uXpGLQU3rXNUhyz3hiBDZD9_d-L0jE0yvboqmFQ@mail.gmail.com>
References: <Z6aIy4aywxUZHAo6@nathan>
<CAHut+Ptw+z=uXpGLQU3rXNUhyz3hiBDZD9_d-L0jE0yvboqmFQ@mail.gmail.com>
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: nathandbossart@gmail.com, smithpb2250@gmail.com
Subject: Re: describe special values in GUC descriptions more consistently
In-Reply-To: <Z6ojAoZPfjGo0qP8@nathan>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox