Consistentify miscellaneous style on remaining manpages

Most notably this fixes the vdev_id(8) non-.Xrs in vdev_id.conf.5 Reviewed-by: Richard Laager <[email protected]> Reviewed-by: Brian Behlendorf <[email protected]> Signed-off-by: Ahelenia Ziemiańska <[email protected]> Closes #12212
openzfs · Jun 9, 2021 · 1b37cc1 · 1b37cc1
1 parent 2badb34
commit 1b37cc1
Show file tree

Hide file tree

Showing 8 changed files with 65 additions and 64 deletions.
diff --git a/man/man1/arcstat.1 b/man/man1/arcstat.1
@@ -22,7 +22,7 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl havxp
-.Op Fl f Ar field Ns Op , Ns Ar field Ns ...
+.Op Fl f Ar field Ns Op , Ns Ar field Ns …
 .Op Fl o Ar file
 .Op Fl s Ar string
 .Op Ar interval
@@ -31,7 +31,7 @@
 .Sh DESCRIPTION
 .Nm
 prints various ZFS ARC and L2ARC statistics in vmstat-like fashion:
-.Bl -tag -width "l2asize"
+.Bl -tag -compact -offset Ds -width "l2asize"
 .It Sy c
 ARC target size
 .It Sy dh%
@@ -155,7 +155,7 @@ Print all possible stats.
 .It Fl f
 Display only specific fields.
 See
-.Sy DESCRIPTION
+.Sx DESCRIPTION
 for supported statistics.
 .It Fl h
 Display help message.
@@ -166,17 +166,19 @@ Disable auto-scaling of numerical fields (for raw, machine-parsable values).
 .It Fl s
 Display data with a specified separator (default: 2 spaces).
 .It Fl x
-Print extended stats (same as
-.Fl f Ar time,mfu,mru,mfug,mrug,eskip,mtxmis,dread,pread,read Ns No ).
+Print extended stats
+.Pq same as Fl f Sy time , Ns Sy mfu , Ns Sy mru , Ns Sy mfug , Ns Sy mrug , Ns Sy eskip , Ns Sy mtxmis , Ns Sy dread , Ns Sy pread , Ns Sy read .
 .It Fl v
 Show field headers and definitions
 .El
 .
 .Sh OPERANDS
 The following operands are supported:
-.Bl -tag -width "interval"
+.Bl -tag -compact -offset Ds -width "interval"
 .It Ar interval
 Specify the sampling interval in seconds.
 .It Ar count
-Display only \fIcount\fR reports.
+Display only
+.Ar count
+reports.
 .El
diff --git a/man/man1/cstyle.1 b/man/man1/cstyle.1
@@ -31,7 +31,7 @@
 .Nm
 .Op Fl chpvCP
 .Op Fl o Ar construct Ns Op , Ns Ar construct Ns …
-.Op Ar file…
+.Oo Ar file Oc Ns …
 .Sh DESCRIPTION
 .Nm
 inspects C source files (*.c and *.h) for common stylistic errors.
@@ -99,7 +99,7 @@ Allow doxygen-style block comments
 .Pq Sy /** No and Sy /*!\& .
 .It Sy splint
 Allow splint-style lint comments
-.Pq Sy /*@...@*/ .
+.Pq Sy /*@ Ns ... Ns Sy @*/ .
 .El
 .El
 .
@@ -118,43 +118,42 @@ statement has balanced parenthesis.
 .It
 Some
 .Xr cpp 1
-macros do not require \fB;\fPs after them.
+macros do not require
+.Sy ;\& Ns s after them.
 Any such macros
 .Em must
 be ALL_CAPS; any lower case letters will cause bad output.
 .Pp
-The bad output will generally be corrected after the next \fB;\fP,
-.Sy { ,
-or
-.Sy } .
+The bad output will generally be corrected after the next
+.Sy ;\& , { , No or Sy } .
 .El
 Some continuation error messages deserve some additional explanation:
 .Bl -tag -width Ds
 .It Sy multiple statements continued over multiple lines
 A multi-line statement which is not broken at statement boundaries.
 For example:
-.Bd -literal
+.Bd -literal -compact -offset Ds
 if (this_is_a_long_variable == another_variable) a =
     b + c;
 .Ed
 .Pp
 Will trigger this error.
 Instead, do:
-.Bd -literal
+.Bd -literal -compact -offset Ds
 if (this_is_a_long_variable == another_variable)
     a = b + c;
 .Ed
 .It Sy empty if/for/while body not on its own line
 For visibility, empty bodies for if, for, and while statements should be
 on their own line.
 For example:
-.Bd -literal
+.Bd -literal -compact -offset Ds
 while (do_something(&x) == 0);
 .Ed
 .Pp
 Will trigger this error.
 Instead, do:
-.Bd -literal
+.Bd -literal -compact -offset Ds
 while (do_something(&x) == 0)
     ;
 .Ed

diff --git a/man/man1/raidz_test.1 b/man/man1/raidz_test.1
@@ -50,44 +50,44 @@ option.
 .Bl -tag -width "-B(enchmark)"
 .It Fl h
 Print a help summary.
-.It Fl a Ar ashift No (default: Sy 9 )
+.It Fl a Ar ashift Pq default: Sy 9
 Ashift value.
-.It Fl o Ar zio_off_shift No (default: Sy 0 )
+.It Fl o Ar zio_off_shift Pq default: Sy 0
 ZIO offset for each raidz block.
 The offset's value is
-.Sy 1 << zio_off_shift .
-.It Fl d Ar raidz_data_disks No (default: Sy 8 )
+.Em 2^zio_off_shift .
+.It Fl d Ar raidz_data_disks Pq default: Sy 8
 Number of raidz data disks to use.
 Additional disks will be used for parity.
-.It Fl s Ar zio_size_shift No (default: Sy 19 )
+.It Fl s Ar zio_size_shift Pq default: Sy 19
 Size of data for raidz block.
 The real size is
-.Sy 1 << zio_size_shift .
-.It Fl r Ar reflow_offset No (default: Sy uint max )
+.Em 2^zio_size_shift .
+.It Fl r Ar reflow_offset Pq default: Sy uint max
 Set raidz expansion offset.
 The expanded raidz map allocation function will
 produce different map configurations depending on this value.
-.It Fl S Ns No (weep)
+.It Fl S Ns Pq weep
 Sweep parameter space while verifying the raidz implementations.
 This option
 will exhaust all most of valid values for the
 .Fl aods
 options.
 Runtime using this option will be long.
-.It Fl t Ns No (imeout)
+.It Fl t Ns Pq imeout
 Wall time for sweep test in seconds.
 The actual runtime could be longer.
-.It Fl B Ns No (enchmark)
+.It Fl B Ns Pq enchmark
 All implementations are benchmarked using increasing per disk data size.
 Results are given as throughput per disk, measured in MiB/s.
-.It Fl e Ns No (xpansion)
+.It Fl e Ns Pq xpansion
 Use expanded raidz map allocation function.
-.It Fl v Ns No (erbose)
+.It Fl v Ns Pq erbose
 Increase verbosity.
-.It Fl T Ns No (est the test)
+.It Fl T Ns Pq est the test
 Debugging option: fail all tests.
 This is to check if tests would properly verify bit-exactness.
-.It Fl D Ns No (ebug)
+.It Fl D Ns Pq ebug
 Debugging option: attach
 .Xr gdb 1
 when

diff --git a/man/man1/zhack.1 b/man/man1/zhack.1
@@ -119,7 +119,7 @@ Can be specified more than once.
 .
 .Sh EXAMPLES
 .Bd -literal
-# zhack feature stat tank
+.No # Nm zhack Cm feature stat Ar tank
 for_read_obj:
 	org.illumos:lz4_compress = 0
 for_write_obj:
@@ -130,10 +130,8 @@ descriptions_obj:
 	com.delphix:empty_bpobj = Snapshots use less space.
 	org.illumos:lz4_compress = LZ4 compression algorithm support.
 
-# zhack feature enable -d 'Predict future disk failures.' \\
-    tank com.example:clairvoyance
-
-# zhack feature ref tank com.example:clairvoyance
+.No # Nm zhack Cm feature enable Fl d No 'Predict future disk failures.' Ar tank com.example:clairvoyance
+.No # Nm zhack Cm feature ref Ar tank com.example:clairvoyance
 .Ed
 .
 .Sh SEE ALSO

diff --git a/man/man5/vdev_id.conf.5 b/man/man5/vdev_id.conf.5
@@ -14,13 +14,13 @@
 .
 .Sh NAME
 .Nm vdev_id.conf
-.Nd Configuration file for vdev_id
+.Nd configuration file for vdev_id(8)
 .Sh DESCRIPTION
 .Nm
 is the configuration file for
-.Nm vdev_id Ns Sy (8) .
+.Xr vdev_id 8 .
 It controls the default behavior of
-.Nm vdev_id Ns Sy (8)
+.Xr vdev_id 8
 while it is mapping a disk device name to an alias.
 .Pp
 The
@@ -37,7 +37,7 @@ Maps a device link in the
 .Pa /dev
 directory hierarchy to a new device name.
 The udev rule defining the device link must have run prior to
-.Nm vdev_id Ns Sy (8) .
+.Xr vdev_id 8 .
 A defined alias takes precedence over a topology-derived name, but the
 two naming methods can otherwise coexist.
 For example, one might name drives in a JBOD with the
@@ -94,12 +94,12 @@ and a default mapping applied to the others.
 .
 .It Sy multipath Sy yes Ns | Ns Sy no
 Specifies whether
-.Nm vdev_id Ns Sy (8)
+.Xr vdev_id 8
 will handle only dm-multipath devices.
 If set to
 .Sy yes
 then
-.Nm vdev_id Ns Sy (8)
+.Xr vdev_id 8
 will examine the first running component disk of a dm-multipath
 device as provided by the driver command to determine the physical path.
 .
@@ -116,7 +116,7 @@ channels are uniquely identified by a SAS switch port number
 .It Sy phys_per_port Ar num
 Specifies the number of PHY devices associated with a SAS HBA port or SAS
 switch port.
-.Nm vdev_id Ns Sy (8)
+.Xr vdev_id 8
 internally uses this value to determine which HBA or switch port a
 device is connected to.
 The default is
@@ -157,13 +157,13 @@ may be unstable across disk replacement.
 .Bl -tag -width "-v v"
 .It Pa /etc/zfs/vdev_id.conf
 The configuration file for
-.Nm vdev_id Ns Sy (8) .
+.Xr vdev_id 8 .
 .El
 .
 .Sh EXAMPLES
 A non-multipath configuration with direct-attached SAS enclosures and an
 arbitrary slot re-mapping:
-.Bd -literal -offset Ds
+.Bd -literal -compact -offset Ds
 multipath     no
 topology      sas_direct
 phys_per_port 4
@@ -195,8 +195,8 @@ slot 4          3
 A SAS-switch topology.
 Note, that the
 .Ar channel
-keyword takes only two arguments in this example.
-.Bd -literal -offset Ds
+keyword takes only two arguments in this example:
+.Bd -literal -compact -offset Ds
 topology      sas_switch
 
 #       SWITCH PORT  CHANNEL NAME
@@ -207,9 +207,8 @@ channel 4            D
 .Ed
 .Pp
 A multipath configuration.
-Note that channel names have multiple
-definitions - one per physical path.
-.Bd -literal -offset Ds
+Note that channel names have multiple definitions - one per physical path:
+.Bd -literal -compact -offset Ds
 multipath yes
 
 #       PCI_SLOT HBA PORT  CHANNEL NAME
@@ -219,8 +218,8 @@ channel 86:00.0  1         A
 channel 86:00.0  0         B
 .Ed
 .Pp
-A configuration with enclosure_symlinks enabled.
-.Bd -literal -offset Ds
+A configuration with enclosure_symlinks enabled:
+.Bd -literal -compact -offset Ds
 multipath yes
 enclosure_symlinks yes
 
@@ -230,17 +229,16 @@ channel    05:00.0     0            L
 channel    06:00.0     1            U
 channel    06:00.0     0            L
 .Ed
-.Pp
 In addition to the disks symlinks, this configuration will create:
-.Bd -literal -offset Ds
+.Bd -literal -compact -offset Ds
 /dev/by-enclosure/enc-L0
 /dev/by-enclosure/enc-L1
 /dev/by-enclosure/enc-U0
 /dev/by-enclosure/enc-U1
 .Ed
 .Pp
-A configuration using device link aliases.
-.Bd -literal -offset Ds
+A configuration using device link aliases:
+.Bd -literal -compact -offset Ds
 #     by-vdev
 #     name     fully qualified or base name of device link
 alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca

diff --git a/man/man8/fsck.zfs.8 b/man/man8/fsck.zfs.8
@@ -58,15 +58,19 @@ interface still allows it to communicate some errors: if the
 .Ar dataset
 is in a degraded pool, then
 .Nm
-will return exit code 4 to indicate an uncorrected filesystem error.
+will return exit code
+.Sy 4
+to indicate an uncorrected filesystem error.
 .Pp
 Similarly, if the
 .Ar dataset
 is in a faulted pool and has a legacy
 .Pa /etc/fstab
 record, then
 .Nm
-will return exit code 8 to indicate a fatal operational error.
+will return exit code
+.Sy 8
+to indicate a fatal operational error.
 .Sh SEE ALSO
 .Xr fstab 5 ,
 .Xr fsck 8 ,

diff --git a/man/man8/zed.8.in b/man/man8/zed.8.in
@@ -147,7 +147,7 @@ is sourced by scripts; these variables should be prefixed with
 The zevent nvpairs are passed to ZEDLETs as environment variables.
 Each nvpair name is converted to an environment variable in the following
 manner:
-.Bl -enum
+.Bl -enum -compact
 .It
 it is prefixed with
 .Sy ZEVENT_ ,
@@ -160,7 +160,7 @@ each non-alphanumeric character is converted to an underscore.
 Some additional environment variables have been defined to present certain
 nvpair values in a more convenient form.
 An incomplete list of zevent environment variables is as follows:
-.Bl -tag -width "ZEVENT_TIME_STRING"
+.Bl -tag -compact -width "ZEVENT_TIME_STRING"
 .It Sy ZEVENT_EID
 The Event IDentifier.
 .It Sy ZEVENT_CLASS
@@ -187,7 +187,7 @@ An almost-RFC3339-compliant string for
 .El
 .Pp
 Additionally, the following ZED & ZFS variables are defined:
-.Bl -tag -width "ZEVENT_TIME_STRING"
+.Bl -tag -compact -width "ZEVENT_TIME_STRING"
 .It Sy ZED_PID
 The daemon's process ID.
 .It Sy ZED_ZEDLET_DIR

diff --git a/man/man8/zpool_influxdb.8 b/man/man8/zpool_influxdb.8
@@ -32,7 +32,7 @@
 .Op Fl e Ns | Ns Fl -execd
 .Op Fl n Ns | Ns Fl -no-histogram
 .Op Fl s Ns | Ns Fl -sum-histogram-buckets
-.Op Fl t Ns | Ns Fl -tags Ar key Ns = Ns Ar value Ns Op , Ns Ar key Ns = Ns Ar value Ns …
+.Op Fl t Ns | Ns Fl -tags Ar key Ns = Ns Ar value Ns Oo , Ns Ar key Ns = Ns Ar value Oc Ns …
 .Op Ar pool
 .
 .Sh DESCRIPTION
@@ -80,7 +80,7 @@ By default, the values are not accumulated and the raw data appears as shown by
 .Nm zpool Cm iostat .
 This works well for Grafana's heatmap plugin.
 Summing the buckets produces output similar to Prometheus histograms.
-.It Fl t , Fl -tags Ar key Ns = Ns Ar value Ns Op , Ns Ar key Ns = Ns Ar value Ns …
+.It Fl t , Fl -tags Ar key Ns = Ns Ar value Ns Oo , Ns Ar key Ns = Ns Ar value Oc Ns …
 Adds specified tags to the tag set.
 No sanity checking is performed.
 See the InfluxDB Line Protocol format documentation for details on escaping