pod2text

pod2text [options] [input file] ...

-help
    Display help information and exit.

-man
    Display complete manual page.

-t
    Display terse help information and exit.

-w=width
    Set the output width to 'width' columns. Default is terminal width or 76.

-i=indent
    Set the indentation to 'indent' spaces. Default is 4.

-s
    Strip any initial sequence of non-POD text.

-u
    Expand — (em dash) to --, – (en dash) to ---, and '...' to ... (a triple dot) - if you don't like nroff's handling.

-no-leading-whitespace
    do not emit any whitespace at the beginning of each line.

-utf8
    output in UTF-8, regardless of locale.

input file
    The POD file to process. If not specified, reads from standard input.

pod2text converts files in the Perl Plain Old Documentation (POD) format into formatted ASCII text. It's a vital tool for making Perl documentation readable outside of a web browser or specialized POD viewer.
The command reads the POD source file (or standard input if no file is specified) and outputs formatted text suitable for viewing in a terminal or printing. pod2text handles basic formatting like headings, bold, italic, code, and lists. It also offers customization options such as setting the page width, indentation, and whether to include a table of contents. This utility is commonly used to generate man pages from POD documentation embedded within Perl modules and scripts. The primary purpose is to render POD markup into a more human-readable form, facilitating documentation consumption without requiring specialized software.

The formatting produced by pod2text is fairly basic. It's not designed to create publication-quality output. Complex formatting or layout requirements may necessitate using more sophisticated tools like pod2html or pod2man.

By default, pod2text attempts to use the current locale's character encoding. The -utf8 option forces UTF-8 output, which can be useful when the locale is not set or when you need a consistent output encoding.

pod2text returns 0 on success and a non-zero value on failure (e.g., if it encounters an unreadable file or a POD syntax error).

pod2text has been a standard utility in the Perl distribution for a very long time. It originated as part of the core toolset for working with POD documentation. Its purpose was always to provide a simple text-based rendering solution. It predates widespread adoption of HTML-based documentation viewers and remains a useful tool for quick viewing and generating basic text files. Over time, it has received updates to improve Unicode support and fix minor formatting issues, but its core functionality has remained consistent.

pod2html(1), pod2man(1), perlpod(1), perldoc(1)