podlinkcheck - Man Page

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.

If a module is not installed in @INC or extra -I directories then its existence is also checked in the CPAN indexes with App::cpanminus, CPAN::SQLite, CPAN or CPANPLUS.  Nothing is downloaded, just current data consulted.  A warning is given if a section name in a link goes unchecked because it's on CPAN but not available locally.

If checking your own work then most likely you will have copies of cross-referenced modules installed (having compared or tried them).  In that sense the CPAN index lookups are a fallback.

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 some confusion between the two.

Internal links are sometimes written

    L<SYNOPSIS>                     # may be ambiguous

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

    See L<"SYNOPSIS"> above.        # good

podlinkcheck warns about L<Synopsis> section links.  But not if it's both an valid external module and internal section -- because it's not uncommon to have a module name as a heading or item and an L<> link still meaning the external one.

An L<> section name can use just the first word of an item or heading.  This is how Pod::Checker behaves and it's 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 anyway, 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 good 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 next paragraph.

    =item 1.                        # good

    The First Thing                 # the 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 a numbered item for POD purposes, 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 rewrite or add some escapes (like E<sol>) for the benefit of all translators which use Pod::Simple.  In Perl 5.10 that includes the basic pod2man.

podchecker (the Pod::Checker module) checks internal links, but it doesn't check external links.

Test::Pod::LinkCheck is similar in a .t test framework.  It uses some of PodLinkCheck but different reporting and a stricter approach to dubious POD.