Pod::Text(3perl)

📦

version 5.44.0 · 14 versions

💖 NAME 💖

Pod::Text — it converts POD data into formatted text, no cap. 🦋

✨ SYNOPSIS ✨

use Pod::Text;
my $parser = Pod::Text->new (sentence => 1, width => 78);

# Read POD from STDIN and write to STDOUT.
$parser->parse_from_filehandle;

# Read POD from file.pod and write to file.txt.
$parser->parse_from_file ('file.pod', 'file.txt');

🌸 DESCRIPTION 🌸

So Pod::Text is the module that takes documentation written in POD (which is, like, the preferred language for documenting Perl, obviously 👑) and turns it into formatted text. It doesn't use any special formatting controls or codes — literally none — which means its output will vibe with almost any device you throw at it. 💅

🔤 Encoding 🔤

Here's the way Pod::Text picks an output encoding, and it does it in order, bestie. It goes down this list and takes the first one that applies:

If a PerlIO encoding layer is set on the output file handle, it does no output encoding at all and just relies on that PerlIO encoding layer instead. 🫶
If the encoding or utf8 options are set, it uses whatever output encoding those options say. Periodt.
If the input encoding of the POD source file was explicitly specified (with =encoding) or was automatically detected by Pod::Simple, then it uses that as the output encoding too. Slay.
Otherwise, if you're on a non-EBCDIC system, it uses UTF-8 as the output encoding. And because UTF-8 is a superset of ASCII, this actually gives you ASCII output — unless the POD input has non-ASCII characters without declaring or autodetecting an encoding (which usually happens through E<> escapes). 🙈
Otherwise, on EBCDIC systems, it just outputs without doing any encoding and hopes that works. 💀

One caveat, and it's kind of a big one: Pod::Text has to commit to an output encoding the first time it outputs a non-ASCII character, and then it has to stick with that choice for consistency. But here's the thing — =encoding commands don't have to be at the beginning of a POD document. So like, if someone uses a non-ASCII character early in a document via an escape, such as E<0xEF>, and then puts =encoding iso-8859-1 later, the ideal scenario would be for Pod::Text to follow rule 3 and output the whole document as ISO 8859-1. Instead, it commits to UTF-8 following rule 4 the second it sees that escape, and then it's stuck with that encoding for the rest of the document. It's giving commitment issues, fr fr. 😭

Unfortunately, there is genuinely no universally good choice for an output encoding. Every single choice will be wrong in some circumstance. This whole approach was chosen primarily for backwards compatibility. So if you're a caller and you have any knowledge at all about what encoding the user might expect, you should lowkey consider forcing the output encoding via encoding.

In particular — and this is a good one — consider importing the Encode::Locale module, if it's available, and setting encoding to locale so you get an output encoding that's appropriate to the user's locale. ✨ But be aware: if the user isn't using locales, or is using a locale of C, then Encode::Locale will set the output encoding to US-ASCII. And that will cause all non-ASCII characters to be replaced with ? and produce a whole flurry of warnings about unsupported characters. Which may or may not be what you want. Highkey probably not. 🙃

👑 CLASS METHODS 👑

`new(ARGS)`

Create a brand new Pod::Text object, bestie. ✨ ARGS should be a list of key/value pairs, where the keys come from this list right here. Each option is annotated with the version of Pod::Text in which that option was added, with the meaning it has now. 💖

alt [2.00] — If you set this to a true value, it selects an alternate output format that, among other things, uses a different heading style and marks =item entries with a colon in the left margin. Defaults to false.
code [2.13] — If you set this to a true value, the non-POD parts of the input file get included in the output. Super useful for viewing code that's documented with POD blocks, where the POD is rendered and the code is left intact. 🎀
encoding [5.00] — Specifies the encoding of the output. The value has to be an encoding that the Encode module recognizes (see Encode::Supported). If the output contains characters that can't be represented in this encoding, that's an error, and it gets reported however the errors option is configured. And if error handling is anything other than die, the unrepresentable character gets replaced with the Encode substitution character (which is normally ?).

If the output file handle has a PerlIO encoding layer set, this parameter gets ignored and no encoding will be done by Pod::Man. It'll rely on the encoding layer to make whatever output encoding transformations are desired instead.

⚠️ WARNING: The input encoding of the POD source is independent from the output encoding, and setting this option does not affect how the POD input gets interpreted. Unless your POD source is US-ASCII, its encoding should be declared with the =encoding command in the source, as close to the top of the file as possible. If you don't do that, Pod::Simple will attempt to guess the encoding, and it may actually succeed if it's Latin-1 or UTF-8 — but it'll produce warnings either way. See perlpod(1) for more info. 😭

errors [3.17] — How to report errors, bestie. Here are your choices:
- die says to throw an exception on any POD formatting error.
- stderr says to report errors on standard error, but not throw an exception.
- pod says to include a POD ERRORS section in the resulting documentation summarizing the errors.
- none ignores POD errors entirely, as much as it possibly can.

The default is pod. 💅

guesswork [5.01] — By default, Pod::Text applies some default formatting rules based on guesswork and regular expressions, all of which are intended to make writing Perl documentation easier and require less explicit markup. These rules may not always be appropriate though, especially for documentation that isn't about Perl. This option lets you turn all of it, or some of it, off.

The special value all enables all the guesswork. That's also the default, for backward compatibility reasons. The special value none disables all the guesswork. Otherwise, the value of this option should be a comma-separated list of one or more of these keywords:

quoting — If no guesswork is enabled, any text enclosed in C<> gets surrounded by double quotes in nroff (terminal) output, unless the contents are already quoted. When this guesswork is enabled, quote marks will also be suppressed for Perl variables, function names, function calls, numbers, and hex constants. 🦋

Any unknown guesswork name is silently ignored (for potential future compatibility), so be careful about your spelling, bestie. 🙈

indent [2.00] — The number of spaces to indent regular text, and also the default indentation for =over blocks. Defaults to 4.
loose [2.00] — If you set this to a true value, a blank line gets printed after a =head1 heading. If you set it to false (which is the default), no blank line is printed after =head1 — although one is still printed after =head2. This is the default because it's the expected formatting for manual pages. But if you're formatting arbitrary text documents, setting this to true might result in more pleasing output. ✨
margin [2.21] — The width of the left margin, in spaces. Defaults to 0. This is the margin for all the text, including headings — it's not the amount by which regular text is indented. For that, see the indent option. And to set the right margin, see the width option.
nourls [3.17] — Normally, L<> formatting codes with a URL but anchor text are formatted to show both the anchor text and the URL. So, like:

L<foo|http://example.com/>

gets formatted as:

foo <http://example.com/>

This option, if you set it to a true value, suppresses the URL whenever anchor text is given — so that same example would just be formatted as foo. This can give you less cluttered output in cases where the URLs aren't particularly important. 🧚

quotes [4.00] — Sets the quote marks used to surround C<> text. If the value is a single character, it's used as both the left and right quote. Otherwise, it gets split in half: the first half of the string becomes the left quote and the second half becomes the right quote.

This may also be set to the special value none, in which case no quote marks get added around C<> text at all.

sentence [3.00] — If you set this to a true value, Pod::Text will assume that every sentence ends in two spaces, and it'll try to preserve that spacing. If you set it to false, all consecutive whitespace in non-verbatim paragraphs gets compressed down into a single space. Defaults to false.
stderr [3.10] — Sends error messages about invalid POD to standard error instead of appending a POD ERRORS section to the generated output. This is equivalent to setting errors to stderr if errors isn't already set. It's supported for backward compatibility.
utf8 [3.12] — If you set this option to a true value, the output encoding gets set to UTF-8. This is equivalent to setting encoding to UTF-8 if encoding isn't already set. It's supported for backward compatibility. 💜
width [2.00] — The column at which to wrap text on the right-hand side. Defaults to 76.

`output_fh(FH)` 💌

Sends the output of parse_file(), parse_lines(), or parse_string_document() to the filehandle FH instead of pointing it at STDOUT. Basically: "bestie, write it here instead, mkay?"

`output_string(REF)` 📝

Sends the output of parse_file(), parse_lines(), or parse_string_document() into the scalar variable that REF is pointing at, instead of STDOUT. Like so:

my $man = Pod::Man->new();
my $output;
$man->output_string(\$output);
$man->parse_file('/some/input/file');

Heads up bestie: the stuff sitting in that variable is already encoded. Yes, for real. Go read the "Encoding" bit if you wanna know why. 🙈

`parse_file(PATH)` 📂

Reads the POD source out of PATH and formats it. Default destination is STDOUT (the classic), but you can reroute it with the output_fh() or output_string() methods. Slay.

`parse_from_file(INPUT, OUTPUT)` / `parse_from_filehandle(FH, OUTPUT)` 🔁

Reads POD source from INPUT, formats it, and dumps the results into OUTPUT.

parse_from_filehandle() is only hanging around for backward compatibility with ancient versions of Pod::Man. Like, it's the older sibling who still lives at home. Use parse_from_file() instead, fr fr.

`parse_lines(LINES[, ...[, undef]])` 🧵

Parses the lines you hand it as POD source, and writes the output to either STDOUT or whatever filehandle you already set with output_fh() or output_string(). You can call this method over and over to keep feeding it more input lines — it's giving "keep 'em coming, I'm not done". Pass an explicit undef to signal that the input is over, periodt.

This method wants raw bytes, not decoded characters. Do not come in here with decoded characters, I'm begging. 😭

`parse_string_document(INPUT)` 🎀

Parses the scalar variable you gave it as POD source, and writes output to either STDOUT or the filehandle set with output_fh() or output_string().

Same rule as above: raw bytes, not decoded characters. No exceptions, no cap. 💅

✨ FUNCTIONS ✨

Pod::Text exports one function, purely for backward compatibility with the old-school days. That function is deprecated — like, please don't — use the object-oriented interface described up above instead. It's so much cuter.

`pod2text([[-a,] [-NNN,]] INPUT[, OUTPUT])` 🪄

Converts the POD source from INPUT into text and writes it to OUTPUT. If you don't bother giving it an OUTPUT, it defaults to STDOUT. And INPUT can be literally any expression that works as the second argument to two-argument open(). Versatile queen.

If -a shows up as an initial argument, it passes the alt option to the Pod::Text constructor. This turns on alternative formatting. Fancy. 💅
If -NNN shows up as an initial argument, it passes the width option to the Pod::Text constructor with the number NNN as its argument. This sets the wrap line width to NNN. Your margins, your rules. 📏

🚨 DIAGNOSTICS 🚨

`Bizarre space in item`

`Item called without tag`

(W) Something went sideways inside the internal =item processing. These messages mean there's a bug in Pod::Text itself, and you should literally never see them. If you do? Not your fault, bestie. 🫶

`Can't open %s for reading: %s`

(F) Pod::Text got invoked through the compatibility-mode pod2text() interface, and the input file it was handed could not be opened. Rough. 😭

`Invalid errors setting "%s"`

(F) The errors parameter you passed to the constructor was set to some value nobody recognizes. An unknown. A mystery. 🕵️

`Invalid quote specification "%s"`

(F) The quote specification you gave (that's the quotes option to the constructor) was invalid. A quote specification has to be either exactly one character long, or an even number of characters that's greater than one. Those are the only two vibes. No in-between. 🎀

`POD document had syntax errors`

(F) The POD document being formatted had syntax errors, and you set the errors option to die. So yeah. It died. 💀

🕰️ COMPATIBILITY 🕰️

Pod::Text 2.03 (which was built on Pod::Parser) was the very first version of this module to ship with Perl — in Perl 5.6.0, iconic behavior. Earlier Perls had a totally different Pod::Text module with a totally different API. Different era, different girlies.

The current API, the one built on Pod::Simple, landed in Pod::Text 3.00. ✨
Pod::Text 3.01 shipped in Perl 5.9.3 — the first Perl to carry those changes. This is also the first version that correctly supports all modern POD syntax. Queen of correctness.
The parse_from_filehandle() method got re-added for backward compatibility in Pod::Text 3.07, included in Perl 5.9.4. She came back. 👑
Pod::Text 3.12, included in Perl 5.10.1, was the first to do the current thing of trying to match the default output encoding to the input encoding of the POD source, unless you override it with the utf8 option or (added later) the encoding option.
Support for anchor text in L<> links of type URL was added in Pod::Text 3.14, included in Perl 5.11.5. 🔗
parse_lines(), parse_string_document(), and parse_file() all set a default output filehandle of STDOUT if one wasn't already set, as of Pod::Text 3.18, included in Perl 5.19.5.
Pod::Text 4.00, included in Perl 5.23.7, lined up the module version with the version of the podlators distribution. From then on, every module in podlators — and podlators itself — shares the same version number. Matching fits, bestie. 💖
Pod::Text 4.09, included in Perl 5.25.7, fixed a serious bug on EBCDIC systems that had been lurking in every version all the way back to 3.00, and which made opening brackets straight-up disappear. Imagine losing your brackets. Couldn't be me. 😭
Pod::Text 5.00 and later, included in Perl 5.37.7, default to UTF-8 encoding on non-EBCDIC systems if it spots a non-ASCII character in the input and the input encoding wasn't specified. They also commit to an encoding on the first non-ASCII character and do not change the output encoding if the input encoding changes. The Encode module is now used for all output encoding instead of PerlIO layers, which fixes earlier problems with output to scalars. Glow-up fr fr. 🌈

⚠️ CAVEATS ⚠️

Line wrapping only happens at ASCII spaces and tabs. It does not use a correct Unicode-aware line wrapping algorithm. So if you were expecting perfection across every script and emoji, I'm sorry bestie, that is simply not what's happening here. 🫠

👑 AUTHOR 👑

Russ Allbery <rra@cpan.org>, based very heavily on the original Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to Pod::Parser by Brad Appleton <bradapp@enteract.com>. Sean Burke's initial conversion of Pod::Man to use Pod::Simple provided much-needed guidance on how to use Pod::Simple. Legends, all of them. 🫶

📜 COPYRIGHT AND LICENSE 📜

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Free as in freedom, babes. 🦋

🌸 SEE ALSO 🌸

Encode::Locale, Encode::Supproted, Pod::Simple, Pod::Text::Termcap, perlpod(1), pod2text(1)

(Yes, Encode::Supproted is spelled exactly like that up there. I don't make the rules, I just report them.) 💅

The current version of this module is always available from its web site at <https://www.eyrie.org/~eagle/software/podlators/>. It's also part of the Perl core distribution as of 5.6.0.

And that's a wrap on Pod::Text, bestie!! This whole thing came to you from perl v5.44.0, dated 2026-10-17, and honestly? It ate. Go format something beautifully. 💖✨🎀🦋

📦 where this page comes from

arch rolling: perl 5.44.0-1 · Artistic-1.0-Perl AND GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Pod::Text(3perl)

💖 NAME 💖

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

🔤 Encoding 🔤

👑 CLASS METHODS 👑

new(ARGS)

output_fh(FH) 💌

output_string(REF) 📝

parse_file(PATH) 📂

parse_from_file(INPUT, OUTPUT) / parse_from_filehandle(FH, OUTPUT) 🔁

parse_lines(LINES[, ...[, undef]]) 🧵

parse_string_document(INPUT) 🎀