Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for pdl::pod::usage (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

Usage(3)		       User Contributed Perl Documentation			 Usage(3)

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

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

       pod2usage will print a usage message for the invoking script (using its embedded pod docu-
       mentation) and then exit the script with the specified exit value. It takes a single argu-
       ment 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 ele-
       ments with one or more of the following keys:

	   The desired exit status to pass to the exit() function.

	   The desired level of "verboseness" to use when printing the usage message. If the cor-
	   responding 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.

	   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").

	   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.

       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);

       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 simi-
       lar to the following:

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

       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.8.0				    1999-12-09					 Usage(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 11:32 PM.