pod2usage

pod2usage [options] [pod_file | module_name]

Common invocations:
pod2usage --help
pod2usage --man
pod2usage --verbose 1 My::Perl::Module

--help, -h
    Displays a concise usage message and exits.

--man
    Displays the full manual page for the specified POD documentation.

--verbose level, -v level
    Controls the verbosity of the output. 0 shows only the usage message, 1 shows the usage message and description, 2 shows the full POD documentation.

--sections section,..., -s section,...
    Specifies a comma-separated list of POD sections (e.g., NAME, SYNOPSIS, DESCRIPTION) to display.

--message string, -m string
    Prints the specified string before the usage message. Useful for adding custom error or informational messages.

--exitval exit_code, -e exit_code
    Specifies the exit status code for pod2usage upon successful completion. Defaults to 0.

--output file, -o file
    Redirects the formatted output to the specified file instead of standard output.

--format format_name, -f format_name
    Specifies the output format, such as text (default for terminal), man, or html.

--input file, -i file
    Specifies the input file to parse. If not provided, it defaults to STDIN or the module specified.

pod2usage is a Perl utility designed to extract and format documentation embedded within Perl scripts and modules. This documentation is written in POD (Plain Old Documentation) format, a simple markup language used by Perl developers. The primary purpose of pod2usage is to quickly display usage messages, help information, or even full manual pages directly from the source code.

When invoked, pod2usage parses the specified Perl file or module, locates its POD sections, and renders them into a user-friendly format, typically plain text suitable for terminal output. It is commonly used by Perl scripts themselves to provide their own --help or --man options, offering a consistent way for users to access documentation without needing external man pages or separate documentation files.

It's an invaluable tool for Perl programmers and users alike, enabling easy access to API documentation and command-line tool usage instructions directly from the software's source.

pod2usage requires a Perl installation and is primarily designed for parsing Perl's POD (Plain Old Documentation) format. It may not be available on systems without Perl or without the Pod::Usage module installed. The quality of the output depends on the clarity and correctness of the embedded POD documentation. While it can output to various formats, its primary strength is generating plain text or man page formats for terminal display.

pod2usage provides specific exit codes to indicate the outcome of its execution:
0: Successful completion.
1: Bad command line arguments provided.
2: Errors encountered during the parsing or processing of the POD documentation.
255: An invalid value was specified for the --exitval-bad-params option.

pod2usage is an integral part of the standard Perl distribution, originating from the Pod::Usage Perl module. Its development has closely tracked the evolution of Perl and its Plain Old Documentation (POD) specification. Initially designed to provide simple usage messages from Perl scripts, it has grown in functionality to support displaying more comprehensive documentation sections and various output formats, becoming a fundamental tool for accessing Perl module documentation directly from the source code. Its inclusion in core Perl distributions ensures widespread availability and consistent documentation access within the Perl ecosystem.

perldoc(1), pod2man(1), pod2text(1), perl(1)