podcheck.t: Improve documentation

This includes a few nits, but also adds documentation about setting the
number of errors for a message to negative in the db to cope with the
number being variable, and the specially handled pods: perldelta and
perltoc, and non-pod: perldelta_template

diff --git a/t/porting/podcheck.t b/t/porting/podcheck.t
index a3a4451..f0a4069 100644 (file)
--- a/t/porting/podcheck.t
+++ b/t/porting/podcheck.t
@@ -36,8 +36,8 @@ podcheck.t - Look for possible problems in the Perl pods
 
 podcheck.t is an extension of Pod::Checker.  It looks for pod errors and
 potential errors in the files given as arguments, or if none specified, in all
-pods in the distribution workspace, except those in the cpan directory (unless
-C<--cpan> is specified).  It does additional checking beyond that done by
+pods in the distribution workspace, except certain known special ones
+(specified below).  It does additional checking beyond that done by
 Pod::Checker, and keeps a database of known potential problems, and will
 fail a pod only if the number of such problems differs from that given in the
 database.  It also suppresses the C<(section) deprecated> message from
@@ -105,7 +105,8 @@ C<FE<lt>...E<gt>> mark-up instead.
 =back
 
 A number of issues raised by podcheck.t and by the base Pod::Checker are not
-really problems, but merely potential problems.  After inspecting them and
+really problems, but merely potential problems, that is, false positives.
+After inspecting them and
 deciding that they aren't real problems, it is possible to shut up this program
 about them, unlike base Pod::Checker.  To do this, call podcheck.t with the
 C<--regen> option to regenerate the database.  This tells it that all existing
@@ -123,9 +124,50 @@ Also, if the count of potential problems of a given type for a pod decreases,
 the database must be regenerated so that it knows the new number.  The program
 gives instructions when this happens.
 
+Some pods will have varying numbers of problems of a given type.  This can
+be handled by manually editing the database file (see L</FILES>), and setting
+the number of those problems for that pod to a negative number.  This will
+cause the corresponding error to always be suppressed no matter how many there
+actually are.
+
 There is currently no check that modules listed as valid in the data base
 actually are.  Thus any errors introduced there will remain there.
 
+=head2 Specially handled pods
+
+=over
+
+=item perltoc
+
+This pod is generated by pasting bits from other pods.  Errors in those bits
+will show up as errors here, as well as for those other pods.  Therefore
+errors here are suppressed, and the pod is checked only to verify that nodes
+within it that are externally linked to actually exist.
+
+=item perldelta
+
+The current perldelta pod is initialized from a template that contains
+placeholder text.  Some of this text is in the form of links that don't really
+exist.  Any such links that are listed in C<@perldelta_ignore_links> will not
+generate messages.  It is presumed that these links will be cleaned up when
+the perldelta is cleaned up for release since they should be marked with
+C<XXX>.
+
+=item Porting/perldelta_template.pod
+
+This is not a pod, but a template for C<perldelta>.  Any errors introduced
+here will show up when C<perldelta> is created from it.
+
+=item cpan-upstream pods
+
+See the L</--cpan> option documentation
+
+=item old perldeltas
+
+See the L</--deltas> option documentation
+
+=back
+
 =head1 OPTIONS
 
 =over
@@ -160,14 +202,15 @@ these.
 
 Normally, all pods in the cpan directory are skipped, except to make sure that
 any blead-upstream links to such pods are valid.
-This option will cause cpan upstream pods to be checked.
+This option will cause cpan upstream pods to be fully checked.
 
 =item --deltas
 
 Normally, all old perldelta pods are skipped, except to make sure that
 any links to such pods are valid.  This is because they are considered
 stable, and perhaps trying to fix them will cause changes that will
-misrepresent Perl's history.  But, this option will cause them to be checked.
+misrepresent Perl's history.  But, this option will cause them to be fully
+checked.
 
 =item --show_all
 
@@ -1011,6 +1054,7 @@ if ($show_counts) {
 }
 
 
+# Not really pods, but can look like them.
 my %excluded_files = (
                         "lib/unicore/mktables" => 1,
                         "Porting/perldelta_template.pod" => 1,
@@ -1653,7 +1697,7 @@ if (%files_with_unknown_issues) {
 HOW TO GET THIS .t TO PASS
 
 There $were_count_files that had new potential problems identified.
-Some of them may be real, and some of them may be false positives, because
+Some of them may be real, and some of them may be false positives because
 this program isn't as smart as it likes to think it is.  You can teach this
 program to ignore the issues it has identified, and hence pass, by doing the
 following: