On 04/29/2011 04:14 AM, Michael Stevens wrote:
On Thu, Apr 28, 2011 at 07:12:49PM -0400, Ricardo Signes wrote:
* Michael Stevens<mstev...@etla.org> [2011-04-28T17:03:36]
Has it got a victim^Wvolunteer?
Yup. Marc Green (the student) and David Wheeler and I will have our first
meeting to kick things off in a few days. From there on, a state of constant
progress!
From my experiments in the area I predict the problem will be getting
people interested and willing to accept or reject patches.
Michael
FWIW, one of the reasons I've brought up a bunch of stuff concerning
this lately, is that I'm about to add to the Perl 5.15 core a revision
of podcheck.t which extends Pod::Checker. I had wondered if I should
add checking for the deprecated constructs, but now I'll let
Pod::Checker do so.
People on this list might be interested in the extensions to
Pod::Checker, some of which might be considered for pulling back into
Pod::Checker. Attached is the current pod for podcheck.t
=pod
=head1 NAME
podcheck.t - Look for possible problems in the Perl pods
=head1 SYNOPSIS
cd t
./perl -I../lib porting/podcheck.t [--show_all] [--cpan] [--counts]
[ FILE ...]
./perl -I../lib porting/podcheck.t --regen
=head1 DESCRIPTION
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
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
Pod::Checker, since specifying the man page section number is quite proper to
do.
The additional checks it makes are:
=over
=item Cross-pod link checking
Pod::Checker verifies that links to an internal target in a pod are not
broken. podcheck.t extends that (when called without FILE arguments) to
external links. It does this by gathering up all the possible targets in the
workspace, and cross-checking them. The database has a list of known targets
outside the workspace, so podcheck.t will not raise a warning for
using those. It also checks that a non-broken link points to just one target.
(The destination pod could have two targets with the same name.)
=item An internal link that isn't so specified
If a link is broken, but there is an existing internal target of the same
name, it is likely that the internal target was meant, and the C<"/"> is
missing from the C<LE<lt>E<gt>> pod command.
=item Verbatim paragraphs that wrap in an 80 column window
It's annoying to have lines wrap when displaying pod documentation in a
terminal window. This checks that all such lines fit, and for those that
don't, it tells you how much needs to be cut in order to fit. However,
if you're fixing these, keep in mind that some terminal/pager combinations
require really a maximum of 79 or 78 columns to display properly.
Often, the easiest thing to do to gain space for these is to lower the indent
to just one space.
=item Missing or duplicate NAME or missing NAME short description
A pod can't be linked to unless it has a unique name.
And a NAME should have a dash and short description after it.
=item =encoding statement issues
This indicates if an C<=encoding> statement should be present, or moved to the
front of the pod.
=item Items that perhaps should be links
There are mentions of apparent files in the pods that perhaps should be links
instead, using C<LE<lt>...E<gt>>
=item Items that perhaps should be C<FE<lt>...E<gt>>
What look like path names enclosed in C<CE<lt>...E<gt>> should perhaps have
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
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
issues are to not be mentioned again.
This isn't fool-proof. The database merely keeps track of the number of these
potential problems of each type for each pod. If a new problem of a given
type is introduced into the pod, podcheck.t will spit out all of them. You
then have to figure out which is the new one, and should it be changed or not.
But doing it this way insulates the database from having to keep track of line
numbers of problems, which may change, or the exact wording of each problem
which might also change without affecting whether it is a problem or not.
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.
=head1 OPTIONS
=over
=item --regen
Regenerate the data base used by podcheck.t to include all the existing
potential problems. Future runs of the program will not then flag any of
these.
=item --cpan
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.
=item --show_all
Normally, if the number of potential problems of a given type found for a
pod matches the expected value in the database, they will not be displayed.
This option forces the database to be ignored during the run, so all potential
problems are displayed and will fail their respective pod test. Specifying
any particular FILES to operate on automatically selects this option.
=item --counts
Instead of testing, this just dumps the counts of the occurrences of the
various types of potential problems in the data base.
=back
=head1 FILES
The database is stored in F<t/porting/known_pod_issues.dat>
=head1 SEE ALSO
L<Pod::Checker>
=cut
