Feedback-ID: ie0a040ee:Fastmail
Message-ID: <c34a650b-6f8b-4da7-9ebb-b6df03ce009d@eisentraut.org>
Date: Thu, 5 Jun 2025 13:14:48 +0200
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: Possibly hard-to-read message
To: Daniel Gustafsson <daniel@yesql.se>,
 "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Kyotaro Horiguchi <horikyota.ntt@gmail.com>,
 pgsql-hackers@lists.postgresql.org
References: <20250326.120732.1167093737847500721.horikyota.ntt@gmail.com>
 <CAKFQuwYN3wP2cz=FDJyOyLEutgXfJOZNS+8SFhWdwUR-QsbRgQ@mail.gmail.com>
 <B078F4D4-ED92-4838-9660-BD8FD781CF2B@yesql.se>
 <CAKFQuwbV7kD-v-SYjyQTvxOUui5HkRcXO4RoMNnbPaDL=Bw0WQ@mail.gmail.com>
 <CAKFQuwYJLJvt17eSAtxeBLngNrEzQD+kU4GpP7HwcupmL_NbmQ@mail.gmail.com>
 <2E4127D5-85B9-40B5-8D6F-C44B57E92DDD@yesql.se>
 <CAKFQuwYDZEmRnmSUUQSi=vX7MiKXb3Z-4eyAB1RqqmtWxJ0DTA@mail.gmail.com>
 <A04BC71A-D3D6-41BD-91A1-CD0721E4E698@yesql.se>
Content-Language: de-DE, en-US
From: Peter Eisentraut <peter@eisentraut.org>
In-Reply-To: <A04BC71A-D3D6-41BD-91A1-CD0721E4E698@yesql.se>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: 
 <https://www.postgresql.org/message-id/c34a650b-6f8b-4da7-9ebb-b6df03ce009d%40eisentraut.org>
Precedence: bulk

On 07.04.25 02:55, Daniel Gustafsson wrote:
>> On 7 Apr 2025, at 02:43, David G. Johnston <david.g.johnston@gmail.com> wrote:
> 
>> How about:
>>
>> + "    if set to a number, overrides the default two second \\watch interval\n"
>>
>> I do like the consistency of "if set" even though most of the others are booleans.
> 
> Ah yes, number is better. I'll go ahead with that in the morning.

I came across this psql help text and had a hard time processing it, 
and, without having read this thread, my thought process was that the 
message should be phrased more like how it was originally.

The problem with the current phrasing is:

- "if set to a number" seems to indicate that something else happens if 
it's not a number.  But it doesn't say what.  And it's also not true. 
And we don't phrase things like that for other numeric settings.

- The way this is phrased now seems to say that the variable is unset by 
default, and only if it is set does it override the default.  But that 
is not what happens.  The variable has a value by default, and that is 
what gets used.

I suggest something like this:

number seconds \watch waits between executions (in seconds, default %d)


While we're here, the documentation could also use some more detail:

       <varlistentry id="app-psql-variables-watch-interval">
         <term><varname>WATCH_INTERVAL</varname></term>
         <listitem>
         <para>
         This variable sets the default interval which 
<command>\watch</command>
         waits between executing the query.  Specifying an interval in the
         command overrides this variable.
         </para>
         </listitem>
       </varlistentry>

This mentions neither the units nor the default value.