Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Policy:PUser:ContributediPerlDDocumentationNAME
       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 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.24.1	     Perl::Critic::Policy::Documentation::RequireLinkedURLs(3)

NAME | DESCRIPTION | SEE ALSO | HOME PAGE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Policy::Documentation::RequireLinkedURLs&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help