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
=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
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
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
}
+# Not really pods, but can look like them.
my %excluded_files = (
"lib/unicore/mktables" => 1,
"Porting/perldelta_template.pod" => 1,
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: