[src/trunk]: src/usr.bin/stat stat(1): Misc fixes.

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

details:   https://anonhg.NetBSD.org/src/rev/00ec977777d2
branches:  trunk
changeset: 367695:00ec977777d2
user:      uwe <uwe%NetBSD.org@localhost>
date:      Wed Jun 22 22:41:13 2022 +0000

description:
stat(1): Misc fixes.

diffstat:

 usr.bin/stat/stat.1 |  202 +++++++++++++++++++++++++++------------------------
 1 files changed, 108 insertions(+), 94 deletions(-)

diffs (truncated from 428 to 300 lines):

diff -r e16c67ced2e8 -r 00ec977777d2 usr.bin/stat/stat.1
--- a/usr.bin/stat/stat.1       Wed Jun 22 22:25:23 2022 +0000
+++ b/usr.bin/stat/stat.1       Wed Jun 22 22:41:13 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: stat.1,v 1.43 2022/06/22 22:25:23 wiz Exp $
+.\"    $NetBSD: stat.1,v 1.44 2022/06/22 22:41:13 uwe Exp $
 .\"
 .\" Copyright (c) 2002-2011 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -75,9 +75,9 @@
 (and also the
 .Sq path name )
 in this case is
-.Dq \&(stdin) .
+.Ql \&(stdin) .
 The file number
-.Pq Dq %@
+.Pq Ql %@
 will be zero.
 .Pp
 Otherwise the information displayed is obtained by calling
@@ -108,23 +108,23 @@
 fields, in that order.
 .Pp
 The options are as follows:
-.Bl -tag -width XFXformatXXX
+.Bl -tag -width Fl
 .It Fl F
 As in
 .Xr ls 1 ,
 display a slash
-.Pq Sq /
+.Pq Ql /
 immediately after each pathname that is a directory, an
 asterisk
-.Pq Sq *
+.Pq Ql *
 after each that is executable, an at sign
-.Pq Sq @
+.Pq Ql @
 after each symbolic link, a percent sign
-.Pq Sq %
+.Pq Ql %
 after each whiteout, an equal sign
-.Pq Sq =
+.Pq Ql =
 after each socket, and a vertical bar
-.Pq Sq \&|
+.Pq Ql \&|
 after each that is a FIFO.
 The use of
 .Fl F
@@ -184,14 +184,20 @@
 stat -t %s -f "$FMT" .
 .Ed
 .Pp
-The timefmt may be altered from the default for
+The
+.Ar timefmt
+may be altered from the default for
 .Fl s
-.Pq Dq \&%s ,
+.Pq Ql \&%s
 by also using the
 .Fl t
 option.
-Note that if you use a timefmt that contains embedded whitespace or shell
-meta-characters, or if the shell's IFS is set to a non-standard value,
+Note that if you use a
+.Ar timefmt
+that contains embedded whitespace or shell
+meta-characters, or if the shell's
+.Dv IFS
+is set to a non-standard value,
 you will need to
 include appropriate quoting in the
 .Fl t
@@ -206,7 +212,9 @@
 This format is
 passed directly to
 .Xr strftime 3
-with the extension that %f prints nanoseconds if available.
+with the extension that
+.Ql %f
+prints nanoseconds if available.
 .It Fl x
 Display information in a more verbose way as seen from some Linux
 distributions.
@@ -235,7 +243,7 @@
 Otherwise the string is examined for the following:
 .Pp
 Any of the following optional flags in any order:
-.Bl -tag -width Ds
+.Bl -tag -width Cm
 .It Cm #
 Selects an alternate output form for string, octal and hexadecimal output.
 String output will be encoded in
@@ -243,7 +251,7 @@
 style.
 Octal output will have a leading zero.
 Non-zero hexadecimal output will have
-.Dq 0x
+.Ql 0x
 prepended to it.
 .It Cm +
 Asserts that a sign indicating whether a number is positive or negative
@@ -262,22 +270,20 @@
 .El
 .Pp
 Then followed by the following fields in the following order:
-.Bl -tag -width Ds
-.It Cm size
+.Bl -tag -width Ar
+.It Ar size
 An optional decimal digit string specifying the minimum field width.
-Note that a leading zero
-.Pq Sq 0
-is treated as the
-.Sq 0
+Note that a leading zero is treated as the
+.Sq Cm 0
 flag (above), subsequent embedded zeroes are part of the
-.Cm size .
-.It Cm prec
+.Ar size .
+.It Ar prec
 An optional precision composed of a decimal point
 .Sq Cm \&.
 and a decimal digit string that indicates the maximum string length,
 the number of digits to appear after the decimal point in floating point
 output, or the minimum number of digits to appear in other numeric output.
-.It Cm fmt
+.It Ar fmt
 An optional output format specifier which is one of
 .Cm D ,
 .Cm O ,
@@ -301,20 +307,22 @@
 .Cm S
 may be used to indicate that the output, if
 applicable, should be in string format.
-May be used in combination with
-.Bl -tag -width Ds
-.It Cm amc
+May be used in combination with the following field specifiers:
+.Bl -tag -width Cm
+.It Cm a , m , c
 Display date in
 .Xr strftime 3
-format with the extension that %f prints nanoseconds if available.
-.It Cm dr
+format with the extension that
+.Ql %f
+prints nanoseconds if available.
+.It Cm d , r
 Display actual device name.
-.It Cm gu
+.It Cm g , u
 Display group or user name.
 .It Cm p
 Display the mode of
 .Ar file
-as in
+symbolically, as in
 .Ic ls -lTd .
 .It Cm N
 Displays the name of
@@ -322,8 +330,10 @@
 .It Cm T
 Displays the type of
 .Ar file .
-.It Cm RY
-Insert a `` -> '' into the output.
+.It Cm R , Y
+Insert a
+.Sq Li \~->\~ \" .Ql, but force quotes even in PS output
+into the output.
 Note that the default output formats for
 .Cm Y
 and
@@ -332,49 +342,51 @@
 .Cm S
 is specified explicitly, these four characters are prepended.
 .El
-.It Cm sub
-An optional sub field specifier (high, middle, or low).
+.It Ar sub
+An optional sub field specifier: high, middle, or low.
 Only applies to the
+.Cm d ,
+.Cm N ,
 .Cm p ,
-.Cm d ,
 .Cm r ,
 .Cm T ,
-.Cm N ,
 and
 .Cm z
 output field specifiers.
 It can be one of the following:
-.Bl -tag -width Ds
+.Bl -tag -width Cm
 .It Cm H
 .Dq High
-\(em depending on the
-.Cm datum :
-.Bl -tag -compact -width door
+subfield of
+.Ar datum\^ :
+.Bl -tag -compact -width Cm
 .It Cm d , r
 Major number for devices
+.It Cm N
+Directory path of the file, similar to what
+.Xr dirname 1
+would show
 .It Cm p
 .Dq User
-bits from the string form of permissions or the file
+bits from the string form of permissions,
+or the file
 .Dq type
 bits from the numeric forms
 .It Cm T
 The long output form of file type
-.It Cm N
-Directory path of the file, similar to what
-.Xr dirname 1
-would show
 .It Cm z
 File size, rounded to the nearest gigabyte
 .El
 .It Cm M
 .Dq Middle
-\(em depending on the
-.Cm datum :
-.Bl -tag -compact -width door
+subfield of
+.Ar datum\^ :
+.Bl -tag -compact -width Cm
 .It Cm p
 The
 .Dq group
-bits from the string form of permissions or the
+bits from the string form of permissions,
+or the
 .Dq suid ,
 .Dq sgid ,
 and
@@ -385,15 +397,20 @@
 .El
 .It Cm L
 .Dq Low
-\(em depending on the
-.Cm datum :
-.Bl -tag -compact -width door
-.It Cm r , d
+subfield of
+.Ar datum\^ :
+.Bl -tag -compact -width Cm
+.It Cm d , r
 Minor number for devices
+.It Cm N
+Base filename of the file, similar to what
+.Xr basename 1
+would show
 .It Cm p
 The
 .Dq other
-bits from the string form of permissions or the
+bits from the string form of permissions,
+or the
 .Dq user ,
 .Dq group ,
 and
@@ -405,15 +422,11 @@
 style output character for file type (the use of
 .Cm L
 here is optional)
-.It Cm N
-Base filename of the file, similar to what
-.Xr basename 1
-would show
 .It Cm z
 File size, rounded to the nearest kilobyte
 .El
 .El
-.It Cm datum
+.It Ar datum
 A required field specifier, ending the conversion specification,
 being one of the following:
 .Bl -tag -width 11n
@@ -469,7 +482,9 @@
 .El
 .Pp
 The following five field specifiers are not drawn directly from the
-data in struct stat, but are:
+data in
+.Vt struct stat ,
+but are:
 .Bl -tag -width Ds