1PODLINKCHECK(1)       User Contributed Perl Documentation      PODLINKCHECK(1)
2
3
4

NAME

6       podlinkcheck -- check Perl pod L<> link references
7

SYNOPSIS

9        podlinkcheck [--options] file-or-dir...
10

OPTIONS

12       The command line options are
13
14       --help
15           Print a command line summary.
16
17       -I dir
18           Add an extra directory to look for target modules.
19
20       --verbose
21           Print more about program operation (including CPAN loading).
22
23       --version
24           Print the program version number and exit.
25

DESCRIPTION

27       PodLinkCheck parses Perl POD from a script, module or documentation and
28       checks that "L<>" links within it refer to a known program, module, or
29       man page.
30
31           L<foo>          check module, pod or program "foo"
32           L<foo/section>    and check section within the pod
33           L<bar(1)>       check man page "bar(1)"
34
35       The command line is either individual files or whole directories.  For
36       a directory all the .pl, .pm and .pod files under it are checked.  So
37       for example to churn through all installed add-on modules,
38
39           podlinkcheck /usr/share/perl5
40
41       Bad links are usually typos in the module name or section name, or
42       sometimes "L<display|target>" parts the wrong way around.  Occasionally
43       there may be an "L<foo>" used where just markup "C<>" or "I<>" was
44       intended.
45
46   Checks
47       External links are checked by seeking the target .pm module or .pod
48       documentation in the @INC path (per Pod::Find), or seeking a script (no
49       file extension) in the usual executable "PATH".  A section name in a
50       link is checked by parsing the POD in the target file.
51
52       If a module is not installed in @INC or extra "-I" directories then its
53       existence is also checked in the CPAN indexes with "App::cpanminus",
54       "CPAN::SQLite", "CPAN" or "CPANPLUS".  Nothing is downloaded, just
55       current data consulted.  A warning is given if a section name in a link
56       goes unchecked because it's on CPAN but not available locally.
57
58       If checking your own work then most likely you will have copies of
59       cross-referenced modules installed (having compared or tried them).  In
60       that sense the CPAN index lookups are a fallback.
61
62       Manpage links are checked by asking the "man" program if it recognises
63       the name, including any number part like chmod(2).  A manpage can also
64       satisfy what otherwise appears to be a POD link with no sub-section,
65       since there's often some confusion between the two.
66
67   Internal Links
68       Internal links are sometimes written
69
70           L<SYNOPSIS>                     # may be ambiguous
71
72       but the Perl 5.10 "perlpodspec" advice is to avoid ambiguity between an
73       external module and a one-word internal section by writing a section
74       with / or quotes,
75
76           See L</SYNOPSIS> above.         # good
77
78           See L<"SYNOPSIS"> above.        # good
79
80       "podlinkcheck" warns about "L<SYNOPSIS>" section links.  But not if
81       it's both an valid external module and internal section -- because it's
82       not uncommon to have a module name as a heading or item and an "L<>"
83       link still meaning the external one.
84
85   Section Name Matching
86       An "L<>" section name can use just the first word of an item or
87       heading.  This is how "Pod::Checker" behaves and it's good for
88       "perlfunc" cross references where just the function name can be given
89       without the full argument list of the "=item".  Eg.
90
91           L<perlfunc/split>
92
93       The first word is everything up to the first whitespace.  This doesn't
94       come out very well on a target like "=item somefun( ARG )", but it's
95       how "Pod::Checker" 1.45 behaves.  If the targets are your own then you
96       might make the first word or full item something sensible to appear in
97       an "L<>".
98
99       If a target section is not found then "podlinkcheck" will try to
100       suggest something close, eg. differing only in punctuation or
101       upper/lower case.  Some of the POD translators may ignore upper/lower
102       case anyway, but it's good to write an "L<>" the same as the actual
103       target.
104
105           foo.pl:130:31: no section "constructor" in "CHI"
106             (file /usr/share/perl5/CHI.pm)
107             perhaps it should be "CONSTRUCTOR"
108
109       For reference, numbered "=item" section names go in an "L<>" without
110       the number.  This is good since the numbering might change.  If
111       "podlinkcheck" suggests a number in a target then it may be a mistake
112       in the target document.  A numbered item should have the number alone
113       on the "=item" and the section name as the next paragraph.
114
115           =item 1.                        # good
116
117           The First Thing                 # the section name
118
119           Paragraph about this thing.
120
121           =item 2. The Second Thing       # bad
122
123           Paragraph about this next thing.
124
125       The second item "2. The Second Thing" is not a numbered item for POD
126       purposes, but rather text that happens to start with a number.  Of
127       course sometimes that's what you want, eg.
128
129           =item 64 Bit Support
130
131       "podlinkcheck" uses "Pod::Simple" for parsing and so follows its
132       interpretation of the various hairy "L<>" link forms.  If an "L<>"
133       appears to be mis-interpreted you might rewrite or add some escapes
134       (like E<sol>) for the benefit of all translators which use
135       "Pod::Simple".  In Perl 5.10 that includes the basic "pod2man".
136
137   Other Ways to Do It
138       "podchecker" (the "Pod::Checker" module) checks internal links, but it
139       doesn't check external links.
140
141       "Test::Pod::LinkCheck" is similar in a .t test framework.  It uses some
142       of PodLinkCheck but different reporting and a stricter approach to
143       dubious POD.
144

EXIT STATUS

146       Exit is 0 for no problems found, or non-zero for problems.
147

ENVIRONMENT VARIABLES

149       "PATH"
150           The search path for installed scripts.
151
152       "HOME"
153           Used by the various "CPAN" modules for "~/.cpan" etc directories.
154
155       "PERL5LIB"
156           The usual extra Perl module directories (see "ENVIRONMENT" in
157           perlrun), which become @INC where link targets are sought.
158

BUGS

160       "App::cpanminus" is checked first since it's a bsearch of
161       02packages.details.txt, and "CPAN::SQLite" second since it's a database
162       lookup.  But if a target is not found there then the full "CPAN" and
163       "CPANPLUS" caches are loaded and checked.  This might use a fair bit of
164       memory for a non-existent target, but it's also possible they're more
165       up-to-date.
166
167       No attempt is made to tell which of the indexes is the most up-to-date.
168       If a module has been renamed (bad) then it may still exist in an old
169       index.  The suggestion is to avoid having old stuff lying around
170       (including old mirror files in "App::cpanminus").
171
172       The code consulting "CPAN.pm" may need a tolerably new version of that
173       module, maybe 1.61 circa Perl 5.8.0.  On earlier versions its index is
174       not used.
175
176       The line:column number reported for an offending "L<>" is found by some
177       gambits extending what "Pod::Simple" normally records.  There's a
178       chance it could be a little off within the paragraph.
179
180       "Pod::Simple" prior to version 3.24 didn't allow dots "." in man-page
181       names, resulting in for example login.conf(5) being treated as a Perl
182       module name not a man page name.  If you have such links then use
183       "Pod::Simple" 3.24 up.
184
185       Directories are currently traversed using File::Find::Iterator.  It
186       follows symlinks but neither its version 0.4 nor PodLinkCheck guard
187       against infinite descent into symlink cycles.  The intention perhaps
188       would be follow all symlinks to files, but follow to a directory just
189       once as protection against cycles.
190

FILES

192       ~/.cpanm/sources/*/02packages.details.txt files from "App::cpanminus"
193
194       ~/.cpan/cpandb.sql used by "CPAN::SQLite"
195
196       ~/.cpan/Metadata used by "CPAN"
197
198       ~/.cpanplus/* variously used by "CPANPLUS"
199

SEE ALSO

201       podchecker, podlint
202
203       Pod::Simple, Pod::Find, CPAN, CPAN::SQLite, CPANPLUS, cpanm
204
205       Test::Pod::LinkCheck, Pod::Checker, Test::Pod
206

HOME PAGE

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

LICENSE

211       Copyright 2010, 2011, 2012, 2013, 2016, 2017 Kevin Ryde
212
213       PodLinkCheck is free software; you can redistribute it and/or modify it
214       under the terms of the GNU General Public License as published by the
215       Free Software Foundation; either version 3, or (at your option) any
216       later version.
217
218       PodLinkCheck is distributed in the hope that it will be useful, but
219       WITHOUT ANY WARRANTY; without even the implied warranty of
220       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
221       General Public License for more details.
222
223       You should have received a copy of the GNU General Public License along
224       with PodLinkCheck.  If not, see <http://www.gnu.org/licenses/>.
225
226
227
228perl v5.30.1                      2020-01-30                   PODLINKCHECK(1)
Impressum