Test::Pod::LinkCheck(3pm)

1Test::Pod::LinkCheck(3pUms)er Contributed Perl DocumentatTieosnt::Pod::LinkCheck(3pm)
2
3
4

NAME

6       Test::Pod::LinkCheck - Tests POD for invalid links
7

VERSION

9         This document describes v0.008 of Test::Pod::LinkCheck - released November 01, 2014 as part of Test-Pod-LinkCheck.
10

SYNOPSIS

12               #!/usr/bin/perl
13               use strict; use warnings;
14
15               use Test::More;
16
17               eval "use Test::Pod::LinkCheck";
18               if ( $@ ) {
19                       plan skip_all => 'Test::Pod::LinkCheck required for testing POD';
20               } else {
21                       Test::Pod::LinkCheck->new->all_pod_ok;
22               }
23

DESCRIPTION

25       This module looks for any links in your POD and verifies that they
26       point to a valid resource. It uses the Pod::Simple parser to analyze
27       the pod files and look at their links. In a nutshell, it looks for
28       "L<Foo>" links and makes sure that Foo exists. It also recognizes
29       section links, "L</SYNOPSIS>" for example. Also, manpages are resolved
30       and checked.
31
32       This module does NOT check "http" links like "L<http://www.google.com>"
33       in your pod. For that, please check out Test::Pod::No404s.
34
35       Normally, you wouldn't want this test to be run during end-user
36       installation because they might not have the modules installed! It is
37       HIGHLY recommended that this be used only for module authors'
38       RELEASE_TESTING phase. To do that, just modify the synopsis to add an
39       env check :)
40
41       This module normally uses the OO method to run tests, but you can use
42       the functional style too. Just explicitly ask for the "all_pod_ok" or
43       "pod_ok" function to be imported when you use this module.
44
45               #!/usr/bin/perl
46               use strict; use warnings;
47               use Test::Pod::LinkCheck qw( all_pod_ok );
48               all_pod_ok();
49

ATTRIBUTES

51   check_cpan
52       If enabled, this module will check the CPAN module database to see if a
53       link is a valid CPAN module or not. It uses the backend defined in
54       "cpan_backend" to do the actual searching.
55
56       If disabled, it will resolve links based on locally installed modules.
57       If it isn't installed it will be an error!
58
59       The default is: true
60
61   cpan_backend
62       Selects the CPAN backend to use for querying modules. The available
63       ones are: CPANPLUS, CPAN, CPANSQLite, MetaDB, MetaCPAN, and CPANIDX.
64
65       The default is: CPANPLUS
66
67               The backends were tested and verified against those versions. Older versions should work, but is untested!
68                       CPANPLUS v0.9010
69                       CPAN v1.9402
70                       CPAN::SQLite v0.199
71                       CPAN::Common::Index::MetaDB v0.005
72                       MetaCPAN::API::Tiny v1.131730
73                       MetaCPAN::Client v1.007001
74                       LWP::UserAgent v6.06
75
76   cpan_backend_auto
77       Enable to automatically try the CPAN backends to find an available one.
78       It will try the backends in the order defined in "cpan_backend"
79
80       If no backend is available, it will disable the "check_cpan" attribute
81       and enable the "cpan_section_err" attribute.
82
83       The default is: true
84
85   cpan_section_err
86       If enabled, a link pointing to a CPAN module's specific section is
87       treated as an error if it isn't installed.
88
89       The default is: false
90
91   verbose
92       If enabled, this module will print extra diagnostics for the links it's
93       checking.
94
95       The default is: copy $ENV{HARNESS_IS_VERBOSE} or $ENV{TEST_VERBOSE} or
96       false
97

METHODS

99   pod_ok
100       Accepts the filename to check, and an optional test name.
101
102       This method will pass the test if there is no POD links present in the
103       POD or if all links are not an error. Furthermore, if the POD was
104       malformed as reported by Pod::Simple, the test will fail and not
105       attempt to check the links.
106
107       When it fails, this will show any failing links as diagnostics. Also,
108       some extra information is printed if verbose is enabled.
109
110       The default test name is: "LinkCheck test for FILENAME"
111
112   all_pod_ok
113       Accepts an optional array of files to check. By default it uses all POD
114       files in your distribution.
115
116       This method is what you will usually run. Every file is passed to the
117       "pod_ok" function. This also sets the test plan to be the number of
118       files.
119

NOTES

121   backend
122       This module uses the CPANPLUS and CPAN modules as the backend to verify
123       valid CPAN modules. Please make sure that the backend you choose is
124       properly configured before running this! This means the index is
125       updated, permissions is set, and whatever else the backend needs to
126       properly function. If you don't want to use them please disable the
127       "check_cpan" attribute.
128
129       If this module fails to check CPAN modules or the testsuite fails, it's
130       probably because of the above reason.
131
132   CPAN module sections
133       One limitation of this module is that it can't check for valid sections
134       on CPAN modules if they aren't installed. If you want that to be an
135       error, please enable the "cpan_section_err" attribute.
136

SUPPORT

148   Perldoc
149       You can find documentation for this module with the perldoc command.
150
151         perldoc Test::Pod::LinkCheck
152
153   Websites
154       The following websites have more information about this module, and may
155       be of help to you. As always, in addition to those websites please use
156       your favorite search engine to discover more resources.
157
158       ·   MetaCPAN
159
160           A modern, open-source CPAN search engine, useful to view POD in
161           HTML format.
162
163           <http://metacpan.org/release/Test-Pod-LinkCheck>
164
165       ·   Search CPAN
166
167           The default CPAN search engine, useful to view POD in HTML format.
168
169           <http://search.cpan.org/dist/Test-Pod-LinkCheck>
170
171       ·   RT: CPAN's Bug Tracker
172
173           The RT ( Request Tracker ) website is the default bug/issue
174           tracking system for CPAN.
175
176           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Pod-LinkCheck>
177
178       ·   AnnoCPAN
179
180           The AnnoCPAN is a website that allows community annotations of Perl
181           module documentation.
182
183           <http://annocpan.org/dist/Test-Pod-LinkCheck>
184
185       ·   CPAN Ratings
186
187           The CPAN Ratings is a website that allows community ratings and
188           reviews of Perl modules.
189
190           <http://cpanratings.perl.org/d/Test-Pod-LinkCheck>
191
192       ·   CPAN Forum
193
194           The CPAN Forum is a web forum for discussing Perl modules.
195
196           <http://cpanforum.com/dist/Test-Pod-LinkCheck>
197
198       ·   CPANTS
199
200           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
201           of a distribution.
202
203           <http://cpants.cpanauthors.org/dist/overview/Test-Pod-LinkCheck>
204
205       ·   CPAN Testers
206
207           The CPAN Testers is a network of smokers who run automated tests on
208           uploaded CPAN distributions.
209
210           <http://www.cpantesters.org/distro/T/Test-Pod-LinkCheck>
211
212       ·   CPAN Testers Matrix
213
214           The CPAN Testers Matrix is a website that provides a visual
215           overview of the test results for a distribution on various
216           Perls/platforms.
217
218           <http://matrix.cpantesters.org/?dist=Test-Pod-LinkCheck>
219
220       ·   CPAN Testers Dependencies
221
222           The CPAN Testers Dependencies is a website that shows a chart of
223           the test results of all dependencies for a distribution.
224
225           <http://deps.cpantesters.org/?module=Test::Pod::LinkCheck>
226
227   Email
228       You can email the author of this module at "APOCAL at cpan.org" asking
229       for help with any problems you have.
230
231   Internet Relay Chat
232       You can get live help by using IRC ( Internet Relay Chat ). If you
233       don't know what IRC is, please read this excellent guide:
234       <http://en.wikipedia.org/wiki/Internet_Relay_Chat>. Please be courteous
235       and patient when talking to us, as we might be busy or sleeping! You
236       can join those networks/channels and get help:
237
238       ·   irc.perl.org
239
240           You can connect to the server at 'irc.perl.org' and join this
241           channel: #perl-help then talk to this person for help: Apocalypse.
242
243       ·   irc.freenode.net
244
245           You can connect to the server at 'irc.freenode.net' and join this
246           channel: #perl then talk to this person for help: Apocal.
247
248       ·   irc.efnet.org
249
250           You can connect to the server at 'irc.efnet.org' and join this
251           channel: #perl then talk to this person for help: Ap0cal.
252
253   Bugs / Feature Requests
254       Please report any bugs or feature requests by email to
255       "bug-test-pod-linkcheck at rt.cpan.org", or through the web interface
256       at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Pod-LinkCheck>.
257       You will be automatically notified of any progress on the request by
258       the system.
259
260   Source Code
261       The code is open to the world, and available for you to hack on. Please
262       feel free to browse it and play with it, or whatever. If you want to
263       contribute patches, please send me a diff or prod me to pull from your
264       repository :)
265
266       <https://github.com/apocalypse/perl-test-pod-linkcheck>
267
268         git clone git://github.com/apocalypse/perl-test-pod-linkcheck.git
269

AUTHOR

271       Apocalypse <APOCAL@cpan.org>
272

COPYRIGHT AND LICENSE

274       This software is copyright (c) 2014 by Apocalypse.
275
276       This is free software; you can redistribute it and/or modify it under
277       the same terms as the Perl 5 programming language system itself.
278
279       The full text of the license can be found in the LICENSE file included
280       with this distribution.
281

DISCLAIMER OF WARRANTY

283       THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
284       APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
285       HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
286       WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
287       LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
288       PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE
289       OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU
290       ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
291
292       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
293       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
294       CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
295       INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
296       ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
297       NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
298       SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
299       OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY
300       HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
301
302
303
304perl v5.30.1                      2020-01-30         Test::Pod::LinkCheck(3pm)