The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
podlinkcheck-8
River stage two • 2 direct dependents • 25 total dependents
/ podlinkcheck

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 and checks that L<> links within it refer to a known program, module, or man page.

    L<foo>       <-- check "foo" exists

The command line is either individual files or whole directories. For a directory all the .pl, .pm and .pod files under it are checked. So for example to churn through all installed add-on modules,

    podlinkcheck /usr/share/perl5

The bad links usually detected are typos in the target page or section name, and sometimes L<text|target> parts the wrong way around. Occasionally there may be an L<foo> used where just markup I<> or C<> was intended.

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. A section name in a link is checked by parsing the POD in the target file.

Module existence is also checked in the CPAN indexes with CPAN::SQLite, CPAN or CPANPLUS. Nothing is downloaded, just current data consulted. This covers cross-references to things not currently installed. A warning is given if a section name in a link 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.

Internal links are sometimes written L<SYNOPSIS> etc but the Perl 5.10 perlpodspec advice is to avoid ambiguity between an external module and a one-word internal section by writing a section with / or quotes,

    See L</SYNOPSIS> above.

    See L<"SYNOPSIS"> above.

podlinkcheck warns about a 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).

Section Name Matching

An L<> section name can use just the first word of an item or heading. This is how Pod::Checker behaves and it's particularly good for perlfunc cross references where just the function name can be given without the full argument list of the =item. Eg.

    L<perlfunc/split>

The first word is everything up to the first whitespace. This doesn't come out very well on a target like =item somefun( ARG ), but it's how Pod::Checker 1.45 behaves. If the targets are your own then you might make the first word or full item something sensible to appear in an L<>.

If a target section is not found then podlinkcheck will try to suggest something close, eg. differing only in punctuation or upper/lower case. Some of the POD translators may ignore upper/lower case, but it's good to write an L<> the same as the actual target.

    foo.pl:130:31: no section "constructor" in "CHI"
      (file /usr/share/perl5/CHI.pm)
      perhaps it should be "CONSTRUCTOR"

For reference, numbered =item section names go in an L<> without the number. This is a good thing since the numbering might change. If podlinkcheck suggests a number in a target then it may be a mistake in the target document. A numbered item should have the number alone on the =item and the section name as the following paragraph.

    =item 1.                        <-- good

    The First Thing                 <-- section name

    Paragraph about this thing.

    =item 2. The Second Thing       <-- bad

    Paragraph about this next thing.

The second item "2. The Second Thing" is not numbered, but rather text that happens to start with a number. Of course sometimes that's what you want, eg.

    =item 64 Bit Support

podlinkcheck uses Pod::Simple for parsing and so follows its interpretation of the various hairy L<> link forms. If an L<> appears to be mis-interpreted you might want to rewrite it (perhaps with escapes like E<sol>) for the benefit of all translators which use Pod::Simple, and which in Perl 5.10 includes the basic pod2man.

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 for an offending L<> is sometimes a bit off due to limited information recorded by Pod::Simple during its parse.

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 and checked. This may use a lot of memory for a non-existent target, but it's possible they're more up-to-date and the SQLite.

Currently the code consulting CPAN.pm may need a tolerably new version of that module, maybe 1.61 circa Perl 5.8.0. On earlier versions the index is not used.

ENVIRONMENT VARIABLES

PATH

Search path for installed scripts.

HOME

Used by the various CPAN modules for the ~/.cpan directory.

PERL5LIB

The usual extra Perl module directories (see "ENVIRONMENT" in perlrun), which is also where link targets are sought.

SEE ALSO

podchecker, podlint

Pod::Simple, Pod::Find, Pod::Checker, CPAN, CPAN::SQLite, CPANPLUS

HOME PAGE

http://user42.tuxfamily.org/podlinkcheck/index.html

LICENSE

Copyright 2010, 2011 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/>.