Postgres Pro
Downloads
Home   >   mailing lists

Thread: Possibly hard-to-read message

Possibly hard-to-read message

From
Kyotaro Horiguchi
Date:
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
Attachment

Re: Possibly hard-to-read message

From
"David G. Johnston"
Date:
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.

Re: Possibly hard-to-read message

From
Daniel Gustafsson
Date:
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.

--
Daniel Gustafsson

Attachment

Re: Possibly hard-to-read message

From
"David G. Johnston"
Date:
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.

Re: Possibly hard-to-read message

From
"David G. Johnston"
Date:
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.