| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "POD2TEXT 1" |
| 58 |
.TH POD2TEXT 1 2026-04-10 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
pod2text \- Convert POD data to formatted ASCII text |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
pod2text [\fB\-aclostu\fR] [\fB\-\-code\fR] [\fB\-e\fR\ \fIencoding\fR] |
| 68 |
[\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]] |
| 69 |
[\fB\-i\fR\ \fIindent\fR] [\fB\-q\fR\ \fIquotes\fR] |
| 70 |
[\fB\-\-nourls\fR] [\fB\-\-stderr\fR] [\fB\-w\fR\ \fIwidth\fR] [\fIinput\fR [\fIoutput\fR ...]] |
| 71 |
.PP |
| 72 |
pod2text \fB\-h\fR |
| 73 |
.SH DESCRIPTION |
| 74 |
.IX Header "DESCRIPTION" |
| 75 |
\&\fBpod2text\fR is a wrapper script around the Pod::Text and its subclasses. |
| 76 |
It uses them to generate formatted text from POD source. It can optionally |
| 77 |
use either termcap sequences or ANSI color escape sequences to format the |
| 78 |
text. |
| 79 |
.PP |
| 80 |
\&\fIinput\fR is the file to read for POD source (the POD can be embedded in code). |
| 81 |
If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR. \fIoutput\fR, if given, is the |
| 82 |
file to which to write the formatted output. If \fIoutput\fR isn't given, the |
| 83 |
formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR. Several POD files can be processed |
| 84 |
in the same \fBpod2text\fR invocation (saving module load and compile times) by |
| 85 |
providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line. |
| 86 |
.PP |
| 87 |
By default, the output encoding is the same as the encoding of the input file, |
| 88 |
or UTF\-8 if that encoding is not set (except on EBCDIC systems). See the |
| 89 |
\&\fB\-e\fR option to explicitly set the output encoding and "Encoding" in Pod::Text |
| 90 |
for more discussion. |
| 91 |
.SH OPTIONS |
| 92 |
.IX Header "OPTIONS" |
| 93 |
Each option is annotated with the version of podlators in which that option |
| 94 |
was added with its current meaning. |
| 95 |
.IP "\fB\-a\fR, \fB\-\-alt\fR" 4 |
| 96 |
.IX Item "-a, --alt" |
| 97 |
[1.00] Use an alternate output format that, among other things, uses a |
| 98 |
different heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a colon in the left |
| 99 |
margin. |
| 100 |
.IP \fB\-\-code\fR 4 |
| 101 |
.IX Item "--code" |
| 102 |
[1.11] Include any non-POD text from the input file in the output as well. |
| 103 |
Useful for viewing code documented with POD blocks with the POD rendered and |
| 104 |
the code left intact. |
| 105 |
.IP "\fB\-c\fR, \fB\-\-color\fR" 4 |
| 106 |
.IX Item "-c, --color" |
| 107 |
[1.00] Format the output with ANSI color escape sequences. Using this option |
| 108 |
requires that Term::ANSIColor be installed on your system. |
| 109 |
.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR" 4 |
| 110 |
.IX Item "-e encoding, --encoding=encoding" |
| 111 |
[5.00] Specifies the encoding of the output. \fIencoding\fR must be an encoding |
| 112 |
recognized by the Encode module (see Encode::Supported). If the output |
| 113 |
contains characters that cannot be represented in this encoding, that is an |
| 114 |
error that will be reported as configured by the \f(CW\*(C`errors\*(C'\fR option. If error |
| 115 |
handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character will be replaced |
| 116 |
with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR). |
| 117 |
.Sp |
| 118 |
WARNING: The input encoding of the POD source is independent from the output |
| 119 |
encoding, and setting this option does not affect the interpretation of the |
| 120 |
POD input. Unless your POD source is US-ASCII, its encoding should be |
| 121 |
declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source, as near to the top of |
| 122 |
the file as possible. If this is not done, Pod::Simple will will attempt to |
| 123 |
guess the encoding and may be successful if it's Latin\-1 or UTF\-8, but it will |
| 124 |
produce warnings. See \fBperlpod\fR\|(1) for more information. |
| 125 |
.IP \fB\-\-errors\fR=\fIstyle\fR 4 |
| 126 |
.IX Item "--errors=style" |
| 127 |
[2.5.0] Set the error handling style. \f(CW\*(C`die\*(C'\fR says to throw an exception on |
| 128 |
any POD formatting error. \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error, |
| 129 |
but not to throw an exception. \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in |
| 130 |
the resulting documentation summarizing the errors. \f(CW\*(C`none\*(C'\fR ignores POD |
| 131 |
errors entirely, as much as possible. |
| 132 |
.Sp |
| 133 |
The default is \f(CW\*(C`die\*(C'\fR. |
| 134 |
.IP \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4 |
| 135 |
.IX Item "--guesswork=rule[,rule...]" |
| 136 |
[5.01] By default, \fBpod2text\fR applies some default formatting rules based on |
| 137 |
guesswork and regular expressions that are intended to make writing Perl |
| 138 |
documentation easier and require less explicit markup. These rules may not |
| 139 |
always be appropriate, particularly for documentation that isn't about Perl. |
| 140 |
This option allows turning all or some of it off. |
| 141 |
.Sp |
| 142 |
The special rule \f(CW\*(C`all\*(C'\fR enables all guesswork. This is also the default for |
| 143 |
backward compatibility reasons. The special rule \f(CW\*(C`none\*(C'\fR disables all |
| 144 |
guesswork. Otherwise, the value of this option should be a comma-separated |
| 145 |
list of one or more of the following keywords: |
| 146 |
.RS 4 |
| 147 |
.IP quoting 4 |
| 148 |
.IX Item "quoting" |
| 149 |
If no guesswork is enabled, any text enclosed in C<> is surrounded by |
| 150 |
double quotes in nroff (terminal) output unless the contents are already |
| 151 |
quoted. When this guesswork is enabled, quote marks will also be suppressed |
| 152 |
for Perl variables, function names, function calls, numbers, and hex |
| 153 |
constants. |
| 154 |
.RE |
| 155 |
.RS 4 |
| 156 |
.Sp |
| 157 |
Any unknown guesswork name is silently ignored (for potential future |
| 158 |
compatibility), so be careful about spelling. |
| 159 |
.RE |
| 160 |
.IP "\fB\-i\fR \fIindent\fR, \fB\-\-indent=\fR\fIindent\fR" 4 |
| 161 |
.IX Item "-i indent, --indent=indent" |
| 162 |
[1.00] Set the number of spaces to indent regular text, and the default |
| 163 |
indentation for \f(CW\*(C`=over\*(C'\fR blocks. Defaults to 4 spaces if this option isn't |
| 164 |
given. |
| 165 |
.IP "\fB\-h\fR, \fB\-\-help\fR" 4 |
| 166 |
.IX Item "-h, --help" |
| 167 |
[1.00] Print out usage information and exit. |
| 168 |
.IP "\fB\-l\fR, \fB\-\-loose\fR" 4 |
| 169 |
.IX Item "-l, --loose" |
| 170 |
[1.00] Print a blank line after a \f(CW\*(C`=head1\*(C'\fR heading. Normally, no blank line |
| 171 |
is printed after \f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR, |
| 172 |
because this is the expected formatting for manual pages; if you're formatting |
| 173 |
arbitrary text documents, using this option is recommended. |
| 174 |
.IP "\fB\-m\fR \fIwidth\fR, \fB\-\-left\-margin\fR=\fIwidth\fR, \fB\-\-margin\fR=\fIwidth\fR" 4 |
| 175 |
.IX Item "-m width, --left-margin=width, --margin=width" |
| 176 |
[1.24] The width of the left margin in spaces. Defaults to 0. This is the |
| 177 |
margin for all text, including headings, not the amount by which regular text |
| 178 |
is indented; for the latter, see \fB\-i\fR option. |
| 179 |
.IP \fB\-\-nourls\fR 4 |
| 180 |
.IX Item "--nourls" |
| 181 |
[2.5.0] Normally, L<> formatting codes with a URL but anchor text are |
| 182 |
formatted to show both the anchor text and the URL. In other words: |
| 183 |
.Sp |
| 184 |
.Vb 1 |
| 185 |
\& L<foo|http://example.com/> |
| 186 |
.Ve |
| 187 |
.Sp |
| 188 |
is formatted as: |
| 189 |
.Sp |
| 190 |
.Vb 1 |
| 191 |
\& foo <http://example.com/> |
| 192 |
.Ve |
| 193 |
.Sp |
| 194 |
This flag, if given, suppresses the URL when anchor text is given, so this |
| 195 |
example would be formatted as just \f(CW\*(C`foo\*(C'\fR. This can produce less cluttered |
| 196 |
output in cases where the URLs are not particularly important. |
| 197 |
.IP "\fB\-o\fR, \fB\-\-overstrike\fR" 4 |
| 198 |
.IX Item "-o, --overstrike" |
| 199 |
[1.06] Format the output with overstrike printing. Bold text is rendered as |
| 200 |
character, backspace, character. Italics and file names are rendered as |
| 201 |
underscore, backspace, character. Many pagers, such as \fBless\fR, know how to |
| 202 |
convert this to bold or underlined text. |
| 203 |
.IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4 |
| 204 |
.IX Item "-q quotes, --quotes=quotes" |
| 205 |
[4.00] Sets the quote marks used to surround C<> text to \fIquotes\fR. If |
| 206 |
\&\fIquotes\fR is a single character, it is used as both the left and right quote. |
| 207 |
Otherwise, it is split in half, and the first half of the string is used as |
| 208 |
the left quote and the second is used as the right quote. |
| 209 |
.Sp |
| 210 |
\&\fIquotes\fR may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote |
| 211 |
marks are added around C<> text. |
| 212 |
.IP "\fB\-s\fR, \fB\-\-sentence\fR" 4 |
| 213 |
.IX Item "-s, --sentence" |
| 214 |
[1.00] Assume each sentence ends with two spaces and try to preserve that |
| 215 |
spacing. Without this option, all consecutive whitespace in non-verbatim |
| 216 |
paragraphs is compressed into a single space. |
| 217 |
.IP \fB\-\-stderr\fR 4 |
| 218 |
.IX Item "--stderr" |
| 219 |
[2.1.3] By default, \fBpod2text\fR dies if any errors are detected in the POD |
| 220 |
input. If \fB\-\-stderr\fR is given and no \fB\-\-errors\fR flag is present, errors are |
| 221 |
sent to standard error, but \fBpod2text\fR does not abort. This is equivalent to |
| 222 |
\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility. |
| 223 |
.IP "\fB\-t\fR, \fB\-\-termcap\fR" 4 |
| 224 |
.IX Item "-t, --termcap" |
| 225 |
[1.00] Try to determine the width of the screen and the bold and underline |
| 226 |
sequences for the terminal from termcap, and use that information in |
| 227 |
formatting the output. Output will be wrapped at two columns less than the |
| 228 |
width of your terminal device. Using this option requires that your system |
| 229 |
have a termcap file somewhere where Term::Cap can find it and requires that |
| 230 |
your system support termios. With this option, the output of \fBpod2text\fR will |
| 231 |
contain terminal control sequences for your current terminal type. |
| 232 |
.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4 |
| 233 |
.IX Item "-u, --utf8" |
| 234 |
[2.2.0] Set the output encoding to UTF\-8. This is equivalent to |
| 235 |
\&\f(CW\*(C`\-\-encoding=UTF\-8\*(C'\fR and is supported for backward compatibility. |
| 236 |
.IP "\fB\-w\fR, \fB\-\-width=\fR\fIwidth\fR, \fB\-\fR\fIwidth\fR" 4 |
| 237 |
.IX Item "-w, --width=width, -width" |
| 238 |
[1.00] The column at which to wrap text on the right-hand side. Defaults to |
| 239 |
76, unless \fB\-t\fR is given, in which case it's two columns less than the width |
| 240 |
of your terminal device. |
| 241 |
.SH "EXIT STATUS" |
| 242 |
.IX Header "EXIT STATUS" |
| 243 |
As long as all documents processed result in some output, even if that output |
| 244 |
includes errata (a \f(CW\*(C`POD ERRORS\*(C'\fR section generated with \f(CW\*(C`\-\-errors=pod\*(C'\fR), |
| 245 |
\&\fBpod2text\fR will exit with status 0. If any of the documents being processed |
| 246 |
do not result in an output document, \fBpod2text\fR will exit with status 1. If |
| 247 |
there are syntax errors in a POD document being processed and the error |
| 248 |
handling style is set to the default of \f(CW\*(C`die\*(C'\fR, \fBpod2text\fR will abort |
| 249 |
immediately with exit status 255. |
| 250 |
.SH DIAGNOSTICS |
| 251 |
.IX Header "DIAGNOSTICS" |
| 252 |
If \fBpod2text\fR fails with errors, see Pod::Text and Pod::Simple for |
| 253 |
information about what those errors might mean. Internally, it can also |
| 254 |
produce the following diagnostics: |
| 255 |
.IP "\-c (\-\-color) requires Term::ANSIColor be installed" 4 |
| 256 |
.IX Item "-c (--color) requires Term::ANSIColor be installed" |
| 257 |
(F) \fB\-c\fR or \fB\-\-color\fR were given, but Term::ANSIColor could not be loaded. |
| 258 |
.ie n .IP "Unknown option: %s" 4 |
| 259 |
.el .IP "Unknown option: \f(CW%s\fR" 4 |
| 260 |
.IX Item "Unknown option: %s" |
| 261 |
(F) An unknown command line option was given. |
| 262 |
.PP |
| 263 |
In addition, other Getopt::Long error messages may result from invalid |
| 264 |
command-line options. |
| 265 |
.SH ENVIRONMENT |
| 266 |
.IX Header "ENVIRONMENT" |
| 267 |
.IP COLUMNS 4 |
| 268 |
.IX Item "COLUMNS" |
| 269 |
If \fB\-t\fR is given, \fBpod2text\fR will take the current width of your screen from |
| 270 |
this environment variable, if available. It overrides terminal width |
| 271 |
information in TERMCAP. |
| 272 |
.IP TERMCAP 4 |
| 273 |
.IX Item "TERMCAP" |
| 274 |
If \fB\-t\fR is given, \fBpod2text\fR will use the contents of this environment |
| 275 |
variable if available to determine the correct formatting sequences for your |
| 276 |
current terminal device. |
| 277 |
.SH AUTHOR |
| 278 |
.IX Header "AUTHOR" |
| 279 |
Russ Allbery <[email protected]>. |
| 280 |
.SH "COPYRIGHT AND LICENSE" |
| 281 |
.IX Header "COPYRIGHT AND LICENSE" |
| 282 |
Copyright 1999\-2001, 2004, 2006, 2008, 2010, 2012\-2019, 2022 Russ Allbery |
| 283 |
<[email protected]> |
| 284 |
.PP |
| 285 |
This program is free software; you may redistribute it and/or modify it |
| 286 |
under the same terms as Perl itself. |
| 287 |
.SH "SEE ALSO" |
| 288 |
.IX Header "SEE ALSO" |
| 289 |
Encode::Supported, Pod::Text, Pod::Text::Color, |
| 290 |
Pod::Text::Overstrike, Pod::Text::Termcap, Pod::Simple, \fBperlpod\fR\|(1) |
| 291 |
.PP |
| 292 |
The current version of this script is always available from its web site at |
| 293 |
<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the |
| 294 |
Perl core distribution as of 5.6.0. |