Perl::Critic::Policy::Documentation::RequireLinkedURLs - use L<> markup on URLs in POD
This policy is part of the Perl::Critic::Pulp add-on. It asks you to put L<> markup on URLs in POD text in Perl 5.8 and higher.
Perl::Critic::Pulp
L<>
use 5.008; =head1 HOME PAGE http://foo.org/mystuff/index.html # bad
L<http://foo.org/mystuff/index.html> # good
L<> markup gives clickable links in pod2html and similar formatters, and even in the plain text formatters may give <http://...> style angles around the URL which is a semi-conventional way to delimit from surrounding text and in particular from an immediately following comma or period.
pod2html
<http://...>
Of course this is only cosmetic and on that basis this policy is low priority and under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic).
Only plain text parts of the POD are considered. Verbatim paragraphs cannot have L<> markup (and it's usually a mistake to put it, as per ProhibitVerbatimMarkup).
ProhibitVerbatimMarkup
This is verbatim text, http://somewhere.com # ok in verbatim
L<http://...> linking of URLs is new in the Perl 5.8 POD specification. It comes out badly from the formatters in earlier Perl where the "/" is taken to be a section delimiter. For that reason this policy only applies if there's an explicit use 5.008 or higher in the code.
L<http://...>
use 5.008
use 5.005;
=item C<http://foo.org> # ok when don't have Perl 5.8 L<>
Some obvious dummy URLs like L<http://foo.org> are ignored. They're only examples and won't go anywhere as a clickable link. You might like to put C<> for a typeface, but L<> is not required by this policy, and in fact is probably undesirable. Currently ignored URLs variations like
L<http://foo.org>
C<>
http://foo.com https://foo.org ftp://bar.org.au http://quux.com.au http://xyzzy.co.uk http://foo.co.nz http://host:port http://...
A URL is anything starting http://, https://, ftp://, news:// or nntp://.
http://
https://
ftp://
news://
nntp://
Text in an =begin html block is not checked, since it contains HTML and so should be <a href=""> etc there, not L<>.
=begin html
<a href="">
=begin html <a href="http://foo.org/index">home page</a> # ok =end html
Other =begin blocks ignored for similar reasons are as follows. They're probably less likely to have URLs.
=begin
comment programmer's notes only latex man roff tex wikidoc links are [http://...] style
Currently all other =begin forms are examined, which may be excessive, but it's hard to be sure what will or won't be POD markup. Keys beginning ":" are supposed to be POD markup, others are guesswork.
If you don't care about this, if for instance it's hard enough to get your programmers to write documentation at all without worrying about markup, then disable RequireLinkedURLs from your ~/.perlcriticrc file in the usual way (see "CONFIGURATION" in Perl::Critic),
RequireLinkedURLs
[-Documentation::RequireLinkedURLs]
Perl::Critic::Pulp, Perl::Critic, Perl::Critic::Policy::Documentation::RequirePodLinksIncludeText
http://user42.tuxfamily.org/perl-critic-pulp/index.html
Copyright 2011, 2012, 2013 Kevin Ryde
Perl-Critic-Pulp 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.
Perl-Critic-Pulp 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 Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses/>.
To install Perl::Critic::Pulp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl::Critic::Pulp
CPAN shell
perl -MCPAN -e shell install Perl::Critic::Pulp
For more information on module installation, please visit the detailed CPAN module installation guide.