Date: Mon, 10 Feb 2025 10:02:10 -0600
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
Message-ID: <Z6ojAoZPfjGo0qP8@nathan>
References: <Z6aIy4aywxUZHAo6@nathan>
 <CAHut+Ptw+z=uXpGLQU3rXNUhyz3hiBDZD9_d-L0jE0yvboqmFQ@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CAHut+Ptw+z=uXpGLQU3rXNUhyz3hiBDZD9_d-L0jE0yvboqmFQ@mail.gmail.com>
Archived-At: <https://www.postgresql.org/message-id/Z6ojAoZPfjGo0qP8%40nathan>
Precedence: bulk

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