Debian Codegraph @

upstream/debian-unstable/man3/Pod::Text.3perl

raw
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 "Pod::Text 3perl"
58 .TH Pod::Text 3perl 2025-11-16 "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 Pod::Text \- Convert POD data to formatted text
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& use Pod::Text;
69 \& my $parser = Pod::Text\->new (sentence => 1, width => 78);
70 \&
71 \& # Read POD from STDIN and write to STDOUT.
72 \& $parser\->parse_from_filehandle;
73 \&
74 \& # Read POD from file.pod and write to file.txt.
75 \& $parser\->parse_from_file (\*(Aqfile.pod\*(Aq, \*(Aqfile.txt\*(Aq);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 Pod::Text is a module that can convert documentation in the POD format (the
80 preferred language for documenting Perl) into formatted text. It uses no
81 special formatting controls or codes, and its output is therefore suitable for
82 nearly any device.
83 .SS Encoding
84 .IX Subsection "Encoding"
85 Pod::Text uses the following logic to choose an output encoding, in order:
86 .IP 1. 4
87 If a PerlIO encoding layer is set on the output file handle, do not do any
88 output encoding and will instead rely on the PerlIO encoding layer.
89 .IP 2. 4
90 If the \f(CW\*(C`encoding\*(C'\fR or \f(CW\*(C`utf8\*(C'\fR options are set, use the output encoding
91 specified by those options.
92 .IP 3. 4
93 If the input encoding of the POD source file was explicitly specified (using
94 \&\f(CW\*(C`=encoding\*(C'\fR) or automatically detected by Pod::Simple, use that as the output
95 encoding as well.
96 .IP 4. 4
97 Otherwise, if running on a non-EBCDIC system, use UTF\-8 as the output
98 encoding. Since this is a superset of ASCII, this will result in ASCII output
99 unless the POD input contains non-ASCII characters without declaring or
100 autodetecting an encoding (usually via E<> escapes).
101 .IP 5. 4
102 Otherwise, for EBCDIC systems, output without doing any encoding and hope
103 this works.
104 .PP
105 One caveat: Pod::Text has to commit to an output encoding the first time it
106 outputs a non-ASCII character, and then has to stick with it for consistency.
107 However, \f(CW\*(C`=encoding\*(C'\fR commands don't have to be at the beginning of a POD
108 document. If someone uses a non-ASCII character early in a document with an
109 escape, such as E<0xEF>, and then puts \f(CW\*(C`=encoding iso\-8859\-1\*(C'\fR later,
110 ideally Pod::Text would follow rule 3 and output the entire document as ISO
111 8859\-1. Instead, it will commit to UTF\-8 following rule 4 as soon as it sees
112 that escape, and then stick with that encoding for the rest of the document.
113 .PP
114 Unfortunately, there's no universally good choice for an output encoding.
115 Each choice will be incorrect in some circumstances. This approach was chosen
116 primarily for backwards compatibility. Callers should consider forcing the
117 output encoding via \f(CW\*(C`encoding\*(C'\fR if they have any knowledge about what encoding
118 the user may expect.
119 .PP
120 In particular, consider importing the Encode::Locale module, if available,
121 and setting \f(CW\*(C`encoding\*(C'\fR to \f(CW\*(C`locale\*(C'\fR to use an output encoding appropriate to
122 the user's locale. But be aware that if the user is not using locales or is
123 using a locale of \f(CW\*(C`C\*(C'\fR, Encode::Locale will set the output encoding to
124 US-ASCII. This will cause all non-ASCII characters will be replaced with \f(CW\*(C`?\*(C'\fR
125 and produce a flurry of warnings about unsupported characters, which may or
126 may not be what you want.
127 .SH "CLASS METHODS"
128 .IX Header "CLASS METHODS"
129 .IP new(ARGS) 4
130 .IX Item "new(ARGS)"
131 Create a new Pod::Text object. ARGS should be a list of key/value pairs,
132 where the keys are chosen from the following. Each option is annotated with
133 the version of Pod::Text in which that option was added with its current
134 meaning.
135 .RS 4
136 .IP alt 4
137 .IX Item "alt"
138 [2.00] If set to a true value, selects an alternate output format that, among
139 other things, uses a different heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a
140 colon in the left margin. Defaults to false.
141 .IP code 4
142 .IX Item "code"
143 [2.13] If set to a true value, the non-POD parts of the input file will be
144 included in the output. Useful for viewing code documented with POD blocks
145 with the POD rendered and the code left intact.
146 .IP encoding 4
147 .IX Item "encoding"
148 [5.00] Specifies the encoding of the output. The value must be an encoding
149 recognized by the Encode module (see Encode::Supported). If the output
150 contains characters that cannot be represented in this encoding, that is an
151 error that will be reported as configured by the \f(CW\*(C`errors\*(C'\fR option. If error
152 handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character will be replaced
153 with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR).
154 .Sp
155 If the output file handle has a PerlIO encoding layer set, this parameter will
156 be ignored and no encoding will be done by Pod::Man. It will instead rely on
157 the encoding layer to make whatever output encoding transformations are
158 desired.
159 .Sp
160 WARNING: The input encoding of the POD source is independent from the output
161 encoding, and setting this option does not affect the interpretation of the
162 POD input. Unless your POD source is US-ASCII, its encoding should be
163 declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source, as near to the top of
164 the file as possible. If this is not done, Pod::Simple will will attempt to
165 guess the encoding and may be successful if it's Latin\-1 or UTF\-8, but it will
166 produce warnings. See \fBperlpod\fR\|(1) for more information.
167 .IP errors 4
168 .IX Item "errors"
169 [3.17] How to report errors. \f(CW\*(C`die\*(C'\fR says to throw an exception on any POD
170 formatting error. \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error, but not
171 to throw an exception. \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in the
172 resulting documentation summarizing the errors. \f(CW\*(C`none\*(C'\fR ignores POD errors
173 entirely, as much as possible.
174 .Sp
175 The default is \f(CW\*(C`pod\*(C'\fR.
176 .IP guesswork 4
177 .IX Item "guesswork"
178 [5.01] By default, Pod::Text applies some default formatting rules based on
179 guesswork and regular expressions that are intended to make writing Perl
180 documentation easier and require less explicit markup. These rules may not
181 always be appropriate, particularly for documentation that isn't about Perl.
182 This option allows turning all or some of it off.
183 .Sp
184 The special value \f(CW\*(C`all\*(C'\fR enables all guesswork. This is also the default for
185 backward compatibility reasons. The special value \f(CW\*(C`none\*(C'\fR disables all
186 guesswork. Otherwise, the value of this option should be a comma-separated
187 list of one or more of the following keywords:
188 .RS 4
189 .IP quoting 4
190 .IX Item "quoting"
191 If no guesswork is enabled, any text enclosed in C<> is surrounded by
192 double quotes in nroff (terminal) output unless the contents are already
193 quoted. When this guesswork is enabled, quote marks will also be suppressed
194 for Perl variables, function names, function calls, numbers, and hex
195 constants.
196 .RE
197 .RS 4
198 .Sp
199 Any unknown guesswork name is silently ignored (for potential future
200 compatibility), so be careful about spelling.
201 .RE
202 .IP indent 4
203 .IX Item "indent"
204 [2.00] The number of spaces to indent regular text, and the default
205 indentation for \f(CW\*(C`=over\*(C'\fR blocks. Defaults to 4.
206 .IP loose 4
207 .IX Item "loose"
208 [2.00] If set to a true value, a blank line is printed after a \f(CW\*(C`=head1\*(C'\fR
209 heading. If set to false (the default), no blank line is printed after
210 \&\f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR. This is the default
211 because it's the expected formatting for manual pages; if you're formatting
212 arbitrary text documents, setting this to true may result in more pleasing
213 output.
214 .IP margin 4
215 .IX Item "margin"
216 [2.21] The width of the left margin in spaces. Defaults to 0. This is the
217 margin for all text, including headings, not the amount by which regular text
218 is indented; for the latter, see the \fIindent\fR option. To set the right
219 margin, see the \fIwidth\fR option.
220 .IP nourls 4
221 .IX Item "nourls"
222 [3.17] Normally, L<> formatting codes with a URL but anchor text are
223 formatted to show both the anchor text and the URL. In other words:
224 .Sp
225 .Vb 1
226 \& L<foo|http://example.com/>
227 .Ve
228 .Sp
229 is formatted as:
230 .Sp
231 .Vb 1
232 \& foo <http://example.com/>
233 .Ve
234 .Sp
235 This option, if set to a true value, suppresses the URL when anchor text is
236 given, so this example would be formatted as just \f(CW\*(C`foo\*(C'\fR. This can produce
237 less cluttered output in cases where the URLs are not particularly important.
238 .IP quotes 4
239 .IX Item "quotes"
240 [4.00] Sets the quote marks used to surround C<> text. If the value is a
241 single character, it is used as both the left and right quote. Otherwise, it
242 is split in half, and the first half of the string is used as the left quote
243 and the second is used as the right quote.
244 .Sp
245 This may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
246 marks are added around C<> text.
247 .IP sentence 4
248 .IX Item "sentence"
249 [3.00] If set to a true value, Pod::Text will assume that each sentence ends
250 in two spaces, and will try to preserve that spacing. If set to false, all
251 consecutive whitespace in non-verbatim paragraphs is compressed into a single
252 space. Defaults to false.
253 .IP stderr 4
254 .IX Item "stderr"
255 [3.10] Send error messages about invalid POD to standard error instead of
256 appending a POD ERRORS section to the generated output. This is equivalent to
257 setting \f(CW\*(C`errors\*(C'\fR to \f(CW\*(C`stderr\*(C'\fR if \f(CW\*(C`errors\*(C'\fR is not already set. It is
258 supported for backward compatibility.
259 .IP utf8 4
260 .IX Item "utf8"
261 [3.12] If this option is set to a true value, the output encoding is set to
262 UTF\-8. This is equivalent to setting \f(CW\*(C`encoding\*(C'\fR to \f(CW\*(C`UTF\-8\*(C'\fR if \f(CW\*(C`encoding\*(C'\fR
263 is not already set. It is supported for backward compatibility.
264 .IP width 4
265 .IX Item "width"
266 [2.00] The column at which to wrap text on the right-hand side. Defaults to
267 76.
268 .RE
269 .RS 4
270 .RE
271 .SH "INSTANCE METHODS"
272 .IX Header "INSTANCE METHODS"
273 As a derived class from Pod::Simple, Pod::Text supports the same methods and
274 interfaces. See Pod::Simple for all the details. This section summarizes
275 the most-frequently-used methods and the ones added by Pod::Text.
276 .IP output_fh(FH) 4
277 .IX Item "output_fh(FH)"
278 Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR
279 to the file handle FH instead of \f(CW\*(C`STDOUT\*(C'\fR.
280 .IP output_string(REF) 4
281 .IX Item "output_string(REF)"
282 Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR
283 to the scalar variable pointed to by REF, rather than \f(CW\*(C`STDOUT\*(C'\fR. For example:
284 .Sp
285 .Vb 4
286 \& my $man = Pod::Man\->new();
287 \& my $output;
288 \& $man\->output_string(\e$output);
289 \& $man\->parse_file(\*(Aq/some/input/file\*(Aq);
290 .Ve
291 .Sp
292 Be aware that the output in that variable will already be encoded (see
293 "Encoding").
294 .IP parse_file(PATH) 4
295 .IX Item "parse_file(PATH)"
296 Read the POD source from PATH and format it. By default, the output is sent
297 to \f(CW\*(C`STDOUT\*(C'\fR, but this can be changed with the \fBoutput_fh()\fR or \fBoutput_string()\fR
298 methods.
299 .IP "parse_from_file(INPUT, OUTPUT)" 4
300 .IX Item "parse_from_file(INPUT, OUTPUT)"
301 .PD 0
302 .IP "parse_from_filehandle(FH, OUTPUT)" 4
303 .IX Item "parse_from_filehandle(FH, OUTPUT)"
304 .PD
305 Read the POD source from INPUT, format it, and output the results to OUTPUT.
306 .Sp
307 \&\fBparse_from_filehandle()\fR is provided for backward compatibility with older
308 versions of Pod::Man. \fBparse_from_file()\fR should be used instead.
309 .IP "parse_lines(LINES[, ...[, undef]])" 4
310 .IX Item "parse_lines(LINES[, ...[, undef]])"
311 Parse the provided lines as POD source, writing the output to either \f(CW\*(C`STDOUT\*(C'\fR
312 or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR methods. This
313 method can be called repeatedly to provide more input lines. An explicit
314 \&\f(CW\*(C`undef\*(C'\fR should be passed to indicate the end of input.
315 .Sp
316 This method expects raw bytes, not decoded characters.
317 .IP parse_string_document(INPUT) 4
318 .IX Item "parse_string_document(INPUT)"
319 Parse the provided scalar variable as POD source, writing the output to either
320 \&\f(CW\*(C`STDOUT\*(C'\fR or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR
321 methods.
322 .Sp
323 This method expects raw bytes, not decoded characters.
324 .SH FUNCTIONS
325 .IX Header "FUNCTIONS"
326 Pod::Text exports one function for backward compatibility with older versions.
327 This function is deprecated; instead, use the object-oriented interface
328 described above.
329 .IP "pod2text([[\-a,] [\-NNN,]] INPUT[, OUTPUT])" 4
330 .IX Item "pod2text([[-a,] [-NNN,]] INPUT[, OUTPUT])"
331 Convert the POD source from INPUT to text and write it to OUTPUT. If OUTPUT
332 is not given, defaults to \f(CW\*(C`STDOUT\*(C'\fR. INPUT can be any expression supported as
333 the second argument to two-argument \fBopen()\fR.
334 .Sp
335 If \f(CW\*(C`\-a\*(C'\fR is given as an initial argument, pass the \f(CW\*(C`alt\*(C'\fR option to the
336 Pod::Text constructor. This enables alternative formatting.
337 .Sp
338 If \f(CW\*(C`\-NNN\*(C'\fR is given as an initial argument, pass the \f(CW\*(C`width\*(C'\fR option to the
339 Pod::Text constructor with the number \f(CW\*(C`NNN\*(C'\fR as its argument. This sets the
340 wrap line width to NNN.
341 .SH DIAGNOSTICS
342 .IX Header "DIAGNOSTICS"
343 .IP "Bizarre space in item" 4
344 .IX Item "Bizarre space in item"
345 .PD 0
346 .IP "Item called without tag" 4
347 .IX Item "Item called without tag"
348 .PD
349 (W) Something has gone wrong in internal \f(CW\*(C`=item\*(C'\fR processing. These
350 messages indicate a bug in Pod::Text; you should never see them.
351 .ie n .IP "Can't open %s for reading: %s" 4
352 .el .IP "Can't open \f(CW%s\fR for reading: \f(CW%s\fR" 4
353 .IX Item "Can't open %s for reading: %s"
354 (F) Pod::Text was invoked via the compatibility mode \fBpod2text()\fR interface
355 and the input file it was given could not be opened.
356 .IP "Invalid errors setting ""%s""" 4
357 .IX Item "Invalid errors setting ""%s"""
358 (F) The \f(CW\*(C`errors\*(C'\fR parameter to the constructor was set to an unknown value.
359 .IP "Invalid quote specification ""%s""" 4
360 .IX Item "Invalid quote specification ""%s"""
361 (F) The quote specification given (the \f(CW\*(C`quotes\*(C'\fR option to the
362 constructor) was invalid. A quote specification must be either one
363 character long or an even number (greater than one) characters long.
364 .IP "POD document had syntax errors" 4
365 .IX Item "POD document had syntax errors"
366 (F) The POD document being formatted had syntax errors and the \f(CW\*(C`errors\*(C'\fR
367 option was set to \f(CW\*(C`die\*(C'\fR.
368 .SH COMPATIBILITY
369 .IX Header "COMPATIBILITY"
370 Pod::Text 2.03 (based on Pod::Parser) was the first version of this module
371 included with Perl, in Perl 5.6.0. Earlier versions of Perl had a different
372 Pod::Text module, with a different API.
373 .PP
374 The current API based on Pod::Simple was added in Pod::Text 3.00.
375 Pod::Text 3.01 was included in Perl 5.9.3, the first version of Perl to
376 incorporate those changes. This is the first version that correctly supports
377 all modern POD syntax. The \fBparse_from_filehandle()\fR method was re-added for
378 backward compatibility in Pod::Text 3.07, included in Perl 5.9.4.
379 .PP
380 Pod::Text 3.12, included in Perl 5.10.1, first implemented the current
381 practice of attempting to match the default output encoding with the input
382 encoding of the POD source, unless overridden by the \f(CW\*(C`utf8\*(C'\fR option or (added
383 later) the \f(CW\*(C`encoding\*(C'\fR option.
384 .PP
385 Support for anchor text in L<> links of type URL was added in Pod::Text
386 3.14, included in Perl 5.11.5.
387 .PP
388 \&\fBparse_lines()\fR, \fBparse_string_document()\fR, and \fBparse_file()\fR set a default output
389 file handle of \f(CW\*(C`STDOUT\*(C'\fR if one was not already set as of Pod::Text 3.18,
390 included in Perl 5.19.5.
391 .PP
392 Pod::Text 4.00, included in Perl 5.23.7, aligned the module version and the
393 version of the podlators distribution. All modules included in podlators, and
394 the podlators distribution itself, share the same version number from this
395 point forward.
396 .PP
397 Pod::Text 4.09, included in Perl 5.25.7, fixed a serious bug on EBCDIC
398 systems, present in all versions back to 3.00, that would cause opening
399 brackets to disappear.
400 .PP
401 Pod::Text 5.00 now defaults, on non-EBCDIC systems, to UTF\-8 encoding if it
402 sees a non-ASCII character in the input and the input encoding is not
403 specified. It also commits to an encoding with the first non-ASCII character
404 and does not change the output encoding if the input encoding changes. The
405 Encode module is now used for all output encoding rather than PerlIO
406 layers, which fixes earlier problems with output to scalars.
407 .SH AUTHOR
408 .IX Header "AUTHOR"
409 Russ Allbery <[email protected]>, based \fIvery\fR heavily on the original Pod::Text
410 by Tom Christiansen <[email protected]> and its conversion to Pod::Parser
411 by Brad Appleton <[email protected]>. Sean Burke's initial conversion of
412 Pod::Man to use Pod::Simple provided much-needed guidance on how to use
413 Pod::Simple.
414 .SH "COPYRIGHT AND LICENSE"
415 .IX Header "COPYRIGHT AND LICENSE"
416 Copyright 1999\-2002, 2004, 2006, 2008\-2009, 2012\-2016, 2018\-2019, 2022 Russ
417 Allbery <[email protected]>
418 .PP
419 This program is free software; you may redistribute it and/or modify it
420 under the same terms as Perl itself.
421 .SH "SEE ALSO"
422 .IX Header "SEE ALSO"
423 Encode::Locale, Encode::Supproted, Pod::Simple,
424 Pod::Text::Termcap, \fBperlpod\fR\|(1), \fBpod2text\fR\|(1)
425 .PP
426 The current version of this module is always available from its web site at
427 <https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
428 Perl core distribution as of 5.6.0.