Add mdoc style checker

Add a new make 'mancheck' target which uses mandoc -Tlint to verify
manpage files: currently only zfs(8), zpool(8) zdb(8) and zgenhostid(8)
are supported.

Additionally fix some outstanding manpage formatting issues.

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: loli10K <[email protected]>
Closes #6646 

4 files changed, 31 insertions, 26 deletions

diff --git a/Makefile.am b/Makefile.am
index ed753c81a..34f740c57 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -39,7 +39,7 @@ dist-hook:
 	sed -i 's/Release:[[:print:]]*/Release:      $(RELEASE)/' \
 		$(distdir)/META
 
-checkstyle: cstyle shellcheck flake8 commitcheck
+checkstyle: cstyle shellcheck flake8 commitcheck mancheck
 
 commitcheck:
 	@if git rev-parse --git-dir > /dev/null 2>&1; then \
@@ -58,6 +58,13 @@ shellcheck:
 			$$(find cmd/zpool/zpool.d/* -executable); \
 	fi
 
+mancheck:
+	@if type mandoc > /dev/null 2>&1; then \
+		for file in zfs zpool zdb zgenhostid; do \
+			mandoc -Tlint -Werror ${top_srcdir}/man/man8/$$file.8; \
+		done \
+	fi
+
 lint: cppcheck paxcheck
 
 cppcheck:
diff --git a/man/man8/zfs.8 b/man/man8/zfs.8
index eb5b6ffb9..5b8f251d1 100644
--- a/man/man8/zfs.8
+++ b/man/man8/zfs.8
@@ -64,7 +64,7 @@
 .Nm
 .Cm snapshot
 .Op Fl r
-.Oo Fl o Ar property Ns = Ns value Oc Ns ...
+.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
 .Nm
 .Cm rollback
@@ -2174,8 +2174,7 @@ Creating an encrypted dataset requires specifying the
 and
 .Sy keyformat
 properties at creation time, along with an optional
-.Sy
-keylocation
+.Sy keylocation
 and
 .Sy pbkdf2iters .
 After entering an encryption key, the
@@ -3443,9 +3442,9 @@ destroyed by using the
 command.
 .Pp
 If
-.Sy Fl o Em property=value
+.Fl o Em property Ns = Ns Ar value
 or
-.Sy Fl x Em property
+.Fl x Em property
 is specified, it applies to the effective value of the property throughout
 the entire subtree of replicated datasets. Effective property values will be
 set (
@@ -3458,7 +3457,7 @@ property to be inherited from the top‐most file system. Received properties
 are retained in spite of being overridden and may be restored with
 .Nm zfs Cm inherit Fl S .
 Specifying
-.Sy Fl o Em origin=snapshot
+.Fl o Sy origin Ns = Ns Em snapshot
 is a special case because, even if
 .Sy origin
 is a read-only property and cannot be set, it's allowed to receive the send
@@ -3537,9 +3536,9 @@ Which snapshot was specified will not affect the success or failure of the
 receive, as long as the snapshot does exist.
 If the stream is an incremental send stream, all the normal verification will be
 performed.
-.It Fl o Em property=value
+.It Fl o Em property Ns = Ns Ar value
 Sets the specified property as if the command
-.Nm zfs Cm set Em property=value
+.Nm zfs Cm set Em property Ns = Ns Ar value
 was invoked immediately before the receive. When receiving a stream from
 .Nm zfs Cm send Fl R ,
 causes the property to be inherited by all descendant datasets, as through
@@ -4536,18 +4535,18 @@ command will be undone if the share is ever unshared (such as at a reboot etc).
 .Sh INTERFACE STABILITY
 .Sy Committed .
 .Sh SEE ALSO
+.Xr attr 1 ,
 .Xr gzip 1 ,
 .Xr ssh 1 ,
-.Xr mount 8 ,
-.Xr zpool 8 ,
-.Xr selinux 8 ,
 .Xr chmod 2 ,
+.Xr fsync 2 ,
 .Xr stat 2 ,
 .Xr write 2 ,
-.Xr fsync 2 ,
-.Xr attr 1 ,
 .Xr acl 5 ,
+.Xr attributes 5 ,
 .Xr exports 5 ,
 .Xr exportfs 8 ,
+.Xr mount 8 ,
 .Xr net 8 ,
-.Xr attributes 5
+.Xr selinux 8 ,
+.Xr zpool 8
diff --git a/man/man8/zgenhostid.8 b/man/man8/zgenhostid.8
index 2c86b8e28..f492f6bd3 100644
--- a/man/man8/zgenhostid.8
+++ b/man/man8/zgenhostid.8
@@ -42,7 +42,6 @@ value to store.
 This emulates the
 .Xr genhostid 1
 utility and is provided for use on systems which do not include the utility.
-.Pp
 .Sh OPTIONS
 .Op Ar hostid
 Specifies the value to be placed in
@@ -67,6 +66,6 @@ exactly 8 digits long.
 .Ed
 .El
 .Sh SEE ALSO
-.Xr spl-module-parameters 5 ,
 .Xr genhostid 1 ,
-.Xr hostid 1
+.Xr hostid 1 ,
+.Xr spl-module-parameters 5
diff --git a/man/man8/zpool.8 b/man/man8/zpool.8
index 2e4f9b49c..85a0cc5f0 100644
--- a/man/man8/zpool.8
+++ b/man/man8/zpool.8
@@ -878,11 +878,11 @@ The pool name must begin with a letter, and can only contain
 alphanumeric characters as well as underscore
 .Pq Qq Sy _ ,
 dash
-.Pq Qq Sy \&. ,
+.Pq Qq Sy \&- ,
 colon
 .Pq Qq Sy \&: ,
 space
-.Pq Qq Sy - ,
+.Pq Qq Sy \&\  ,
 and period
 .Pq Qq Sy \&. .
 The pool names
@@ -1500,7 +1500,7 @@ If
 is passed without a script name, it prints a list of all scripts.
 .Fl c
 also sets verbose mode
-.No ( Ns Fl v Ns No ).
+.No \&( Ns Fl v Ns No \&).
 .Pp
 Script output should be in the form of "name=value". The column name is
 set to "name" and the value is set to "value". Multiple lines can be
@@ -1511,7 +1511,6 @@ messages. Blank or NULL values are printed as a '-' to make output
 awk-able.
 .Pp
 The following environment variables are set before running each script:
-.Pp
 .Bl -tag -width "VDEV_PATH"
 .It Sy VDEV_PATH
 Full path to the vdev
@@ -2289,7 +2288,7 @@ option.
 Cause
 .Nm zpool
 to dump core on exit for the purposes of running
-.Sy::findleaks .
+.Sy ::findleaks .
 .El
 .Bl -tag -width "ZPOOL_IMPORT_PATH"
 .It Ev ZPOOL_IMPORT_PATH
@@ -2380,11 +2379,12 @@ option. If
 .Sy ZPOOL_SCRIPTS_ENABLED
 is not set, it is assumed that the user is allowed to run
 .Nm zpool status/iostat -c .
+.El
 .Sh INTERFACE STABILITY
 .Sy Evolving
 .Sh SEE ALSO
-.Xr zed 8 ,
-.Xr zfs 8 ,
 .Xr zfs-events 5 ,
 .Xr zfs-module-parameters 5 ,
-.Xr zpool-features 5
+.Xr zpool-features 5 ,
+.Xr zed 8 ,
+.Xr zfs 8