Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Pod::Text.3pm

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