Extract subroutines used to test File-Find into separate package.

t/porting/manifest.t and pod_rules.t:  Add comments describing how to handle a
MANIFEST which is not sorted properly (per recommendation by Nicholas Clark).

2 files changed, 42 insertions, 1 deletions

diff --git a/t/porting/manifest.t b/t/porting/manifest.t
index ea4fe832d7..b8c63c5b5a 100644
--- a/t/porting/manifest.t
+++ b/t/porting/manifest.t
@@ -1,6 +1,28 @@
 #!./perl -w
 
-# Test the well-formed-ness of the MANIFEST file.
+# What does this test?
+# This tests the well-formed-ness of the MANIFEST file.
+#
+# Why do we test this?
+# TK
+#
+# It's broken - how do I fix it?
+# If MANIFEST is not sorted properly, you will get this error output:
+#      got ''MANIFEST' is NOT sorted properly
+#      # '
+#      # expected /(?^:is sorted properly)/
+#
+# To correct this, run either:
+#
+#   ./perl -Ilib Porting/manisort -o MANIFEST MANIFEST
+#
+# which will output "'MANIFEST' is NOT sorted properly" but which will
+# correct the problem; or:
+#
+#   make manifest
+#
+# which will output "WARNING: re-sorting MANIFEST" but which will also
+# correct the problem.
 
 BEGIN {
     @INC = '..' if -f '../TestInit.pm';
diff --git a/t/porting/pod_rules.t b/t/porting/pod_rules.t
index cdf2ae67e9..5c69483351 100644
--- a/t/porting/pod_rules.t
+++ b/t/porting/pod_rules.t
@@ -1,5 +1,24 @@
 #!./perl
 
+# What does this test?
+# This test executes Porting/pod_rules.pl and reports the result of that
+# program.
+#
+# Why do we test this?
+# Among other reasons, to check the well-formed-ness of these files:
+#   win32/makefile.mk
+#   MANIFEST
+#   win32/Makefile
+#   win32/pod.mak
+#   Makefile.SH
+#   vms/descrip_mms.template
+#
+# It's broken - how do I fix it?
+# If MANIFEST fails the 'up to date' test, it will probably also fail
+# t/porting/manifest.t as well.  Follow instructions in that file for
+# correcting the MANIFEST.  When that file passes, the MANIFEST check in this
+# file will probably pass as well.
+
 BEGIN {
     chdir '..' unless -d 't';
     unshift @INC, 'lib';