Unify manpage makefiles, move pages to better sexions, revisit some

cmd/zpool/zpool_main.c

@@ -533,7 +533,7 @@ usage(boolean_t requested)
 		(void) fprintf(fp, "YES   disabled | enabled | active\n");
 
 		(void) fprintf(fp, gettext("\nThe feature@ properties must be "
-		    "appended with a feature name.\nSee zpool-features(5).\n"));
+		    "appended with a feature name.\nSee zpool-features(7).\n"));
 	}
 
 	/*
@@ -8248,7 +8248,7 @@ status_callback(zpool_handle_t *zhp, void *data)
 		printf_color(ANSI_YELLOW, gettext("Enable all features using "
 		    "'zpool upgrade'. Once this is done,\n\tthe pool may no "
 		    "longer be accessible by software that does not support\n\t"
-		    "the features. See zpool-features(5) for details.\n"));
+		    "the features. See zpool-features(7) for details.\n"));
 		break;
 
 	case ZPOOL_STATUS_COMPATIBILITY_ERR:
@@ -8951,7 +8951,7 @@ upgrade_list_disabled_cb(zpool_handle_t *zhp, void *arg)
 					    "pool may become incompatible with "
 					    "software\nthat does not support "
 					    "the feature. See "
-					    "zpool-features(5) for "
+					    "zpool-features(7) for "
 					    "details.\n\n"
 					    "Note that the pool "
 					    "'compatibility' feature can be "

cmd/zpool_influxdb/dashboards/grafana/ZFS-pool-latency-heatmaps-influxdb.json

@@ -1360,7 +1360,7 @@
       "type": "row"
     },
     {
-      "content": "I/O requests that are satisfied by accessing pool devices are managed by the ZIO scheduler.\nThe total latency is measured from the start of the I/O to completion by the disk.\nLatency through each queue is shown prior to its submission to the disk queue.\n\nThis view is useful for observing the effects of tuning the ZIO scheduler min and max values\n(see zfs-module-parameters(5) and [ZFS on Linux Module Parameters](https://openzfs.github.io/openzfs-docs/Performance%20and%20tuning/ZFS%20on%20Linux%20Module%20Parameters.html)):\n+ *zfs_vdev_max_active* controls the ZIO scheduler's disk queue depth (do not confuse with the block device's nr_requests)\n+ *zfs_vdev_sync_read_min_active* and *zfs_vdev_sync_read_max_active* control the synchronous queue for reads: most reads are sync\n+ *zfs_vdev_sync_write_min_active* and *zfs_vdev_sync_write_max_active* control the synchronous queue for writes: \nusually metadata or user data depending on the \"sync\" property setting or I/Os that are requested to be flushed\n+ *zfs_vdev_async_read_min_active* and *zfs_vdev_async_read_max_active* control the asynchronous queue for reads: usually prefetches\n+ *zfs_vdev_async_write_min_active* and *zfs_vdev_async_write_max_active* control the asynchronous queue for writes: \nusually the bulk of all writes at transaction group (txg) commit\n+ *zfs_vdev_scrub_min_active* and *zfs_vdev_scrub_max_active* controls the scan reads: usually scrub or resilver\n\n",
+      "content": "I/O requests that are satisfied by accessing pool devices are managed by the ZIO scheduler.\nThe total latency is measured from the start of the I/O to completion by the disk.\nLatency through each queue is shown prior to its submission to the disk queue.\n\nThis view is useful for observing the effects of tuning the ZIO scheduler min and max values\n(see zfs(4) and [ZFS on Linux Module Parameters](https://openzfs.github.io/openzfs-docs/Performance%20and%20tuning/ZFS%20on%20Linux%20Module%20Parameters.html)):\n+ *zfs_vdev_max_active* controls the ZIO scheduler's disk queue depth (do not confuse with the block device's nr_requests)\n+ *zfs_vdev_sync_read_min_active* and *zfs_vdev_sync_read_max_active* control the synchronous queue for reads: most reads are sync\n+ *zfs_vdev_sync_write_min_active* and *zfs_vdev_sync_write_max_active* control the synchronous queue for writes: \nusually metadata or user data depending on the \"sync\" property setting or I/Os that are requested to be flushed\n+ *zfs_vdev_async_read_min_active* and *zfs_vdev_async_read_max_active* control the asynchronous queue for reads: usually prefetches\n+ *zfs_vdev_async_write_min_active* and *zfs_vdev_async_write_max_active* control the asynchronous queue for writes: \nusually the bulk of all writes at transaction group (txg) commit\n+ *zfs_vdev_scrub_min_active* and *zfs_vdev_scrub_max_active* controls the scan reads: usually scrub or resilver\n\n",
       "datasource": "${DS_MACBOOK-INFLUX}",
       "fieldConfig": {
         "defaults": {
@@ -1664,4 +1664,4 @@
     "list": []
   },
   "version": 2
-}
+}

configure.ac

@@ -171,9 +171,6 @@ AC_CONFIG_FILES([
 	lib/libzstd/Makefile
 	lib/libzutil/Makefile
 	man/Makefile
-	man/man1/Makefile
-	man/man5/Makefile
-	man/man8/Makefile
 	module/Kbuild
 	module/Makefile
 	module/avl/Makefile

man/Makefile.am

@@ -1 +1,117 @@
-SUBDIRS = man1 man5 man8
+include $(top_srcdir)/config/Substfiles.am
+
+EXTRA_DIST += \
+	man1/cstyle.1
+
+dist_man_MANS = \
+	man1/zhack.1 \
+	man1/ztest.1 \
+	man1/raidz_test.1 \
+	man1/zvol_wait.1 \
+	man1/arcstat.1 \
+	\
+	man5/vdev_id.conf.5 \
+	\
+	man4/spl.4 \
+	man4/zfs.4 \
+	\
+	man7/zpool-features.7 \
+	man7/zfsconcepts.7 \
+	man7/zfsprops.7 \
+	man7/zpoolconcepts.7 \
+	man7/zpoolprops.7 \
+	\
+	man8/fsck.zfs.8 \
+	man8/mount.zfs.8 \
+	man8/vdev_id.8 \
+	man8/zdb.8 \
+	man8/zfs.8 \
+	man8/zfs-allow.8 \
+	man8/zfs-bookmark.8 \
+	man8/zfs-change-key.8 \
+	man8/zfs-clone.8 \
+	man8/zfs-create.8 \
+	man8/zfs-destroy.8 \
+	man8/zfs-diff.8 \
+	man8/zfs-get.8 \
+	man8/zfs-groupspace.8 \
+	man8/zfs-hold.8 \
+	man8/zfs-inherit.8 \
+	man8/zfs-jail.8 \
+	man8/zfs-list.8 \
+	man8/zfs-load-key.8 \
+	man8/zfs-mount.8 \
+	man8/zfs-program.8 \
+	man8/zfs-project.8 \
+	man8/zfs-projectspace.8 \
+	man8/zfs-promote.8 \
+	man8/zfs-receive.8 \
+	man8/zfs-recv.8 \
+	man8/zfs-redact.8 \
+	man8/zfs-release.8 \
+	man8/zfs-rename.8 \
+	man8/zfs-rollback.8 \
+	man8/zfs-send.8 \
+	man8/zfs-set.8 \
+	man8/zfs-share.8 \
+	man8/zfs-snapshot.8 \
+	man8/zfs-unallow.8 \
+	man8/zfs-unjail.8 \
+	man8/zfs-unload-key.8 \
+	man8/zfs-unmount.8 \
+	man8/zfs-upgrade.8 \
+	man8/zfs-userspace.8 \
+	man8/zfs-wait.8 \
+	man8/zfs_ids_to_path.8 \
+	man8/zgenhostid.8 \
+	man8/zinject.8 \
+	man8/zpool.8 \
+	man8/zpool-add.8 \
+	man8/zpool-attach.8 \
+	man8/zpool-checkpoint.8 \
+	man8/zpool-clear.8 \
+	man8/zpool-create.8 \
+	man8/zpool-destroy.8 \
+	man8/zpool-detach.8 \
+	man8/zpool-events.8 \
+	man8/zpool-export.8 \
+	man8/zpool-get.8 \
+	man8/zpool-history.8 \
+	man8/zpool-import.8 \
+	man8/zpool-initialize.8 \
+	man8/zpool-iostat.8 \
+	man8/zpool-labelclear.8 \
+	man8/zpool-list.8 \
+	man8/zpool-offline.8 \
+	man8/zpool-online.8 \
+	man8/zpool-reguid.8 \
+	man8/zpool-remove.8 \
+	man8/zpool-reopen.8 \
+	man8/zpool-replace.8 \
+	man8/zpool-resilver.8 \
+	man8/zpool-scrub.8 \
+	man8/zpool-set.8 \
+	man8/zpool-split.8 \
+	man8/zpool-status.8 \
+	man8/zpool-sync.8 \
+	man8/zpool-trim.8 \
+	man8/zpool-upgrade.8 \
+	man8/zpool-wait.8 \
+	man8/zstream.8 \
+	man8/zstreamdump.8 \
+	man8/zpool_influxdb.8
+
+nodist_man_MANS = \
+	man8/zed.8 \
+	man8/zfs-mount-generator.8
+
+SUBSTFILES += $(nodist_man_MANS)
+
+
+if BUILD_LINUX
+# The manual pager in most Linux distros defaults to "BSD" when .Os is blank,
+# but leaving it blank makes things a lot easier on
+# FreeBSD when OpenZFS is vendored in the base system.
+install-data-hook:
+	cd $(DESTDIR)$(mandir) && $(SED) ${ac_inplace} -e 's/^\.Os$$/.Os OpenZFS/' $(dist_man_MANS) $(nodist_man_MANS)
+endif

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

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

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

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,13 +130,11 @@ 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
 .Xr ztest 1 ,
-.Xr zpool-features 5 ,
+.Xr zpool-features 7 ,
 .Xr zfs 8

man/man1/ztest.1

@@ -230,4 +230,4 @@ By default the stack size is limited to
 .Xr zdb 1 ,
 .Xr zfs 1 ,
 .Xr zpool 1 ,
-.Xr spl-module-parameters 5
+.Xr spl 4