Subject: Re: Possibly hard-to-read message

From: Daniel Gustafsson <[email-masked]>
Date: Mon, 7 Apr 2025 02:55:07 +0200

> On 7 Apr 2025, at 02:43, David G. Johnston <[email-masked]> 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

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 5 Jun 2025 13:14:48 +0200

> 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.

---

From: "David G. Johnston" <[email-masked]>
Date: Thu, 5 Jun 2025 08:57:44 -0700

On Thursday, June 5, 2025, Peter Eisentraut <[email-masked]> wrote:

> 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.
>
> 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.

> 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.

> 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.

> 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.

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 11 Jun 2025 11:08:53 +0200

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 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

---

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 11 Jun 2025 11:36:13 +0200

> On 5 Jun 2025, at 13:14, Peter Eisentraut <[email-masked]> wrote:
> 
> 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.
> 
> - "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.
> 
>        This variable sets the default interval which <command>\watch</command>

How about the attached (reflowing rows in docs not done to keep the diff readable)?

--
Daniel Gustafsson

---

From: "David G. Johnston" <[email-masked]>
Date: Wed, 11 Jun 2025 04:11:22 -0700

> How about the attached (reflowing rows in docs not done to keep the diff
WFM

David J.

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 12 Jun 2025 08:27:42 +0200

> 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.

---

From: Daniel Gustafsson <[email-masked]>
Date: Mon, 16 Jun 2025 10:01:27 +0200

> On 12 Jun 2025, at 08:27, Peter Eisentraut <[email-masked]> wrote:

> The rest looks good to me.

FTR this was committed last week but I missed following up here.

--
Daniel Gustafsson