-exitval => 2,              -verbose => 0,              -output  => \*STDERR);Each of the following invocations of C<pod2usage()> will print the"SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections toC<STDOUT> and will exit with a status of 1:    pod2usage(1);    pod2usage(-verbose => 1);    pod2usage(-exitval => 1);    pod2usage({-exitval => 1, -output => \*STDOUT});    pod2usage({-verbose => 1, -output => \*STDOUT});    pod2usage(-exitval => 1, -verbose => 1);    pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});Each of the following invocations of C<pod2usage()> will print theentire manual page to C<STDOUT> and will exit with a status of 1:    pod2usage(-verbose  => 2);    pod2usage({-verbose => 2, -output => \*STDOUT});    pod2usage(-exitval  => 1, -verbose => 2);    pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});=head2 Recommended UseMost scripts should print some type of usage message to C<STDERR> when acommand line syntax error is detected. They should also provide anoption (usually C<-H> or C<-help>) to print a (possibly more verbose)usage message to C<STDOUT>. Some scripts may even wish to go so far as toprovide a means of printing their complete documentation to C<STDOUT>(perhaps by allowing a C<-man> option). The following complete exampleuses B<Pod::Usage> in combination with B<Getopt::Long> to do all of thesethings:    use Getopt::Long;    use Pod::Usage;    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;    ## If no arguments were given, then allow STDIN to be used only    ## if it's not connected to a terminal (otherwise print usage)    pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));    __END__    =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=head1 CAVEATSBy default, B<pod2usage()> will use C<$0> as the path to the pod inputfile.  Unfortunately, not all systems on which Perl runs will set C<$0>properly (although if C<$0> isn't found, B<pod2usage()> will searchC<$ENV{PATH}> or else the list specified by the C<-pathlist> option).If this is the case for your system, you may need to explicitly specifythe path to the pod docs for the invoking script using somethingsimilar to the following:    pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");=head1 AUTHORBrad Appleton E<lt>bradapp@enteract.comE<gt>Based on code for B<Pod::Text::pod2text()> written byTom Christiansen E<lt>tchrist@mox.perl.comE<gt>=head1 ACKNOWLEDGEMENTSSteven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patiencewith re-writing this manpage.=cut#############################################################################use strict;#use diagnostics;use Carp;use Exporter;use File::Spec;use vars qw(@ISA @EXPORT);@EXPORT = qw(&pod2usage);BEGIN {    if ( $] >= 5.005_58 ) {       require Pod::Text;       @ISA = qw( Pod::Text );    }    else {       require Pod::PlainText;       @ISA = qw( Pod::PlainText );    }}##---------------------------------------------------------------------------##---------------------------------## Function definitions begin here##---------------------------------sub pod2usage {    local($_) = shift || "";    my %opts;    ## Collect arguments    if (@_ > 0) {        ## Too many arguments - assume that this is a hash and        ## the user forgot to pass a reference to it.        %opts = ($_, @_);    }    elsif (ref $_) {        ## User passed a ref to a hash        %opts = %{$_}  if (ref($_) eq 'HASH');    }    elsif (/^[-+]?\d+$/) {        ## User passed in the exit value to use        $opts{"-exitval"} =  $_;    }    else {        ## User passed in a message to print before issuing usage.        $_  and  $opts{"-message"} = $_;    }    ## Need this for backward compatibility since we formerly used    ## options that were all uppercase words rather than ones that    ## looked like Unix command-line options.    ## to be uppercase keywords)    %opts = map {        my $val = $opts{$_};        s/^(?=\w)/-/;        /^-msg/i   and  $_ = '-message';        /^-exit/i  and  $_ = '-exitval';        lc($_) => $val;        } (keys %opts);    ## Now determine default -exitval and -verbose values to use    if ((! defined $opts{"-exitval"}) && (! defined $opts{"-verbose"})) {        $opts{"-exitval"} = 2;        $opts{"-verbose"} = 0;    }    elsif (! defined $opts{"-exitval"}) {        $opts{"-exitval"} = ($opts{"-verbose"} > 0) ? 1 : 2;    }    elsif (! defined $opts{"-verbose"}) {        $opts{"-verbose"} = ($opts{"-exitval"} < 2);    }    ## Default the output file    $opts{"-output"} = ($opts{"-exitval"} < 2) ? \*STDOUT : \*STDERR            unless (defined $opts{"-output"});    ## Default the input file    $opts{"-input"} = $0  unless (defined $opts{"-input"});    ## Look up input file in path if it doesnt exist.    unless ((ref $opts{"-input"}) || (-e $opts{"-input"})) {        my ($dirname, $basename) = ('', $opts{"-input"});        my $pathsep = ($^O =~ /^(?:dos|os2|MSWin32)$/) ? ";"                            : (($^O eq 'MacOS') ? ',' :  ":");        my $pathspec = $opts{"-pathlist"} || $ENV{PATH} || $ENV{PERL5LIB};        my @paths = (ref $pathspec) ? @$pathspec : split($pathsep, $pathspec);        for $dirname (@paths) {            $_ = File::Spec->catfile($dirname, $basename)  if length;            last if (-e $_) && ($opts{"-input"} = $_);        }    }    ## Now create a pod reader and constrain it to the desired sections.    my $parser = new Pod::Usage(USAGE_OPTIONS => \%opts);    if ($opts{"-verbose"} == 0) {        $parser->select("SYNOPSIS");    }    elsif ($opts{"-verbose"} == 1) {        my $opt_re = '(?i)' .                     '(?:OPTIONS|ARGUMENTS)' .                     '(?:\s*(?:AND|\/)\s*(?:OPTIONS|ARGUMENTS))?';        $parser->select( 'SYNOPSIS', $opt_re, "DESCRIPTION/$opt_re" );    }    ## Now translate the pod document and then exit with the desired status    $parser->parse_from_file($opts{"-input"}, $opts{"-output"});    exit($opts{"-exitval"});}##---------------------------------------------------------------------------##-------------------------------## Method definitions begin here##-------------------------------sub new {    my $this = shift;    my $class = ref($this) || $this;    my %params = @_;    my $self = {%params};    bless $self, $class;    $self->initialize();    return $self;}sub begin_pod {    my $self = shift;    $self->SUPER::begin_pod();  ## Have to call superclass    my $msg = $self->{USAGE_OPTIONS}->{-message}  or  return 1;    my $out_fh = $self->output_handle();    print $out_fh "$msg\n";}sub preprocess_paragraph {    my $self = shift;    local $_ = shift;    my $line = shift;    ## See if this is a heading and we arent printing the entire manpage.    if (($self->{USAGE_OPTIONS}->{-verbose} < 2) && /^=head/) {        ## Change the title of the SYNOPSIS section to USAGE        s/^=head1\s+SYNOPSIS\s*$/=head1 USAGE/;        ## Try to do some lowercasing instead of all-caps in headings        s{([A-Z])([A-Z]+)}{((length($2) > 2) ? $1 : lc($1)) . lc($2)}ge;        ## Use a colon to end all headings        s/\s*$/:/  unless (/:\s*$/);        $_ .= "\n";    }    return  $self->SUPER::preprocess_paragraph($_);}