pod2text

pod2text [options] [file...]

-c, --code
    Formats C<> sequences (inline code examples) using a fixed-width style, making them visually distinct like code snippets.

-i columns, --indent=columns
    Indents the main body text of the document by the specified number of columns spaces from the left margin, improving readability.

-l, --loose
    Adds a blank line before and after each heading (e.g., =head1, =head2), making the document appear less dense and improving visual separation between sections.

-s, --sentence
    Forces pod2text to treat each paragraph block as a single sentence. This can influence how inline formatting codes, particularly B<> (bold), are rendered, often ensuring proper capitalization where appropriate.

-u, --utf8
    Ensures that the output text is encoded in UTF-8. This is crucial for correctly displaying international characters and symbols present in the POD documentation.

-w columns, --width=columns
    Sets the maximum output width for the text, in columns. Lines exceeding this width will be wrapped to the next line. This is highly useful for controlling layout and fitting output to specific terminal sizes.

--errors=style
    Determines how pod2text handles POD parsing errors. style can be die (exit immediately upon error), warn (print a warning and continue), or ignore (silently ignore errors).

--encoding=encoding
    Specifies the character encoding of the input POD file. This helps pod2text correctly interpret non-ASCII or multi-byte characters within the document.

--nourl
    Disables the underlining or highlighting of URLs in the output. This can be useful if your terminal does not support or renders underlining poorly, or if you prefer plain text output for URLs.

file...
    One or more POD files to be converted. If no file arguments are specified, pod2text reads its input from standard input (stdin).

The pod2text command is a utility included with Perl that converts documentation written in Perl's Plain Old Documentation (POD) format into a readable plain text. POD is a simple, lightweight markup language primarily used for documenting Perl modules, scripts, and other components directly within the source code. pod2text is essential for viewing this documentation on the command line, especially when perldoc might not be fully configured or when you need to pipe the output to other text processing tools. It intelligently handles various POD formatting codes like bold (B<>), italic (I<>), code (C<>), and links (L<>), rendering them into appropriate plain text representations, often using capitalization, indentation, or underlining to signify the original formatting.

While pod2text is effective for basic text conversion, it is primarily designed for simple rendering. It may not perfectly reproduce complex formatting, elaborate tables, or highly structured layouts found in more advanced markup languages. The final output quality also depends on the capabilities of the displaying terminal and the inherent structure of the POD file. For interactive viewing of Perl documentation, perldoc is often preferred as it integrates a pager and handles module lookup.

If no file arguments are provided on the command line, pod2text will automatically read its input from standard input (stdin). This allows for flexible use cases, such as piping the output of other commands (e.g., cat my_script.pl | pod2text) or processing dynamically generated POD content.

The output of pod2text is typically clean ASCII or UTF-8 plain text. Headings are often capitalized or underlined to stand out, lists are properly indented, and code examples maintain their preformatted structure. This plain text output is highly versatile, suitable for display in any terminal, saving to a text file, or further processing by other command-line utilities like grep or less.

pod2text is an integral utility within the Perl programming language distribution, designed to make Perl's native Plain Old Documentation (POD) format widely accessible. The POD format itself was introduced in the early 1990s as a straightforward way to embed documentation directly within Perl source code. pod2text, alongside other pod2* utilities like pod2man (for manual pages) and pod2html (for HTML output), has continuously evolved as part of the Perl core, ensuring robust and consistent conversion capabilities for Perl documentation across various environments and output formats.

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