[src/trunk]: src/usr.bin/systat systat(1): try to give this page a quick face...

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b401dc85a9bf
branches:  trunk
changeset: 374063:b401dc85a9bf
user:      uwe <uwe%NetBSD.org@localhost>
date:      Wed Mar 29 21:44:35 2023 +0000

description:
systat(1): try to give this page a quick facelift

... too bad what it really needs is reconstructive surgery.  I tried
to fix the most obvious problems (unsorted lists, obviously wrong
markup, pleonastic wording that drowns out useful information in
repetition and lifetime supply of quote marks).

This page really needs a native speaker to take some loving care of it.

diffstat:

 usr.bin/systat/systat.1 |  245 ++++++++++++++++++++++++++---------------------
 1 files changed, 137 insertions(+), 108 deletions(-)

diffs (truncated from 447 to 300 lines):

diff -r 0ef351637b8e -r b401dc85a9bf usr.bin/systat/systat.1
--- a/usr.bin/systat/systat.1   Wed Mar 29 19:40:18 2023 +0000
+++ b/usr.bin/systat/systat.1   Wed Mar 29 21:44:35 2023 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: systat.1,v 1.53 2023/03/29 19:40:18 kre Exp $
+.\"    $NetBSD: systat.1,v 1.54 2023/03/29 21:44:35 uwe Exp $
 .\"
 .\" Copyright (c) 1985, 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"    @(#)systat.1    8.2 (Berkeley) 12/30/93
 .\"
-.Dd August 21, 2021
+.Dd March 29, 2023
 .Dt SYSTAT 1
 .Os
 .Sh NAME
@@ -43,17 +43,18 @@
 .Op Fl t Ar turns
 .Op Fl w Ar wait
 .Op Ar display
-.Op Ar refresh-interval
+.Op Ar wait
 .Sh DESCRIPTION
 .Nm
 displays various system statistics in a screen oriented fashion
-using the curses screen display library,
-.Xr curses 3 .
+using the
+.Xr curses 3
+screen display library.
 .Pp
 While
 .Nm
-is running the screen is usually divided into two windows (an exception
-is the vmstat display which uses the entire screen).
+is running the screen is usually divided into two windows
+.Pq an exception is the vmstat display which uses the entire screen .
 The upper window depicts the current system load average.
 The information displayed in the lower window may vary, depending on
 user commands.
@@ -65,27 +66,27 @@ displays the processes getting the large
 in the lower window.
 Other displays show more detailed process information,
 swap space usage,
-disk usage statistics (a la
-.Xr df 1 ) ,
-disk I/O statistics (a la
-.Xr iostat 8 ) ,
-virtual memory statistics (a la
-.Xr vmstat 1 ) ,
-network
-.Qq Ic mbufs
-utilization, network
-.Qq Ic ifstat 
-traffic, and network connections (a la
-.Xr netstat 1 ) .
+disk usage statistics
+.Pq a\~la Xr df 1 ,
+disk I/O statistics
+.Pq a\~la Xr iostat 8 ,
+virtual memory statistics
+.Pq a\~la Xr vmstat 1 ,
+network mbuf utilization,
+network interface traffic,
+and network connections
+.Pq a\~la Xr netstat 1 .
 .Pp
 Input is interpreted at two different levels.
-A ``global'' command interpreter processes all keyboard input.
+A global command interpreter processes all keyboard input.
 If this command interpreter fails to recognize a command, the
 input line is passed to a per-display command interpreter.
 This allows each display to have certain display-specific commands.
 .Pp
 Command line options:
-.Bl -tag -width "refresh_interval"
+.Bl -tag -width Fl
+.It Fl b
+Show the chosen display once and exit.
 .It Fl M Ar core
 Extract values associated with the name list from
 .Ar core
@@ -96,22 +97,26 @@ Extract the name list from
 .Ar system
 instead of the default
 .Pa /netbsd .
-.It Fl b
-Show the chosen display once and exit.
 .It Fl n
 Do not resolve IP addresses into string hostnames
-.Pq FQDNs
-on
-.Ic netstat .
+.Pf ( Tn FQDN Ns s ) .
 It has the same effect as
 .Ic numbers
 subcommand in
 .Ic netstat .
+.It Fl t Ar turns
+How many refresh cycles to show each screen in
+.Sq all
+display mode.
+The default is 2.
 .It Fl w Ar wait
-See
-.Ar refresh-interval .
-.It Fl t Ar turns
-How many refreshes to show each screen in 'all' display mode.
+Set the screen refresh interval to
+.Ar wait
+seconds.
+Floating point numbers are accepted.
+The default is 1\~second.
+.It Fl z
+Display 0 instead of space when there is no data.
 .It Ar display
 The
 .Ar display
@@ -136,30 +141,23 @@ or
 .Ic vmstat .
 These displays can also be requested interactively and are described in
 full detail below.
-.It Ar refresh-interval
-The
-.Ar refresh-interval
-specifies the screen refresh time interval in seconds.
-This is provided for backwards compatibility, and overrides the
-.Ar refresh-interval
-specified with the
-.Fl w
-flag.
-.It Fl z
-Display 0 instead of space when there is no data.
+.It Ar wait
+The same as
+.Fl w Ar wait .
+This form is provided for backwards compatibility.
 .El
 .Pp
 Certain characters cause immediate action by
 .Nm  .
 These are
-.Bl -tag -width Fl
+.Bl -tag -width Ic
 .It Ic \&^L
 Refresh the screen.
 .It Ic \&^G
-Print the name of the current ``display'' being shown in
+Print the name of the current display being shown in
 the lower window and the refresh interval.
 .It Ic \&^Z
-Stop
+Suspend
 .Nm  .
 .It Ic \&? , Ic h
 Print the names of the available displays on the command line.
@@ -170,15 +168,15 @@ While entering a command the current cha
 and line kill characters may be used.
 .El
 .Pp
-The following commands are interpreted by the ``global''
+The following commands are interpreted by the global
 command interpreter.
-.Bl -tag -width Fl
-.It Ic help Ar key
+.Bl -tag -width Ic
+.It Ic help Op Ar key
 Print the names of the available displays on the command line.
 It will print long names as
-.Dq Ic inet.* .
+.Ql inet.* .
 To print items under
-.Dq Ic inet ,
+.Ic inet ,
 give
 .Ic inet
 as
@@ -186,19 +184,18 @@ as
 .It Ic load
 Print the load average over the past 1, 5, and 15 minutes
 on the command line.
-.It Ic stop
-Stop refreshing the screen.
+.It Ic quit
+Exit
+.Nm  .
+.Pq This may be abbreviated to Ic q .
 .It Oo Ic start Oc Oo Ar number Oc
 Start (continue) refreshing the screen.
 If a second, numeric, argument is provided it is interpreted as a
 refresh interval in seconds.
 Supplying only a number will set the refresh interval to this
 value.
-.It Ic quit
-Exit
-.Nm  .
-(This may be abbreviated to
-.Ic q  . )
+.It Ic stop
+Stop refreshing the screen.
 .El
 .Pp
 The available displays are:
@@ -226,7 +223,7 @@ The following commands are specific to t
 .Ic df
 display:
 .Pp
-.Bl -tag -width Fl -compact
+.Bl -tag -width Fl
 .It Cm all
 Displays information for all filesystems, including
 kernfs, procfs and null-mounts.
@@ -251,33 +248,43 @@ peak
 traffic columns can be altered by the
 .Ic scale
 command.
-.Bl -tag -width ".Cm scale Op Ar units"
+.Bl -tag -width Cm
 .It Cm scale Op Ar units
 Modify the scale used to display the current and peak traffic over all
 interfaces.
-The following units are recognised: kbit, kbyte, mbit,
-mbyte, gbit, gbyte and auto.
+The following units are recognised:
+.Ic kbit , kbyte , mbit , mbyte , gbit , gbyte
+and
+.Ic auto .
 .It Cm pps
-Show statistics in packets per second instead of bytes/bits per second.
+Show statistics in packets per second instead of bytes or bits per second.
 A subsequent call of
 .Ic pps
 switches this mode off.
-.It Cm match Op Ar patterns
-Display only interfaces that match pattern provided as an argument.
-Patterns should be in shell syntax separated by whitespaces or commas.
+.It Cm match Op Ar pattern ...
+Display only interfaces that match
+.Ar pattern\^ Ns s
+provided as an argument.
+Patterns should be in shell
+.Xr glob 7
+syntax separated by whitespaces or commas.
 If this command is called without arguments then all interfaces are displayed.
 For example:
 .Pp
 .Dl match re0, bge1
 .Pp
-This will display re0 and bge1 interfaces.
+This will display
+.Li re0
+and
+.Li bge1
+interfaces.
 .Pp
-.Dl match re*, bge*, lo0
+.Dl match re* bge* lo0
 .Pp
 This will display all
-.Ic re
+.Li re
 interfaces, all
-.Ic bge
+.Li bge
 interfaces and the loopback interface.
 .El
 .It Ic inet.icmp
@@ -287,16 +294,19 @@ Display IPv4 and UDP statistics.
 .It Ic inet.tcp
 Display TCP statistics.
 .It Ic inet.tcpsyn
-Display statistics about the TCP ``syncache''.
+Display statistics about the TCP syncache.
 .It Ic inet6.ip6
 Display IPv6 statistics.
 .It Ic iostat
 Display, in the lower window, statistics about processor use
 and disk throughput.
 Statistics on processor use appear as bar graphs of the amount of
-time executing in user mode (``user''), in user mode running low
-priority processes (``nice''), in system mode (``system''), and
-idle (``idle'').
+time executing in user mode,
+in user mode running low priority
+.Pq Dq nice
+processes,
+in system mode,
+and idle.
 Statistics on disk throughput show, for each drive, kilobytes of
 data transferred, number of disk transactions performed, and time
 spent in disk accesses in milliseconds.
@@ -329,62 +339,74 @@ for particular uses, i.e. data, socket s
 .It Ic netstat
 Display, in the lower window, network connections.
 By default, network servers awaiting requests are not displayed.
-Each address is displayed in the format ``host.port'', with each
+Each address is displayed in the format
+.Ar host Ns Li . Ns Ar port ,