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
my $Warnings_Level = 200;
# perldelta during construction may have place holder links.
-our @perldelta_ignore_links = ( "XXX", "perl5YYYdelta" );
+our @perldelta_ignore_links = ( "XXX", "perl5YYYdelta", "perldiag/message" );
# To see if two pods with the same NAME are actually copies of the same pod,
# which is not an error, it uses a checksum to save work.
my $copy_fh;
my $MAX_LINE_LENGTH = 80; # 80 columns
-my $INDENT = 8; # default nroff indent
+my $INDENT = 7; # default nroff indent
# Our warning messages. Better not have [('"] in them, as those are used as
# delimiters for variable parts of the messages by poderror.
| old # buildtoc output
)
$
- ) | ~$ # Another editor dropping
+ ) | ~$ | \ \(Autosaved\)\.txt$ # Other editor droppings
/x;
sub hyperlink {
my $self = shift;
- # If the hyperlink is to an interior node of another page, save it
- # so that we can see if we need to parse normally skipped files.
- $has_referred_to_node{$_[0][1]{'-page'}} = 1
- if $_[0] && $_[0][1]{'-page'} && $_[0][1]{'-node'};
+ my $page;
+ if ($_[0] && ($page = $_[0][1]{'-page'})) {
+ my $node = $_[0][1]{'-node'};
+
+ # If the hyperlink is to an interior node of another page, save it
+ # so that we can see if we need to parse normally skipped files.
+ $has_referred_to_node{$page} = 1 if $node;
+
+ # Ignore certain placeholder links in perldelta. Check if the
+ # link is page-level, and also check if to a node within the page
+ if ($self->name && $self->name eq "perldelta"
+ && ((grep { $page eq $_ } @perldelta_ignore_links)
+ || ($node
+ && (grep { "$page/$node" eq $_ } @perldelta_ignore_links)
+ ))) {
+ return;
+ }
+ }
return $self->SUPER::hyperlink($_[0]);
}
}
+# Not really pods, but can look like them.
my %excluded_files = (
"lib/unicore/mktables" => 1,
"Porting/perldelta_template.pod" => 1,
if (! defined $NAME) {
$checker->poderror(\%problem);
}
- elsif ($NAME ne "perldelta"
- || ! grep { $linked_to_page eq $_ } @perldelta_ignore_links)
- {
+ else {
if ($nodes{$NAME}{$linked_to_page}) {
$problem{-msg} = $broken_internal_link;
}
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 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
+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:
1) If a problem is about a link to an unknown module or man page that
ones you decided to, and rerun this test to verify that the fixes
worked.
-3) If there remain potential problems that you don't plan to fix right
- now (or aren't really problems),
+3) If there remain false positive or problems that you don't plan to fix right
+ now,
$how_to
That should cause all current potential problems to be accepted by
the program, so that the next time it runs, they won't be flagged.