NAME
podlinkcheck -- check Perl pod L<> link references
SYNOPSIS
podlinkcheck [--options] file-or-dir...DESCRIPTION
PodLinkCheck parses Perl POD from a script, module or documentation file and checks that L<foo> links within it refer to a known program, module, or man page.
The command line is either individual files or whole directories. For a directory all the .pl, .pm and .pod files under it are checked. For example to churn through all installed add-on modules,
podlinkcheck /usr/share/perl5The usual things detected are typos in the target page or section name, and sometimes L<text|name> parts the wrong way around. Occasionally there may be an L<foo> used where say I<> or C<> was intended too.
Checks
External links are checked by seeking the target .pm module or .pod documentation in the @INC path (per Pod::Find), or seeking a script (no file extension) in the usual executable PATH. The target section is checked by parsing the POD from that file.
Module existence is also checked in the CPAN::SQLite, CPAN or CPANPLUS indexes. They're not re-downloaded, just current data consulted. This covers cross-references to things not currently installed. A warning is given if a target section name goes unchecked because it's only on cpan, not available locally.
Manpage links are checked by asking the man program if it recognises the name, including any number part like chmod(2). A manpage can also satisfy what otherwise appears to be a POD link (with no sub-section), since there's often a bit of confusion between the two.
One-Word Links
Internal links have been written as say L<SYNOPSIS> but the current perlpodspec advice is to avoid ambiguity between a module and a section by writing a section with / or quotes,
See L</SYNOPSIS> above.
See L<"SYNOPSIS"> above.A warning is given for an apparent section link written like this, but not if there's an external module etc of the given name because it's not uncommon to have a module name as a heading or item, but the L<> link still meaning external.
OTHER WAYS TO DO IT
podchecker (the Pod::Checker module) checks internal links (along with POD markup syntax), but it doesn't check external links.
BUGS
The line:column number reported is sometimes a bit off due to limited information recorded by Pod::Simple during its parse.
Man pages are checked with man --location, which is not a POSIX standard option and might require a reasonably new "man" or might even be "man-db" specific.
CPAN::SQLite is checked first because it's fast and compact, but if a target is not found there then the CPAN and CPANPLUS caches are both loaded. This allows for whichever of the three is up-to-date, but can use up a lot of memory for a non-existent target.
The current code consulting the CPAN.pm index might need a tolerably new version of that module, maybe 1.61 circa Perl 5.8.0. On earlier versions the index will not be used.
ENVIRONMENT VARIABLES
PATH-
Search path for scripts.
SEE ALSO
Pod::Simple, Pod::Find, Pod::Checker, CPANPLUS, CPAN
HOME PAGE
http://user42.tuxfamily.org/podlinkcheck/index.html
LICENSE
Copyright 2010 Kevin Ryde
PodLinkCheck is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.
PodLinkCheck is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with PodLinkCheck. If not, see <http://www.gnu.org/licenses/>.