NAME
Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup - don't use C<> markup in a NAME section
DESCRIPTION
This policy is part of the Perl::Critic::Pulp
add-on. It asks you not to write C<> markup in the NAME section of the POD because it comes out badly in the man-db "apropos" database. For example,
=head1 NAME
foo - like the C<bar> program # bad
pod2man
formats "C<>" using nroff macros which "man-db"'s lexgrog
program doesn't expand, resulting in unattractive description lines from apropos
like
foo - like the *(C`bar*(C' program
Man's actual formatted output is fine, and the desired text is in there, just surrounded by *(C
bits. On that basis this policy is low severity and under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic).
The NAME section is everything from =head1 NAME
to the next =head1
. Other markup like "B<>", "I<>" and "F<>" is allowed because pod2man
uses builtin \fB
etc directives for them, which lexgrog
recognises.
=begin :man
and =begin :roff
blocks are checked since Pod::Man
processes those. Other =begin
blocks are ignored as they won't appear in the roff output.
Disabling
If want markup in the NAME line, perhaps if printed output is more important than apropos
, then you can always disable from your .perlcriticrc in the usual way (see "CONFIGURATION" in Perl::Critic),
[-Documentation::ProhibitBadAproposMarkup]
Or in an individual file with the usual ## no critic
## no critic (ProhibitBadAproposMarkup)
though if the NAME part is after an __END__
token then Perl::Critic
1.112 or higher is required (and the annotation must be before the __END__
).
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/>.