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

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::PoPerl::UseriContributedDPerleDocumentationibitVerbatimMarkup(3)

NAME
       Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup -
       unexpanded C<> etc markup in POD	verbatim paras

DESCRIPTION
       This policy is part of the "Perl::Critic::Pulp" add-on.	It reports POD
       verbatim	paragraphs which contain markup	like B<> or C<>.  That markup
       will appear literally in	the formatted output where you may have	meant
       fontification.

	   =head1 SOME THING

	   Paragraph of	text introducing an example,

	       # call the C<foo> function      # bad
	       &foo();

       This is purely cosmetic so this policy is low severity and under	the
       "cosmetic" theme	(see "POLICY THEMES" in	Perl::Critic).	Normally it
       means one of two	things,

       o   You want markup -- it should	be a plain paragraph not a verbatim
	   indented one.  An "=over" can be used for indentation if desired.

       o   You want verbatim --	replace	the markup with	an ascii approximation
	   like	"func()" or perhaps "*bold*" or	"_underline_".

       Don't forget that a verbatim paragraph extends to the next blank	line
       and includes unindented lines until then	too (see "Pod Definitions" in
       perlpodspec).  If you forget the	blank line then	the verbatimness
       continues

	   =pod

	       $some->sample;
	       code();
	   And this was	I<meant> to be plain text.    #	bad

   Markup Forms
       The check for markup is unsophisticated.	 Any of	the POD	specified "I<"
       "C<" etc	is taken to be markup, plus "J<" of "Pod::MultiLang".

	   I<	    # bad
	   B<	    # bad
	   C<	    # bad
	   L<	    # bad
	   E<	    # bad
	   F<	    # bad
	   S<	    # bad
	   X<	    # bad
	   Z<	    # bad
	   J<	    # bad, for Pod::MultiLang

       It's possible a "<" might be something mathematical like	"X<Y", but in
       practice	spaces "XA <A Y" or lower case letters are more	common (and
       are ok).

       "DB<1>" style sample Perl debugger output is exempted (see perldebug).
       It's uncommon, but not likely to	have intended "B<>" bold.

	   DB<123> dump	b	 # ok

   Disabling
       If a verbatim paragraph is showing how to write POD markup then you can
       add an "=for" to	tell "ProhibitVerbatimMarkup" to allow it.  This
       happens most often in documentation for modules which themselves
       operate on POD markup.

	   =for	ProhibitVerbatimMarkup allow next

	       blah blah E<gt> etc

	   =for	ProhibitVerbatimMarkup allow next 2

	       Two verbatims of	C<code>

	       or B<bold> etc

       The usual no critic works too,

	   ## no critic	(ProhibitVerbatimMarkup)

       But the annotation must be before any "__END__" token, and if the POD
       is after	an "__END__" token then	"Perl::Critic" 1.112 up	is required.
       An "=for" has the advantage of being together with the exception.

       As always if you	don't care at all about	this at	all then disable
       "ProhibitVerbatimMarkup"	from your .perlcriticrc	in the usual way (see
       "CONFIGURATION" in Perl::Critic),

	   [-Documentation::ProhibitVerbatimMarkup]

SEE ALSO
       Perl::Critic::Pulp, Perl::Critic,
       Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup,
       Perl::Critic::Policy::Documentation::RequireEndBeforeLastPod

HOME PAGE
       http://user42.tuxfamily.org/perl-critic-pulp/index.html

COPYRIGHT
       Copyright 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::ProhibitVerbatimMarkup(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::ProhibitVerbatimMarkup&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help