Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup - unexpanded C<> etc markup in POD verbatim paras
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.
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 severity and under the "cosmetic" theme (see "POLICY THEMES" in Perl::Critic). Normally it means one of two things,
You want markup -- it should be a plain paragraph not a verbatim indented one. An =over can be used for indentation if desired.
=over
You want verbatim -- replace the markup with an ascii approximation like func() or perhaps *bold* or _underline_.
func()
*bold*
_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
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, for Pod::MultiLang
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).
<
DB<1> style sample Perl debugger output is exempted (see perldebug). It's uncommon, but not likely to have intended B<> bold.
DB<1>
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
ProhibitVerbatimMarkup
=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.
__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),
[-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, 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/>.
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.