pod2usage - print a usage message using a script's embedded pod documentation

- NAME
- SYNOPSIS
- DESCRIPTION
- EXAMPLE
- CAVEATS
- AUTHOR

# NAME

pod2usage - print a usage message using a script's embedded pod documentation

# SYNOPSIS

        use PDL::Pod::Usage;
        pod2usage();
        pod2usage(2);
        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 corresponding 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() function.

`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.

`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 specified, 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 example uses pod2usage in combination with Getopt::Long to do all of these things:

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

        GetOptions("help", "man")  ||  pod2usage(2);
        pod2usage(1)  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 something similar to the following:

- `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>