.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Perl::Critic::Policy::Documentation::RequireLinkedURLs 3pm" .TH Perl::Critic::Policy::Documentation::RequireLinkedURLs 3pm "2021-02-28" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Perl::Critic::Policy::Documentation::RequireLinkedURLs \- use L<> markup on URLs in POD .SH "DESCRIPTION" .IX Header "DESCRIPTION" This policy is part of the \f(CW\*(C`Perl::Critic::Pulp\*(C'\fR add-on. It asks you to put \f(CW\*(C`L<>\*(C'\fR markup on URLs in \s-1POD\s0 text in Perl 5.8 and higher. .PP .Vb 1 \& use 5.008; \& \& =head1 HOME PAGE \& \& http://foo.org/mystuff/index.html # bad .Ve .PP .Vb 1 \& L # good .Ve .PP \&\f(CW\*(C`L<>\*(C'\fR markup gives clickable links in \f(CW\*(C`pod2html\*(C'\fR and similar formatters, and even in the plain text formatters may give \&\f(CW\*(C`\*(C'\fR style angles around the \s-1URL\s0 which is a semi-conventional way to delimit from surrounding text and in particular from an immediately following comma or period. .PP This is only cosmetic and on that basis this policy is low severity and under the \*(L"cosmetic\*(R" theme (see \*(L"\s-1POLICY THEMES\*(R"\s0 in Perl::Critic). .PP Only plain text parts of the \s-1POD\s0 are considered. Verbatim paragraphs cannot have \f(CW\*(C`L<>\*(C'\fR markup (and it's usually a mistake to put it there, as per \&\f(CW\*(C`ProhibitVerbatimMarkup\*(C'\fR). .PP .Vb 1 \& This is verbatim text, \& \& http://somewhere.com # ok in verbatim .Ve .SS "Perl 5.8" .IX Subsection "Perl 5.8" \&\f(CW\*(C`L\*(C'\fR linking of URLs is new in the Perl 5.8 \s-1POD\s0 specification. It comes out badly from the formatters in earlier Perl where the \*(L"/\*(R" is taken to be a section delimiter. For that reason this policy only applies if there's an explicit \f(CW\*(C`use 5.008\*(C'\fR or higher in the code. .PP .Vb 1 \& use 5.005; .Ve .PP .Vb 1 \& =item C # ok when don\*(Aqt have Perl 5.8 L<> .Ve .SS "Bad URLs" .IX Subsection "Bad URLs" Some obvious intentional dummy URLs like \f(CW\*(C`L\*(C'\fR are ignored. They're examples and won't go anywhere as a clickable link. You might like to put \f(CW\*(C`C<>\*(C'\fR on them for a typeface, but that is not required by this policy. Currently ignored \s-1URL\s0 variations are like .PP .Vb 9 \& 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://... .Ve .PP A \s-1URL\s0 is anything starting \f(CW\*(C`http://\*(C'\fR, \f(CW\*(C`https://\*(C'\fR, \f(CW\*(C`ftp://\*(C'\fR, \f(CW\*(C`news://\*(C'\fR or \&\f(CW\*(C`nntp://\*(C'\fR. .SS "Begin Blocks" .IX Subsection "Begin Blocks" Text in any \f(CW\*(C`=begin :foo\*(C'\fR block is checked since \f(CW\*(C`:\*(C'\fR means \s-1POD\s0 markup and it's likely URLs can be helpfully linked there, even if it's only for some particular formatter. .PP Other \f(CW\*(C`=begin\*(C'\fR blocks are ignored since \f(CW\*(C`L<>\*(C'\fR there will not normally be possible or desirable. .SS "Disabling" .IX Subsection "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 \f(CW\*(C`RequireLinkedURLs\*(C'\fR from your \fI~/.perlcriticrc\fR file in the usual way (see \*(L"\s-1CONFIGURATION\*(R"\s0 in Perl::Critic), .PP .Vb 1 \& [\-Documentation::RequireLinkedURLs] .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Perl::Critic::Pulp, Perl::Critic, Perl::Critic::Policy::Documentation::RequirePodLinksIncludeText .SH "HOME PAGE" .IX Header "HOME PAGE" .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019, 2021 Kevin Ryde .PP Perl-Critic-Pulp is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. .PP Perl-Critic-Pulp is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with Perl-Critic-Pulp. If not, see .