1POD2TEXT(1)           User Contributed Perl Documentation          POD2TEXT(1)
2
3
4

NAME

6       pod2text - Convert POD data to formatted ASCII text
7

SYNOPSIS

9       pod2text [-aclostu] [--code] [--errors=style] [-i indent]
10           [-q quotes] [--nourls] [--stderr] [-w width]
11           [input [output ...]]
12
13       pod2text -h
14

DESCRIPTION

16       pod2text is a front-end for Pod::Text and its subclasses.  It uses them
17       to generate formatted ASCII text from POD source.  It can optionally
18       use either termcap sequences or ANSI color escape sequences to format
19       the text.
20
21       input is the file to read for POD source (the POD can be embedded in
22       code).  If input isn't given, it defaults to "STDIN".  output, if
23       given, is the file to which to write the formatted output.  If output
24       isn't given, the formatted output is written to "STDOUT".  Several POD
25       files can be processed in the same pod2text invocation (saving module
26       load and compile times) by providing multiple pairs of input and output
27       files on the command line.
28

OPTIONS

30       -a, --alt
31           Use an alternate output format that, among other things, uses a
32           different heading style and marks "=item" entries with a colon in
33           the left margin.
34
35       --code
36           Include any non-POD text from the input file in the output as well.
37           Useful for viewing code documented with POD blocks with the POD
38           rendered and the code left intact.
39
40       -c, --color
41           Format the output with ANSI color escape sequences.  Using this
42           option requires that Term::ANSIColor be installed on your system.
43
44       --errors=style
45           Set the error handling style.  "die" says to throw an exception on
46           any POD formatting error.  "stderr" says to report errors on
47           standard error, but not to throw an exception.  "pod" says to
48           include a POD ERRORS section in the resulting documentation
49           summarizing the errors.  "none" ignores POD errors entirely, as
50           much as possible.
51
52           The default is "die".
53
54       -i indent, --indent=indent
55           Set the number of spaces to indent regular text, and the default
56           indentation for "=over" blocks.  Defaults to 4 spaces if this
57           option isn't given.
58
59       -h, --help
60           Print out usage information and exit.
61
62       -l, --loose
63           Print a blank line after a "=head1" heading.  Normally, no blank
64           line is printed after "=head1", although one is still printed after
65           "=head2", because this is the expected formatting for manual pages;
66           if you're formatting arbitrary text documents, using this option is
67           recommended.
68
69       -m width, --left-margin=width, --margin=width
70           The width of the left margin in spaces.  Defaults to 0.  This is
71           the margin for all text, including headings, not the amount by
72           which regular text is indented; for the latter, see -i option.
73
74       --nourls
75           Normally, L<> formatting codes with a URL but anchor text are
76           formatted to show both the anchor text and the URL.  In other
77           words:
78
79               L<foo|http://example.com/>
80
81           is formatted as:
82
83               foo <http://example.com/>
84
85           This flag, if given, suppresses the URL when anchor text is given,
86           so this example would be formatted as just "foo".  This can produce
87           less cluttered output in cases where the URLs are not particularly
88           important.
89
90       -o, --overstrike
91           Format the output with overstrike printing.  Bold text is rendered
92           as character, backspace, character.  Italics and file names are
93           rendered as underscore, backspace, character.  Many pagers, such as
94           less, know how to convert this to bold or underlined text.
95
96       -q quotes, --quotes=quotes
97           Sets the quote marks used to surround C<> text to quotes.  If
98           quotes is a single character, it is used as both the left and right
99           quote.  Otherwise, it is split in half, and the first half of the
100           string is used as the left quote and the second is used as the
101           right quote.
102
103           quotes may also be set to the special value "none", in which case
104           no quote marks are added around C<> text.
105
106       -s, --sentence
107           Assume each sentence ends with two spaces and try to preserve that
108           spacing.  Without this option, all consecutive whitespace in non-
109           verbatim paragraphs is compressed into a single space.
110
111       --stderr
112           By default, pod2text dies if any errors are detected in the POD
113           input.  If --stderr is given and no --errors flag is present,
114           errors are sent to standard error, but pod2text does not abort.
115           This is equivalent to "--errors=stderr" and is supported for
116           backward compatibility.
117
118       -t, --termcap
119           Try to determine the width of the screen and the bold and underline
120           sequences for the terminal from termcap, and use that information
121           in formatting the output.  Output will be wrapped at two columns
122           less than the width of your terminal device.  Using this option
123           requires that your system have a termcap file somewhere where
124           Term::Cap can find it and requires that your system support
125           termios.  With this option, the output of pod2text will contain
126           terminal control sequences for your current terminal type.
127
128       -u, --utf8
129           By default, pod2text tries to use the same output encoding as its
130           input encoding (to be backward-compatible with older versions).
131           This option says to instead force the output encoding to UTF-8.
132
133           Be aware that, when using this option, the input encoding of your
134           POD source should be properly declared unless it's US-ASCII.
135           Pod::Simple will attempt to guess the encoding and may be
136           successful if it's Latin-1 or UTF-8, but it will warn, which by
137           default results in a pod2text failure.  Use the "=encoding" command
138           to declare the encoding.  See perlpod(1) for more information.
139
140       -w, --width=width, -width
141           The column at which to wrap text on the right-hand side.  Defaults
142           to 76, unless -t is given, in which case it's two columns less than
143           the width of your terminal device.
144

EXIT STATUS

146       As long as all documents processed result in some output, even if that
147       output includes errata (a "POD ERRORS" section generated with
148       "--errors=pod"), pod2text will exit with status 0.  If any of the
149       documents being processed do not result in an output document, pod2text
150       will exit with status 1.  If there are syntax errors in a POD document
151       being processed and the error handling style is set to the default of
152       "die", pod2text will abort immediately with exit status 255.
153

DIAGNOSTICS

155       If pod2text fails with errors, see Pod::Text and Pod::Simple for
156       information about what those errors might mean.  Internally, it can
157       also produce the following diagnostics:
158
159       -c (--color) requires Term::ANSIColor be installed
160           (F) -c or --color were given, but Term::ANSIColor could not be
161           loaded.
162
163       Unknown option: %s
164           (F) An unknown command line option was given.
165
166       In addition, other Getopt::Long error messages may result from invalid
167       command-line options.
168

ENVIRONMENT

170       COLUMNS
171           If -t is given, pod2text will take the current width of your screen
172           from this environment variable, if available.  It overrides
173           terminal width information in TERMCAP.
174
175       TERMCAP
176           If -t is given, pod2text will use the contents of this environment
177           variable if available to determine the correct formatting sequences
178           for your current terminal device.
179

AUTHOR

181       Russ Allbery <rra@cpan.org>.
182
184       Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019 Russ Allbery
185       <rra@cpan.org>
186
187       This program is free software; you may redistribute it and/or modify it
188       under the same terms as Perl itself.
189

SEE ALSO

191       Pod::Text, Pod::Text::Color, Pod::Text::Overstrike, Pod::Text::Termcap,
192       Pod::Simple, perlpod(1)
193
194       The current version of this script is always available from its web
195       site at <https://www.eyrie.org/~eagle/software/podlators/>.  It is also
196       part of the Perl core distribution as of 5.6.0.
197
198
199
200perl v5.34.0                      2022-01-21                       POD2TEXT(1)
Impressum