--- name: "Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup" section: "3pm" platform: "linux" package: "libperl-critic-pulp-perl" version: "99-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup" --- # Perl::Critic::Policy::Documentation::ProhibitVerbatimMarkup(3pm) unexpanded C\<\> etc markup in POD verbatim paras ## 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 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. - • 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 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\"` 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 etc =for ProhibitVerbatimMarkup allow next 2 Two verbatims of C


        or B 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, 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 \.