Perl::...edURLs(3pm)

📦
version 100 · 7 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

Perl::Critic::Policy::Documentation::RequireLinkedURLs — bestie, this policy wants you to use L<> markup on URLs in your POD. That's it, that's the whole job. 💅

✨ DESCRIPTION ✨

Okay so this policy is part of the Perl::Critic::Pulp add-on 🌸 and it politely but firmly asks you to wrap L<> markup around URLs in your POD text — but only when you're on Perl 5.8 and up. No cap.

use 5.008;

=head1 HOME PAGE

http://foo.org/mystuff/index.html      # bad

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

Why are we doing this, you ask? Because L<> markup gives you actual clickable links in pod2html and friends 🔥 — and honestly even the plain-text formatters might give you <http://...> style angle brackets around the URL. Which is, like, a semi-conventional way to clearly delimit the URL from the surrounding text, especially when there's a comma or a period breathing down its neck. Iconic behavior honestly.

It's giving cosmetic. On that basis this policy is low severity and lives under the cosmetic theme (peep "POLICY THEMES" in Perl::Critic for the deets).

Important: only the plain text parts of the POD get checked. Verbatim paragraphs literally cannot have L<> markup, and ngl putting it there is usually a mistake anyway (as covered by "ProhibitVerbatimMarkup").

This is verbatim text,

    http://somewhere.com      # ok in verbatim

🦋 Perl 5.8 🦋

L<http://...>-style linking of URLs is a new thing in the Perl 5.8 POD specification, bestie. On earlier Perls it comes out badly from the formatters, because the / gets treated as a section delimiter 😭. So for that reason, this policy only kicks in if there's an explicit use 5.008 or higher chillin' in the code.

use 5.005;

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

👀 Bad URLs 👀

Some obviously-intentional dummy URLs like L<http://example.com> get ignored, periodt. They're examples — they're not gonna go anywhere as a clickable link, so why bother. You might like to slap C<> on them for the typeface, but this policy is not requiring that of you. Bestie, the URL variations we currently ignore go a lil something like this:

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

And for the record, a URL is anything starting with http://, https://, ftp://, news:// or nntp://. Those five. That's the squad. 🫶

🎀 Begin Blocks 🎀

Text inside any =begin :foo block does get checked, because that : means POD markup, and it's pretty likely URLs can be helpfully linked in there — even if it's only for some particular formatter. Every little bit helps, y'know? ✨

Every other =begin block gets ignored, because L<> in there won't normally be possible or desirable. Vibe check failed, moving on. 💀

🙈 Disabling 🙈

If you simply do not care — like, if it's already hard enough getting your programmers to write documentation at all without also worrying about markup — then go ahead and 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 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/>.

and that's the whole page, bestie 💖 this rundown was brought to you by perl v5.40.1, dated 2025-10-21 — stay linked, stay slay, mwah 💅✨

📦 where this page comes from