pod2usage

pod2usage [options] [file]

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

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.

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.

perlpod(1), perldoc(1)