From 90cdf2833d163dd4db31aded1e6940cc9edb67f6 Mon Sep 17 00:00:00 2001 From: LOLi Date: Sat, 16 Sep 2017 19:51:24 +0200 Subject: [PATCH] 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 Signed-off-by: loli10K Closes #6646 --- Makefile.am | 9 ++++++++- man/man8/zfs.8 | 27 +++++++++++++-------------- man/man8/zgenhostid.8 | 5 ++--- man/man8/zpool.8 | 16 ++++++++-------- 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