NAME

podcheck.t - Look for possible problems in the Perl pods

SYNOPSIS

cd t
./perl -I../lib porting/podcheck.t [--show_all] [--cpan] [--deltas]
                                   [--counts] [--pedantic] [FILE ...]

./perl -I../lib porting/podcheck.t --add_link MODULE ...

./perl -I../lib porting/podcheck.t --regen

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 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 (section) deprecated message from Pod::Checker, since specifying the man page section number is quite proper to do.

The additional checks it always makes are:

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. It also checks that a non-broken link points to just one target. (The destination pod could have two targets with the same name.)

The way that the L<> pod command works (for links outside the pod) is to actually create a link to search.cpan.org with an embedded query for the desired pod or man page. That means that links outside the distribution are valid. podcheck.t doesn't verify the validity of such links, but instead keeps a database of those known to be valid. This means that if a link to a target not on the list is created, the target needs to be added to the data base. This is accomplished via the --add_link option to podcheck.t, described below.

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 "/" is missing from the L<> pod command.

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.

=encoding statement issues

This indicates if an =encoding statement should be present, or moved to the front of the pod.

If the PERL_POD_PEDANTIC environment variable is set or the --pedantic command line argument is provided then a few more checks are made. The pedantic checks are:

Verbatim paragraphs that wrap in an 80 (including 1 spare) column window

It's annoying to have lines wrap when displaying pod documentation in a terminal window. This checks that all verbatim lines fit in a standard 80 column window, even when using a pager that reserves a column for its own use. (Thus the check is for a net of 79 columns.) For those lines that don't fit, it tells you how much needs to be cut in order to fit.

Often, the easiest thing to do to gain space for these is to lower the indent to just one space.

Items that perhaps should be links

There are mentions of apparent files in the pods that perhaps should be links instead, using L<...>

Items that perhaps should be F<...>

What look like path names enclosed in C<...> should perhaps have F<...> mark-up instead.

A number of issues raised by podcheck.t and by the base Pod::Checker are not 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. For a valid link to an outside module or man page, call podcheck.t with the --add_link option to add it to the the database of known links; for other causes, call podcheck.t with the --regen option to regenerate the entire database. This tells it that all existing issues are to not be mentioned again.

--regen 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.

Some pods will have varying numbers of problems of a given type. This can be handled by manually editing the database file (see "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.

Another problem is that there is currently no check that modules listed as valid in the database actually are. Thus any errors introduced there will remain there.

Specially handled pods

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 actually exist that are externally linked to.

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 @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 XXX.

Porting/perldelta_template.pod

This is not a pod, but a template for perldelta. Any errors introduced here will show up when perldelta is created from it.

cpan-upstream pods

See the "--cpan" option documentation

old perldeltas

See the "--deltas" option documentation

OPTIONS

--add_link MODULE ...

Use this option to teach podcheck.t that the MODULEs or man pages actually exist, and to silence any messages that links to them are broken.

podcheck.t checks that links within the Perl core distribution are valid, but it doesn't check links to man pages or external modules. When it finds a broken link, it checks its database of external modules and man pages, and only if not found there does it raise a message. This option just adds the list of modules and man page references that follow it on the command line to that database.

For example,

cd t
./perl -I../lib porting/podcheck.t --add_link Unicode::Casing

causes the external module "Unicode::Casing" to be added to the database, so L<Unicode::Casing> will be considered valid.

--regen

Regenerate the database used by podcheck.t to include all the existing potential problems. Future runs of the program will not then flag any of these. Setting this option also sets --pedantic.

--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 fully checked.

--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 fully checked.

--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.

--counts

Instead of testing, this just dumps the counts of the occurrences of the various types of potential problems in the database.

--pedantic

There are three potential problems that are not checked for by default. This options enables them. The environment variable PERL_POD_PEDANTIC can be set to 1 to enable this option also. This option is set when --regen is used.

FILES

The database is stored in t/porting/known_pod_issues.dat

SEE ALSO

Pod::Checker