Manual Reference Pages - PERL::CRITIC::POLICY::DOCUMENTATION::PROHIBITBADAPROPOSMARKUP (3)
Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup - dont use C<> markup in a NAME section
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
foo - like the C<bar> program # bad
pod2man formats C<> using nroff macros which man-dbs
lexgrog program doesnt expand, resulting in unattractive description
lines from apropos like
foo - like the *(C`bar*(C program
Mans actual formatted output is fine, and the desired text is in there,
just surrounded by *(C bits. On that basis this policy is low priority
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
=begin :man and =begin :roff blocks are checked since Pod::Man
processes those. Other =begin blocks are ignored as they wont appear in
the roff output.
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),
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
man(1), apropos(1), lexgrog(1)
Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015 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
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
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.20.3 ||PERL::CRITIC::POLICY::DOCUMENTATION::PROHIBITBADAPROPOSMARKUP (3) ||2015-01-04 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.