/ 
Perl-Critic-Pulp-60
River stage two • 5 direct dependents • 18 total dependents
/ Perl::Critic::Policy::Documentation::RequireLinkedURLs

NAME

Perl::Critic::Policy::Documentation::RequireLinkedURLs - use L<> markup on URLs in POD

DESCRIPTION

This policy is part of the Perl::Critic::Pulp addon. It asks you to put L<> markup on URLs in POD text in Perl 5.8 and higher.

use 5.008;

=head1 HOME PAGE

http://foo.org/mystuff/index.html      # bad
L<http://foo.org/mystuff/index.html>   # good

=cut

L<> markup gives clickable links in pod2html and similar formatters, and even in the plain text formatters it gives <http://...> style angles around the URL which is a semi-conventional way to delimit from surrounding text and in particular from an immediately following period or comma.

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. Indented verbatim text cannot have L<> markup (and it's often a mistake to put it, as per 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 (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.

use 5.005;
=item C<http://foo.org>       # ok, don't have Perl 5.8 L<>

Some obviously bogus URLs like L<http://foo.org> are ignored, they'll only be as examples and won't go anywhere as a clickable link. Some C<> for monospacing might look good. Exactly what's ignored is not quite settled, but currently includes variations like

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://...

In the current implementation a URL is anything starting http://, https://, ftp://, news:// or nntp://.

Disabling

If you don't care about this, for instance if it's hard enough to get your programmers to write documentation at all without worrying about markup!, then you can disable RequireLinkedURLs from your ~/.perlcriticrc file in the usual way (see "CONFIGURATION" in Perl::Critic),

[-Documentation::RequireLinkedURLs]

SEE ALSO

Perl::Critic::Pulp, Perl::Critic, Perl::Critic::Policy::Documentation::RequirePodLinksIncludeText

HOME PAGE

http://user42.tuxfamily.org/perl-critic-pulp/index.html

COPYRIGHT

Copyright 2011 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/>.