0

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?

Mogsdad
  • 44,709
  • 21
  • 151
  • 275
AtomicPorkchop
  • 2,625
  • 5
  • 36
  • 55

1 Answers1

3

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.

Sdaz MacSkibbons
  • 27,668
  • 7
  • 32
  • 34
  • Ok I looked over the Pod::Usage docs more slowly and saw the part that are talking about. The only part I can't seem to get working is the GetOptions..... or pod2usage(2); It just dumps to a prompt, it does not display the menu like it should. Just to see I edited one of the my command flags to do the same thing as pod2usage(2) and it works perfect. – AtomicPorkchop Jan 20 '11 at 06:01
  • 1
    In your example, none of the options are required options, and as such, `GetOptions` returns true (well, `1`), so the `or pod2usage(2);` clause is never executed. Has nothing to do with `pod2usage`. – Sdaz MacSkibbons Jan 20 '11 at 06:09
  • But doesn't no args = 0? Which would fire the or clause. – AtomicPorkchop Jan 20 '11 at 06:20
  • Nope, GetOptions "will return a true value if the command line could be processed successfully. Otherwise, it will write error messages to STDERR, and return a false result." (From the Getopt::Long documentation). Since there were no *required* arguments, it was "processed successfully." – Sdaz MacSkibbons Jan 20 '11 at 06:27