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.

I'm sorry, I'm obviously pretty new to perl - what do you mean by legal POD? — MrDuk, Apr 01 '14 at 16:32
You know the part where you said you "pretty much copy / pasted from the online example"? Well, it seems that every change you made was an error. — ikegami, Apr 01 '14 at 16:34
In particular, the indentation mangles it badly. In POD, indented text is a verbatim block, so an indented `=item` is not a POD *item* at all. You can verify this by running `pod2text` on your file. — tripleee, Apr 01 '14 at 16:39
Re "I had no clue spacing was such an issue in Perl", The Perl is fine. The problem is with the POD. — ikegami, Apr 01 '14 at 18:23

score 2 · Answer 1 · answered Apr 01 '14 at 18:31

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

score 1 · Answer 2 · edited May 23 '17 at 11:49

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.

Thanks for chiming in to explain more about POD syntax. This is one area where I don't fully know all the rules, I just follow them by appropriate use of Cntl-C & Cntl-V — Miller, Apr 01 '14 at 21:47
The rules of POD are pretty straight forward. See [Perlpod](http://perldoc.perl.org/perlpod.html), [Perlpodspec](http://perldoc.perl.org/perlpodspec.html), and [Perlpodstyle](http://perldoc.perl.org/perlpodstyle.html). The major issue is that none of these documents make it clear that you need a blank line between each of these _commands_. Personally, I think POD was great. It's simple, but powerful. However, it should now be retired (or at least allow) Markdown which is just as powerful, and easier to read in raw form. — David W., Apr 02 '14 at 14:03
[Pod::Usage](http://perldoc.perl.org/Pod/Usage.html) sort of _breaks_ the way POD works because it requires specific section names of _SYNOPSIS_ and _OPTIONS_, or _ARGUMENTS_ or _OPTIONS AND ARGUMENTS_. This works fine for POD documentation in manpage style and _in English_. But, all heck breaks loose if you put how your program works under a setting called _DESCRIPTION_, or maybe _USAGE_. You can set `--verbose` to `99`, and provide the sections you want, but that's not very convenient. — David W., Apr 02 '14 at 14:12

Pod::Usage not working correctly

2 Answers2