docs: mention long options in man watch.1

This patch also changed a little the manual page structure, and wording.

Signed-off-by: Sami Kerola <kerolasa@iki.fi>
This commit is contained in:
Sami Kerola 2011-06-06 23:02:14 +02:00
parent 3fc07c1068
commit 2cf4e8e03a

156
watch.1
View File

@ -1,42 +1,29 @@
.TH WATCH 1 "2010 Mar 01" " " "Linux User's Manual"
.TH WATCH "1" "June 2011" "procps-ng" "User Commands"
.SH NAME
watch \- execute a program periodically, showing output fullscreen
.SH SYNOPSIS
.na
.B watch
.RB [ \-bdehpvtx ]
.RB [ \-n
.IR seconds ]
.RB [ \-\-beep ]
.RB [ \-\-color ]
.RB [ \-\-differences[=\fIcumulative\fP]]
.RB [ \-\-errexit ]
.RB [ \-\-exec ]
.RB [ \-\-help ]
.RB [ \-\-interval=\fIseconds\fP]
.RB [ \-\-no\-title ]
.RB [ \-\-precise ]
.RB [ \-\-version ]
.I command
[\fIoptions\fR] \fIcommand\fR
.SH DESCRIPTION
.B watch
runs
.I command
repeatedly, displaying its output and errors (the first screenfull). This
allows you to
watch the program output change over time. By default, the program is run
every 2 seconds; use
.B \-n
or
.B \-\-interval
to specify a different interval. Normally, this interval is interpreted
as the amout of time between the completion of one run of
.I command
and the beginning of the next run. However, with the
.I \-p
or
.I \-\-precise
option, you can make
allows you to watch the program output change over time. By default, the
program is run every 2 seconds.
.B watch
will run until interrupted.
.SH OPTIONS
.TP
\fB\-f\fR, \fB\-\-differences\fR
Highlight the differences between successive updates.
.TP
\fB\-n\fR, \fB\-\-interval\fR \fIseconds\fR
Specify update interval. The command will not allow quicker than 0.1 second
interval, in which the smaller values are converted.
.TP
\fB\-p\fR, \fB\-\-precise\fR
Make
.BR watch
attempt to run
.I command
@ -44,54 +31,37 @@ every
.I interval
seconds. Try it with
.B ntptime
and notice how the fractional seconds stays
(nearly) the same, as opposed to normal mode where they continuously
increase.
.PP
The
.B \-d
or
.B \-\-differences
flag will highlight the differences between successive updates. Using
.B \-\-differences=\fIcumulative\fP
makes highlighting "sticky", presenting a running display of all
positions that have ever changed. The
.B \-t
or
.B \-\-no\-title
option turns off the header showing the interval, command, and current
time at the top of the display, as well as the following blank line. The
.I \-b
or
.I \-\-beep
option causes the command to beep if it has a non-zero exit.
.PP
.B watch
will normally run until interrupted. If you want
.B watch
to exit on an error from the program running use the
.I \-e
or
.I \-\-errexit
options, which will cause
.B watch
to exit if the return value from the program is non-zero.
.PP
By default \fBwatch\fR will normally not pass escape characters, however
if you use the \fI\-\-c\fR or \fI\-\-color\fR option, then
\fBwatch\fR will interpret ANSI color sequences for the foreground.
.SH NOTE
Note that
and notice how the fractional seconds stays (nearly) the same, as opposed to
normal mode where they continuously increase.
.TP
\fB\-t\fR, \fB\-\-no\-title\fR
Turn off the header showing the interval, command, and current time at the
top of the display, as well as the following blank line.
.TP
\fB\-b\fR, \fB\-\-beep\fR
Beep if command has a non-zero exit.
.TP
\fB\-e\fR, \fB\-\-errexit\fR
Exit on a command error.
.TP
\fB\-c\fR, \fB\-\-color\fR
Interpret ANSI color sequences.
.TP
\fB\-x\fR, \fB\-\-exec\fR
.I command
is given to "sh \-c"
is given to
.B sh \-c
which means that you may need to use extra quoting to get the desired effect.
You can disable this with the
.I -x
or
.I --exec
option, which passes the command to exec(2) instead.
.PP
This with the \-\-exec option, which passes the command to
.BR exec (2)
instead.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display help text and exit.
.TP
\fB\-v\fR, \fB\-\-version\fR
Display version information and exit.
.SH NOTE
Note that POSIX option processing is used (i.e., option processing stops at
the first non\-option argument). This means that flags after
.I command
@ -156,8 +126,8 @@ Blank lines directly after a line which ends in the last column do not
display.
.PP
.I \-\-precise
mode doesn't yet have advanced temporal distortion technology to
compensate for a
mode doesn't yet have advanced temporal distortion technology to compensate
for a
.I command
that takes more than
.I interval
@ -173,12 +143,26 @@ taking ages on a DNS lookup).
.SH AUTHORS
The original
.B watch
was written by Tony Rems <rembo@unisoft.com> in 1991, with mods and
was written by
.UR rembo\@\:unisoft.\:com
Tony Rems
.UE
in 1991, with mods and
corrections by Francois Pinard. It was reworked and new features added by
Mike Coleman <mkc@acm.org> in 1999. The beep, exec, and error handling
features were added by Morty Abzug <morty@frakir.org> in 2008.
On a not so dark and stormy morning
in March of 2003, Anthony DeRobertis <asd@suespammers.org> got sick of
his watches that should update every minute eventually updating many
seconds after the minute started, and added microsecond precision.
Unicode support was added in 2009 by Jarrod Lowe <procps@rrod.net>.
.UR mkc\@\:acm.\:org
Mike Coleman
.UE
in 1999. The beep, exec, and error handling features were added by
.UR morty\@\:frakir.\:org
Morty Abzug
.UE
in 2008. On a not so dark and stormy morning in March of 2003,
.UR asd\@\:suespammers.\:org
Anthony DeRobertis
.UE
got sick of his watches that should update every minute eventually updating
many seconds after the minute started, and added microsecond precision.
Unicode support was added in 2009 by
.UR procps\@\:rrod.\:net
Jarrod Lowe
.UE