1PODLINKCHECK(1) User Contributed Perl Documentation PODLINKCHECK(1)
2
6 podlinkcheck -- check Perl pod L<> link references
7
9 podlinkcheck [--options] file-or-dir...
10
12 The command line options are
13 --help
15 Print a command line summary.
16 -I dir
18 Add an extra directory to look for target modules.
19 --verbose
21 Print more about program operation (including CPAN loading).
22 --version
24 Print the program version number and exit.
25
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 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 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 podlinkcheck /usr/share/perl5
40 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 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 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 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 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 Internal Links
68 Internal links are sometimes written
69 L<SYNOPSIS> # may be ambiguous
71 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 See L</SYNOPSIS> above. # good
77 See L<"SYNOPSIS"> above. # good
79 "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 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 L<perlfunc/split>
92 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 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 foo.pl:130:31: no section "constructor" in "CHI"
106 (file /usr/share/perl5/CHI.pm)
107 perhaps it should be "CONSTRUCTOR"
108 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 =item 1. # good
116 The First Thing # the section name
118 Paragraph about this thing.
120 =item 2. The Second Thing # bad
122 Paragraph about this next thing.
124 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 =item 64 Bit Support
130 "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 Other Ways to Do It
138 "podchecker" (the "Pod::Checker" module) checks internal links, but it
139 doesn't check external links.
140 "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
146 Exit is 0 for no problems found, or non-zero for problems.
147
149 "PATH"
150 The search path for installed scripts.
151 "HOME"
153 Used by the various "CPAN" modules for "~/.cpan" etc directories.
154 "PERL5LIB"
156 The usual extra Perl module directories (see "ENVIRONMENT" in
157 perlrun), which become @INC where link targets are sought.
158
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 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 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 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 "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 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
192 ~/.cpanm/sources/*/02packages.details.txt files from "App::cpanminus"
193 ~/.cpan/cpandb.sql used by "CPAN::SQLite"
195 ~/.cpan/Metadata used by "CPAN"
197 ~/.cpanplus/* variously used by "CPANPLUS"
199
201 podchecker, podlint
202 Pod::Simple, Pod::Find, CPAN, CPAN::SQLite, CPANPLUS, cpanm
204 Test::Pod::LinkCheck, Pod::Checker, Test::Pod
206
208 http://user42.tuxfamily.org/podlinkcheck/index.html
209
211 Copyright 2010, 2011, 2012, 2013, 2016, 2017 Kevin Ryde
212 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 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 You should have received a copy of the GNU General Public License along
224 with PodLinkCheck. If not, see <http://www.gnu.org/licenses/>.
225perl v5.32.1 2021-01-27 PODLINKCHECK(1)