Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Perl::CrUser:ContributedcPerltDocumentationitBadAproposMarkup(3)

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

perl v5.24.1  Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup(3)

NAME | DESCRIPTION | SEE ALSO | HOME PAGE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help