In perl.git, the branch blead has been updated
<http://perl5.git.perl.org/perl.git/commitdiff/ef4474b5b7af564ed5f0979a4019b7fb79bb0233?hp=15e86abf063edd54ddbaa668e527d496dbebfe70>
- Log -----------------------------------------------------------------
commit ef4474b5b7af564ed5f0979a4019b7fb79bb0233
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Wed Jul 27 11:26:17 2011 -0600
release managers guide: perldelta broken link handling
podcheck.t contains a list of placeholder links in perldelta that don't
point to a real target, and hence shouldn't generate messages. This
list is to make the release manager's job easier. But if new
placeholder links are created, it may be that they have to be added to
the list.
M Porting/release_managers_guide.pod
commit bc20e6b8a4c898602b2a6d438e089d520615b45e
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Wed Jul 27 11:10:35 2011 -0600
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
M t/porting/podcheck.t
commit 2feebde01af6b8c3009e87995f143f59ec8aa642
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Wed Jul 27 09:54:04 2011 -0600
podcheck.t: Don't warn on perldelta placeholder link
perldelta has a placeholder link that doesn't point to a real node,
"perldiag/message". This link should be cleaned up as part of making a
release by looking for all the XXX lines that remain. Add this link to
the list of those that should be skipped when looking for broken links
in perldelta.
M t/porting/known_pod_issues.dat
M t/porting/podcheck.t
commit 02987562b510cee72ea618cdfe2941f92d1af964
Author: Karl Williamson <pub...@khwilliamson.com>
Date: Wed Jul 27 09:34:28 2011 -0600
podcheck.t: Move perldelta placeholder link checks
podcheck has the capability to ignore certain broken links in
perldelta.pod. This is because this pod is special, initialized to a
template with various placeholder text including links that are to
eventually be changed to their correct values. One of the final steps
in making a release is to clean it up, removing any of these links that
haven't been changed, and hence don't apply to the current release.
To lessen the number of steps in making a release, a list of these links is
hard-coded into podcheck, and it doesn't warn on those. The check to
skip these links prior to this commit did not easily allow links of the
form page/node to be checked for.
M t/porting/podcheck.t
-----------------------------------------------------------------------
Summary of changes:
Porting/release_managers_guide.pod | 25 +++++++++-
t/porting/known_pod_issues.dat | 1 -
t/porting/podcheck.t | 84 ++++++++++++++++++++++++++++++------
3 files changed, 92 insertions(+), 18 deletions(-)
diff --git a/Porting/release_managers_guide.pod
b/Porting/release_managers_guide.pod
index 935394b..3e72e18 100644
--- a/Porting/release_managers_guide.pod
+++ b/Porting/release_managers_guide.pod
@@ -940,9 +940,28 @@ Run a clean build and test to make sure nothing obvious is
broken.
In particular, F<Porting/perldelta_template.pod> is intentionally exempted
from podchecker tests, to avoid false positives about placeholder text.
However, once it's copied to F<pod/perldelta.pod> the contents can now
-cause test failures. Problems should resolved either by replacing placeholder
-text with correct text, or following the instructions output by
-F<t/porting/podcheck.t> on how to update its exceptions database.
+cause test failures. Problems should resolved by doing one of the
+following:
+
+=over
+
+=item 1
+
+Replace placeholder text with correct text.
+
+=item 2
+
+If the problem is from a broken placeholder link, you can add it to the
+array C<@perldelta_ignore_links> in F<t/porting/podcheck.t>. Lines
+containing such links should be marked with C<XXX> so that they get
+cleaned up before the next release.
+
+=item 3
+
+Following the instructions output by F<t/porting/podcheck.t> on how to
+update its exceptions database.
+
+=back
=head3 push commits
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 4a85c2d..6d58627 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -225,7 +225,6 @@ pod/perldbmfilter.pod Verbatim line length including
indents exceeds 80 by 1
pod/perldebguts.pod Verbatim line length including indents exceeds 80 by
68
pod/perldebtut.pod Verbatim line length including indents exceeds 80 by
22
pod/perldebug.pod Verbatim line length including indents exceeds 80 by
3
-pod/perldelta.pod Apparent broken link 2
pod/perldiag.pod =item type mismatch 1
pod/perldiag.pod Verbatim line length including indents exceeds 80 by
2
pod/perldsc.pod Verbatim line length including indents exceeds 80 by
4
diff --git a/t/porting/podcheck.t b/t/porting/podcheck.t
index 873e810..f0a4069 100644
--- 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
@@ -225,7 +268,7 @@ L<Pod::Checker>
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.
@@ -826,10 +869,24 @@ package My::Pod::Checker { # Extend Pod::Checker
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]);
}
@@ -997,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,
@@ -1519,9 +1577,7 @@ if (! $has_input_files) {
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;
}
@@ -1641,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:
--
Perl5 Master Repository
