How do I add multiple PODs to the end of my perl script?

Question

I was working with a tutorial found in the perl documentation about how to use Getopt::Long in a script. In there it shows how to add documentation using Pod::Usage rather then having to type everything out a subroutine or something. Anyhow in the example they have this;

    GetOptions('help|?' => \$help, 'b|backup' => \&backup, d|discover => \&discover, man => \$man) or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-exitstatus => 0, -verbose => 2) if $man;

I added some of my own arguments.

I get how to refer to the first section of documentation. But how do I refer to the second section as stated by pod2usage(2)?

When I add a new section after the =cut at the end of section 1, when I try to have it display it I am met with a command prompt, like it went in and then out without show the section. Am I doing something wrong?

Answer 1

You don't need "multiple PODs".

pod2usage, when called as, e.g., pod2usage(1), here the 1 represents the exit status, and the verbosity level is implied as 1, so it will print the SYNOPSIS, and any sections titled OPTIONS, ARGUMENTS or OPTIONS AND ARGUMENTS

When called as pod2usage(-exitval => 0, -verbose => 2), it will print the entirety of the POD, within your text pager (identical to what perldoc yourscriptname.pl would do) and exit with 0. (Note it's -exitval and not -exitstatus).

It's well-described in the Pod::Usage documentation here, and works just as described.

You may find the optional -sections parameter to pod2usage useful for what you have described, combined with -verbose => 1, to pick and choose what you wish to display.