1POD2TEXT(1) User Contributed Perl Documentation POD2TEXT(1)
2
6 pod2text - Convert POD data to formatted ASCII text
7
9 pod2text [-aclostu] [--code] [--errors=style] [-i indent]
10 [-q quotes] [--nourls] [--stderr] [-w width]
11 [input [output ...]]
12 pod2text -h
14
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 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
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 --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 -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 --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 The default is "die".
53 -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 -h, --help
60 Print out usage information and exit.
61 -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 -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 --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 L<foo|http://example.com/>
80 is formatted as:
82 foo <http://example.com/>
84 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 -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 -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 quotes may also be set to the special value "none", in which case
104 no quote marks are added around C<> text.
105 -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 --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 -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 -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 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 -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
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
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 -c (--color) requires Term::ANSIColor be installed
160 (F) -c or --color were given, but Term::ANSIColor could not be
161 loaded.
162 Unknown option: %s
164 (F) An unknown command line option was given.
165 In addition, other Getopt::Long error messages may result from invalid
167 command-line options.
168
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 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
181 Russ Allbery <rra@cpan.org>.
182
184 Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019 Russ Allbery
185 <rra@cpan.org>
186 This program is free software; you may redistribute it and/or modify it
188 under the same terms as Perl itself.
189
191 Pod::Text, Pod::Text::Color, Pod::Text::Overstrike, Pod::Text::Termcap,
192 Pod::Simple, perlpod(1)
193 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.
197perl v5.34.0 2022-01-21 POD2TEXT(1)