Pod::Usage not working correctly

Question

I have:

my $man = 0;
my $help = 0;
## Parse options and print usage if there is a syntax error,
## or if usage was explicitly requested.
GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
pod2usage(1) if $help;
pod2usage(-verbose => 2) if $man;

#-----------------------------------------------------------------
#----------------  Documentation / Usage / Help ------------------
=head1 NAME
  sample - Using GetOpt::Long and Pod::Usage

=head1 SYNOPSIS
  sample [options] [file ...]
   Options:
     -help            brief help message
     -man             full documentation

=head1 OPTIONS
  =over 8
  =item B<-help>  
    Print a brief help message and exits.
  =item B<-man>
    Prints the manual page and exits.
  =back

=head1 DESCRIPTION
  B<This program> will read the given input file(s) and do something
  useful with the contents thereof.
=cut

Pretty much copy / pasted from the online example. However, when I do script.pl --help nothing prints, and the script exits.

Answer 1

As has been stated, the spacing of pod documentation matters. Additionally, it's not necessary to duplicate your options in the synopsis, instead just leave them in the options section.

The following is a cleaned up version of your trial usage of Pod::Usage

use strict;
use warnings;

use Getopt::Long qw(GetOptions);
use Pod::Usage qw(pod2usage);

## Parse options and print usage if there is a syntax error,
## or if usage was explicitly requested.

GetOptions(
    'help|?'    => \my $help,
    'man'       => \my $man,
) or pod2usage(-verbose => 0);
pod2usage(-verbose => 1) if $help;
pod2usage(-verbose => 2) if $man;

## Check for File
pod2usage("$0: No filename specified.\n") unless @ARGV;

#-----------------------------------------------------------------
#----------------  Documentation / Usage / Help ------------------
=head1 NAME

sample - Using GetOpt::Long and Pod::Usage

=head1 SYNOPSIS

sample [file]

=head1 OPTIONS

=over 8

=item B<--help>  

Print a brief help message and exits.

=item B<--man>

Prints the manual page and exits.

=back

=head1 DESCRIPTION

B<This program> will read the given input file(s) and do something
useful with the contents thereof.

=cut

Answer 2

Miller has the answer.

When you create POD documentation, you need a blank line between each paragraph including the command paragraphs. The POD Documentation does not make that clear. Also, all POD command paragraphs must start in the first column. For example, this is wrong:

=head1 NAME
foo.cmd
=head1 DESCRIPTION
This is my description of my command.
....

I need to space this out:

=head1 NAME

foo.cmd

=head1 DESCRIPTION

This is my description.

Otherwise, POD would interpret it this way:

=head1 NAME foo.cmd =head1 DESCRIPTION This is my description of my command.

Now, you don't have a header named NAME or DESCRIPTION, so your pod2usage won't print.

I also need to start my commands on column 1. This won't work:

=over 4

    =item *
        blah, blah, blah...

I need to do this:

=over 4

=item *

blah, blah, blah

=back

You can run the podchecker program to check your pod and make sure everything is correct. This should be in the same directory as the perl command. I put your pod documentation into test.pod and ran this command:

$ podchecker test.pod
*** WARNING: empty section in previous paragraph at line 4 in file test.pod
*** WARNING: empty section in previous paragraph at line 10 in file test.pod
*** ERROR: Apparent command =cut not preceded by blank line at line 21 in file test.pod
*** WARNING: empty section in previous paragraph at line 18 in file test.pod
test.pod has 1 pod syntax error.

The empty section in previous paragraph warnings come from not skipping a line after =head1.