Manual Reference Pages - PERL::CRITIC::POLICY::DOCUMENTATION::REQUIRELINKEDURLS (3)
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.
=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.
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 its usually a mistake to put it there, as
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 theres an explicit use 5.008 or higher in the code.
=item C<http://foo.org> # ok when dont have Perl 5.8 L<>
Some obvious dummy URLs like L<http://foo.org> are ignored.
Theyre only examples and wont 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
A URL is anything starting http://, https://, ftp://, news:// or
Text in any =begin :foo block is checked since : means POD markup and
its likely URLs can be helpfully linked there, even if its only for some
Other =begin blocks are ignored since L<> there will not
normally be possible or desirable.
If you dont care about this, if for instance its 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),
Copyright 2011, 2012, 2013, 2014, 2015 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
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
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/>.
|perl v5.20.3 ||PERL::CRITIC::POLICY::DOCUMENTATION::REQUIRELINKEDURLS (3) ||2015-01-04 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.