Reorganize main POD tests and add a spelling check

Add a POD spelling test to the non-Perl-module part of the code and
move the documentation tests into a separate directory.  Merge the
POD syntax tests between client and server into one test.

Reformat all of the POD documentation to use 74 columns.  Fix a few
revealed spelling errors or weird wordings.

5 files changed, 103 insertions, 46 deletions

diff --git a/tests/TESTS b/tests/TESTS
index ac6fd82..161941c 100644
--- a/tests/TESTS
+++ b/tests/TESTS
@@ -1,7 +1,8 @@
 client/basic
 client/full
-client/pod
 client/prompt
+docs/pod
+docs/pod-spelling
 portable/asprintf
 portable/mkstemp
 portable/setenv
@@ -11,7 +12,6 @@ portable/strlcpy
 server/admin
 server/backend
 server/keytab
-server/pod
 util/concat
 util/messages
 util/messages-krb5
diff --git a/tests/client/pod-t b/tests/client/pod-t
deleted file mode 100755
index 9963567..0000000
--- a/tests/client/pod-t
+++ /dev/null
@@ -1,22 +0,0 @@
-#!/usr/bin/perl
-#
-# Test POD formatting for client documentation.
-#
-# Written by Russ Allbery <rra@stanford.edu>
-# Copyright 2008, 2010 Board of Trustees, Leland Stanford Jr. University
-#
-# See LICENSE for licensing terms.
-
-use Test::More;
-
-my @files = qw(wallet.pod);
-my $total = scalar (@files);
-plan tests => $total;
-
-eval 'use Test::Pod 1.00';
-SKIP: {
-    skip $total, 'Test::Pod 1.00 required for testing POD' if $@;
-    for my $file (@files) {
-        pod_file_ok ("$ENV{SOURCE}/../client/$file", "client/$file");
-    }
-}
diff --git a/tests/docs/pod-spelling-t b/tests/docs/pod-spelling-t
new file mode 100755
index 0000000..433d841
--- /dev/null
+++ b/tests/docs/pod-spelling-t
@@ -0,0 +1,80 @@
+#!/usr/bin/perl
+#
+# Check for spelling errors in POD documentation
+#
+# Checks all POD files in the tree for spelling problems using Pod::Spell and
+# either aspell or ispell.  aspell is preferred.  This test is disabled unless
+# RRA_MAINTAINER_TESTS is set, since spelling dictionaries vary too much
+# between environments.
+#
+# Copyright 2008, 2009 Russ Allbery <rra@stanford.edu>
+#
+# See LICENSE for licensing terms.
+
+use strict;
+use Test::More;
+
+# Skip all spelling tests unless the maintainer environment variable is set.
+plan skip_all => 'spelling tests only run for maintainer'
+    unless $ENV{RRA_MAINTAINER_TESTS};
+
+# Load required Perl modules.
+eval 'use Test::Pod 1.00';
+plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@;
+eval 'use Pod::Spell';
+plan skip_all => 'Pod::Spell required to test POD spelling' if $@;
+
+# Locate a spell-checker.  hunspell is not currently supported due to its lack
+# of support for contractions (at least in the version in Debian).
+my @spell;
+my %options = (aspell => [ qw(-d en_US --home-dir=./ list) ],
+               ispell => [ qw(-d american -l -p /dev/null) ]);
+SEARCH: for my $program (qw/aspell ispell/) {
+    for my $dir (split ':', $ENV{PATH}) {
+        if (-x "$dir/$program") {
+            @spell = ("$dir/$program", @{ $options{$program} });
+        }
+        last SEARCH if @spell;
+    }
+}
+plan skip_all => 'aspell or ispell required to test POD spelling'
+    unless @spell;
+
+# Prerequisites are satisfied, so we're going to do some testing.  Figure out
+# what POD files we have and from that develop our plan.
+$| = 1;
+my @pod = map {
+    my $pod = "$ENV{SOURCE}/../" . $_;
+    $pod =~ s,[^/.][^/]*/../,,g;
+    $pod;
+} qw(client/wallet.pod server/keytab-backend server/wallet-admin
+     server/wallet-backend);
+plan tests => scalar @pod;
+
+# Finally, do the checks.
+for my $pod (@pod) {
+    my $child = open (CHILD, '-|');
+    if (not defined $child) {
+        BAIL_OUT ("cannot fork: $!");
+    } elsif ($child == 0) {
+        my $pid = open (SPELL, '|-', @spell)
+            or BAIL_OUT ("cannot run @spell: $!");
+        open (POD, '<', $pod) or BAIL_OUT ("cannot open $pod: $!");
+        my $parser = Pod::Spell->new;
+        $parser->parse_from_filehandle (\*POD, \*SPELL);
+        close POD;
+        close SPELL;
+        exit ($? >> 8);
+    } else {
+        my @words = <CHILD>;
+        close CHILD;
+      SKIP: {
+            skip "@spell failed for $pod", 1 unless $? == 0;
+            for (@words) {
+                s/^\s+//;
+                s/\s+$//;
+            }
+            is ("@words", '', $pod);
+        }
+    }
+}
diff --git a/tests/docs/pod-t b/tests/docs/pod-t
new file mode 100755
index 0000000..9b6c5d1
--- /dev/null
+++ b/tests/docs/pod-t
@@ -0,0 +1,21 @@
+#!/usr/bin/perl -w
+#
+# Test POD formatting for documentation.
+#
+# Written by Russ Allbery <rra@stanford.edu>
+# Copyright 2008, 2010 Board of Trustees, Leland Stanford Jr. University
+#
+# See LICENSE for licensing terms.
+
+use strict;
+use Test::More;
+eval 'use Test::Pod 1.00';
+plan skip_all => 'Test::Pod 1.00 required for testing POD' if $@;
+
+my @files = qw(client/wallet.pod server/keytab-backend server/wallet-admin
+               server/wallet-backend);
+my $total = scalar (@files);
+plan tests => $total;
+for my $file (@files) {
+    pod_file_ok ("$ENV{SOURCE}/../$file", $file);
+}
diff --git a/tests/server/pod-t b/tests/server/pod-t
deleted file mode 100755
index 52d81eb..0000000
--- a/tests/server/pod-t
+++ /dev/null
@@ -1,22 +0,0 @@
-#!/usr/bin/perl
-#
-# Test POD formatting for client documentation.
-#
-# Written by Russ Allbery <rra@stanford.edu>
-# Copyright 2008, 2010 Board of Trustees, Leland Stanford Jr. University
-#
-# See LICENSE for licensing terms.
-
-use Test::More;
-
-my @files = qw(keytab-backend wallet-admin wallet-backend);
-my $total = scalar (@files);
-plan tests => $total;
-
-eval 'use Test::Pod 1.00';
-SKIP: {
-    skip 'Test::Pod 1.00 required for testing POD', $total if $@;
-    for my $file (@files) {
-        pod_file_ok ("$ENV{SOURCE}/../server/$file", "server/$file");
-    }
-}