NAME

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

DESCRIPTION

       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.

           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.

       This is only cosmetic and on that basis this policy is low severity 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 there, as per "ProhibitVerbatimMarkup").

           This is verbatim text,

               http://somewhere.com      # ok in verbatim

   Perl 5.8
       "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.

           use 5.005;

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

   Bad URLs
       Some obvious intentional dummy URLs like "L<http://example.com>" are ignored.  They're
       examples and won't go anywhere as a clickable link.  You might like to put "C<>" on them
       for a typeface, but that is not required by this policy.  Currently ignored URL variations
       are like

           http://example.com
           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://".

   Begin Blocks
       Text in any "=begin :foo" block is checked since ":" means POD markup and it's likely URLs
       can be helpfully linked there, even if it's only for some particular formatter.

       Other "=begin" blocks are ignored since "L<>" there will not normally be possible or
       desirable.

   Disabling
       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),

           [-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, 2012, 2013, 2014, 2015, 2016, 2017, 2019, 2021 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/>.

perl v5.32.1                          Perl::Critic::Policy::Documentation::RequireLinkedURLs(3pm)