perl's pod2usage(-verbose => 2) shows the source code instead of the formatted documentation

Question

According to the documentation of Pod::Usage, with pod2usage(-verbose => 2) "the entire manpage is printed". However, in some cases, the perl source code for the script is displayed instead of the properly formatted manpage.

Here's an example:

use Pod::Usage qw(pod2usage);
pod2usage(-verbose => 2);

__END__

=head1 NAME

Minimal example

=head1 SYNOPSIS

This is the synopsys section.

=cut

Running the script:

$ perl test.perl            
You need to install the perl-doc package to use this program.
use Pod::Usage qw(pod2usage);
pod2usage(-verbose => 2);

__END__

=head1 NAME

Minimal example

=head1 SYNOPSIS

This is the synopsys section.

=cut

Answer 1

The issue is that pod2usage uses the command-line program perldoc. If this program is not installed, then no formatting is done and you get the full source code in the output.

Note that in the question, the text "You need to install the perl-doc package to use this program." appears in the output to give you a hint about what's going on (but when the help text is long and piped to a pager, this line is not always visible).

Solution: install perldoc (e.g. apt install perl-doc on Ubuntu). After this:

$ perl test.perl 
NAME
    Minimal example

SYNOPSIS
    This is the synopsys section.