From: Job Snijders <job@openbsd.org>
Subject: Re: watch(1) - periodically execute a command and display its output
To: tech@openbsd.org
Date: Tue, 20 May 2025 06:46:30 +0000

On Tue, May 20, 2025 at 12:43:34AM -0600, Theo de Raadt wrote:
> A good example of actual useful truth is in less(1):

How about this?

Index: watch.1
===================================================================
RCS file: /cvs/src/usr.bin/watch/watch.1,v
diff -u -p -r1.3 watch.1
--- watch.1	20 May 2025 06:17:04 -0000	1.3
+++ watch.1	20 May 2025 06:45:48 -0000
@@ -1,3 +1,4 @@
+.\"	$OpenBSD$
 .\"
 .\" Copyright (c) 2000, 2001, 2014, 2016 Internet Initiative Japan Inc.
 .\"
@@ -13,33 +14,25 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" The following requests are required for all man pages.
-.\"
-.Dd April 18, 2013
-.Dt IWATCH 1
+.Dd $Mdocdate$
+.Dt WATCH 1
 .Os
 .Sh NAME
-.Nm iwatch
-.Nd watch the command output with interval timer
+.Nm watch
+.Nd periodically execute a command and display its output
 .Sh SYNOPSIS
 .Nm
 .Op Fl rewpx
 .Op Fl i Ar interval
 .Ar command Op Ar argument ...
 .Sh DESCRIPTION
+The
 .Nm
-displays the output of a
+utility periodically executes and displays the output of
 .Ar command
 with
-.Ar argument
-and update the output with a specified number of
-.Ar interval .
-The changes of outputs can be highlighted.
-Note that shell escaping needed at the command and arguments since they
-are given to
-.Ic sh -c .
-.Fl x
-option changes this behaviour.
+.Ar argument .
+Differences between successive runs can be highlighted.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
@@ -52,24 +45,15 @@ Highlight the changed word.
 .It Fl p
 Start with pausing the update.
 .It Fl x
-Pass the
+Pass
 .Ar command
 and
 .Ar arguments
 to
-.Xr exec 2
-as it is.
-In default behaviour,
-shell escaping is required at the
-.Ar command
-and
-.Ar argument
-because
-.Nm
-uses
-.Ic sh -c
-for handing them.
-Use this option not to do unnecessary shell escaping.
+.Xr execl 3
+instead of
+.Ic sh -c ,
+for different quoting and shell escaping behaviour.
 .It Fl i Ar interval
 Set the initial interval second of the periodical update to
 .Ar interval .
@@ -137,12 +121,13 @@ Show help message.
 Quit the program.
 .El
 .Sh SEE ALSO
-.Xr sh 1
-.Xr exec 2
+.Xr sh 1 ,
+.Xr execl 3
 .Sh HISTORY
-The
 .Nm
-program is slightly derived from
-.Nm watch
-command come with BSD/OS 3.1 by BSDI, Inc.,
-which originally came from some free distribution.
+was first published in 1991 and has been available since
+.Ox 7.8 .
+.Sh AUTHORS
+Takuya Sato, Kazumasa Utashiro, and YASUOKA Masahiko from Internet Initiative
+Japan, with contributions from
+.An Job Snijders Aq Mt job@openbsd.org .