Usage(e)       User Contributed Perl Documentation       Usage(e)



NAME
       pod2usage - print a usage message using a script's embed-
       ded pod documentation

SYNOPSIS
           use PDL::Pod::Usage;
           pod2usage();
           pod2usage(e);
           pod2usage({EXIT => 2});
           pod2usage({EXIT => 2, VERBOSE => 0});
           pod2usage(EXIT => 1, VERBOSE => 2, OUTPUT=\*STDERR);
           pod2usage(VERBOSE => 2);


DESCRIPTION
       pod2usage will print a usage message for the invoking
       script (using its embedded pod documentation) and then
       exit the script with the specified exit value. It takes a
       single argument which is either a numeric value corre-
       sponding to the desired exit status (which defaults to 2),
       or a reference to a hash. If more than one argument is
       given then the entire argument list is assumed to be a
       hash. If a hash is supplied it should contain elements
       with one or more of the following keys:

       "EXIT"
           The desired exit status to pass to the exit() func-
           tion.

       "VERBOSE"
           The desired level of "verboseness" to use when print-
           ing the usage message. If the corresponding value is
           0, then only the "SYNOPSIS" section of the pod docu-
           mentation is printed. If the corresponding value is 1,
           then the "SYNOPSIS" section, along with any section
           entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGU-
           MENTS" is printed.  If the corresponding value is 2 or
           more then the entire manpage is printed.

       "OUTPUT"
           A reference to a filehandle, or the pathname of a file
           to which the usage message should be written. The
           default is "\*STDERR" unless the exit value is less
           than 2 (in which case the default is "\*STDOUT").

       "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
           $0 ($PROGRAM_NAME for "use English;" users).

       If neither the exit value nor the verbose level is speci-
       fied, then the default is to use an exit value of 2 with a
       verbose level of 0.

       If an exit value is specified but the verbose level is
       not, then the verbose level will default to 1 if the exit
       value is less than 2 and will default to 0 otherwise.

       If a verbose level is specified but an exit value is not,
       then the exit value will default to 2 if the verbose level
       is 0 and will default to 1 otherwise.

EXAMPLE
       Most scripts should print some type of usage message to
       STDERR when a command line syntax error is detected. They
       should also provide an option (usually "-h" or "-help") to
       print a (possibly more verbose) usage message to STDOUT.
       Some scripts may even wish to go so far as to provide a
       means of printing their complete documentation to STDOUT
       (perhaps by allowing a "-man" option). The following exam-
       ple uses pod2usage in combination with Getopt::Long to do
       all of these things:

           use PDL::Pod::Usage;
           use Getopt::Long;

           GetOptions("help", "man")  ||  pod2usage(e);
           pod2usage(e)  if ($opt_help);
           pod2usage(VERBOSE => 2)  if ($opt_man);


CAVEATS
       By default, pod2usage() will use $0 as the path to the pod
       input file.  Unfortunately, not all systems on which Perl
       runs will set $0 properly (although if $0 isn't found,
       pod2usage() will search $ENV{PATH}).  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 some-
       thing similar to the following:

       o   "pod2usage(EXIT => 2, INPUT =>
           "/path/to/your/pod/docs");"

AUTHOR
       Brad Appleton <Brad_Appleton-GBDA001@email.mot.com>

       Based on code for Pod::Text::pod2text() written by Tom
       Christiansen <tchrist@mox.perl.com>



perl v5.6.1                 1999-12-09                   Usage(e)