#!perl -w
# Copyright 2010, 2011, 2012, 2013, 2016, 2017 Kevin Ryde
# This file is part of PodLinkCheck.
# 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/>.
use 5.006;
use strict;
use warnings;
use App::PodLinkCheck;
use vars '$VERSION';
$VERSION = 15;
my $plc = App::PodLinkCheck->new;
exit $plc->command_line;
__END__
=for stopwords podlinkcheck Ryde subdirs cpan Manpage manpage whitespace eg mis-interpreted SQLite bsearch lookups recognises
=head1 NAME
podlinkcheck -- check Perl pod LE<lt>E<gt> link references
=head1 SYNOPSIS
podlinkcheck [--options] file-or-dir...
=head1 OPTIONS
The command line options are
=over 4
=item --help
Print a command line summary.
=item -I dir
Add an extra directory to look for target modules.
=item --verbose
Print more about program operation (including CPAN loading).
=item --version
Print the program version number and exit.
=back
=head1 DESCRIPTION
PodLinkCheck parses Perl POD from a script, module or documentation and
checks that C<LE<lt>E<gt>> links within it refer to a known program, module,
or man page.
=for ProhibitVerbatimMarkup allow next
L<foo> check module, pod or program "foo"
L<foo/section> and check section within the pod
L<bar(1)> check man page "bar(1)"
The command line is either individual files or whole directories. For a
directory all the F<.pl>, F<.pm> and F<.pod> files under it are checked. So
for example to churn through all installed add-on modules,
podlinkcheck /usr/share/perl5
Bad links are usually typos in the module name or section name, or sometimes
C<LE<lt>display|targetE<gt>> parts the wrong way around. Occasionally there
may be an C<LE<lt>fooE<gt>> used where just markup C<CE<lt>E<gt>> or
C<IE<lt>E<gt>> was intended.
=head2 Checks
External links are checked by seeking the target F<.pm> module or F<.pod>
documentation in the C<@INC> path (per L<Pod::Find>), or seeking a script
(no file extension) in the usual executable C<PATH>. A section name in a
link is checked by parsing the POD in the target file.
If a module is not installed in C<@INC> or extra C<-I> directories then its
existence is also checked in the CPAN indexes with C<App::cpanminus>,
C<CPAN::SQLite>, C<CPAN> or C<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 C<man> program if it recognises the
name, including any number part like C<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.
=head2 Internal Links
Internal links are sometimes written
L<SYNOPSIS> # may be ambiguous
but the Perl 5.10 C<perlpodspec> advice is to avoid ambiguity between an
external module and a one-word internal section by writing a section with /
or quotes,
=for ProhibitVerbatimMarkup allow next 2
See L</SYNOPSIS> above. # good
See L<"SYNOPSIS"> above. # good
C<podlinkcheck> warns about C<LE<lt>SYNOPSISE<gt>> 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
C<LE<lt>E<gt>> link still meaning the external one.
=head2 Section Name Matching
An C<LE<lt>E<gt>> section name can use just the first word of an item or
heading. This is how C<Pod::Checker> behaves and it's good for C<perlfunc>
cross references where just the function name can be given without the full
argument list of the C<=item>. Eg.
=for ProhibitVerbatimMarkup allow next
L<perlfunc/split>
The first word is everything up to the first whitespace. This doesn't come
out very well on a target like C<=item somefun( ARG )>, but it's how
C<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
C<LE<lt>E<gt>>.
If a target section is not found then C<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 C<LE<lt>E<gt>> 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 C<=item> section names go in an C<LE<lt>E<gt>>
without the number. This is good since the numbering might change. If
C<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
C<=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
C<podlinkcheck> uses C<Pod::Simple> for parsing and so follows its
interpretation of the various hairy C<LE<lt>E<gt>> link forms. If an
C<LE<lt>E<gt>> appears to be mis-interpreted you might rewrite or add some
escapes (like EE<lt>solE<gt>) for the benefit of all translators which use
C<Pod::Simple>. In Perl 5.10 that includes the basic C<pod2man>.
=head2 Other Ways to Do It
C<podchecker> (the C<Pod::Checker> module) checks internal links, but it
doesn't check external links.
C<Test::Pod::LinkCheck> is similar in a F<.t> test framework. It uses some
of PodLinkCheck but different reporting and a stricter approach to dubious
POD.
=head1 EXIT STATUS
Exit is 0 for no problems found, or non-zero for problems.
=head1 ENVIRONMENT VARIABLES
=over 4
=item C<PATH>
The search path for installed scripts.
=item C<HOME>
Used by the various C<CPAN> modules for C<~/.cpan> etc directories.
=item C<PERL5LIB>
The usual extra Perl module directories (see L<perlrun/ENVIRONMENT>), which
become C<@INC> where link targets are sought.
=back
=head1 BUGS
C<App::cpanminus> is checked first since it's a bsearch of
F<02packages.details.txt>, and C<CPAN::SQLite> second since it's a database
lookup. But if a target is not found there then the full C<CPAN> and
C<CPANPLUS> caches are loaded and checked. This might use a fair bit of
memory for a non-existent target, but it's also possible they're more
up-to-date.
No attempt is made to tell which of the indexes is the most up-to-date. If
a module has been renamed (bad) then it may still exist in an old index.
The suggestion is to avoid having old stuff lying around (including old
mirror files in C<App::cpanminus>).
The code consulting C<CPAN.pm> may need a tolerably new version of that
module, maybe 1.61 circa Perl 5.8.0. On earlier versions its index is not
used.
The line:column number reported for an offending C<LE<lt>E<gt>> is found by
some gambits extending what C<Pod::Simple> normally records. There's a
chance it could be a little off within the paragraph.
C<Pod::Simple> prior to version 3.24 didn't allow dots "." in man-page
names, resulting in for example L<login.conf(5)> being treated as a Perl
module name not a man page name. If you have such links then use
C<Pod::Simple> 3.24 up.
Directories are currently traversed using L<File::Find::Iterator>. It
follows symlinks but neither its version 0.4 nor PodLinkCheck guard against
infinite descent into symlink cycles. The intention perhaps would be follow
all symlinks to files, but follow to a directory just once as protection
against cycles.
=head1 FILES
F<~/.cpanm/sources/*/02packages.details.txt> files from C<App::cpanminus>
F<~/.cpan/cpandb.sql> used by C<CPAN::SQLite>
F<~/.cpan/Metadata> used by C<CPAN>
F<~/.cpanplus/*> variously used by C<CPANPLUS>
=head1 SEE ALSO
L<podchecker>, L<podlint>
L<Pod::Simple>, L<Pod::Find>, L<CPAN>, L<CPAN::SQLite>,
L<CPANPLUS>, L<cpanm>
L<Test::Pod::LinkCheck>, L<Pod::Checker>, L<Test::Pod>
=head1 HOME PAGE
http://user42.tuxfamily.org/podlinkcheck/index.html
=head1 LICENSE
Copyright 2010, 2011, 2012, 2013, 2016, 2017 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/>.
=cut