pod2man

pod2man [options] inputfile [outputfile]
pod2man [options] < inputfile > outputfile

--section=name | -s name
    Set the manual section. Default is 3.

--release=version | -r version
    Set the release value. Default is the Perl version.

--center=text | -c text
    Set the centered header. Default is "Perl Programmers Reference Guide".

--date=string | -d string
    Set the date. Default is the current date.

--fullpath
    Use full path for the name, e.g., Foo::Bar(3).

--name=name
    Set the name. Default is derived from inputfile.

--noperl
    Don't add Perl-specific sections (e.g., SEE ALSO perl(1)).

--nocenter
    Don't include a centered header.

--nourl
    Don't add a URL to the SEE ALSO section for L<> codes.

--laxbreak
    Don't break paragraphs for L<> codes.

--htmlroot=url
    Specify the base URL for L<> codes to HTML.

--podpath=dir1:dir2:...
    Search path for L<...> references.

--quiet
    Don't display warnings.

--errors
    Display errors in the output.

--utf8
    Encode output as UTF-8.

--encoding=encoding
    Specify input encoding.

--permute
    Change position of NAME section.

--stderr
    Send errors to stderr.

--verbose
    Display verbose messages.

--version
    Display version information.

--help
    Display usage message.

pod2man is a Perl utility that translates documentation written in the Perl POD (Plain Old Documentation) format into the roff input format used by the man program. POD is a simple markup language commonly used for documenting Perl modules and scripts.

pod2man allows developers to easily create standard UNIX manual pages from their POD-formatted documentation, making it accessible via the man command. It handles various aspects of man page formatting, including sections, bolding, italics, and cross-references. It's typically invoked during the installation of Perl modules to generate man pages for scripts and library functions, ensuring that documentation is readily available in a standardized format.

• Requires a Perl interpreter to run.
• Output is in roff format, which needs to be processed by tools like man or groff for display.
• Relies on correct POD syntax in the input file; malformed POD may lead to unexpected output or errors.
• Default header/footer values (section, release, center, date) might not be suitable for all projects and often need to be overridden with explicit options.

pod2man reads POD from inputfile (or standard input if no file is specified) and writes the formatted man page to outputfile (or standard output if no output file is specified).

It is commonly used during the installation of Perl modules (e.g., via ExtUtils::MakeMaker or Module::Build) to automatically generate and install man pages alongside the module files, ensuring that documentation is consistently available through the system's manual page viewer.

pod2man is an integral part of the Perl distribution, developed as part of the effort to provide consistent and easily maintainable documentation for Perl itself, its modules, and scripts. It has been part of the standard Perl toolkit for many years, evolving with the language to support various POD features and output formatting requirements. Its existence facilitates the widespread use of POD as a primary documentation format within the Perl ecosystem, making it a cornerstone for creating standardized manual pages for Perl-based software.

perlpod(1), pod2html(1), pod2text(1), man(1), groff(1)