man: Examples: use subsections instead of lists

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #13228

man/man8/zdb.8

@@ -464,12 +464,7 @@ If no options are specified, all information about the named pool will be
 displayed at default verbosity.
 .
 .Sh EXAMPLES
-.Bl -tag -width Ds
+.Ss Example 1 : No Display the configuration of imported pool Ar rpool
-.It Xo
-.Sy Example 1 :
-Display the configuration of imported pool
-.Ar rpool
-.Xc
 .Bd -literal
 .No # Nm zdb Fl C Ar rpool
 MOS Configuration:
@@ -477,22 +472,16 @@ MOS Configuration:
         name: 'rpool'
  …
 .Ed
-.It Xo
+.
-.Sy Example 2 :
+.Ss Example 2 : No Display basic dataset information about Ar rpool
-Display basic dataset information about
-.Ar rpool
-.Xc
 .Bd -literal
 .No # Nm zdb Fl d Ar rpool
 Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects
 Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects
  …
 .Ed
-.It Xo
+.
-.Sy Example 3 :
+.Ss Example 3 : No Display basic information about object 0 in Ar rpool/export/home
-Display basic information about object 0 in
-.Ar rpool/export/home
-.Xc
 .Bd -literal
 .No # Nm zdb Fl d Ar rpool/export/home 0
 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
@@ -500,11 +489,8 @@ Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects
     Object  lvl   iblk   dblk  dsize  lsize   %full  type
          0    7    16K    16K  15.0K    16K   25.00  DMU dnode
 .Ed
-.It Xo
+.
-.Sy Example 4 :
+.Ss Example 4 : No Display the predicted effect of enabling deduplication on Ar rpool
-Display the predicted effect of enabling deduplication on
-.Ar rpool
-.Xc
 .Bd -literal
 .No # Nm zdb Fl S Ar rpool
 Simulated DDT histogram:
@@ -518,7 +504,6 @@ refcnt   blocks   LSIZE   PSIZE   DSIZE   blocks   LSIZE   PSIZE   DSIZE
  …
 dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00
 .Ed
-.El
 .
 .Sh SEE ALSO
 .Xr zfs 8 ,

man/man8/zfs.8

@@ -36,7 +36,7 @@
 .\" Copyright 2018 Nexenta Systems, Inc.
 .\" Copyright 2019 Joyent, Inc.
 .\"
-.Dd June 30, 2019
+.Dd March 16, 2022
 .Dt ZFS 8
 .Os
 .
@@ -299,9 +299,7 @@ if an error occurs, and
 if invalid command line options were specified.
 .
 .Sh EXAMPLES
-.Bl -tag -width ""
+.Ss Example 1 : No Creating a ZFS File System Hierarchy
-.
-.It Sy Example 1 : No Creating a ZFS File System Hierarchy
 The following commands create a file system named
 .Ar pool/home
 and a file system named
@@ -314,7 +312,7 @@ file system.
 .Dl # Nm zfs Cm set Sy mountpoint Ns = Ns Ar /export/home pool/home
 .Dl # Nm zfs Cm create Ar pool/home/bob
 .
-.It Sy Example 2 : No Creating a ZFS Snapshot
+.Ss Example 2 : No Creating a ZFS Snapshot
 The following command creates a snapshot named
 .Ar yesterday .
 This snapshot is mounted on demand in the
@@ -324,7 +322,7 @@ directory at the root of the
 file system.
 .Dl # Nm zfs Cm snapshot Ar pool/home/bob Ns @ Ns Ar yesterday
 .
-.It Sy Example 3 : No Creating and Destroying Multiple Snapshots
+.Ss Example 3 : No Creating and Destroying Multiple Snapshots
 The following command creates snapshots named
 .Ar yesterday No of Ar pool/home
 and all of its descendent file systems.
@@ -335,7 +333,7 @@ The second command destroys the newly created snapshots.
 .Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday
 .Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday
 .
-.It Sy Example 4 : No Disabling and Enabling File System Compression
+.Ss Example 4 : No Disabling and Enabling File System Compression
 The following command disables the
 .Sy compression
 property for all file systems under
@@ -347,7 +345,7 @@ for
 .Dl # Nm zfs Cm set Sy compression Ns = Ns Sy off Ar pool/home
 .Dl # Nm zfs Cm set Sy compression Ns = Ns Sy on Ar pool/home/anne
 .
-.It Sy Example 5 : No Listing ZFS Datasets
+.Ss Example 5 : No Listing ZFS Datasets
 The following command lists all active file systems and volumes in the system.
 Snapshots are displayed if
 .Sy listsnaps Ns = Ns Sy on .
@@ -365,12 +363,12 @@ pool/home/anne             18K   457G    18K  /export/home/anne
 pool/home/bob             276K   457G   276K  /export/home/bob
 .Ed
 .
-.It Sy Example 6 : No Setting a Quota on a ZFS File System
+.Ss Example 6 : No Setting a Quota on a ZFS File System
 The following command sets a quota of 50 Gbytes for
 .Ar pool/home/bob :
 .Dl # Nm zfs Cm set Sy quota Ns = Ns Ar 50G pool/home/bob
 .
-.It Sy Example 7 : No Listing ZFS Properties
+.Ss Example 7 : No Listing ZFS Properties
 The following command lists all properties for
 .Ar pool/home/bob :
 .Bd -literal -compact -offset Ds
@@ -435,7 +433,7 @@ pool/home/bob  quota                 20G
 pool/home/bob  compression           on
 .Ed
 .
-.It Sy Example 8 : No Rolling Back a ZFS File System
+.Ss Example 8 : No Rolling Back a ZFS File System
 The following command reverts the contents of
 .Ar pool/home/anne
 to the snapshot named
@@ -443,13 +441,13 @@ to the snapshot named
 deleting all intermediate snapshots:
 .Dl # Nm zfs Cm rollback Fl r Ar pool/home/anne Ns @ Ns Ar yesterday
 .
-.It Sy Example 9 : No Creating a ZFS Clone
+.Ss Example 9 : No Creating a ZFS Clone
 The following command creates a writable file system whose initial contents are
 the same as
 .Ar pool/home/bob@yesterday .
 .Dl # Nm zfs Cm clone Ar pool/home/bob@yesterday pool/clone
 .
-.It Sy Example 10 : No Promoting a ZFS Clone
+.Ss Example 10 : No Promoting a ZFS Clone
 The following commands illustrate how to test out changes to a file system, and
 then replace the original file system with the changed one, using clones, clone
 promotion, and renaming:
@@ -466,7 +464,7 @@ promotion, and renaming:
 .No # Nm zfs Cm destroy Ar pool/project/legacy
 .Ed
 .
-.It Sy Example 11 : No Inheriting ZFS Properties
+.Ss Example 11 : No Inheriting ZFS Properties
 The following command causes
 .Ar pool/home/bob No and Ar pool/home/anne
 to inherit the
@@ -474,7 +472,7 @@ to inherit the
 property from their parent.
 .Dl # Nm zfs Cm inherit Sy checksum Ar pool/home/bob pool/home/anne
 .
-.It Sy Example 12 : No Remotely Replicating ZFS Data
+.Ss Example 12 : No Remotely Replicating ZFS Data
 The following commands send a full stream and then an incremental stream to a
 remote machine, restoring them into
 .Em poolB/received/fs@a
@@ -493,7 +491,7 @@ and must not initially contain
 .No "   " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs
 .Ed
 .
-.It Sy Example 13 : No Using the Nm zfs Cm receive Fl d No Option
+.Ss Example 13 : No Using the Nm zfs Cm receive Fl d No Option
 The following command sends a full stream of
 .Ar poolA/fsA/fsB@snap
 to a remote machine, receiving it into
@@ -513,13 +511,13 @@ does not exist, it is created as an empty file system.
 .No "   " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received
 .Ed
 .
-.It Sy Example 14 : No Setting User Properties
+.Ss Example 14 : No Setting User Properties
 The following example sets the user-defined
 .Ar com.example : Ns Ar department
 property for a dataset:
 .Dl # Nm zfs Cm set Ar com.example : Ns Ar department Ns = Ns Ar 12345 tank/accounting
 .
-.It Sy Example 15 : No Performing a Rolling Snapshot
+.Ss Example 15 : No Performing a Rolling Snapshot
 The following example shows how to maintain a history of snapshots with a
 consistent naming scheme.
 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
@@ -536,7 +534,7 @@ renames the remaining snapshots, and then creates a new snapshot, as follows:
 .No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today
 .Ed
 .
-.It Sy Example 16 : No Setting sharenfs Property Options on a ZFS File System
+.Ss Example 16 : No Setting sharenfs Property Options on a ZFS File System
 The following commands show how to set
 .Sy sharenfs
 property options to enable read-write
@@ -550,7 +548,7 @@ file system:
 If you are using DNS for host name resolution,
 specify the fully-qualified hostname.
 .
-.It Sy Example 17 : No Delegating ZFS Administration Permissions on a ZFS Dataset
+.Ss Example 17 : No Delegating ZFS Administration Permissions on a ZFS Dataset
 The following example shows how to set permissions so that user
 .Ar cindys
 can create, destroy, mount, and take snapshots on
@@ -575,7 +573,7 @@ will be unable to mount file systems under
 Add an ACE similar to the following syntax to provide mount point access:
 .Dl # Cm chmod No A+user: Ns Ar cindys Ns :add_subdirectory:allow Ar /tank/cindys
 .
-.It Sy Example 18 : No Delegating Create Time Permissions on a ZFS Dataset
+.Ss Example 18 : No Delegating Create Time Permissions on a ZFS Dataset
 The following example shows how to grant anyone in the group
 .Ar staff
 to create file systems in
@@ -596,7 +594,7 @@ Local+Descendent permissions:
         group staff create,mount
 .Ed
 .
-.It Sy Example 19 : No Defining and Granting a Permission Set on a ZFS Dataset
+.Ss Example 19 : No Defining and Granting a Permission Set on a ZFS Dataset
 The following example shows how to define and grant a permission set on the
 .Ar tank/users
 file system.
@@ -614,7 +612,7 @@ Local+Descendent permissions:
         group staff @pset
 .Ed
 .
-.It Sy Example 20 : No Delegating Property Permissions on a ZFS Dataset
+.Ss Example 20 : No Delegating Property Permissions on a ZFS Dataset
 The following example shows to grant the ability to set quotas and reservations
 on the
 .Ar users/home
@@ -634,7 +632,7 @@ NAME              PROPERTY  VALUE  SOURCE
 users/home/marks  quota     10G    local
 .Ed
 .
-.It Sy Example 21 : No Removing ZFS Delegated Permissions on a ZFS Dataset
+.Ss Example 21 : No Removing ZFS Delegated Permissions on a ZFS Dataset
 The following example shows how to remove the snapshot permission from the
 .Ar staff
 group on the
@@ -653,7 +651,7 @@ Local+Descendent permissions:
         group staff @pset
 .Ed
 .
-.It Sy Example 22 : No Showing the differences between a snapshot and a ZFS Dataset
+.Ss Example 22 : No Showing the differences between a snapshot and a ZFS Dataset
 The following example shows how to see what has changed between a prior
 snapshot of a ZFS dataset and its current state.
 The
@@ -669,12 +667,12 @@ R       F       /tank/test/oldname -> /tank/test/newname
 M       F       /tank/test/modified
 .Ed
 .
-.It Sy Example 23 : No Creating a bookmark
+.Ss Example 23 : No Creating a bookmark
 The following example create a bookmark to a snapshot.
 This bookmark can then be used instead of snapshot in send streams.
 .Dl # Nm zfs Cm bookmark Ar rpool Ns @ Ns Ar snapshot rpool Ns # Ns Ar bookmark
 .
-.It Sy Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System
+.Ss Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System
 The following example show how to share SMB filesystem through ZFS.
 Note that a user and their password must be given.
 .Dl # Nm smbmount Ar //127.0.0.1/share_tmp /mnt/tmp Fl o No user=workgroup/turbo,password=obrut,uid=1000
@@ -701,7 +699,6 @@ in case you need to modify any options of the share afterwards.
 Do note that any changes done with the
 .Xr net 8
 command will be undone if the share is ever unshared (like via a reboot).
-.El
 .
 .Sh ENVIRONMENT VARIABLES
 .Bl -tag -width "ZFS_MOUNT_HELPER"

man/man8/zpool-scrub.8

@@ -97,10 +97,8 @@ again.
 Wait until scrub has completed before returning.
 .El
 .Sh EXAMPLES
-.Bl -tag -width "Exam"
+.Ss Example 1 : No Status of pool with ongoing scrub:
-.It Sy Example 1 : Status of pool with ongoing scrub:
+.Bd -literal -compact
-Output:
-.Bd -literal -compact -offset Ds
 .No # Nm zpool Cm status
   ...
   scan: scrub in progress since Sun Jul 25 16:07:49 2021
@@ -108,14 +106,10 @@ Output:
         0B repaired, 16.91% done, 00:00:04 to go
   ...
 .Ed
-Where:
+.Pp
-.Bl -dash -offset indent
+Where metadata which references 403M of file data has been
-.It
-Metadata which references 403M of file data has been
 scanned at 100M/s, and 68.4M of that file data has been
 scrubbed sequentially at 10.0M/s.
-.El
-.El
 .Sh PERIODIC SCRUB
 On machines using systemd, scrub timers can be enabled on per-pool basis.
 .Nm weekly

man/man8/zpool.8

@@ -230,35 +230,34 @@ Invalid command line options were specified.
 .El
 .
 .Sh EXAMPLES
-.Bl -tag -width "Exam"
+.Ss Example 1 : No Creating a RAID-Z Storage Pool
-.It Sy Example 1 : No Creating a RAID-Z Storage Pool
 The following command creates a pool with a single raidz root vdev that
 consists of six disks:
 .Dl # Nm zpool Cm create Ar tank Sy raidz Pa sda sdb sdc sdd sde sdf
 .
-.It Sy Example 2 : No Creating a Mirrored Storage Pool
+.Ss Example 2 : No Creating a Mirrored Storage Pool
 The following command creates a pool with two mirrors, where each mirror
 contains two disks:
 .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy mirror Pa sdc sdd
 .
-.It Sy Example 3 : No Creating a ZFS Storage Pool by Using Partitions
+.Ss Example 3 : No Creating a ZFS Storage Pool by Using Partitions
 The following command creates a non-redundant pool using two disk partitions:
 .Dl # Nm zpool Cm create Ar tank Pa sda1 sdb2
 .
-.It Sy Example 4 : No Creating a ZFS Storage Pool by Using Files
+.Ss Example 4 : No Creating a ZFS Storage Pool by Using Files
 The following command creates a non-redundant pool using files.
 While not recommended, a pool based on files can be useful for experimental
 purposes.
 .Dl # Nm zpool Cm create Ar tank Pa /path/to/file/a /path/to/file/b
 .
-.It Sy Example 5 : No Adding a Mirror to a ZFS Storage Pool
+.Ss Example 5 : No Adding a Mirror to a ZFS Storage Pool
 The following command adds two mirrored disks to the pool
 .Ar tank ,
 assuming the pool is already made up of two-way mirrors.
 The additional space is immediately available to any datasets within the pool.
 .Dl # Nm zpool Cm add Ar tank Sy mirror Pa sda sdb
 .
-.It Sy Example 6 : No Listing Available ZFS Storage Pools
+.Ss Example 6 : No Listing Available ZFS Storage Pools
 The following command lists all available pools on the system.
 In this case, the pool
 .Ar zion
@@ -272,19 +271,19 @@ tank   61.5G  20.0G  41.5G         -    48%    32%  1.00x  ONLINE  -
 zion       -      -      -         -      -      -      -  FAULTED -
 .Ed
 .
-.It Sy Example 7 : No Destroying a ZFS Storage Pool
+.Ss Example 7 : No Destroying a ZFS Storage Pool
 The following command destroys the pool
 .Ar tank
 and any datasets contained within:
 .Dl # Nm zpool Cm destroy Fl f Ar tank
 .
-.It Sy Example 8 : No Exporting a ZFS Storage Pool
+.Ss Example 8 : No Exporting a ZFS Storage Pool
 The following command exports the devices in pool
 .Ar tank
 so that they can be relocated or later imported:
 .Dl # Nm zpool Cm export Ar tank
 .
-.It Sy Example 9 : No Importing a ZFS Storage Pool
+.Ss Example 9 : No Importing a ZFS Storage Pool
 The following command displays available pools, and then imports the pool
 .Ar tank
 for use on the system.
@@ -305,7 +304,7 @@ config:
 .No # Nm zpool Cm import Ar tank
 .Ed
 .
-.It Sy Example 10 : No Upgrading All ZFS Storage Pools to the Current Version
+.Ss Example 10 : No Upgrading All ZFS Storage Pools to the Current Version
 The following command upgrades all ZFS Storage pools to the current version of
 the software:
 .Bd -literal -compact -offset Ds
@@ -313,7 +312,7 @@ the software:
 This system is currently running ZFS version 2.
 .Ed
 .
-.It Sy Example 11 : No Managing Hot Spares
+.Ss Example 11 : No Managing Hot Spares
 The following command creates a new pool with an available hot spare:
 .Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy spare Pa sdc
 .Pp
@@ -328,12 +327,12 @@ The hot spare can be permanently removed from the pool using the following
 command:
 .Dl # Nm zpool Cm remove Ar tank Pa sdc
 .
-.It Sy Example 12 : No Creating a ZFS Pool with Mirrored Separate Intent Logs
+.Ss Example 12 : No Creating a ZFS Pool with Mirrored Separate Intent Logs
 The following command creates a ZFS storage pool consisting of two, two-way
 mirrors and mirrored log devices:
 .Dl # Nm zpool Cm create Ar pool Sy mirror Pa sda sdb Sy mirror Pa sdc sdd Sy log mirror Pa sde sdf
 .
-.It Sy Example 13 : No Adding Cache Devices to a ZFS Pool
+.Ss Example 13 : No Adding Cache Devices to a ZFS Pool
 The following command adds two disks for use as cache devices to a ZFS storage
 pool:
 .Dl # Nm zpool Cm add Ar pool Sy cache Pa sdc sdd
@@ -346,7 +345,7 @@ Capacity and reads can be monitored using the
 subcommand as follows:
 .Dl # Nm zpool Cm iostat Fl v Ar pool 5
 .
-.It Sy Example 14 : No Removing a Mirrored top-level (Log or Data) Device
+.Ss Example 14 : No Removing a Mirrored top-level (Log or Data) Device
 The following commands remove the mirrored log device
 .Sy mirror-2
 and mirrored top-level data device
@@ -381,7 +380,7 @@ The command to remove the mirrored data
 .Ar mirror-1 No is:
 .Dl # Nm zpool Cm remove Ar tank mirror-1
 .
-.It Sy Example 15 : No Displaying expanded space on a device
+.Ss Example 15 : No Displaying expanded space on a device
 The following command displays the detailed information for the pool
 .Ar data .
 This pool is comprised of a single raidz vdev where one of its devices
@@ -398,7 +397,7 @@ data        23.9G  14.6G  9.30G         -    48%    61%  1.00x  ONLINE  -
     sdc         -      -      -         -      -
 .Ed
 .
-.It Sy Example 16 : No Adding output columns
+.Ss Example 16 : No Adding output columns
 Additional columns can be added to the
 .Nm zpool Cm status No and Nm zpool Cm iostat No output with Fl c .
 .Bd -literal -compact -offset Ds
@@ -421,7 +420,6 @@ rpool       14.6G  54.9G      4     55   250K  2.69M
   sda1      14.6G  54.9G      4     55   250K  2.69M   70G
 ----------  -----  -----  -----  -----  -----  -----  ----
 .Ed
-.El
 .
 .Sh ENVIRONMENT VARIABLES
 .Bl -tag -compact -width "ZPOOL_IMPORT_UDEV_TIMEOUT_MS"
@@ -432,7 +430,7 @@ to dump core on exit for the purposes of running
 .Sy ::findleaks .
 .It Sy ZFS_COLOR
 Use ANSI color in
-.Nm zpool status
+.Nm zpool Cm status
 output.
 .It Sy ZPOOL_IMPORT_PATH
 The search path for devices or files to use with the pool.
@@ -449,7 +447,7 @@ The maximum time in milliseconds that
 will wait for an expected device to be available.
 .It Sy ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE
 If set, suppress warning about non-native vdev ashift in
-.Nm zpool status .
+.Nm zpool Cm status .
 The value is not used, only the presence or absence of the variable matters.
 .It Sy ZPOOL_VDEV_NAME_GUID
 Cause
@@ -481,7 +479,7 @@ NVP value is present in the pool's config.
 For example, a pool that originated on illumos platform would have a
 .Sy devid
 value in the config and
-.Nm zpool status
+.Nm zpool Cm status
 would fail when listing the config.
 This would also be true for future Linux-based pools.
 .Pp
@@ -497,12 +495,12 @@ by setting
 .Pp
 .It Sy ZPOOL_SCRIPTS_AS_ROOT
 Allow a privileged user to run
-.Nm zpool status/iostat Fl c .
+.Nm zpool Cm status Ns / Ns Cm iostat Fl c .
 Normally, only unprivileged users are allowed to run
 .Fl c .
 .It Sy ZPOOL_SCRIPTS_PATH
 The search path for scripts when running
-.Nm zpool status/iostat Fl c .
+.Nm zpool Cm status Ns / Ns Cm iostat Fl c .
 This is a colon-separated list of directories and overrides the default
 .Pa ~/.zpool.d
 and
@@ -510,7 +508,7 @@ and
 search paths.
 .It Sy ZPOOL_SCRIPTS_ENABLED
 Allow a user to run
-.Nm zpool status/iostat Fl c .
+.Nm zpool Cm status Ns / Ns Cm iostat Fl c .
 If
 .Sy ZPOOL_SCRIPTS_ENABLED
 is not set, it is assumed that the user is allowed to run