perldoc does not display text between section

Question

I have this POD file:

=head1 Create professional slideshows with Mojolicious::Plugin::RevealJS


=head2 Install and run a Mojolicious server

Santa's elf had a problem. He had to write very fast a presentation and show it to a bunch of new elf's.
The email assigning this to him was sent by Santa himself.
The elf started to look on Metacpan and found this module: L<Mojolicious::Plugin::RevealJS|https://metacpan.org/pod/Mojolicious::Plugin::RevealJS>

He quickly typed the following commands:

C<cpanm Mojolicius Mojolicious::Plugin::RevealJS>

Now he could generate an mojo lite app using:

C<mojo generate lite-app slide_show>

Because the elf was trained in the ancient arts  of the elders
he cloud open new file with vim and paste this code in:

=begin perl

use Mojolicious::Lite -signatures;

app->static->paths(['.']);

plugin 'RevealJS';

any '/' => { template => 'presentation', layout => 'revealjs' };

app->start;

=end perl

When I run perldoc t.pod, the code between '=begin perl' and '=end perl' is not visible. I don't understand what I'm doing wrong.

Answer 1

The perlpod documentation says ...

For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.

The formatter in this case is the thing that perldoc uses to render your POD into text. I suspect it doesn't know what to do with the format perl, so it ignores it.

A formatter that produces HTML might know what to do with the perl format, and might replace this with a code block that has syntax highlighting.

If you want your code examples in the POD to always show up as code, use a verbatim paragraph instead. This is done by adding indentation at the front.

=head2 frobnicate($foo)

This function frobnicates the C<$foo>.

    my $bar = frobnicate($foo)

=cut

sub frobnicate { ... }

Answer 2

The description of a =begin <format>/=end <format> in perlpod starts by saying this:

=begin formatname
=end formatname
=for formatname text...

For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.

Anything between =begin perl and =end perl is ignored by the standard Pod formatter and will only be processed by a specialised "perl" formatter (and no such formatter exists in the standard Perl toolset - you'd need to write your own).

You don't say what you expect this syntax to achieve, but it seems likely that you're looking for a verbatim paragraph.

Verbatim Paragraph

Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped.

A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else.