Perl::...sMarkup(3pm)

💖 NAME 💖

Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup — bestie, please don't use C<> markup in a NAME section, it's giving chaos 😭

(also this page header literally says Perl::...sMarkup(3pm) because the real name is too long to fit, girls with long names know the struggle 💅)

---

🌸 DESCRIPTION 🌸

Okay so this policy is part of the Perl::Critic::Pulp add-on, and it's basically begging you: do not write C<> markup in the NAME section of your POD. Why? Because it comes out absolutely cursed in the man-db apropos database. Not cute. Not slay. Just cursed.

Like, say you do this:

=head1 NAME

foo - like the C<bar> program     # bad

and pod2man formats that C<> using nroff macros, which man-db's lexgrog program does not expand. So your lovely apropos description line ends up looking like:

foo - like the *(C`bar*(C' program

literally 💀 the *(C bits are just hanging out there, uninvited, no vibe check passed.

Okay but here's the thing — the actual formatted man output? Totally fine. The text you wanted is in there, it's just wrapped in those *(C bits like it's wearing an ugly sweater to a party. So on that basis this policy is low severity and lives under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic). It's a glow-up suggestion, not a red alert.

The NAME section = everything from =head1 NAME down to the next =head1. Periodt.

Other markup like B<>, I<> and F<> is allowed, bestie, because pod2man uses builtin \fB etc directives for those, which lexgrog actually recognises. So those ones ate. 💅

And heads up: =begin :man and =begin :roff blocks are checked, since Pod::Man processes those. Other =begin blocks get ignored because they won't appear in the roff output anyway. 🦋

🚫 Disabling 🚫

So if you genuinely want markup in that NAME line — maybe printed output matters more to you than apropos, and honestly valid — you can always turn this off from your .perlcriticrc the usual way (see "CONFIGURATION" in Perl::Critic):

[-Documentation::ProhibitBadAproposMarkup]

Or in a single individual file, with the usual ## no critic:

## no critic (ProhibitBadAproposMarkup)

⚠️ but listen — if the NAME part comes after an __END__ token, then you need Perl::Critic 1.112 or higher for that annotation to work (and the annotation has to be before the __END__, no cap).

---

✨ SEE ALSO ✨

• Perl::Critic::Pulp
• Perl::Critic
• Perl::Critic::Policy::Documentation::RequirePackageMatchesPodName
• Perl::Critic::Policy::Documentation::RequirePodSections
• Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup
• man(1)
• apropos(1)
• lexgrog(1)

---

🏠 HOME PAGE 🏠

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

---

👑 COPYRIGHT 👑

Copyright 2009, 2010, 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 babes 🎀 this one shipped in perl v5.40.1, dated 2025-10-21, filed under Perl::...sMarkup(3pm) (yes the header is still squished, we don't talk about it) 🌈✨