Introduce TAP tests of man pages for command_subcommand

Introduces the first batch of man page testing as part of
the TAP tests.  We would like to fail, for example, when
someone has added a new command to vos but not AHEM documented
it.

For now, the tests consist of checking to ensure that for
every subcommand listed in the output of "command help"
(e.g. vos help), fail the test if there is not a man page
for those (e.g. vos_delentry.1 etc).

Copy any of the -man-t tests and edit to make a new one

All tests make use of a simple new Perl library stored
in tests-lib/perl5 (a new area, not just named 'lib'
because I didn't want it to be confused with a s test
for a 'lib' in the src).

Change-Id: I1e07adafe718c4549f1855c5e5b0d10dd9ab5f00
Reviewed-on: http://gerrit.openafs.org/4846
Reviewed-by: Simon Wilkinson <sxw@inf.ed.ac.uk>
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: Derrick Brashear <shadow@dementia.org>

tests/TESTS

@@ -6,3 +6,7 @@ auth/superuser
 auth/authcon
 cmd/command
 ptserver/pt_util
+ptserver/pts-man
+volser/vos-man
+bucoord/backup-man
+kauth/kas

tests/bozo/bos-man-t

@@ -0,0 +1,26 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use File::Basename;
+use lib "./tests-lib/perl5";
+use mancheck_utils;
+
+# Set this to the bare command to test
+my $command = 'bos';
+my $builddir = $ENV{BUILD};
+if (!$builddir) {
+    $builddir = dirname($0) . "/..";
+}
+$builddir .= "/..";
+# Set this to the directory holding $command
+my $srcdir = "$builddir/src/bozo";
+
+#---------------------------------------------------------------------
+
+# Keep track of number of tests we ran. We don't know up front.
+my $testcount = 0;
+
+check_command_binary("$srcdir/$command");
+my $count = test_command_man_pages($builddir, "$srcdir/$command");
+done_testing($count);

tests/bucoord/backup-man-t

@@ -0,0 +1,26 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use File::Basename;
+use lib "./tests-lib/perl5";
+use mancheck_utils;
+
+# Set this to the bare command to test
+my $command = 'backup';
+my $builddir = $ENV{BUILD};
+if (!$builddir) {
+    $builddir = dirname($0) . "/..";
+}
+$builddir .= "/..";
+# Set this to the directory holding $command
+my $srcdir = "$builddir/src/bucoord";
+
+#---------------------------------------------------------------------
+
+# Keep track of number of tests we ran. We don't know up front.
+my $testcount = 0;
+
+check_command_binary("$srcdir/$command");
+my $count = test_command_man_pages($builddir, "$srcdir/$command");
+done_testing($count);

tests/kauth/kas-man-t

@@ -0,0 +1,26 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use File::Basename;
+use lib "./tests-lib/perl5";
+use mancheck_utils;
+
+# Set this to the bare command to test
+my $command = 'kas';
+my $builddir = $ENV{BUILD};
+if (!$builddir) {
+    $builddir = dirname($0) . "/..";
+}
+$builddir .= "/..";
+# Set this to the directory holding $command
+my $srcdir = "$builddir/src/kauth";
+
+#---------------------------------------------------------------------
+
+# Keep track of number of tests we ran. We don't know up front.
+my $testcount = 0;
+
+check_command_binary("$srcdir/$command");
+my $count = test_command_man_pages($builddir, "$srcdir/$command");
+done_testing($count);

tests/ptserver/pts-man-t

@@ -0,0 +1,26 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use File::Basename;
+use lib "./tests-lib/perl5";
+use mancheck_utils;
+
+# Set this to the bare command to test
+my $command = 'pts';
+my $builddir = $ENV{BUILD};
+if (!$builddir) {
+    $builddir = dirname($0) . "/..";
+}
+$builddir .= "/..";
+# Set this to the directory holding $command
+my $srcdir = "$builddir/src/ptserver";
+
+#---------------------------------------------------------------------
+
+# Keep track of number of tests we ran. We don't know up front.
+my $testcount = 0;
+
+check_command_binary("$srcdir/$command");
+my $count = test_command_man_pages($builddir, "$srcdir/$command");
+done_testing($count);

tests/tests-lib/perl5/mancheck_utils.pm

@@ -0,0 +1,86 @@
+#
+# This is probably horrific code to any Perl coder.  I'm sorry,
+# I'm not one.  It runs.
+#
+# Proposed Coding Standard:
+#
+#     * Subroutines starting with test_ should be TAP tests
+#       utilizing ok(), is(), etc... and return the number
+#       of tests run if they get that far (could exit early
+#       from a BAIL_OUT())
+#
+use File::Basename;
+use Test::More;
+
+sub check_command_binary {
+    my $c = shift(@_);
+    if (! -e "$c") {
+	BAIL_OUT("Cannot find $c");
+    }
+}
+
+# TAP test: test_command_man_pages
+#
+# Gather a list of a command's subcommands (like listvol for vos)
+# by running a command with the "help" argument.  From that list
+# of subcommands spit out, see if a man page exists for that
+# command_subcommand
+#
+# Arguments: two scalars:
+#
+#                builddir : A path to the OpenAFS build directory,
+#                           such as /tmp/1.4.14
+#
+#         fullpathcommand : The full path to the actual command's
+#                           binary, such as /tmp/1.4.14/src/volser/vos
+#
+# Returns: the number of tests run
+#
+sub test_command_man_pages {
+    my ($builddir, $fullpathcommand) = @_;
+
+    my $command = basename($fullpathcommand);
+
+    # build up our list of available commands from the help output
+    open(HELPOUT, "$fullpathcommand help 2>&1 |") or BAIL_OUT("can't fork: $!");
+    my @subcommlist;
+    my @comm;
+    while (<HELPOUT>) {
+        # Skip the header thingy
+        next if /Commands are/;
+        @comm = split();
+        push(@subcommlist, $comm[0]);
+    }
+    close HELPOUT;
+    @subcommlist = sort(@subcommlist);
+
+    # The following is because File::Find makes no sense to me
+    # for this purpose, and actually seems totally misnamed
+    my $found = 0;
+    my $subcommand = "";
+    my $frex = "";
+    # Since we don't know what man section it might be in,
+    # search all existing man page files for a filename match
+    my @mandirglob = glob("$builddir/doc/man-pages/man[1-8]/*");
+    # For every subcommand, see if command_subcommand.[1-8] exists
+    # in our man page build dir.
+    foreach (@subcommlist) {
+        my $subcommand = $_;
+        $found = 0;
+        my $frex = $command . '_' . $subcommand . '.[1-8]';
+        # diag("Looking for $frex");
+        foreach my $x (@mandirglob) {
+	    # diag("TRYING: $x");
+	    $x = basename($x);
+	    if ($x =~ /$frex$/) {
+		# diag("FOUND");
+		$found = 1;
+		last;
+	    }
+	}
+	$testcount = $testcount + 1;
+	ok($found eq 1, "existence of man page for $command" . "_$subcommand");
+    }
+    return $testcount;
+}
+1;

tests/venus/fs-man-t

@@ -0,0 +1,26 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use File::Basename;
+use lib "./tests-lib/perl5";
+use mancheck_utils;
+
+# Set this to the bare command to test
+my $command = 'fs';
+my $builddir = $ENV{BUILD};
+if (!$builddir) {
+    $builddir = dirname($0) . "/..";
+}
+$builddir .= "/..";
+# Set this to the directory holding $command
+my $srcdir = "$builddir/src/venus";
+
+#---------------------------------------------------------------------
+
+# Keep track of number of tests we ran. We don't know up front.
+my $testcount = 0;
+
+check_command_binary("$srcdir/$command");
+my $count = test_command_man_pages($builddir, "$srcdir/$command");
+done_testing($count);

tests/volser/vos-man-t

@@ -0,0 +1,27 @@
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use File::Basename;
+
+# Set this to the bare command to test
+my $command = 'vos';
+my $builddir = $ENV{BUILD};
+if (!$builddir) {
+    $builddir = dirname($0) . "/..";
+}
+$builddir .= "/..";
+# Set this to the directory holding $command
+my $srcdir = "$builddir/src/volser";
+
+#---------------------------------------------------------------------
+
+# Keep track of number of tests we ran. We don't know up front.
+my $testcount = 0;
+
+use lib "./tests-lib/perl5";
+use mancheck_utils;
+
+check_command_binary("$srcdir/$command");
+my $count = test_command_man_pages($builddir, "$srcdir/$command");
+done_testing($count);