pod2usage Command in Linux
The pod2usage command in Linux displays the usage message from Perl scripts and POD files. It is used to print usage messages from embedded POD (Plain Old Documentation) sections in Perl scripts or modules. It is a convenient way to provide usage information directly extracted from the script's embedded documentation. It also eliminates the need for hardcoding usage messages separately.
Table of Contents
Here is a comprehensive guide to the options available with the pod2usage command −
Syntax of pod2usage Command
The syntax of the Linux pod2usage command is as follows −
pod2usage [options] [file]
In the above syntax, the [options] field is used to specify various options to modify the command behavior. The [file] field is used to specify the Perl script file.
pod2usage Command Options
The options of the pod2usage command as listed below −
| Option | Description |
|---|---|
| -exit exitval | Set the exit status value to return |
| -formatter module | Specify the text formatting module (default: Pod::Text, or Pod::PlainText for older Perl) |
| -help | Print a brief help message and exit |
| -man | Print this command's manual page and exit |
| -output outfile | Specify the output file for printing. Use - or >&STDOUT for standard output, >&STDERR for standard error |
| -pathlist dirlist | Set directories to search for the input file, separated by : on Unix or ; on Windows |
| -utf8 | Enable utf8 output if supported by the formatter |
| -verbose level | Set verbosity level: 1=SYNOPSIS, 2=SYNOPSIS + OPTIONS, 3=Full manpage |
Examples of pod2usage Command in Linux
This section discussed the usage of the pod2usage command in Linux with examples.
Displaying the Usage Message of a POD File
To display the usage message of a POD file, use the pod2usage command with the POD file name −
pod2usage file.pod
It displays the SYNOPSIS section of the .pod file by default. The SYNOPSIS section contains a concise example of using the module or script and is often the first section in a well-documented POD file.
Displaying the Usage Message of a Script
To display the usage message of embedded POD documentation in a script, use the pod2usage command with the script file name −
pod2usage file.pl
The perl script must have embedded POD documentation.
Setting the Exit Status
The -exit option in pod2usage allows specifying an exit status code when the command finishes. This is useful for controlling the exit status of a script or program based on the usage output. To run the pod2usage command with the exit code 1, use the following command −
pod2usage -exit 1 file.pod
The output displays the SYNOPSIS section of the POD file. To check the exit code, use the following command −
echo $?
If the 0 is used with the -exit option the exit code will be 0.
Saving the Output to a File
To save the output to a separate file, use the -output option with the output file name −
pod2usage -output outfile.txt file.pod
Use a dash - or >&STDOUT for standard output, and >&STDERR for standard error.
Specifying Formatter for Output
To specify the output format module, use the -formatter option with the format module name. For example, to use the Pod::Text::Termcap module for the output format, use the pod2usage command in the following way −
pod2usage -formatter Pod::Text::Termcap file.pod
Other commonly used formatting modules are listed below −
- Pod::Text
- Pod::PlainText
- Pod::Html
- Pod::LaTeX
- Pod::Text::Color
Some of the above-mentioned modules must be installed on Linux before using.
Setting Verbosity Level
To get detailed output, use the -verbose option with the verbosity level. The verbosity levels are listed below −
| Verbosity Level | Description |
|---|---|
| 1 | Print only the SYNOPSIS section |
| 2 | Print the SYNOPSIS section along with any OPTIONS/ARGUMENTS sections |
| 3 | Print the full manpage, similar to running pod2text |
To set the verbosity level, use the -verbose option with the level number. To set the verbosity level to 2, use the following command −
pod2usage -verbose 2 file.pod
Displaying Help
To display a brief usage help of pod2usage command, use the -help option −
pod2usage -help
Conclusion
The pod2usage command in Linux is a handy tool for displaying usage information from Perl scripts or POD files. It simplifies the process of extracting and showing embedded documentation, removing the need for separate usage messages.
Through various options, pod2usage can control how information is presented, set exit statuses, and even save output to files. It supports multiple formatting options, and verbosity levels, and allows access to detailed help messages.