From 1b37cc1abee9a1c58ed54a93df569a81f86072c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=BD=D0=B0=D0=B1?= Date: Fri, 4 Jun 2021 22:08:50 +0200 Subject: [PATCH] Consistentify miscellaneous style on remaining manpages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Most notably this fixes the vdev_id(8) non-.Xrs in vdev_id.conf.5 Reviewed-by: Richard Laager Reviewed-by: Brian Behlendorf Signed-off-by: Ahelenia Ziemiańska Closes #12212 --- man/man1/arcstat.1 | 16 +++++++++------- man/man1/cstyle.1 | 21 ++++++++++----------- man/man1/raidz_test.1 | 28 ++++++++++++++-------------- man/man1/zhack.1 | 8 +++----- man/man5/vdev_id.conf.5 | 38 ++++++++++++++++++-------------------- man/man8/fsck.zfs.8 | 8 ++++++-- man/man8/zed.8.in | 6 +++--- man/man8/zpool_influxdb.8 | 4 ++-- 8 files changed, 65 insertions(+), 64 deletions(-) diff --git a/man/man1/arcstat.1 b/man/man1/arcstat.1 index a0240e40e..a69cd8937 100644 --- 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 index 16f47ba35..f5f9ec78f 100644 --- 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,29 +118,28 @@ 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 @@ -148,13 +147,13 @@ if (this_is_a_long_variable == another_variable) 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 index 1c61c7a87..4283a4b52 100644 --- 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 index b18b3a4c0..83046ee8f 100644 --- 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 index 1268114bd..a2d38add4 100644 --- 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 index b88dd847b..0ce7576eb 100644 --- a/man/man8/fsck.zfs.8 +++ b/man/man8/fsck.zfs.8 @@ -58,7 +58,9 @@ 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 @@ -66,7 +68,9 @@ 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 index b0b26bfcf..d32976052 100644 --- 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 index a4e417078..021fbdeaa 100644 --- 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