Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup - unexpanded C<> etc markup in POD verbatim paras
This policy is part of the Perl::Critic::Pulp addon. 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.
Perl::Critic::Pulp
=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 priority and under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic). Normally it means one of two things,
You wanted markup -- it should be a plain paragraph not an indented verbatim one. An =over can be used for indentation if desired.
=over
You wanted verbatim -- drop the markup in favour of some ascii approximation like func() or even *bold* or _underline_.
func()
*bold*
_underline_
Don't forget a verbatim paragraph extends to the next blank line and includes unindented lines until then (see "Pod Definitions" in perlpodspec). So if you forget the blank the verbatimness continues
=pod $some->sample; code(); And this was I<meant> to be plain text. # bad
The check for markup is unsophisticated. Any of the POD specified "I<" "C<" etc is taken to be markup, plus "J<" of Pod::MultiLang.
Pod::MultiLang
I< # bad B< # bad C< # bad L< # bad E< # bad F< # bad S< # bad X< # bad Z< # bad J< # bad
It's possible a < might be something mathematical like "X<Y", but in practice spaces "X < Y" or lower case letters are more common and are ok.
<
Sample debugger output is exempted. It's uncommon, but also unlikely to have meant B<> bold.
B<>
DB<123> dump b # ok
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
=for ProhibitVerbatimMarkup allow next blah blah E<gt> etc
The usual ## no critic (ProhibitVerbatimMarkup) works too, though if the POD is after an __END__ token then Perl::Critic 1.112 is required (and the annotation must be before the __END__). An =for has the advantage of being immediately before the exception.
## no critic (ProhibitVerbatimMarkup)
__END__
Perl::Critic
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),
ProhibitVerbatimMarkup
[-Documentation::ProhibitVerbatimMarkup]
Perl::Critic::Pulp, Perl::Critic, Perl::Critic::Policy::Documentation::ProhibitBadAproposMarkup, Perl::Critic::Policy::Documentation::RequireEndBeforeLastPod
http://user42.tuxfamily.org/perl-critic-pulp/index.html
Copyright 2010, 2011 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/>.
To install Perl::Critic::Pulp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl::Critic::Pulp
CPAN shell
perl -MCPAN -e shell install Perl::Critic::Pulp
For more information on module installation, please visit the detailed CPAN module installation guide.