pod2usage
Generate usage message from a Perl module
SYNOPSIS
pod2usage [options] [file]
PARAMETERS
-help
Prints the usage message and exits.
-man
Prints the manual page and exits.
-exit
Exits after printing the usage message (default).
-noexit
Do not exit after printing the usage message.
-verbose
Sets the verbosity level (0, 1, 2, or 3).
-msg
Error message before printing usage message (implies -exit).
-input
Specifies the input file (defaults to STDIN).
DESCRIPTION
pod2usage is a command-line utility that extracts embedded usage messages from Perl Plain Old Documentation (POD) format. It's primarily used to generate helpful usage information for Perl scripts, making them more user-friendly. The tool searches for specially formatted POD blocks within the script containing usage instructions. The tool then outputs these messages to standard output, typically helping users understand how to execute the script, its options, and any required parameters.
It's particularly valuable for larger or more complex Perl scripts where a clear and concise usage message is critical for effective operation. Pod2usage provides a standardized way to document script usage and allows for easy extraction and presentation of that documentation.
POD FORMAT
pod2usage relies on a specific POD format. The usage messages are typically located within =head1 USAGE sections or other specially marked POD blocks. Proper formatting ensures that the tool can accurately extract and display the intended usage information.
For example =head1 USAGE.
Use of =item when specifying optional or mandatory parameters helps make usage more readable.
Avoid long lines for better display.
SEE ALSO
perlpod(1), perldoc(1)