This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Pod-Usage to CPAN version 1.63
[perl5.git] / cpan / Pod-Usage / lib / Pod / Usage.pm
index e09d69e..f0dd835 100644 (file)
-#############################################################################\r
-# Pod/Usage.pm -- print usage messages for the running script.\r
-#\r
-# Copyright (C) 1996-2000 by Bradford Appleton. All rights reserved.\r
-# This file is part of "PodParser". PodParser is free software;\r
-# you can redistribute it and/or modify it under the same terms\r
-# as Perl itself.\r
-#############################################################################\r
-\r
-package Pod::Usage;\r
-use strict;\r
-\r
-use vars qw($VERSION @ISA @EXPORT);\r
-$VERSION = '1.61';  ## Current version of this package\r
-require  5.005;    ## requires this Perl version or later\r
-\r
-#use diagnostics;\r
-use Carp;\r
-use Config;\r
-use Exporter;\r
-use File::Spec;\r
-\r
-@EXPORT = qw(&pod2usage);\r
-BEGIN {\r
-    $Pod::Usage::Formatter ||=\r
-      ( $] >= 5.005_58 ? 'Pod::Text' : 'Pod::PlainText');\r
-    eval "require $Pod::Usage::Formatter";\r
-    die $@ if $@;\r
-    @ISA = ( $Pod::Usage::Formatter );\r
-}\r
-\r
-require Pod::Select;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-##---------------------------------\r
-## Function definitions begin here\r
-##---------------------------------\r
-\r
-sub pod2usage {\r
-    local($_) = shift;\r
-    my %opts;\r
-    ## Collect arguments\r
-    if (@_ > 0) {\r
-        ## Too many arguments - assume that this is a hash and\r
-        ## the user forgot to pass a reference to it.\r
-        %opts = ($_, @_);\r
-    }\r
-    elsif (!defined $_) {\r
-      $_ = '';\r
-    }\r
-    elsif (ref $_) {\r
-        ## User passed a ref to a hash\r
-        %opts = %{$_}  if (ref($_) eq 'HASH');\r
-    }\r
-    elsif (/^[-+]?\d+$/) {\r
-        ## User passed in the exit value to use\r
-        $opts{'-exitval'} =  $_;\r
-    }\r
-    else {\r
-        ## User passed in a message to print before issuing usage.\r
-        $_  and  $opts{'-message'} = $_;\r
-    }\r
-\r
-    ## Need this for backward compatibility since we formerly used\r
-    ## options that were all uppercase words rather than ones that\r
-    ## looked like Unix command-line options.\r
-    ## to be uppercase keywords)\r
-    %opts = map {\r
-        my ($key, $val) = ($_, $opts{$_});\r
-        $key =~ s/^(?=\w)/-/;\r
-        $key =~ /^-msg/i   and  $key = '-message';\r
-        $key =~ /^-exit/i  and  $key = '-exitval';\r
-        lc($key) => $val;\r
-    } (keys %opts);\r
-\r
-    ## Now determine default -exitval and -verbose values to use\r
-    if ((! defined $opts{'-exitval'}) && (! defined $opts{'-verbose'})) {\r
-        $opts{'-exitval'} = 2;\r
-        $opts{'-verbose'} = 0;\r
-    }\r
-    elsif (! defined $opts{'-exitval'}) {\r
-        $opts{'-exitval'} = ($opts{'-verbose'} > 0) ? 1 : 2;\r
-    }\r
-    elsif (! defined $opts{'-verbose'}) {\r
-        $opts{'-verbose'} = (lc($opts{'-exitval'}) eq 'noexit' ||\r
-                             $opts{'-exitval'} < 2);\r
-    }\r
-\r
-    ## Default the output file\r
-    $opts{'-output'} = (lc($opts{'-exitval'}) eq 'noexit' ||\r
-                        $opts{'-exitval'} < 2) ? \*STDOUT : \*STDERR\r
-            unless (defined $opts{'-output'});\r
-    ## Default the input file\r
-    $opts{'-input'} = $0  unless (defined $opts{'-input'});\r
-\r
-    ## Look up input file in path if it doesnt exist.\r
-    unless ((ref $opts{'-input'}) || (-e $opts{'-input'})) {\r
-        my $basename = $opts{'-input'};\r
-        my $pathsep = ($^O =~ /^(?:dos|os2|MSWin32)$/i) ? ';'\r
-                            : (($^O eq 'MacOS' || $^O eq 'VMS') ? ',' :  ':');\r
-        my $pathspec = $opts{'-pathlist'} || $ENV{PATH} || $ENV{PERL5LIB};\r
-\r
-        my @paths = (ref $pathspec) ? @$pathspec : split($pathsep, $pathspec);\r
-        for my $dirname (@paths) {\r
-            $_ = File::Spec->catfile($dirname, $basename)  if length;\r
-            last if (-e $_) && ($opts{'-input'} = $_);\r
-        }\r
-    }\r
-\r
-    ## Now create a pod reader and constrain it to the desired sections.\r
-    my $parser = new Pod::Usage(USAGE_OPTIONS => \%opts);\r
-    if ($opts{'-verbose'} == 0) {\r
-        $parser->select('(?:SYNOPSIS|USAGE)\s*');\r
-    }\r
-    elsif ($opts{'-verbose'} == 1) {\r
-        my $opt_re = '(?i)' .\r
-                     '(?:OPTIONS|ARGUMENTS)' .\r
-                     '(?:\s*(?:AND|\/)\s*(?:OPTIONS|ARGUMENTS))?';\r
-        $parser->select( '(?:SYNOPSIS|USAGE)\s*', $opt_re, "DESCRIPTION/$opt_re" );\r
-    }\r
-    elsif ($opts{'-verbose'} >= 2 && $opts{'-verbose'} != 99) {\r
-        $parser->select('.*');\r
-    }\r
-    elsif ($opts{'-verbose'} == 99) {\r
-        my $sections = $opts{'-sections'};\r
-        $parser->select( (ref $sections) ? @$sections : $sections );\r
-        $opts{'-verbose'} = 1;\r
-    }\r
-\r
-    ## Check for perldoc\r
-    my $progpath = File::Spec->catfile($Config{scriptdirexp} \r
-       || $Config{scriptdir}, 'perldoc');\r
-\r
-    my $version = sprintf("%vd",$^V);\r
-    if ($Config{versiononly} and $Config{startperl} =~ /\Q$version\E$/ ) {\r
-      $progpath .= $version;\r
-    }\r
-    $opts{'-noperldoc'} = 1 unless -e $progpath;\r
-\r
-    ## Now translate the pod document and then exit with the desired status\r
-    if (      !$opts{'-noperldoc'}\r
-         and  $opts{'-verbose'} >= 2\r
-         and  !ref($opts{'-input'})\r
-         and  $opts{'-output'} == \*STDOUT )\r
-    {\r
-       ## spit out the entire PODs. Might as well invoke perldoc\r
-       print { $opts{'-output'} } ($opts{'-message'}, "\n") if($opts{'-message'});\r
-       if(defined $opts{-input} && $opts{-input} =~ /^\s*(\S.*?)\s*$/) {\r
-         # the perldocs back to 5.005 should all have -F\r
-        # without -F there are warnings in -T scripts\r
-         system($progpath, '-F', $1);\r
-         if($?) {\r
-           # RT16091: fall back to more if perldoc failed\r
-           system(($Config{pager} || $ENV{PAGER} || '/bin/more'), $1);\r
-         }\r
-       } else {\r
-         croak "Unspecified input file or insecure argument.\n";\r
-       }\r
-    }\r
-    else {\r
-       $parser->parse_from_file($opts{'-input'}, $opts{'-output'});\r
-    }\r
-\r
-    exit($opts{'-exitval'})  unless (lc($opts{'-exitval'}) eq 'noexit');\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-##-------------------------------\r
-## Method definitions begin here\r
-##-------------------------------\r
-\r
-sub new {\r
-    my $this = shift;\r
-    my $class = ref($this) || $this;\r
-    my %params = @_;\r
-    my $self = {%params};\r
-    bless $self, $class;\r
-    if ($self->can('initialize')) {\r
-        $self->initialize();\r
-    } else {\r
-        # pass through options to Pod::Text\r
-        my %opts;\r
-               for (qw(alt code indent loose margin quotes sentence stderr utf8 width)) {\r
-            my $val = $params{USAGE_OPTIONS}{"-$_"};\r
-            $opts{$_} = $val if defined $val;\r
-        }\r
-        $self = $self->SUPER::new(%opts);\r
-        %$self = (%$self, %params);\r
-    }\r
-    return $self;\r
-}\r
-\r
-sub select {\r
-    my ($self, @sections) = @_;\r
-    if ($ISA[0]->can('select')) {\r
-        $self->SUPER::select(@sections);\r
-    } else {\r
-        # we're using Pod::Simple - need to mimic the behavior of Pod::Select\r
-        my $add = ($sections[0] eq '+') ? shift(@sections) : '';\r
-        ## Reset the set of sections to use\r
-        unless (@sections) {\r
-          delete $self->{USAGE_SELECT} unless ($add);\r
-          return;\r
-        }\r
-        $self->{USAGE_SELECT} = []\r
-          unless ($add && $self->{USAGE_SELECT});\r
-        my $sref = $self->{USAGE_SELECT};\r
-        ## Compile each spec\r
-        for my $spec (@sections) {\r
-          my $cs = Pod::Select::_compile_section_spec($spec);\r
-          if ( defined $cs ) {\r
-            ## Store them in our sections array\r
-            push(@$sref, $cs);\r
-          } else {\r
-            carp qq{Ignoring section spec "$spec"!\n};\r
-          }\r
-        }\r
-    }\r
-}\r
-\r
-# Override Pod::Text->seq_i to return just "arg", not "*arg*".\r
-sub seq_i { return $_[1] }\r
-\r
-# This overrides the Pod::Text method to do something very akin to what\r
-# Pod::Select did as well as the work done below by preprocess_paragraph.\r
-# Note that the below is very, very specific to Pod::Text.\r
-sub _handle_element_end {\r
-    my ($self, $element) = @_;\r
-    if ($element eq 'head1') {\r
-        $self->{USAGE_HEADINGS} = [ $$self{PENDING}[-1][1] ];\r
-        if ($self->{USAGE_OPTIONS}->{-verbose} < 2) {\r
-            $$self{PENDING}[-1][1] =~ s/^\s*SYNOPSIS\s*$/USAGE/;\r
-        }\r
-    } elsif ($element =~ /^head(\d+)$/ && $1) { # avoid 0\r
-        my $idx = $1 - 1;\r
-        $self->{USAGE_HEADINGS} = [] unless($self->{USAGE_HEADINGS});\r
-        $self->{USAGE_HEADINGS}->[$idx] = $$self{PENDING}[-1][1];\r
-    }\r
-    if ($element =~ /^head\d+$/) {\r
-        $$self{USAGE_SKIPPING} = 1;\r
-        if (!$$self{USAGE_SELECT} || !@{ $$self{USAGE_SELECT} }) {\r
-            $$self{USAGE_SKIPPING} = 0;\r
-        } else {\r
-            my @headings = @{$$self{USAGE_HEADINGS}};\r
-            for my $section_spec ( @{$$self{USAGE_SELECT}} ) {\r
-                my $match = 1;\r
-                for (my $i = 0; $i < $Pod::Select::MAX_HEADING_LEVEL; ++$i) {\r
-                    $headings[$i] = '' unless defined $headings[$i];\r
-                    my $regex   = $section_spec->[$i];\r
-                    my $negated = ($regex =~ s/^\!//);\r
-                    $match  &= ($negated ? ($headings[$i] !~ /${regex}/)\r
-                                         : ($headings[$i] =~ /${regex}/));\r
-                    last unless ($match);\r
-                } # end heading levels\r
-                if ($match) {\r
-                  $$self{USAGE_SKIPPING} = 0;\r
-                  last;\r
-                }\r
-            } # end sections\r
-        }\r
-\r
-        # Try to do some lowercasing instead of all-caps in headings, and use\r
-        # a colon to end all headings.\r
-        if($self->{USAGE_OPTIONS}->{-verbose} < 2) {\r
-            local $_ = $$self{PENDING}[-1][1];\r
-            s{([A-Z])([A-Z]+)}{((length($2) > 2) ? $1 : lc($1)) . lc($2)}ge;\r
-            s/\s*$/:/  unless (/:\s*$/);\r
-            $_ .= "\n";\r
-            $$self{PENDING}[-1][1] = $_;\r
-        }\r
-    }\r
-    if ($$self{USAGE_SKIPPING} && $element !~ m/^over-/) {\r
-        pop @{ $$self{PENDING} };\r
-    } else {\r
-        $self->SUPER::_handle_element_end($element);\r
-    }\r
-}\r
-\r
-# required for Pod::Simple API\r
-sub start_document {\r
-    my $self = shift;\r
-    $self->SUPER::start_document();\r
-    my $msg = $self->{USAGE_OPTIONS}->{-message}  or  return 1;\r
-    my $out_fh = $self->output_fh();\r
-    print $out_fh "$msg\n";\r
-}\r
-\r
-# required for old Pod::Parser API\r
-sub begin_pod {\r
-    my $self = shift;\r
-    $self->SUPER::begin_pod();  ## Have to call superclass\r
-    my $msg = $self->{USAGE_OPTIONS}->{-message}  or  return 1;\r
-    my $out_fh = $self->output_handle();\r
-    print $out_fh "$msg\n";\r
-}\r
-\r
-sub preprocess_paragraph {\r
-    my $self = shift;\r
-    local $_ = shift;\r
-    my $line = shift;\r
-    ## See if this is a heading and we arent printing the entire manpage.\r
-    if (($self->{USAGE_OPTIONS}->{-verbose} < 2) && /^=head/) {\r
-        ## Change the title of the SYNOPSIS section to USAGE\r
-        s/^=head1\s+SYNOPSIS\s*$/=head1 USAGE/;\r
-        ## Try to do some lowercasing instead of all-caps in headings\r
-        s{([A-Z])([A-Z]+)}{((length($2) > 2) ? $1 : lc($1)) . lc($2)}ge;\r
-        ## Use a colon to end all headings\r
-        s/\s*$/:/  unless (/:\s*$/);\r
-        $_ .= "\n";\r
-    }\r
-    return  $self->SUPER::preprocess_paragraph($_);\r
-}\r
-\r
-1; # keep require happy\r
-\r
-__END__\r
-\r
-=head1 NAME\r
-\r
-Pod::Usage, pod2usage() - print a usage message from embedded pod documentation\r
-\r
-=head1 SYNOPSIS\r
-\r
-  use Pod::Usage\r
-\r
-  my $message_text  = "This text precedes the usage message.";\r
-  my $exit_status   = 2;          ## The exit status to use\r
-  my $verbose_level = 0;          ## The verbose level to use\r
-  my $filehandle    = \*STDERR;   ## The filehandle to write to\r
-\r
-  pod2usage($message_text);\r
-\r
-  pod2usage($exit_status);\r
-\r
-  pod2usage( { -message => $message_text ,\r
-               -exitval => $exit_status  ,  \r
-               -verbose => $verbose_level,  \r
-               -output  => $filehandle } );\r
-\r
-  pod2usage(   -msg     => $message_text ,\r
-               -exitval => $exit_status  ,  \r
-               -verbose => $verbose_level,  \r
-               -output  => $filehandle   );\r
-\r
-  pod2usage(   -verbose => 2,\r
-               -noperldoc => 1  )\r
-\r
-=head1 ARGUMENTS\r
-\r
-B<pod2usage> should be given either a single argument, or a list of\r
-arguments corresponding to an associative array (a "hash"). When a single\r
-argument is given, it should correspond to exactly one of the following:\r
-\r
-=over 4\r
-\r
-=item *\r
-\r
-A string containing the text of a message to print I<before> printing\r
-the usage message\r
-\r
-=item *\r
-\r
-A numeric value corresponding to the desired exit status\r
-\r
-=item *\r
-\r
-A reference to a hash\r
-\r
-=back\r
-\r
-If more than one argument is given then the entire argument list is\r
-assumed to be a hash.  If a hash is supplied (either as a reference or\r
-as a list) it should contain one or more elements with the following\r
-keys:\r
-\r
-=over 4\r
-\r
-=item C<-message>\r
-\r
-=item C<-msg>\r
-\r
-The text of a message to print immediately prior to printing the\r
-program's usage message. \r
-\r
-=item C<-exitval>\r
-\r
-The desired exit status to pass to the B<exit()> function.\r
-This should be an integer, or else the string "NOEXIT" to\r
-indicate that control should simply be returned without\r
-terminating the invoking process.\r
-\r
-=item C<-verbose>\r
-\r
-The desired level of "verboseness" to use when printing the usage\r
-message. If the corresponding value is 0, then only the "SYNOPSIS"\r
-section of the pod documentation is printed. If the corresponding value\r
-is 1, then the "SYNOPSIS" section, along with any section entitled\r
-"OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed.  If the\r
-corresponding value is 2 or more then the entire manpage is printed.\r
-\r
-The special verbosity level 99 requires to also specify the -sections\r
-parameter; then these sections are extracted (see L<Pod::Select>)\r
-and printed.\r
-\r
-=item C<-sections>\r
-\r
-A string representing a selection list for sections to be printed\r
-when -verbose is set to 99, e.g. C<"NAME|SYNOPSIS|DESCRIPTION|VERSION">.\r
-\r
-Alternatively, an array reference of section specifications can be used:\r
-\r
-  pod2usage(-verbose => 99, \r
-            -sections => [ qw(fred fred/subsection) ] );\r
-\r
-=item C<-output>\r
-\r
-A reference to a filehandle, or the pathname of a file to which the\r
-usage message should be written. The default is C<\*STDERR> unless the\r
-exit value is less than 2 (in which case the default is C<\*STDOUT>).\r
-\r
-=item C<-input>\r
-\r
-A reference to a filehandle, or the pathname of a file from which the\r
-invoking script's pod documentation should be read.  It defaults to the\r
-file indicated by C<$0> (C<$PROGRAM_NAME> for users of F<English.pm>).\r
-\r
-If you are calling B<pod2usage()> from a module and want to display\r
-that module's POD, you can use this:\r
-\r
-  use Pod::Find qw(pod_where);\r
-  pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );\r
-\r
-=item C<-pathlist>\r
-\r
-A list of directory paths. If the input file does not exist, then it\r
-will be searched for in the given directory list (in the order the\r
-directories appear in the list). It defaults to the list of directories\r
-implied by C<$ENV{PATH}>. The list may be specified either by a reference\r
-to an array, or by a string of directory paths which use the same path\r
-separator as C<$ENV{PATH}> on your system (e.g., C<:> for Unix, C<;> for\r
-MSWin32 and DOS).\r
-\r
-=item C<-noperldoc>\r
-\r
-By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is\r
-specified. This does not work well e.g. if the script was packed\r
-with L<PAR>. The -noperldoc option suppresses the external call to\r
-L<perldoc> and uses the simple text formatter (L<Pod::Text>) to \r
-output the POD.\r
-\r
-=back\r
-\r
-=head2 Formatting base class\r
-\r
-The default text formatter depends on the Perl version (L<Pod::Text> or \r
-L<Pod::PlainText> for Perl versions E<lt> 5.005_58). The base class for\r
-Pod::Usage can be defined by pre-setting C<$Pod::Usage::Formatter> I<before>\r
-loading Pod::Usage, e.g.:\r
-\r
-    BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }\r
-    use Pod::Usage qw(pod2usage);\r
-\r
-=head2 Pass-through options\r
-\r
-The following options are passed through to the underlying text formatter.\r
-See the manual pages of these modules for more information.\r
-\r
-  alt code indent loose margin quotes sentence stderr utf8 width\r
-\r
-=head1 DESCRIPTION\r
-\r
-B<pod2usage> will print a usage message for the invoking script (using\r
-its embedded pod documentation) and then exit the script with the\r
-desired exit status. The usage message printed may have any one of three\r
-levels of "verboseness": If the verbose level is 0, then only a synopsis\r
-is printed. If the verbose level is 1, then the synopsis is printed\r
-along with a description (if present) of the command line options and\r
-arguments. If the verbose level is 2, then the entire manual page is\r
-printed.\r
-\r
-Unless they are explicitly specified, the default values for the exit\r
-status, verbose level, and output stream to use are determined as\r
-follows:\r
-\r
-=over 4\r
-\r
-=item *\r
-\r
-If neither the exit status nor the verbose level is specified, then the\r
-default is to use an exit status of 2 with a verbose level of 0.\r
-\r
-=item *\r
-\r
-If an exit status I<is> specified but the verbose level is I<not>, then the\r
-verbose level will default to 1 if the exit status is less than 2 and\r
-will default to 0 otherwise.\r
-\r
-=item *\r
-\r
-If an exit status is I<not> specified but verbose level I<is> given, then\r
-the exit status will default to 2 if the verbose level is 0 and will\r
-default to 1 otherwise.\r
-\r
-=item *\r
-\r
-If the exit status used is less than 2, then output is printed on\r
-C<STDOUT>.  Otherwise output is printed on C<STDERR>.\r
-\r
-=back\r
-\r
-Although the above may seem a bit confusing at first, it generally does\r
-"the right thing" in most situations.  This determination of the default\r
-values to use is based upon the following typical Unix conventions:\r
-\r
-=over 4\r
-\r
-=item *\r
-\r
-An exit status of 0 implies "success". For example, B<diff(1)> exits\r
-with a status of 0 if the two files have the same contents.\r
-\r
-=item *\r
-\r
-An exit status of 1 implies possibly abnormal, but non-defective, program\r
-termination.  For example, B<grep(1)> exits with a status of 1 if\r
-it did I<not> find a matching line for the given regular expression.\r
-\r
-=item *\r
-\r
-An exit status of 2 or more implies a fatal error. For example, B<ls(1)>\r
-exits with a status of 2 if you specify an illegal (unknown) option on\r
-the command line.\r
-\r
-=item *\r
-\r
-Usage messages issued as a result of bad command-line syntax should go\r
-to C<STDERR>.  However, usage messages issued due to an explicit request\r
-to print usage (like specifying B<-help> on the command line) should go\r
-to C<STDOUT>, just in case the user wants to pipe the output to a pager\r
-(such as B<more(1)>).\r
-\r
-=item *\r
-\r
-If program usage has been explicitly requested by the user, it is often\r
-desirable to exit with a status of 1 (as opposed to 0) after issuing\r
-the user-requested usage message.  It is also desirable to give a\r
-more verbose description of program usage in this case.\r
-\r
-=back\r
-\r
-B<pod2usage> doesn't force the above conventions upon you, but it will\r
-use them by default if you don't expressly tell it to do otherwise.  The\r
-ability of B<pod2usage()> to accept a single number or a string makes it\r
-convenient to use as an innocent looking error message handling function:\r
-\r
-    use Pod::Usage;\r
-    use Getopt::Long;\r
-\r
-    ## Parse options\r
-    GetOptions("help", "man", "flag1")  ||  pod2usage(2);\r
-    pod2usage(1)  if ($opt_help);\r
-    pod2usage(-verbose => 2)  if ($opt_man);\r
-\r
-    ## Check for too many filenames\r
-    pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);\r
-\r
-Some user's however may feel that the above "economy of expression" is\r
-not particularly readable nor consistent and may instead choose to do\r
-something more like the following:\r
-\r
-    use Pod::Usage;\r
-    use Getopt::Long;\r
-\r
-    ## Parse options\r
-    GetOptions("help", "man", "flag1")  ||  pod2usage(-verbose => 0);\r
-    pod2usage(-verbose => 1)  if ($opt_help);\r
-    pod2usage(-verbose => 2)  if ($opt_man);\r
-\r
-    ## Check for too many filenames\r
-    pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")\r
-        if (@ARGV > 1);\r
-\r
-As with all things in Perl, I<there's more than one way to do it>, and\r
-B<pod2usage()> adheres to this philosophy.  If you are interested in\r
-seeing a number of different ways to invoke B<pod2usage> (although by no\r
-means exhaustive), please refer to L<"EXAMPLES">.\r
-\r
-=head1 EXAMPLES\r
-\r
-Each of the following invocations of C<pod2usage()> will print just the\r
-"SYNOPSIS" section to C<STDERR> and will exit with a status of 2:\r
-\r
-    pod2usage();\r
-\r
-    pod2usage(2);\r
-\r
-    pod2usage(-verbose => 0);\r
-\r
-    pod2usage(-exitval => 2);\r
-\r
-    pod2usage({-exitval => 2, -output => \*STDERR});\r
-\r
-    pod2usage({-verbose => 0, -output  => \*STDERR});\r
-\r
-    pod2usage(-exitval => 2, -verbose => 0);\r
-\r
-    pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);\r
-\r
-Each of the following invocations of C<pod2usage()> will print a message\r
-of "Syntax error." (followed by a newline) to C<STDERR>, immediately\r
-followed by just the "SYNOPSIS" section (also printed to C<STDERR>) and\r
-will exit with a status of 2:\r
-\r
-    pod2usage("Syntax error.");\r
-\r
-    pod2usage(-message => "Syntax error.", -verbose => 0);\r
-\r
-    pod2usage(-msg  => "Syntax error.", -exitval => 2);\r
-\r
-    pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});\r
-\r
-    pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});\r
-\r
-    pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);\r
-\r
-    pod2usage(-message => "Syntax error.",\r
-              -exitval => 2,\r
-              -verbose => 0,\r
-              -output  => \*STDERR);\r
-\r
-Each of the following invocations of C<pod2usage()> will print the\r
-"SYNOPSIS" section and any "OPTIONS" and/or "ARGUMENTS" sections to\r
-C<STDOUT> and will exit with a status of 1:\r
-\r
-    pod2usage(1);\r
-\r
-    pod2usage(-verbose => 1);\r
-\r
-    pod2usage(-exitval => 1);\r
-\r
-    pod2usage({-exitval => 1, -output => \*STDOUT});\r
-\r
-    pod2usage({-verbose => 1, -output => \*STDOUT});\r
-\r
-    pod2usage(-exitval => 1, -verbose => 1);\r
-\r
-    pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});\r
-\r
-Each of the following invocations of C<pod2usage()> will print the\r
-entire manual page to C<STDOUT> and will exit with a status of 1:\r
-\r
-    pod2usage(-verbose  => 2);\r
-\r
-    pod2usage({-verbose => 2, -output => \*STDOUT});\r
-\r
-    pod2usage(-exitval  => 1, -verbose => 2);\r
-\r
-    pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});\r
-\r
-=head2 Recommended Use\r
-\r
-Most scripts should print some type of usage message to C<STDERR> when a\r
-command line syntax error is detected. They should also provide an\r
-option (usually C<-H> or C<-help>) to print a (possibly more verbose)\r
-usage message to C<STDOUT>. Some scripts may even wish to go so far as to\r
-provide a means of printing their complete documentation to C<STDOUT>\r
-(perhaps by allowing a C<-man> option). The following complete example\r
-uses B<Pod::Usage> in combination with B<Getopt::Long> to do all of these\r
-things:\r
-\r
-    use Getopt::Long;\r
-    use Pod::Usage;\r
-\r
-    my $man = 0;\r
-    my $help = 0;\r
-    ## Parse options and print usage if there is a syntax error,\r
-    ## or if usage was explicitly requested.\r
-    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);\r
-    pod2usage(1) if $help;\r
-    pod2usage(-verbose => 2) if $man;\r
-\r
-    ## If no arguments were given, then allow STDIN to be used only\r
-    ## if it's not connected to a terminal (otherwise print usage)\r
-    pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));\r
-    __END__\r
-\r
-    =head1 NAME\r
-\r
-    sample - Using GetOpt::Long and Pod::Usage\r
-\r
-    =head1 SYNOPSIS\r
-\r
-    sample [options] [file ...]\r
-\r
-     Options:\r
-       -help            brief help message\r
-       -man             full documentation\r
-\r
-    =head1 OPTIONS\r
-\r
-    =over 8\r
-\r
-    =item B<-help>\r
-\r
-    Print a brief help message and exits.\r
-\r
-    =item B<-man>\r
-\r
-    Prints the manual page and exits.\r
-\r
-    =back\r
-\r
-    =head1 DESCRIPTION\r
-\r
-    B<This program> will read the given input file(s) and do something\r
-    useful with the contents thereof.\r
-\r
-    =cut\r
-\r
-=head1 CAVEATS\r
-\r
-By default, B<pod2usage()> will use C<$0> as the path to the pod input\r
-file.  Unfortunately, not all systems on which Perl runs will set C<$0>\r
-properly (although if C<$0> isn't found, B<pod2usage()> will search\r
-C<$ENV{PATH}> or else the list specified by the C<-pathlist> option).\r
-If this is the case for your system, you may need to explicitly specify\r
-the path to the pod docs for the invoking script using something\r
-similar to the following:\r
-\r
-    pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");\r
-\r
-In the pathological case that a script is called via a relative path\r
-I<and> the script itself changes the current working directory\r
-(see L<perlfunc/chdir>) I<before> calling pod2usage, Pod::Usage will\r
-fail even on robust platforms. Don't do that. Or use L<FindBin> to locate\r
-the script:\r
-\r
-    use FindBin;\r
-    pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);\r
-\r
-=head1 AUTHOR\r
-\r
-Please report bugs using L<http://rt.cpan.org>.\r
-\r
-Marek Rouchal E<lt>marekr@cpan.orgE<gt>\r
-\r
-Brad Appleton E<lt>bradapp@enteract.comE<gt>\r
-\r
-Based on code for B<Pod::Text::pod2text()> written by\r
-Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>\r
-\r
-=head1 ACKNOWLEDGMENTS\r
-\r
-Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience\r
-with re-writing this manpage.\r
-\r
-=head1 SEE ALSO\r
-\r
-B<Pod::Usage> is now a standalone distribution.\r
-\r
-L<Pod::Parser>, L<Pod::Perldoc>, L<Getopt::Long>, L<Pod::Find>, L<FindBin>,\r
-L<Pod::Text>, L<Pod::PlainText>, L<Pod::Text::Termcap>\r
-\r
-=cut\r
-\r
+#############################################################################
+# Pod/Usage.pm -- print usage messages for the running script.
+#
+# Copyright (C) 1996-2000 by Bradford Appleton. All rights reserved.
+# This file is part of "PodParser". PodParser is free software;
+# you can redistribute it and/or modify it under the same terms
+# as Perl itself.
+#############################################################################
+
+package Pod::Usage;
+use strict;
+
+use vars qw($VERSION @ISA @EXPORT);
+$VERSION = '1.63';  ## Current version of this package
+require  5.006;    ## requires this Perl version or later
+
+#use diagnostics;
+use Carp;
+use Config;
+use Exporter;
+use File::Spec;
+
+@EXPORT = qw(&pod2usage);
+BEGIN {
+    $Pod::Usage::Formatter ||= 'Pod::Text';
+    eval "require $Pod::Usage::Formatter";
+    die $@ if $@;
+    @ISA = ( $Pod::Usage::Formatter );
+}
+
+our $MAX_HEADING_LEVEL = 3;
+
+##---------------------------------------------------------------------------
+
+##---------------------------------
+## 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 (!defined $_) {
+      $_ = '';
+    }
+    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 ($key, $val) = ($_, $opts{$_});
+        $key =~ s/^(?=\w)/-/;
+        $key =~ /^-msg/i   and  $key = '-message';
+        $key =~ /^-exit/i  and  $key = '-exitval';
+        lc($key) => $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'} = (lc($opts{'-exitval'}) eq 'noexit' ||
+                             $opts{'-exitval'} < 2);
+    }
+
+    ## Default the output file
+    $opts{'-output'} = (lc($opts{'-exitval'}) eq 'noexit' ||
+                        $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 doesn't exist.
+    unless ((ref $opts{'-input'}) || (-e $opts{'-input'})) {
+        my $basename = $opts{'-input'};
+        my $pathsep = ($^O =~ /^(?:dos|os2|MSWin32)$/i) ? ';'
+                            : (($^O eq 'MacOS' || $^O eq 'VMS') ? ',' :  ':');
+        my $pathspec = $opts{'-pathlist'} || $ENV{PATH} || $ENV{PERL5LIB};
+
+        my @paths = (ref $pathspec) ? @$pathspec : split($pathsep, $pathspec);
+        for my $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|USAGE)\s*');
+    }
+    elsif ($opts{'-verbose'} == 1) {
+        my $opt_re = '(?i)' .
+                     '(?:OPTIONS|ARGUMENTS)' .
+                     '(?:\s*(?:AND|\/)\s*(?:OPTIONS|ARGUMENTS))?';
+        $parser->select( '(?:SYNOPSIS|USAGE)\s*', $opt_re, "DESCRIPTION/$opt_re" );
+    }
+    elsif ($opts{'-verbose'} >= 2 && $opts{'-verbose'} != 99) {
+        $parser->select('.*');
+    }
+    elsif ($opts{'-verbose'} == 99) {
+        my $sections = $opts{'-sections'};
+        $parser->select( (ref $sections) ? @$sections : $sections );
+        $opts{'-verbose'} = 1;
+    }
+
+    ## Check for perldoc
+    my $progpath = File::Spec->catfile($Config{scriptdirexp} 
+       || $Config{scriptdir}, 'perldoc');
+
+    my $version = sprintf("%vd",$^V);
+    if ($Config{versiononly} and $Config{startperl} =~ /\Q$version\E$/ ) {
+      $progpath .= $version;
+    }
+    $opts{'-noperldoc'} = 1 unless -e $progpath;
+
+    ## Now translate the pod document and then exit with the desired status
+    if (      !$opts{'-noperldoc'}
+         and  $opts{'-verbose'} >= 2
+         and  !ref($opts{'-input'})
+         and  $opts{'-output'} == \*STDOUT )
+    {
+       ## spit out the entire PODs. Might as well invoke perldoc
+       print { $opts{'-output'} } ($opts{'-message'}, "\n") if($opts{'-message'});
+       if(defined $opts{-input} && $opts{-input} =~ /^\s*(\S.*?)\s*$/) {
+         # the perldocs back to 5.005 should all have -F
+        # without -F there are warnings in -T scripts
+         system($progpath, '-F', $1);
+         if($?) {
+           # RT16091: fall back to more if perldoc failed
+           system(($Config{pager} || $ENV{PAGER} || '/bin/more'), $1);
+         }
+       } else {
+         croak "Unspecified input file or insecure argument.\n";
+       }
+    }
+    else {
+       $parser->parse_from_file($opts{'-input'}, $opts{'-output'});
+    }
+
+    exit($opts{'-exitval'})  unless (lc($opts{'-exitval'}) eq 'noexit');
+}
+
+##---------------------------------------------------------------------------
+
+##-------------------------------
+## Method definitions begin here
+##-------------------------------
+
+sub new {
+    my $this = shift;
+    my $class = ref($this) || $this;
+    my %params = @_;
+    my $self = {%params};
+    bless $self, $class;
+    if ($self->can('initialize')) {
+        $self->initialize();
+    } else {
+        # pass through options to Pod::Text
+        my %opts;
+               for (qw(alt code indent loose margin quotes sentence stderr utf8 width)) {
+            my $val = $params{USAGE_OPTIONS}{"-$_"};
+            $opts{$_} = $val if defined $val;
+        }
+        $self = $self->SUPER::new(%opts);
+        %$self = (%$self, %params);
+    }
+    return $self;
+}
+
+# This subroutine was copied in whole-cloth from Pod::Select 1.60 in order to
+# allow the ejection of Pod::Select from the core without breaking Pod::Usage.
+# -- rjbs, 2013-03-18
+sub _compile_section_spec {
+    my ($section_spec) = @_;
+    my (@regexs, $negated);
+
+    ## Compile the spec into a list of regexs
+    local $_ = $section_spec;
+    s{\\\\}{\001}g;  ## handle escaped backward slashes
+    s{\\/}{\002}g;   ## handle escaped forward slashes
+
+    ## Parse the regexs for the heading titles
+    @regexs = split(/\//, $_, $MAX_HEADING_LEVEL);
+
+    ## Set default regex for ommitted levels
+    for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
+        $regexs[$i]  = '.*'  unless ((defined $regexs[$i])
+                                     && (length $regexs[$i]));
+    }
+    ## Modify the regexs as needed and validate their syntax
+    my $bad_regexs = 0;
+    for (@regexs) {
+        $_ .= '.+'  if ($_ eq '!');
+        s{\001}{\\\\}g;       ## restore escaped backward slashes
+        s{\002}{\\/}g;        ## restore escaped forward slashes
+        $negated = s/^\!//;   ## check for negation
+        eval "m{$_}";         ## check regex syntax
+        if ($@) {
+            ++$bad_regexs;
+            carp qq{Bad regular expression /$_/ in "$section_spec": $@\n};
+        }
+        else {
+            ## Add the forward and rear anchors (and put the negator back)
+            $_ = '^' . $_  unless (/^\^/);
+            $_ = $_ . '$'  unless (/\$$/);
+            $_ = '!' . $_  if ($negated);
+        }
+    }
+    return  (! $bad_regexs) ? [ @regexs ] : undef;
+}
+
+sub select {
+    my ($self, @sections) = @_;
+    if ($ISA[0]->can('select')) {
+        $self->SUPER::select(@sections);
+    } else {
+        # we're using Pod::Simple - need to mimic the behavior of Pod::Select
+        my $add = ($sections[0] eq '+') ? shift(@sections) : '';
+        ## Reset the set of sections to use
+        unless (@sections) {
+          delete $self->{USAGE_SELECT} unless ($add);
+          return;
+        }
+        $self->{USAGE_SELECT} = []
+          unless ($add && $self->{USAGE_SELECT});
+        my $sref = $self->{USAGE_SELECT};
+        ## Compile each spec
+        for my $spec (@sections) {
+          my $cs = _compile_section_spec($spec);
+          if ( defined $cs ) {
+            ## Store them in our sections array
+            push(@$sref, $cs);
+          } else {
+            carp qq{Ignoring section spec "$spec"!\n};
+          }
+        }
+    }
+}
+
+# Override Pod::Text->seq_i to return just "arg", not "*arg*".
+sub seq_i { return $_[1] }
+
+# This overrides the Pod::Text method to do something very akin to what
+# Pod::Select did as well as the work done below by preprocess_paragraph.
+# Note that the below is very, very specific to Pod::Text.
+sub _handle_element_end {
+    my ($self, $element) = @_;
+    if ($element eq 'head1') {
+        $self->{USAGE_HEADINGS} = [ $$self{PENDING}[-1][1] ];
+        if ($self->{USAGE_OPTIONS}->{-verbose} < 2) {
+            $$self{PENDING}[-1][1] =~ s/^\s*SYNOPSIS\s*$/USAGE/;
+        }
+    } elsif ($element =~ /^head(\d+)$/ && $1) { # avoid 0
+        my $idx = $1 - 1;
+        $self->{USAGE_HEADINGS} = [] unless($self->{USAGE_HEADINGS});
+        $self->{USAGE_HEADINGS}->[$idx] = $$self{PENDING}[-1][1];
+    }
+    if ($element =~ /^head\d+$/) {
+        $$self{USAGE_SKIPPING} = 1;
+        if (!$$self{USAGE_SELECT} || !@{ $$self{USAGE_SELECT} }) {
+            $$self{USAGE_SKIPPING} = 0;
+        } else {
+            my @headings = @{$$self{USAGE_HEADINGS}};
+            for my $section_spec ( @{$$self{USAGE_SELECT}} ) {
+                my $match = 1;
+                for (my $i = 0; $i < $MAX_HEADING_LEVEL; ++$i) {
+                    $headings[$i] = '' unless defined $headings[$i];
+                    my $regex   = $section_spec->[$i];
+                    my $negated = ($regex =~ s/^\!//);
+                    $match  &= ($negated ? ($headings[$i] !~ /${regex}/)
+                                         : ($headings[$i] =~ /${regex}/));
+                    last unless ($match);
+                } # end heading levels
+                if ($match) {
+                  $$self{USAGE_SKIPPING} = 0;
+                  last;
+                }
+            } # end sections
+        }
+
+        # Try to do some lowercasing instead of all-caps in headings, and use
+        # a colon to end all headings.
+        if($self->{USAGE_OPTIONS}->{-verbose} < 2) {
+            local $_ = $$self{PENDING}[-1][1];
+            s{([A-Z])([A-Z]+)}{((length($2) > 2) ? $1 : lc($1)) . lc($2)}ge;
+            s/\s*$/:/  unless (/:\s*$/);
+            $_ .= "\n";
+            $$self{PENDING}[-1][1] = $_;
+        }
+    }
+    if ($$self{USAGE_SKIPPING} && $element !~ m/^over-/) {
+        pop @{ $$self{PENDING} };
+    } else {
+        $self->SUPER::_handle_element_end($element);
+    }
+}
+
+# required for Pod::Simple API
+sub start_document {
+    my $self = shift;
+    $self->SUPER::start_document();
+    my $msg = $self->{USAGE_OPTIONS}->{-message}  or  return 1;
+    my $out_fh = $self->output_fh();
+    print $out_fh "$msg\n";
+}
+
+# required for old Pod::Parser API
+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 aren't 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($_);
+}
+
+1; # keep require happy
+
+__END__
+
+=head1 NAME
+
+Pod::Usage, pod2usage() - print a usage message from embedded pod documentation
+
+=head1 SYNOPSIS
+
+  use Pod::Usage
+
+  my $message_text  = "This text precedes the usage message.";
+  my $exit_status   = 2;          ## The exit status to use
+  my $verbose_level = 0;          ## The verbose level to use
+  my $filehandle    = \*STDERR;   ## The filehandle to write to
+
+  pod2usage($message_text);
+
+  pod2usage($exit_status);
+
+  pod2usage( { -message => $message_text ,
+               -exitval => $exit_status  ,  
+               -verbose => $verbose_level,  
+               -output  => $filehandle } );
+
+  pod2usage(   -msg     => $message_text ,
+               -exitval => $exit_status  ,  
+               -verbose => $verbose_level,  
+               -output  => $filehandle   );
+
+  pod2usage(   -verbose => 2,
+               -noperldoc => 1  )
+
+=head1 ARGUMENTS
+
+B<pod2usage> should be given either a single argument, or a list of
+arguments corresponding to an associative array (a "hash"). When a single
+argument is given, it should correspond to exactly one of the following:
+
+=over 4
+
+=item *
+
+A string containing the text of a message to print I<before> printing
+the usage message
+
+=item *
+
+A numeric value corresponding to the desired exit status
+
+=item *
+
+A reference to a hash
+
+=back
+
+If more than one argument is given then the entire argument list is
+assumed to be a hash.  If a hash is supplied (either as a reference or
+as a list) it should contain one or more elements with the following
+keys:
+
+=over 4
+
+=item C<-message>
+
+=item C<-msg>
+
+The text of a message to print immediately prior to printing the
+program's usage message. 
+
+=item C<-exitval>
+
+The desired exit status to pass to the B<exit()> function.
+This should be an integer, or else the string "NOEXIT" to
+indicate that control should simply be returned without
+terminating the invoking process.
+
+=item C<-verbose>
+
+The desired level of "verboseness" to use when printing the usage
+message. If the corresponding value is 0, then only the "SYNOPSIS"
+section of the pod documentation is printed. If the corresponding value
+is 1, then the "SYNOPSIS" section, along with any section entitled
+"OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is printed.  If the
+corresponding value is 2 or more then the entire manpage is printed.
+
+The special verbosity level 99 requires to also specify the -sections
+parameter; then these sections are extracted and printed.
+
+=item C<-sections>
+
+A string representing a selection list for sections to be printed
+when -verbose is set to 99, e.g. C<"NAME|SYNOPSIS|DESCRIPTION|VERSION">.
+
+Alternatively, an array reference of section specifications can be used:
+
+  pod2usage(-verbose => 99, 
+            -sections => [ qw(fred fred/subsection) ] );
+
+=item C<-output>
+
+A reference to a filehandle, or the pathname of a file to which the
+usage message should be written. The default is C<\*STDERR> unless the
+exit value is less than 2 (in which case the default is C<\*STDOUT>).
+
+=item C<-input>
+
+A reference to a filehandle, or the pathname of a file from which the
+invoking script's pod documentation should be read.  It defaults to the
+file indicated by C<$0> (C<$PROGRAM_NAME> for users of F<English.pm>).
+
+If you are calling B<pod2usage()> from a module and want to display
+that module's POD, you can use this:
+
+  use Pod::Find qw(pod_where);
+  pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );
+
+=item C<-pathlist>
+
+A list of directory paths. If the input file does not exist, then it
+will be searched for in the given directory list (in the order the
+directories appear in the list). It defaults to the list of directories
+implied by C<$ENV{PATH}>. The list may be specified either by a reference
+to an array, or by a string of directory paths which use the same path
+separator as C<$ENV{PATH}> on your system (e.g., C<:> for Unix, C<;> for
+MSWin32 and DOS).
+
+=item C<-noperldoc>
+
+By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is
+specified. This does not work well e.g. if the script was packed
+with L<PAR>. The -noperldoc option suppresses the external call to
+L<perldoc> and uses the simple text formatter (L<Pod::Text>) to 
+output the POD.
+
+=back
+
+=head2 Formatting base class
+
+The default text formatter is L<Pod::Text>.  The base class for Pod::Usage can
+be defined by pre-setting C<$Pod::Usage::Formatter> I<before>
+loading Pod::Usage, e.g.:
+
+    BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
+    use Pod::Usage qw(pod2usage);
+
+=head2 Pass-through options
+
+The following options are passed through to the underlying text formatter.
+See the manual pages of these modules for more information.
+
+  alt code indent loose margin quotes sentence stderr utf8 width
+
+=head1 DESCRIPTION
+
+B<pod2usage> will print a usage message for the invoking script (using
+its embedded pod documentation) and then exit the script with the
+desired exit status. The usage message printed may have any one of three
+levels of "verboseness": If the verbose level is 0, then only a synopsis
+is printed. If the verbose level is 1, then the synopsis is printed
+along with a description (if present) of the command line options and
+arguments. If the verbose level is 2, then the entire manual page is
+printed.
+
+Unless they are explicitly specified, the default values for the exit
+status, verbose level, and output stream to use are determined as
+follows:
+
+=over 4
+
+=item *
+
+If neither the exit status nor the verbose level is specified, then the
+default is to use an exit status of 2 with a verbose level of 0.
+
+=item *
+
+If an exit status I<is> specified but the verbose level is I<not>, then the
+verbose level will default to 1 if the exit status is less than 2 and
+will default to 0 otherwise.
+
+=item *
+
+If an exit status is I<not> specified but verbose level I<is> given, then
+the exit status will default to 2 if the verbose level is 0 and will
+default to 1 otherwise.
+
+=item *
+
+If the exit status used is less than 2, then output is printed on
+C<STDOUT>.  Otherwise output is printed on C<STDERR>.
+
+=back
+
+Although the above may seem a bit confusing at first, it generally does
+"the right thing" in most situations.  This determination of the default
+values to use is based upon the following typical Unix conventions:
+
+=over 4
+
+=item *
+
+An exit status of 0 implies "success". For example, B<diff(1)> exits
+with a status of 0 if the two files have the same contents.
+
+=item *
+
+An exit status of 1 implies possibly abnormal, but non-defective, program
+termination.  For example, B<grep(1)> exits with a status of 1 if
+it did I<not> find a matching line for the given regular expression.
+
+=item *
+
+An exit status of 2 or more implies a fatal error. For example, B<ls(1)>
+exits with a status of 2 if you specify an illegal (unknown) option on
+the command line.
+
+=item *
+
+Usage messages issued as a result of bad command-line syntax should go
+to C<STDERR>.  However, usage messages issued due to an explicit request
+to print usage (like specifying B<-help> on the command line) should go
+to C<STDOUT>, just in case the user wants to pipe the output to a pager
+(such as B<more(1)>).
+
+=item *
+
+If program usage has been explicitly requested by the user, it is often
+desirable to exit with a status of 1 (as opposed to 0) after issuing
+the user-requested usage message.  It is also desirable to give a
+more verbose description of program usage in this case.
+
+=back
+
+B<pod2usage> doesn't force the above conventions upon you, but it will
+use them by default if you don't expressly tell it to do otherwise.  The
+ability of B<pod2usage()> to accept a single number or a string makes it
+convenient to use as an innocent looking error message handling function:
+
+    use Pod::Usage;
+    use Getopt::Long;
+
+    ## Parse options
+    GetOptions("help", "man", "flag1")  ||  pod2usage(2);
+    pod2usage(1)  if ($opt_help);
+    pod2usage(-verbose => 2)  if ($opt_man);
+
+    ## Check for too many filenames
+    pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);
+
+Some user's however may feel that the above "economy of expression" is
+not particularly readable nor consistent and may instead choose to do
+something more like the following:
+
+    use Pod::Usage;
+    use Getopt::Long;
+
+    ## Parse options
+    GetOptions("help", "man", "flag1")  ||  pod2usage(-verbose => 0);
+    pod2usage(-verbose => 1)  if ($opt_help);
+    pod2usage(-verbose => 2)  if ($opt_man);
+
+    ## Check for too many filenames
+    pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
+        if (@ARGV > 1);
+
+As with all things in Perl, I<there's more than one way to do it>, and
+B<pod2usage()> adheres to this philosophy.  If you are interested in
+seeing a number of different ways to invoke B<pod2usage> (although by no
+means exhaustive), please refer to L<"EXAMPLES">.
+
+=head1 EXAMPLES
+
+Each of the following invocations of C<pod2usage()> will print just the
+"SYNOPSIS" section to C<STDERR> and will exit with a status of 2:
+
+    pod2usage();
+
+    pod2usage(2);
+
+    pod2usage(-verbose => 0);
+
+    pod2usage(-exitval => 2);
+
+    pod2usage({-exitval => 2, -output => \*STDERR});
+
+    pod2usage({-verbose => 0, -output  => \*STDERR});
+
+    pod2usage(-exitval => 2, -verbose => 0);
+
+    pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);
+
+Each of the following invocations of C<pod2usage()> will print a message
+of "Syntax error." (followed by a newline) to C<STDERR>, immediately
+followed by just the "SYNOPSIS" section (also printed to C<STDERR>) and
+will exit with a status of 2:
+
+    pod2usage("Syntax error.");
+
+    pod2usage(-message => "Syntax error.", -verbose => 0);
+
+    pod2usage(-msg  => "Syntax error.", -exitval => 2);
+
+    pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
+
+    pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
+
+    pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);
+
+    pod2usage(-message => "Syntax error.",
+              -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 to
+C<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 the
+entire 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 Use
+
+Most scripts should print some type of usage message to C<STDERR> when a
+command line syntax error is detected. They should also provide an
+option (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 to
+provide a means of printing their complete documentation to C<STDOUT>
+(perhaps by allowing a C<-man> option). The following complete example
+uses B<Pod::Usage> in combination with B<Getopt::Long> to do all of these
+things:
+
+    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 CAVEATS
+
+By default, B<pod2usage()> will use C<$0> as the path to the pod input
+file.  Unfortunately, not all systems on which Perl runs will set C<$0>
+properly (although if C<$0> isn't found, B<pod2usage()> will search
+C<$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 specify
+the path to the pod docs for the invoking script using something
+similar to the following:
+
+    pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");
+
+In the pathological case that a script is called via a relative path
+I<and> the script itself changes the current working directory
+(see L<perlfunc/chdir>) I<before> calling pod2usage, Pod::Usage will
+fail even on robust platforms. Don't do that. Or use L<FindBin> to locate
+the script:
+
+    use FindBin;
+    pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);
+
+=head1 AUTHOR
+
+Please report bugs using L<http://rt.cpan.org>.
+
+Marek Rouchal E<lt>marekr@cpan.orgE<gt>
+
+Brad Appleton E<lt>bradapp@enteract.comE<gt>
+
+Based on code for B<Pod::Text::pod2text()> written by
+Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
+
+=head1 ACKNOWLEDGMENTS
+
+rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
+
+Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience
+with re-writing this manpage.
+
+=head1 SEE ALSO
+
+B<Pod::Usage> is now a standalone distribution, depending on
+L<Pod::Text> which in turn depends on L<Pod::Simple>.
+
+L<Pod::Perldoc>, L<Getopt::Long>, L<Pod::Find>, L<FindBin>,
+L<Pod::Text>, L<Pod::Text::Termcap>, L<Pod::Simple>
+
+=cut
+