tests: Add script to check documented tool options match actual options.

podcheck.pl is run as part of the tests to perform various checks on the documentation and the tool. Currently we check only that the documented options matches the options that the tool implements and vice versa. This commit would also allow us (in future) to check --help, --long-options, --short-options, --version output. This commit includes scripts to run the tests and various fixes to the manual pages to ensure that the tests pass.
2026-03-21 22:53:37 +00:00 · 2016-07-16 20:52:49 +01:00
parent 1fa3bf14e5
commit 08e27451a6
51 changed files with 859 additions and 141 deletions
--- a/Makefile.am
+++ b/Makefile.am
@@ -222,6 +222,7 @@ EXTRA_DIST = \
 	logo/virt-builder.svg \
 	m4/.gitignore \
 	ocaml-link.sh \
+	podcheck.pl \
 	tests/automake2junit.ml \
 	tmp/.gitignore \
 	update-bugs.sh \
--- a/align/Makefile.am
+++ b/align/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	test-virt-alignment-scan.sh \
+	test-virt-alignment-scan-docs.sh \
 	test-virt-alignment-scan-guests.sh \
 	virt-alignment-scan.pod

@@ -92,7 +93,8 @@ stamp-virt-alignment-scan.pod: virt-alignment-scan.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-TESTS =
+TESTS = \
+	test-virt-alignment-scan-docs.sh

 if ENABLE_APPLIANCE
 TESTS += \
--- a/align/test-virt-alignment-scan-docs.sh
+++ b/align/test-virt-alignment-scan-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-alignment-scan.pod virt-alignment-scan
--- a/builder/Makefile.am
+++ b/builder/Makefile.am
@@ -27,6 +27,7 @@ EXTRA_DIST = \
 	test-simplestreams/streams/v1/index.json \
 	test-simplestreams/streams/v1/net.cirros-cloud_released_download.json \
 	test-virt-builder.sh \
+	test-virt-builder-docs.sh \
 	test-virt-builder-list.sh \
 	test-virt-builder-list-simplestreams.sh \
 	test-virt-builder-planner.sh \
@@ -249,6 +250,7 @@ yajl_tests_LINK = \
 	  $(yajl_tests_THEOBJECTS) -o $@

 TESTS = \
+	test-virt-builder-docs.sh \
 	test-virt-builder-list.sh \
 	test-virt-index-validate.sh \
 	$(SLOW_TESTS)
--- a/builder/test-virt-builder-docs.sh
+++ b/builder/test-virt-builder-docs.sh
@@ -0,0 +1,25 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-builder.pod virt-builder \
+  --insert $srcdir/../customize/customize-synopsis.pod:__CUSTOMIZE_SYNOPSIS__ \
+  --insert $srcdir/../customize/customize-options.pod:__CUSTOMIZE_OPTIONS__ \
+  --ignore=--check-signatures,--no-check-signatures
--- a/builder/virt-builder.pod
+++ b/builder/virt-builder.pod
@@ -324,9 +324,9 @@ alternate home directory:

 =item B<--list> [os-version]

-=item B<--list --list-format> format [os-version]
+=item B<--list> B<--list-format> format [os-version]

-=item B<--list --long> [os-version]
+=item B<--list> B<--long> [os-version]

 List all the available templates if no guest is specified, or only for the
 specified one.
--- a/cat/Makefile.am
+++ b/cat/Makefile.am
@@ -18,6 +18,7 @@
 include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
+	test-docs.sh \
 	test-virt-cat.sh \
 	virt-cat.pod \
 	test-virt-filesystems.sh \
@@ -201,8 +202,11 @@ stamp-virt-ls.pod: virt-ls.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-if ENABLE_APPLIANCE
 TESTS = \
+	test-docs.sh
+
+if ENABLE_APPLIANCE
+TESTS += \
 	test-virt-cat.sh \
 	test-virt-filesystems.sh \
 	test-virt-log.sh \
--- a/cat/test-docs.sh
+++ b/cat/test-docs.sh
@@ -0,0 +1,26 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-cat.pod virt-cat
+$srcdir/../podcheck.pl virt-filesystems.pod virt-filesystems
+$srcdir/../podcheck.pl virt-log.pod virt-log
+$srcdir/../podcheck.pl virt-ls.pod virt-ls \
+                       --ignore=--checksums,--extra-stat,--time,--uid
--- a/cat/virt-cat.pod
+++ b/cat/virt-cat.pod
@@ -126,9 +126,9 @@ security problem with malicious guests (CVE-2010-3851).
 Read key or passphrase parameters from stdin.  The default is
 to try to read passphrases from the user by opening F</dev/tty>.

-=item B<-m dev[:mountpoint[:options[:fstype]]]>
+=item B<-m> dev[:mountpoint[:options[:fstype]]]

-=item B<--mount dev[:mountpoint[:options[:fstype]]]>
+=item B<--mount> dev[:mountpoint[:options[:fstype]]]

 Mount the named partition or logical volume on the given mountpoint.

--- a/cat/virt-ls.pod
+++ b/cat/virt-ls.pod
@@ -357,9 +357,9 @@ L</RECURSIVE LONG LISTING> above.
 Read key or passphrase parameters from stdin.  The default is
 to try to read passphrases from the user by opening F</dev/tty>.

-=item B<-m dev[:mountpoint[:options[:fstype]]]>
+=item B<-m> dev[:mountpoint[:options[:fstype]]]

-=item B<--mount dev[:mountpoint[:options[:fstype]]]>
+=item B<--mount> dev[:mountpoint[:options[:fstype]]]

 Mount the named partition or logical volume on the given mountpoint.

--- a/customize/Makefile.am
+++ b/customize/Makefile.am
@@ -22,6 +22,7 @@ EXTRA_DIST = \
 	$(SOURCES_MLI) $(SOURCES_ML) $(SOURCES_C) \
 	customize_main.ml \
 	test-virt-customize.sh \
+	test-virt-customize-docs.sh \
 	virt-customize.pod

 CLEANFILES = \
@@ -191,8 +192,12 @@ stamp-virt-customize.pod: virt-customize.pod $(top_srcdir)/customize/customize-s

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

+TESTS = \
+	test-virt-customize-docs.sh
+
 if ENABLE_APPLIANCE
-TESTS = test-virt-customize.sh
+TESTS += \
+	test-virt-customize.sh
 endif

 check-valgrind:
--- a/customize/test-virt-customize-docs.sh
+++ b/customize/test-virt-customize-docs.sh
@@ -0,0 +1,25 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-customize.pod virt-customize \
+  --insert $srcdir/../customize/customize-synopsis.pod:__CUSTOMIZE_SYNOPSIS__ \
+  --insert $srcdir/../customize/customize-options.pod:__CUSTOMIZE_OPTIONS__ \
+  --ignore=--dryrun
--- a/df/Makefile.am
+++ b/df/Makefile.am
@@ -20,6 +20,7 @@ include $(top_srcdir)/subdir-rules.mk
 EXTRA_DIST = \
 	README \
 	test-virt-df.sh \
+	test-virt-df-docs.sh \
 	test-virt-df-guests.sh \
 	virt-df.pod

@@ -95,7 +96,8 @@ stamp-virt-df.pod: virt-df.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-TESTS =
+TESTS = \
+	test-virt-df-docs.sh

 if ENABLE_APPLIANCE
 TESTS += \
--- a/df/test-virt-df-docs.sh
+++ b/df/test-virt-df-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-df.pod virt-df
--- a/df/virt-df.pod
+++ b/df/virt-df.pod
@@ -76,20 +76,20 @@ not do this with unrelated guest disks.>

 Display brief help.

-=item B<-a> file
+=item B<-a> FILE

-=item B<--add> file
+=item B<--add> FILE

-Add I<file> which should be a disk image from a virtual machine.  If
+Add C<FILE> which should be a disk image from a virtual machine.  If
 the virtual machine has multiple block devices, you must supply all of
 them with separate I<-a> options.

 The format of the disk image is auto-detected.  To override this and
 force a particular format use the I<--format=..> option.

-=item B<-a URI>
+=item B<-a> URI

-=item B<--add URI>
+=item B<--add> URI

 Add a remote disk.  See L<guestfish(1)/ADDING REMOTE STORAGE>.

--- a/dib/Makefile.am
+++ b/dib/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	$(SOURCES_MLI) $(SOURCES_ML) $(SOURCES_C) \
+	test-virt-dib-docs.sh \
        virt-dib.pod

 CLEANFILES = *~ *.annot *.cmi *.cmo *.cmx *.cmxa *.o virt-dib
@@ -96,6 +97,12 @@ virt_dib_LINK = \
 	  $(OCAMLFIND) $(BEST) $(OCAMLFLAGS) $(OCAMLPACKAGES) $(OCAMLLINKFLAGS) \
 	  $(OBJECTS) -o $@

+# Tests.
+
+TESTS_ENVIRONMENT = $(top_builddir)/run --test
+
+TESTS = test-virt-dib-docs.sh
+
 # Manual pages and HTML files for the website.

 man_MANS = virt-dib.1
--- a/dib/test-virt-dib-docs.sh
+++ b/dib/test-virt-dib-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-dib.pod virt-dib
--- a/diff/Makefile.am
+++ b/diff/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	test-virt-diff.sh \
+	test-virt-diff-docs.sh \
 	virt-diff.pod

 CLEANFILES = \
@@ -82,8 +83,11 @@ stamp-virt-diff.pod: virt-diff.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-if ENABLE_APPLIANCE
 TESTS = \
+	test-virt-diff-docs.sh
+
+if ENABLE_APPLIANCE
+TESTS += \
 	test-virt-diff.sh
 endif ENABLE_APPLIANCE

--- a/diff/test-virt-diff-docs.sh
+++ b/diff/test-virt-diff-docs.sh
@@ -0,0 +1,23 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-diff.pod virt-diff \
+  --ignore=--checksums,--dir-link,--dir-nlink,--dir-nlinks,--dir-time,--extra-stat,--time,--uid,--xattr
--- a/edit/Makefile.am
+++ b/edit/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	test-virt-edit.sh \
+	test-virt-edit-docs.sh \
 	virt-edit.pod

 CLEANFILES = \
@@ -85,6 +86,10 @@ stamp-virt-edit.pod: virt-edit.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

+TESTS = \
+	test-virt-edit-docs.sh
+
 if ENABLE_APPLIANCE
-TESTS = test-virt-edit.sh
+TESTS += \
+	test-virt-edit.sh
 endif ENABLE_APPLIANCE
--- a/edit/test-virt-edit-docs.sh
+++ b/edit/test-virt-edit-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-edit.pod virt-edit
--- a/edit/virt-edit.pod
+++ b/edit/virt-edit.pod
@@ -70,15 +70,15 @@ them with separate I<-a> options.
 The format of the disk image is auto-detected.  To override this and
 force a particular format use the I<--format=..> option.

-=item B<-a URI>
+=item B<-a> URI

-=item B<--add URI>
+=item B<--add> URI

 Add a remote disk.  See L<guestfish(1)/ADDING REMOTE STORAGE>.

-=item B<-b> extension
+=item B<-b> EXTENSION

-=item B<--backup> extension
+=item B<--backup> EXTENSION

 Create a backup of the original file I<in the guest disk image>.
 The backup has the original filename with C<extension> added.
@@ -90,9 +90,9 @@ so you would write:

 By default, no backup file is made.

-=item B<-c URI>
+=item B<-c> URI

-=item B<--connect URI>
+=item B<--connect> URI

 If using libvirt, connect to the given I<URI>.  If omitted, then we
 connect to the default libvirt hypervisor.
@@ -100,9 +100,9 @@ connect to the default libvirt hypervisor.
 If you specify guest block devices directly, then libvirt is not used
 at all.

-=item B<-d> guest
+=item B<-d> GUEST

-=item B<--domain> guest
+=item B<--domain> GUEST

 Add all the disks from the named libvirt guest.  Domain UUIDs can be
 used instead of names.
@@ -158,9 +158,9 @@ security problem with malicious guests (CVE-2010-3851).
 Read key or passphrase parameters from stdin.  The default is
 to try to read passphrases from the user by opening F</dev/tty>.

-=item B<-m dev[:mountpoint[:options[:fstype]]]>
+=item B<-m> dev[:mountpoint[:options[:fstype]]]

-=item B<--mount dev[:mountpoint[:options[:fstype]]]>
+=item B<--mount> dev[:mountpoint[:options[:fstype]]]

 Mount the named partition or logical volume on the given mountpoint.

--- a/fish/Makefile.am
+++ b/fish/Makefile.am
@@ -285,6 +285,7 @@ TESTS = \
 	test-add-domain.sh \
 	test-add-uri.sh \
 	test-d.sh \
+	test-docs.sh \
 	test-escapes.sh \
 	test-events.sh \
 	test-invalid-params.sh \
@@ -323,6 +324,7 @@ EXTRA_DIST += \
 	test-alloc.sh \
 	test-copy.sh \
 	test-d.sh \
+	test-docs.sh \
 	test-edit.sh \
 	test-escapes.sh \
 	test-events.sh \
--- a/fish/guestfish.pod
+++ b/fish/guestfish.pod
@@ -156,15 +156,15 @@ Displays general help on options.

 Lists all available guestfish commands.

-=item B<-h cmd>
+=item B<-h> CMD

-=item B<--cmd-help cmd>
+=item B<--cmd-help> CMD

 Displays detailed help on a single command C<cmd>.

-=item B<-a image>
+=item B<-a> IMAGE

-=item B<--add image>
+=item B<--add> IMAGE

 Add a block device or virtual machine image to the shell.

@@ -175,15 +175,15 @@ Using this flag is mostly equivalent to using the C<add> command,
 with C<readonly:true> if the I<--ro> flag was given, and
 with C<format:...> if the I<--format=...> flag was given.

-=item B<-a URI>
+=item B<-a> URI

-=item B<--add URI>
+=item B<--add> URI

 Add a remote disk.  See L</ADDING REMOTE STORAGE>.

-=item B<-c URI>
+=item B<-c> URI

-=item B<--connect URI>
+=item B<--connect> URI

 When used in conjunction with the I<-d> option, this specifies
 the libvirt URI to use.  The default is to use the default libvirt
@@ -194,9 +194,9 @@ connection.
 If using the I<--listen> option and a csh-like shell, use this option.
 See section L</REMOTE CONTROL AND CSH> below.

-=item B<-d libvirt-domain>
+=item B<-d> LIBVIRT-DOMAIN

-=item B<--domain libvirt-domain>
+=item B<--domain> LIBVIRT-DOMAIN

 Add disks from the named libvirt domain.  If the I<--ro> option is
 also used, then any libvirt domain can be used.  However in write
@@ -215,11 +215,11 @@ echoing off so you cannot see what you are typing.  If you are not
 worried about Tempest attacks and there is no one else in the room
 you can specify this flag to see what you are typing.

-=item B<-f file>
+=item B<-f> FILE

-=item B<--file file>
+=item B<--file> FILE

-Read commands from C<file>.  To write pure guestfish
+Read commands from C<FILE>.  To write pure guestfish
 scripts, use:

 #!/usr/bin/guestfish -f
@@ -295,9 +295,9 @@ L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
 Connect to a live virtual machine.
 (Experimental, see L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>).

-=item B<-m dev[:mountpoint[:options[:fstype]]]>
+=item B<-m> dev[:mountpoint[:options[:fstype]]]

-=item B<--mount dev[:mountpoint[:options[:fstype]]]>
+=item B<--mount> dev[:mountpoint[:options[:fstype]]]

 Mount the named partition or logical volume on the given mountpoint.

@@ -335,13 +335,13 @@ or if libguestfs misidentifies a filesystem.

 Enable QEMU user networking in the guest.

-=item B<-N [filename=]type>
+=item B<-N> [FILENAME=]TYPE

-=item B<--new [filename=]type>
+=item B<--new> [FILENAME=]TYPE

-=item B<-N help>
+=item B<-N> B<help>

-Prepare a fresh disk image formatted as "type".  This is an
+Prepare a fresh disk image formatted as C<TYPE>.  This is an
 alternative to the I<-a> option: whereas I<-a> adds an existing disk,
 I<-N> creates a preformatted disk with a filesystem and adds it.
 See L</PREPARED DISK IMAGES> below.
@@ -383,7 +383,9 @@ interactive shell.

 Disable progress bars.

-=item B<--remote[=pid]>
+=item B<--remote>
+
+=item B<--remote=>PID

 Send remote commands to C<$GUESTFISH_PID> or C<pid>.  See section
 L</REMOTE CONTROL GUESTFISH OVER A SOCKET> below.
--- a/fish/test-docs.sh
+++ b/fish/test-docs.sh
@@ -0,0 +1,26 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl guestfish.pod guestfish \
+    --insert $srcdir/guestfish-actions.pod:__ACTIONS__ \
+    --insert $srcdir/guestfish-commands.pod:__FISH_COMMANDS__ \
+    --insert $srcdir/guestfish-prepopts.pod:__PREPOPTS__ \
+    --ignore=-D
--- a/format/Makefile.am
+++ b/format/Makefile.am
@@ -18,6 +18,8 @@
 include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
+	test-virt-format-docs.sh \
+	test-virt-format.sh \
 	virt-format.pod

 CLEANFILES = \
@@ -81,11 +83,13 @@ stamp-virt-format.pod: virt-format.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

+TESTS = \
+	test-virt-format-docs.sh
+
 if ENABLE_APPLIANCE
-TESTS = test-virt-format.sh
+TESTS += \
+	test-virt-format.sh
 endif ENABLE_APPLIANCE

 check-valgrind:
 	$(MAKE) VG="$(top_builddir)/run @VG@" check
-
-EXTRA_DIST += test-virt-format.sh
--- a/format/test-virt-format-docs.sh
+++ b/format/test-virt-format-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-format.pod virt-format
--- a/format/virt-format.pod
+++ b/format/virt-format.pod
@@ -35,11 +35,11 @@ partitions, filesystems, etc.  The most commonly used options are:

 =over 4

-=item I<--filesystem=[ext3|ntfs|vfat|...]>
+=item B<--filesystem=[ext3|ntfs|vfat|...]>

 Create an empty filesystem (C<ext3>, C<ntfs> etc) inside the partition.

-=item I<--lvm[=/dev/VG/LV]>
+=item B<--lvm[=/dev/VG/LV]>

 Create a Linux LVM2 logical volume on the disk.  When used with
 I<--filesystem>, the filesystem is created inside the LV.
@@ -73,9 +73,9 @@ force a particular format use the I<--format=..> option.

 B<Any existing data on the disk is erased.>

-=item B<-a URI>
+=item B<-a> URI

-=item B<--add URI>
+=item B<--add> URI

 Add a remote disk.  See L<guestfish(1)/ADDING REMOTE STORAGE>.

@@ -112,7 +112,7 @@ If you have untrusted raw-format guest disk images, you should use
 this option to specify the disk format.  This avoids a possible
 security problem with malicious guests (CVE-2010-3851).

-=item B<--label=LABEL>
+=item B<--label=>LABEL

 Set the filesystem label.

--- a/fuse/Makefile.am
+++ b/fuse/Makefile.am
@@ -20,6 +20,7 @@ include $(top_srcdir)/subdir-rules.mk
 EXTRA_DIST = \
 	guestmount.pod \
 	guestunmount.pod \
+	test-docs.sh \
 	test-fuse-umount-race.sh \
 	test-guestunmount-not-mounted.sh

@@ -131,6 +132,7 @@ stamp-guestunmount.pod: guestunmount.pod
 # Tests.

 TESTS = \
+	test-docs.sh \
 	test-guestunmount-fd \
 	test-guestunmount-not-mounted.sh

--- a/fuse/guestmount.pod
+++ b/fuse/guestmount.pod
@@ -155,32 +155,32 @@ race-free program.

 =over 4

-=item B<-a image>
+=item B<-a> IMAGE

-=item B<--add image>
+=item B<--add> IMAGE

 Add a block device or virtual machine image.

 The format of the disk image is auto-detected.  To override this and
 force a particular format use the I<--format=..> option.

-=item B<-a URI>
+=item B<-a> URI

-=item B<--add URI>
+=item B<--add> URI

 Add a remote disk.  See L<guestfish(1)/ADDING REMOTE STORAGE>.

-=item B<-c URI>
+=item B<-c> URI

-=item B<--connect URI>
+=item B<--connect> URI

 When used in conjunction with the I<-d> option, this specifies
 the libvirt URI to use.  The default is to use the default libvirt
 connection.

-=item B<-d libvirt-domain>
+=item B<-d> LIBVIRT-DOMAIN

-=item B<--domain libvirt-domain>
+=item B<--domain> LIBVIRT-DOMAIN

 Add disks from the named libvirt domain.  If the I<--ro> option is
 also used, then any libvirt domain can be used.  However in write
@@ -188,7 +188,7 @@ mode, only libvirt domains which are shut down can be named here.

 Domain UUIDs can be used instead of names.

-=item B<--dir-cache-timeout N>
+=item B<--dir-cache-timeout> N

 Set the readdir cache timeout to I<N> seconds, the default being 60
 seconds.  The readdir cache [actually, there are several
@@ -207,7 +207,7 @@ echoing off so you cannot see what you are typing.  If you are not
 worried about Tempest attacks and there is no one else in the room
 you can specify this flag to see what you are typing.

-=item B<--fd=FD>
+=item B<--fd=>FD

 Specify a pipe or eventfd file descriptor.  When the mountpoint is
 ready to be used, guestmount writes a single byte to this file
@@ -254,9 +254,9 @@ to try to read passphrases from the user by opening F</dev/tty>.
 Connect to a live virtual machine.
 (Experimental, see L<guestfs(3)/ATTACHING TO RUNNING DAEMONS>).

-=item B<-m dev[:mountpoint[:options[:fstype]]>
+=item B<-m> dev[:mountpoint[:options[:fstype]]

-=item B<--mount dev[:mountpoint[:options[:fstype]]]>
+=item B<--mount> dev[:mountpoint[:options[:fstype]]]

 Mount the named partition or logical volume on the given mountpoint
 B<in the guest> (this has nothing to do with mountpoints in the host).
@@ -292,9 +292,9 @@ is unmounted.  If you specify this option, then we don't attempt to
 sync the disk.  See the discussion of autosync in the L<guestfs(3)>
 manpage.

-=item B<-o option>
+=item B<-o> OPTION

-=item B<--option option>
+=item B<--option> OPTION

 Pass extra options to FUSE.

@@ -308,26 +308,26 @@ Some potentially useful FUSE options:

 =over 4

-=item B<-o allow_other>
+=item B<-o> B<allow_other>

 Allow other users to see the filesystem.

-=item B<-o attr_timeout=N>
+=item B<-o> B<attr_timeout=N>

 Enable attribute caching by FUSE, and set the timeout to I<N> seconds.

-=item B<-o kernel_cache>
+=item B<-o> B<kernel_cache>

 Allow the kernel to cache files (reduces the number of reads
 that have to go through the L<guestfs(3)> API).  This is generally
 a good idea if you can afford the extra memory usage.

-=item B<-o uid=N> B<-o gid=N>
+=item B<-o> B<uid=N> B<-o> B<gid=N>

 Use these options to map all UIDs and GIDs inside the guest filesystem
 to the chosen values.

-=item B<-o use_ino>
+=item B<-o> B<use_ino>

 Preserve inode numbers from the underlying filesystem.

@@ -342,7 +342,7 @@ some software.

 =back

-=item B<--pid-file filename>
+=item B<--pid-file> FILENAME

 Write the PID of the guestmount worker process to C<filename>.

--- a/fuse/test-docs.sh
+++ b/fuse/test-docs.sh
@@ -0,0 +1,26 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl guestmount.pod guestmount
+
+# guestunmount doesn't implement bash completion, so we cannot
+# test it at the moment. XXX
+#$srcdir/../podcheck.pl guestunmount.pod guestunmount
--- a/get-kernel/Makefile.am
+++ b/get-kernel/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	$(SOURCES_ML) $(SOURCES_C) \
+	test-virt-get-kernel-docs.sh \
 	virt-get-kernel.pod

 CLEANFILES = *~ *.annot *.cmi *.cmo *.cmx *.cmxa *.o virt-get-kernel
@@ -93,6 +94,12 @@ virt_get_kernel_LINK = \
 	  $(OCAMLFIND) $(BEST) $(OCAMLFLAGS) $(OCAMLPACKAGES) $(OCAMLLINKFLAGS) \
 	  $(OBJECTS) -o $@

+# Tests.
+
+TESTS_ENVIRONMENT = $(top_builddir)/run --test
+
+TESTS = test-virt-get-kernel-docs.sh
+
 # Manual pages and HTML files for the website.

 man_MANS += virt-get-kernel.1
--- a/get-kernel/test-virt-get-kernel-docs.sh
+++ b/get-kernel/test-virt-get-kernel-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-get-kernel.pod virt-get-kernel
--- a/make-fs/Makefile.am
+++ b/make-fs/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	test-virt-make-fs.sh \
+	test-virt-make-fs-docs.sh \
 	virt-make-fs.pod

 CLEANFILES = \
@@ -76,8 +77,11 @@ stamp-virt-make-fs.pod: virt-make-fs.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-if ENABLE_APPLIANCE
 TESTS = \
+	test-virt-make-fs-docs.sh
+
+if ENABLE_APPLIANCE
+TESTS += \
 	test-virt-make-fs.sh
 endif ENABLE_APPLIANCE

--- a/make-fs/test-virt-make-fs-docs.sh
+++ b/make-fs/test-virt-make-fs-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-make-fs.pod virt-make-fs --ignore=--debug
--- a/make-fs/virt-make-fs.pod
+++ b/make-fs/virt-make-fs.pod
@@ -129,13 +129,13 @@ Create a virtual floppy disk.
 Currently this preselects the size (1440K), partition type (MBR) and
 filesystem type (VFAT).  In future it may also choose the geometry.

-=item B<--size=E<lt>NE<gt>>
+=item B<--size=>N

-=item B<--size=+E<lt>NE<gt>>
+=item B<--size=+>N

-=item B<-s E<lt>NE<gt>>
+=item B<-s> N

-=item B<-s +E<lt>NE<gt>>
+=item B<-s> B<+>N

 Use the I<--size> (or I<-s>) option to choose the size of the output
 image.
@@ -159,17 +159,17 @@ produce filesystems containing precisely the free space requested.
 (It is much more expensive and time-consuming to produce a filesystem
 which has precisely the desired free space).

-=item B<--format=E<lt>fmtE<gt>>
+=item B<--format=>FMT

-=item B<-F E<lt>fmtE<gt>>
+=item B<-F> FMT

 Choose the output disk image format.

 The default is C<raw> (raw sparse disk image).

-=item B<--type=E<lt>fsE<gt>>
+=item B<--type=>FS

-=item B<-t E<lt>fsE<gt>>
+=item B<-t> FS

 Choose the output filesystem type.

@@ -178,13 +178,13 @@ The default is C<ext2>.
 Any filesystem which is supported read-write by libguestfs can be used
 here.

-=item B<--label=E<lt>LABELE<gt>>
+=item B<--label=>LABEL

 Set the filesystem label.

 =item B<--partition>

-=item B<--partition=E<lt>parttypeE<gt>>
+=item B<--partition=>PARTTYPE

 If specified, this flag adds an MBR partition table to the output disk
 image.
--- a/podcheck.pl
+++ b/podcheck.pl
@@ -0,0 +1,228 @@
+#!/usr/bin/env perl
+# podcheck.pl
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+use warnings;
+use strict;
+
+use Pod::Usage;
+use Getopt::Long;
+use Pod::Man;
+
+=head1 NAME
+
+podcheck.pl - Compare man page and tools to check all arguments are documented
+
+=head1 SYNOPSIS
+
+ podcheck.pl virt-foo.pod ./virt-foo [--ignore=--arg,--arg,...]
+
+=head1 DESCRIPTION
+
+This script compares a manual page (eg. C<virt-foo.pod>) and the
+corresponding tool (eg. C<./virt-foo>) and checks that each command
+line argument is documented in the manual, and that there is no rogue
+documentation for arguments which do not exist.  It works by running
+the tool with the standard C<--long-options> and C<--short-options>
+parameters and comparing their output with the man page.
+
+You can also ignore options, in case this script gets things wrong or
+if there are options that you don't intend to document.
+
+=head1 OPTIONS
+
+=over 4
+
+=cut
+
+my $help;
+
+=item B<--help>
+
+Display brief help.
+
+=cut
+
+my $ignore = "";
+
+=item B<--ignore=--arg,--arg,...>
+
+Ignore the comma-separated list of arguments given.
+
+=cut
+
+my @inserts;
+
+=item B<--insert filename:__PATTERN__>
+
+This works like the L<podwrapper.pl(1)> I<--insert> option and should be
+used where the POD includes patterns which podwrapper would substitute.
+
+=cut
+
+my @verbatims;
+
+=item B<--verbatim filename:__PATTERN__>
+
+This works like the podwrapper I<--verbatim> option and should be
+used where the POD includes patterns which podwrapper would substitute.
+
+=cut
+
+# Clean up the program name.
+my $progname = $0;
+$progname =~ s{.*/}{};
+
+# Parse options.
+GetOptions ("help|?" => \$help,
+            "ignore=s" => \$ignore,
+            "insert=s" => \@inserts,
+            "verbatim=s" => \@verbatims,
+    ) or pod2usage (2);
+pod2usage (1) if $help;
+
+die "$progname: missing argument: podcheck.pl input.pod tool\n"
+    unless @ARGV == 2;
+my $input = $ARGV[0];
+my $tool = $ARGV[1];
+
+my %ignore = ();
+$ignore{$_} = 1 foreach (split /,/, $ignore);
+
+# Open the man page and slurp it in.
+my $content = read_whole_file ($input);
+
+# Perform @inserts.
+foreach (@inserts) {
+    my @a = split /:/, $_, 2;
+    die "$progname: $input: no colon in parameter of --insert\n" unless @a >= 2;
+    my $replacement = read_whole_file ($a[0]);
+    my $oldcontent = $content;
+    $content =~ s/$a[1]/$replacement/ge;
+    die "$progname: $input: could not find pattern '$a[1]' in input file\n"
+        if $content eq $oldcontent;
+}
+
+# Perform @verbatims.
+foreach (@verbatims) {
+    my @a = split /:/, $_, 2;
+    die "$progname: $input: no colon in parameter of --verbatim\n" unless @a >= 2;
+    my $replacement = read_verbatim_file ($a[0]);
+    my $oldcontent = $content;
+    $content =~ s/$a[1]/$replacement/ge;
+    die "$progname: $input: could not find pattern '$a[1]' in input file\n"
+        if $content eq $oldcontent;
+}
+
+# Run the tool with --long-options and --short-options.
+my @tool_options = ();
+open PIPE, "$tool --long-options |"
+    or die "$progname: $tool --long-options: $!";
+while (<PIPE>) {
+    chomp;
+    push @tool_options, $_;
+}
+close PIPE;
+open PIPE, "$tool --short-options |"
+    or die "$progname: $tool --short-options: $!";
+while (<PIPE>) {
+    chomp;
+    push @tool_options, $_;
+}
+close PIPE;
+
+my %tool_option_exists = ();
+$tool_option_exists{$_} = 1 foreach @tool_options;
+
+# There are some tool options which we automatically ignore.
+delete $tool_option_exists{"--color"};
+delete $tool_option_exists{"--colour"};
+delete $tool_option_exists{"--debug-gc"};
+
+my $errors = 0;
+
+# Check each option exists in the manual.
+my $tool_options_checked = 0;
+
+foreach (sort keys %tool_option_exists) {
+    unless ($ignore{$_}) {
+        $tool_options_checked++;
+        unless ($content =~ /^=item.*B<$_(?:=.*)?>/m) {
+            $errors++;
+            warn "$progname: $input does not define $_\n";
+        }
+    }
+}
+
+# Check there are no extra options defined in the manual which
+# don't exist in the tool.
+my $pod_options_checked = 0;
+
+my %pod_options = ();
+$pod_options{$_} = 1 foreach ( $content =~ /^=item.*B<(-[-\w]+)(?:=.*)?>/gm );
+foreach (sort keys %pod_options) {
+    unless ($ignore{$_}) {
+        $pod_options_checked++;
+        unless (exists $tool_option_exists{$_}) {
+            $errors++;
+            warn "$progname: $input defines option $_ which does not exist in the tool\n"
+        }
+    }
+}
+
+exit 1 if $errors > 0;
+
+printf "$progname: $tool: checked $tool_options_checked tool options against $pod_options_checked documented options\n";
+
+exit 0;
+
+sub read_whole_file
+{
+    my $input = shift;
+    local $/ = undef;
+
+    open FILE, $input or die "$progname: $input: $!";
+    $_ = <FILE>;
+    close FILE;
+    $_;
+}
+
+sub read_verbatim_file
+{
+    my $input = shift;
+    my $r = "";
+
+    open FILE, $input or die "$progname: $input: $!";
+    while (<FILE>) {
+        $r .= " $_";
+    }
+    close FILE;
+    $r;
+}
+
+=head1 SEE ALSO
+
+L<podwrapper.pl(1)>,
+libguestfs.git/README.
+
+=head1 AUTHOR
+
+Richard W.M. Jones.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2016 Red Hat Inc.
--- a/rescue/Makefile.am
+++ b/rescue/Makefile.am
@@ -19,6 +19,7 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	test-virt-rescue.pl \
+	test-virt-rescue-docs.sh \
 	test-virt-rescue-suggest.sh \
 	virt-rescue.pod

@@ -83,7 +84,8 @@ stamp-virt-rescue.pod: virt-rescue.pod

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-TESTS =
+TESTS = \
+	test-virt-rescue-docs.sh

 if ENABLE_APPLIANCE
 TESTS += \
--- a/rescue/test-virt-rescue-docs.sh
+++ b/rescue/test-virt-rescue-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-rescue.pod virt-rescue
--- a/rescue/virt-rescue.pod
+++ b/rescue/virt-rescue.pod
@@ -108,24 +108,24 @@ use to make scripted changes to guests, use L<guestfish(1)>.

 Display brief help.

-=item B<-a> file
+=item B<-a> FILE

-=item B<--add> file
+=item B<--add> FILE

-Add I<file> which should be a disk image from a virtual machine.  If
+Add C<FILE> which should be a disk image from a virtual machine.  If
 the virtual machine has multiple block devices, you must supply all of
 them with separate I<-a> options.

 The format of the disk image is auto-detected.  To override this and
 force a particular format use the I<--format=..> option.

-=item B<-a URI>
+=item B<-a> URI

-=item B<--add URI>
+=item B<--add> URI

 Add a remote disk.  See L<guestfish(1)/ADDING REMOTE STORAGE>.

-=item B<--append kernelopts>
+=item B<--append> KERNELOPTS

 Pass additional options to the rescue kernel.

@@ -170,9 +170,9 @@ If you have untrusted raw-format guest disk images, you should use
 this option to specify the disk format.  This avoids a possible
 security problem with malicious guests (CVE-2010-3851).

-=item B<-m MB>
+=item B<-m> MB

-=item B<--memsize MB>
+=item B<--memsize> MB

 Change the amount of memory allocated to the rescue system.  The
 default is set by libguestfs and is small but adequate for running
--- a/resize/Makefile.am
+++ b/resize/Makefile.am
@@ -19,8 +19,9 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	$(SOURCES_MLI) $(SOURCES_ML) $(SOURCES_C) \
-	virt-resize.pod \
-	test-virt-resize.pl
+	test-virt-resize.pl \
+	test-virt-resize-docs.sh \
+	virt-resize.pod

 CLEANFILES = *~ *.annot *.cmi *.cmo *.cmx *.cmxa *.o virt-resize

@@ -115,9 +116,12 @@ CLEANFILES += \

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-TESTS =
+TESTS = \
+	test-virt-resize-docs.sh
+
 if ENABLE_APPLIANCE
-TESTS += test-virt-resize.pl
+TESTS += \
+	test-virt-resize.pl
 endif

 check-valgrind:
--- a/resize/test-virt-resize-docs.sh
+++ b/resize/test-virt-resize-docs.sh
@@ -0,0 +1,23 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-resize.pod virt-resize \
+    --ignore=--LVexpand,--lv-expand,--lvexpand,--dryrun
--- a/resize/virt-resize.pod
+++ b/resize/virt-resize.pod
@@ -271,11 +271,11 @@ command line.  Doing so will give an error.

 Display help.

-=item B<--align-first auto>
+=item B<--align-first> B<auto>

-=item B<--align-first never>
+=item B<--align-first> B<never>

-=item B<--align-first always>
+=item B<--align-first> B<always>

 Align the first partition for improved performance (see also the
 I<--alignment> option).
@@ -293,7 +293,7 @@ I<--align-first always> means we always align the first partition (if
 it needs to be aligned).  For some guests this will break the
 bootloader, making the guest unbootable.

-=item B<--alignment N>
+=item B<--alignment> N

 Set the alignment of partitions to C<N> sectors.  The default in
 virt-resize E<lt> 1.13.19 was 64 sectors, and after that is 128
@@ -344,7 +344,7 @@ option.

 Enable debugging messages.

-=item B<--delete part>
+=item B<--delete> PART

 Delete the named partition.  It would be more accurate to describe
 this as "don't copy it over", since virt-resize doesn't do in-place
@@ -357,7 +357,7 @@ unbootable.

 You can give this option multiple times.

-=item B<--expand part>
+=item B<--expand> PART

 Expand the named partition so it uses up all extra space (space left
 over after any other resize changes that you request have been done).
@@ -402,7 +402,7 @@ XFS filesystems, if libguestfs was compiled with support for XFS.

 Note that you cannot use I<--expand> and I<--shrink> together.

-=item B<--format> raw
+=item B<--format> B<raw>

 Specify the format of the input disk image.  If this flag is not
 given then it is auto-detected from the image itself.
@@ -413,7 +413,7 @@ ensure the format is always specified.
 Note that this option I<does not> affect the output format.
 See L</QCOW2 AND NON-SPARSE RAW FORMATS>.

-=item B<--ignore part>
+=item B<--ignore> PART

 Ignore the named partition.  Effectively this means the partition is
 allocated on the destination disk, but the content is not copied
@@ -422,7 +422,7 @@ blank (all zero bytes).

 You can give this option multiple times.

-=item B<--LV-expand logvol>
+=item B<--LV-expand> LOGVOL

 This takes the logical volume and, as a final step, expands it to fill
 all the space available in its volume group.  A typical usage,
@@ -453,7 +453,7 @@ L</MACHINE READABLE OUTPUT> below.

 =item B<-n>

-=item B<--dryrun>
+=item B<--dry-run>

 Print a summary of what would be done, but don't do anything.

@@ -498,7 +498,7 @@ You have to use this option if you want to resize a Windows
 guest multiple times without booting into Windows between each
 resize.

-=item B<--output-format> raw
+=item B<--output-format> B<raw>

 Specify the format of the output disk image.  If this flag is not
 given then it is auto-detected from the image itself.
@@ -517,12 +517,12 @@ L</QCOW2 AND NON-SPARSE RAW FORMATS>.

 Don't print the summary.

-=item B<--resize part=size>
+=item B<--resize> PART=SIZE

 Resize the named partition (expanding or shrinking it) so that it has
 the given size.

-C<size> can be expressed as an absolute number followed by
+C<SIZE> can be expressed as an absolute number followed by
 b/K/M/G to mean bytes, Kilobytes, Megabytes, or Gigabytes;
 or as a percentage of the current size;
 or as a relative number or percentage.
@@ -553,7 +553,7 @@ error (see also I<--resize-force>).

 You can give this option multiple times.

-=item B<--resize-force part=size>
+=item B<--resize-force> PART=SIZE

 This is the same as I<--resize> except that it will let you decrease
 the size of any partition.  Generally this means you will lose any
@@ -563,7 +563,7 @@ easily recreate it such as a swap partition).

 See also the I<--ignore> option.

-=item B<--shrink part>
+=item B<--shrink> PART

 Shrink the named partition until the overall disk image fits in the
 destination.  The named partition B<must> contain a filesystem or PV
@@ -581,11 +581,11 @@ gigabyte of free space.

 Note that you cannot use I<--expand> and I<--shrink> together.

-=item B<--unknown-filesystems ignore>
+=item B<--unknown-filesystems> B<ignore>

-=item B<--unknown-filesystems warn>
+=item B<--unknown-filesystems> B<warn>

-=item B<--unknown-filesystems error>
+=item B<--unknown-filesystems> B<error>

 Configure the behaviour of virt-resize when asking to expand a
 filesystem, and neither libguestfs has the support it, nor virt-resize
--- a/sparsify/Makefile.am
+++ b/sparsify/Makefile.am
@@ -19,9 +19,10 @@ include $(top_srcdir)/subdir-rules.mk

 EXTRA_DIST = \
 	$(SOURCES_MLI) $(SOURCES_ML) $(SOURCES_C) \
-	virt-sparsify.pod \
 	test-virt-sparsify.sh \
-	test-virt-sparsify-in-place.sh
+	test-virt-sparsify-docs.sh \
+	test-virt-sparsify-in-place.sh \
+	virt-sparsify.pod

 CLEANFILES = *~ *.annot *.cmi *.cmo *.cmx *.cmxa *.o virt-sparsify

@@ -119,8 +120,11 @@ CLEANFILES += \

 TESTS_ENVIRONMENT = $(top_builddir)/run --test

-if ENABLE_APPLIANCE
 TESTS = \
+	test-virt-sparsify-docs.sh
+
+if ENABLE_APPLIANCE
+TESTS += \
 	test-virt-sparsify.sh \
 	test-virt-sparsify-in-place.sh
 endif ENABLE_APPLIANCE
--- a/sparsify/test-virt-sparsify-docs.sh
+++ b/sparsify/test-virt-sparsify-docs.sh
@@ -0,0 +1,23 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-sparsify.pod virt-sparsify \
+                       --ignore=--inplace
--- a/sparsify/virt-sparsify.pod
+++ b/sparsify/virt-sparsify.pod
@@ -119,13 +119,13 @@ in place by doing:

 Display help.

-=item B<--check-tmpdir ignore>
+=item B<--check-tmpdir> B<ignore>

-=item B<--check-tmpdir continue>
+=item B<--check-tmpdir> B<continue>

-=item B<--check-tmpdir warn>
+=item B<--check-tmpdir> B<warn>

-=item B<--check-tmpdir fail>
+=item B<--check-tmpdir> B<fail>

 Check if L</TMPDIR> or I<--tmp> directory has enough space to complete
 the operation.  This is just an estimate.
--- a/sysprep/Makefile.am
+++ b/sysprep/Makefile.am
@@ -21,6 +21,7 @@ EXTRA_DIST = \
 	$(SOURCES_MLI) $(SOURCES_ML) $(SOURCES_C) \
 	script1.sh script2.sh script3.sh script4.sh \
 	test-virt-sysprep.sh \
+	test-virt-sysprep-docs.sh \
 	test-virt-sysprep-passwords.sh \
 	test-virt-sysprep-script.sh \
 	virt-sysprep.pod
@@ -178,8 +179,11 @@ TESTS_ENVIRONMENT = \
 	PATH=$(abs_top_builddir)/fuse:$(PATH) \
 	$(top_builddir)/run --test

-if ENABLE_APPLIANCE
 TESTS = \
+	test-virt-sysprep-docs.sh
+
+if ENABLE_APPLIANCE
+TESTS += \
 	test-virt-sysprep.sh \
 	test-virt-sysprep-passwords.sh

--- a/sysprep/test-virt-sysprep-docs.sh
+++ b/sysprep/test-virt-sysprep-docs.sh
@@ -0,0 +1,25 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-sysprep.pod virt-sysprep \
+    --insert sysprep-extra-options.pod:__EXTRA_OPTIONS__ \
+    --insert sysprep-operations.pod:__OPERATIONS__ \
+    --ignore=--dryrun,--dump-pod,--dump-pod-options,--no-selinux-relabel
--- a/v2v/Makefile.am
+++ b/v2v/Makefile.am
@@ -254,6 +254,7 @@ CLEANFILES += \
 TESTS_ENVIRONMENT = $(top_builddir)/run --test

 TESTS = \
+	test-v2v-docs.sh \
 	test-v2v-i-ova-formats.sh \
 	test-v2v-i-ova-gz.sh \
 	test-v2v-i-ova-subfolders.sh \
@@ -332,6 +333,7 @@ EXTRA_DIST += \
 	test-v2v-cdrom.sh \
 	test-v2v-cdrom.xml \
 	test-v2v-copy-to-local.sh \
+	test-v2v-docs.sh \
 	test-v2v-floppy.expected \
 	test-v2v-floppy.sh \
 	test-v2v-floppy.xml \
--- a/v2v/test-v2v-docs.sh
+++ b/v2v/test-v2v-docs.sh
@@ -0,0 +1,23 @@
+#!/bin/bash -
+# libguestfs
+# Copyright (C) 2016 Red Hat Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+export LANG=C
+set -e
+
+$srcdir/../podcheck.pl virt-v2v.pod virt-v2v \
+  --ignore=--dcPath,--debug-overlay,--ic,--if,--no-trim,--oa,--oc,--of,--on,--os,--vmtype
--- a/v2v/virt-v2v.pod
+++ b/v2v/virt-v2v.pod
@@ -291,7 +291,7 @@ Save the overlay file(s) created during conversion.  This option is
 only used for debugging virt-v2v and may be removed in a future
 version.

-=item B<-i disk>
+=item B<-i> B<disk>

 Set the input method to I<disk>.

@@ -301,7 +301,7 @@ usually adequate but you can get finer control (eg. of memory and
 vCPUs) by using I<-i libvirtxml> instead.  Only guests that use a single
 disk can be imported this way.

-=item B<-i libvirt>
+=item B<-i> B<libvirt>

 Set the input method to I<libvirt>.  This is the default.

@@ -309,7 +309,7 @@ In this mode you have to specify a libvirt guest name or UUID on the
 command line.  You may also specify a libvirt connection URI (see
 I<-ic>).

-=item B<-i libvirtxml>
+=item B<-i> B<libvirtxml>

 Set the input method to I<libvirtxml>.

@@ -318,11 +318,11 @@ This file is read in order to get metadata about the source guest
 (such as its name, amount of memory), and also to locate the input
 disks.  See L</MINIMAL XML FOR -i libvirtxml OPTION> below.

-=item B<-i local>
+=item B<-i> B<local>

 This is the same as I<-i disk>.

-=item B<-i ova>
+=item B<-i> B<ova>

 Set the input method to I<ova>.

@@ -406,16 +406,16 @@ a faulty guest (one with no disks).

 This option is not compatible with I<-o glance> for technical reasons.

-=item B<-o disk>
+=item B<-o> B<disk>

 This is the same as I<-o local>.

-=item B<-o glance>
+=item B<-o> B<glance>

 Set the output method to OpenStack Glance.  In this mode the converted
 guest is uploaded to Glance.  See L</OUTPUT TO GLANCE> below.

-=item B<-o libvirt>
+=item B<-o> B<libvirt>

 Set the output method to I<libvirt>.  This is the default.

@@ -424,7 +424,7 @@ may also specify a libvirt connection URI (see I<-oc>).

 See L</OUTPUT TO LIBVIRT> below.

-=item B<-o local>
+=item B<-o> B<local>

 Set the output method to I<local>.

@@ -442,7 +442,7 @@ and a libvirt XML file is created containing guest metadata:

 where C<name> is the guest name.

-=item B<-o null>
+=item B<-o> B<null>

 Set the output method to I<null>.

@@ -450,11 +450,11 @@ The guest is converted and copied (unless you also specify
 I<--no-copy>), but the results are thrown away and no metadata is
 written.

-=item B<-o ovirt>
+=item B<-o> B<ovirt>

 This is the same as I<-o rhev>.

-=item B<-o qemu>
+=item B<-o> B<qemu>

 Set the output method to I<qemu>.

@@ -465,7 +465,7 @@ shell script are written to the directory specified by I<-os>.
 When using this output mode, you can also specify the I<--qemu-boot>
 option which boots the guest under qemu immediately.

-=item B<-o rhev>
+=item B<-o> B<rhev>

 Set the output method to I<rhev>.

@@ -476,7 +476,7 @@ into RHEV.  You have to do that manually later using the UI.

 See L</OUTPUT TO RHEV> below.

-=item B<-o vdsm>
+=item B<-o> B<vdsm>

 Set the output method to I<vdsm>.

@@ -485,9 +485,9 @@ data domain must be given:
 F</rhev/data-center/E<lt>data-center-uuidE<gt>/E<lt>data-domain-uuidE<gt>>.
 This mode is only used when virt-v2v runs under VDSM control.

-=item B<-oa sparse>
+=item B<-oa> B<sparse>

-=item B<-oa preallocated>
+=item B<-oa> B<preallocated>

 Set the output file allocation mode.  The default is C<sparse>.