Possibly hard-to-read message
Hello,
I came across the following help message added in commit 1a759c83278:
+ HELP0(" WATCH_INTERVAL\n"
+ " number of seconds \\watch by default waits between executing the query buffer\n");It took me a little while to understand it. I read "executing the
query buffer" as referring to executions of the query buffer, which
clarified that the wait occurs between each execution.
number of seconds \\watch waits by default between executions of the query buffer
I’m just wondering if the message might be worth revising. If it’s
already clear enough, please feel free to disregard this.
regards.
--
Kyotaro Horiguchi
NTT Open Source Software Center
Attachments:
0001-Minor-rewording-of-WATCH_INTERVAL-help-message.patchtext/x-patch; charset=us-asciiDownload
From 523d624f0b3efe94f58934a3c4508c4cc39735bd Mon Sep 17 00:00:00 2001
From: Kyotaro Horiguchi <horikyota.ntt@gmail.com>
Date: Wed, 26 Mar 2025 11:58:37 +0900
Subject: [PATCH] Minor rewording of WATCH_INTERVAL help message
Improve phrasing for better readability of the recently added message.
---
src/bin/psql/help.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index fe96e3e1de9..62edfb121c7 100644
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -461,7 +461,7 @@ helpVariables(unsigned short int pager)
" VERSION_NUM\n"
" psql's version (in verbose string, short string, or numeric format)\n");
HELP0(" WATCH_INTERVAL\n"
- " number of seconds \\watch by default waits between executing the query buffer\n");
+ " number of seconds \\watch waits by default between executions of the query buffer\n");
HELP0("\nDisplay settings:\n");
HELP0("Usage:\n");
--
2.43.5
On Tue, Mar 25, 2025 at 8:07 PM Kyotaro Horiguchi <horikyota.ntt@gmail.com>
wrote:
Hello,
I came across the following help message added in commit 1a759c83278:
+ HELP0(" WATCH_INTERVAL\n" + " number of seconds \\watch by default waits between executing the query buffer\n");It took me a little while to understand it. I read "executing the
query buffer" as referring to executions of the query buffer, which
clarified that the wait occurs between each execution.number of seconds \\watch waits by default between executions of the
query buffer
I’m just wondering if the message might be worth revising. If it’s
already clear enough, please feel free to disregard this.
I'm on board with tweaking this.
default number of seconds \watch waits after each execution.
Requires changing \watch:
- Wait the specified number of seconds (default 2) between executions.
+Wait the specified number of seconds (default 2) after each execution.The fragment "of the query buffer" can be omitted from the description for
watch_interval to match up with the wording in \watch.
The manual too would be updated:
- This variable sets the default interval which \watch waits between
executing the query.
+This variable sets the default interval \watch waits after each query
execution.(Removing "which" should be considered regardless; tongue-twister and not
all that sure it is grammatically correct or necessary.)
I'm guess I'm ok with the second sentence there; but all it is doing is
explain how defaults work...
Specifying an interval in the command overrides this variable.
David J.
On 26 Mar 2025, at 04:52, David G. Johnston <david.g.johnston@gmail.com> wrote:
On Tue, Mar 25, 2025 at 8:07 PM Kyotaro Horiguchi <horikyota.ntt@gmail.com <mailto:horikyota.ntt@gmail.com>> wrote:
I came across the following help message added in commit 1a759c83278:
+ HELP0(" WATCH_INTERVAL\n" + " number of seconds \\watch by default waits between executing the query buffer\n");It took me a little while to understand it.
I'm on board with tweaking this.
How about the attached? We already have "(default: X)" in other places so this
aligns it better while simplifying the language.
--
Daniel Gustafsson

Attachments:
helptext.diffapplication/octet-stream; name=helptext.diff; x-unix-mode=0644Download
diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index fe96e3e1de9..5c490cbfaa3 100644
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -460,8 +460,9 @@ helpVariables(unsigned short int pager)
" VERSION_NAME\n"
" VERSION_NUM\n"
" psql's version (in verbose string, short string, or numeric format)\n");
- HELP0(" WATCH_INTERVAL\n"
- " number of seconds \\watch by default waits between executing the query buffer\n");
+ HELPN(" WATCH_INTERVAL\n"
+ " number of seconds \\watch waits after each query (default: %s)\n",
+ DEFAULT_WATCH_INTERVAL);
HELP0("\nDisplay settings:\n");
HELP0("Usage:\n");
On Wed, Mar 26, 2025 at 2:11 AM Daniel Gustafsson <daniel@yesql.se> wrote:
On 26 Mar 2025, at 04:52, David G. Johnston <david.g.johnston@gmail.com>
wrote:
On Tue, Mar 25, 2025 at 8:07 PM Kyotaro Horiguchi <horikyota.ntt@gmail.com>
wrote:I came across the following help message added in commit 1a759c83278:
+ HELP0(" WATCH_INTERVAL\n" + " number of seconds \\watch by default waits between executing the query buffer\n");It took me a little while to understand it.
I'm on board with tweaking this.
How about the attached? We already have "(default: X)" in other places so
this
aligns it better while simplifying the language.
This change is technically wrong on two points:
I pondered mentioning the 2s interval but the environment variable itself
doesn't have a default, it's either set or unset which determines whether
it provides the default or not. IMO, adding this detail produces too much
text for little benefit.
Your wording loses the idea that this environment variable only establishes
a new default that can be subsequently overridden by explicitly specifying
an interval to \watch.
David J.
On Wed, Mar 26, 2025 at 6:34 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:
I pondered mentioning the 2s interval but the environment variable itself
doesn't have a default, it's either set or unset which determines whether
it provides the default or not. IMO, adding this detail produces too much
text for little benefit.
On second thought, something like:
WATCH_INTERVAL: an integer number of seconds; overrides the default two
second \watch interval
(not quite happy but it's close...keeps the 2s reference point)
David J.
On 27 Mar 2025, at 02:42, David G. Johnston <david.g.johnston@gmail.com> wrote:
On second thought, something like:
WATCH_INTERVAL: an integer number of seconds; overrides the default two second \watch interval
(not quite happy but it's close...keeps the 2s reference point)
Looking at the other variables they tend to use "if set, then" so we should
probably stick to that for this as well? Something like the below perhaps?
HELP0(" WATCH_INTERVAL\n"
- " number of seconds \\watch by default waits between executing the query buffer\n");
+ " if set to an interval value, overrides the default two second \\watch interval\n");--
Daniel Gustafsson
On Sun, Apr 6, 2025 at 2:52 PM Daniel Gustafsson <daniel@yesql.se> wrote:
Looking at the other variables they tend to use "if set, then" so we should
probably stick to that for this as well? Something like the below perhaps?HELP0(" WATCH_INTERVAL\n" - " number of seconds \\watch by default waits between executing the query buffer\n"); + " if set to an interval value, overrides the default two second \\watch interval\n");
Using "interval" here could cause minor confusion since it is a valid core
data type but not accepted here.
psql --set=WATCH_INTERVAL='10m' postgres
psql: error: invalid value "10m" for "WATCH_INTERVAL"
select '10m'::interval;
interval
----------
00:10:00
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.
David J.
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.
--
Daniel Gustafsson
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.
On Thursday, June 5, 2025, Peter Eisentraut <peter@eisentraut.org> wrote:
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.
If not set to a number (data type indicator) it doesn’t override. I
suppose “to a number” could be removed since mention of seconds implies
that you better enter a number for the value.
- 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.
Can you demonstrate this claim? It’s basically an environment variable -
which are conventionally unset in the environment, and when set their value
overrides some other externally defined value. In this case a define.
I suggest something like this:
number seconds \watch waits between executions (in seconds, default %d)
So, get rid of the technicality of it being set/unset and just phrase it
from the user’s perspective. I could live with that.
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.
True, it needs to be clear the input number is interpreted as seconds.
Again, technically has no default being an environment variable but I’m
fine if people want to ignore that fact and instead treat it like it does
from the user’s perspective. The environment variable set/unset just seems
like standard behavior in our world, I am not seeing why it’s confusing
here. Do you want to point out an example we should be emulating?
David J.
On 05.06.25 17:57, David G. Johnston wrote:
- "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.If not set to a number (data type indicator) it doesn’t override. I
suppose “to a number” could be removed since mention of seconds implies
that you better enter a number for the value.
If you don't set it to a number, you get an error, so this case can't
even happen:
postgres=# \set WATCH_INTERVAL foo
invalid value "foo" for "WATCH_INTERVAL"
- 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.Can you demonstrate this claim? It’s basically an environment variable
- which are conventionally unset in the environment, and when set their
value overrides some other externally defined value. In this case a define.
$ psql -X
postgres=# \echo :WATCH_INTERVAL
2
On 5 Jun 2025, at 13:14, Peter Eisentraut <peter@eisentraut.org> wrote:
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.
How about the attached (reflowing rows in docs not done to keep the diff readable)?
--
Daniel Gustafsson
Attachments:
helptext_v2.diffapplication/octet-stream; name=helptext_v2.diff; x-unix-mode=0644Download
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 8f7d8758ca0..2dfbdc9f740 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -4752,8 +4752,8 @@ bar
<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
+ This variable sets the default interval, in seconds, which <command>\watch</command>
+ waits between executing the query. The default is 2 seconds. Specifying an interval in the
command overrides this variable.
</para>
</listitem>
diff --git a/src/bin/psql/help.c b/src/bin/psql/help.c
index 403b51325a7..907c7f78093 100644
--- a/src/bin/psql/help.c
+++ b/src/bin/psql/help.c
@@ -464,7 +464,8 @@ helpVariables(unsigned short int pager)
" VERSION_NUM\n"
" psql's version (in verbose string, short string, or numeric format)\n");
HELP0(" WATCH_INTERVAL\n"
- " if set to a number, overrides the default two second \\watch interval\n");
+ " number of seconds \\watch waits between executions (default %s seconds)\n",
+ DEFAULT_WATCH_INTERVAL);
HELP0("\nDisplay settings:\n");
HELP0("Usage:\n");
On Wednesday, June 11, 2025, Daniel Gustafsson <daniel@yesql.se> wrote:
How about the attached (reflowing rows in docs not done to keep the diff
readable)?
WFM
David J.
On 11.06.25 11:36, Daniel Gustafsson wrote:
On 5 Jun 2025, at 13:14, Peter Eisentraut <peter@eisentraut.org> wrote:
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.
How about the attached (reflowing rows in docs not done to keep the diff readable)?
HELP0(" WATCH_INTERVAL\n"
- " if set to a number, overrides the default two second \\watch
interval\n");
+ " number of seconds \\watch waits between executions (default %s
seconds)\n",
+ DEFAULT_WATCH_INTERVAL);This wording has the disadvantage that it requires plural-enabling the
translation of "seconds". I think you can just leave off the second
"seconds" to avoid that.
The rest looks good to me.