On 04/29/2011 04:14 AM, Michael Stevens wrote:
On Thu, Apr 28, 2011 at 07:12:49PM -0400, Ricardo Signes wrote:
* Michael Stevensmstev...@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 CLEltEgt 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 CLElt...Egt
=item Items that perhaps should be CFElt...Egt
What look like path names enclosed in CCElt...Egt should perhaps have
CFElt...Egt 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
