Pod::Text(3pm)

1Pod::Text(3)          User Contributed Perl Documentation         Pod::Text(3)
2
3
4

NAME

6       Pod::Text - Convert POD data to formatted text
7

SYNOPSIS

9           use Pod::Text;
10           my $parser = Pod::Text->new (sentence => 1, width => 78);
11
12           # Read POD from STDIN and write to STDOUT.
13           $parser->parse_from_filehandle;
14
15           # Read POD from file.pod and write to file.txt.
16           $parser->parse_from_file ('file.pod', 'file.txt');
17

DESCRIPTION

19       Pod::Text is a module that can convert documentation in the POD format
20       (the preferred language for documenting Perl) into formatted text.  It
21       uses no special formatting controls or codes, and its output is
22       therefore suitable for nearly any device.
23
24   Encoding
25       Pod::Text uses the following logic to choose an output encoding, in
26       order:
27
28       1.  If a PerlIO encoding layer is set on the output file handle, do not
29           do any output encoding and will instead rely on the PerlIO encoding
30           layer.
31
32       2.  If the "encoding" or "utf8" options are set, use the output
33           encoding specified by those options.
34
35       3.  If the input encoding of the POD source file was explicitly
36           specified (using "=encoding") or automatically detected by
37           Pod::Simple, use that as the output encoding as well.
38
39       4.  Otherwise, if running on a non-EBCDIC system, use UTF-8 as the
40           output encoding.  Since this is a superset of ASCII, this will
41           result in ASCII output unless the POD input contains non-ASCII
42           characters without declaring or autodetecting an encoding (usually
43           via E<> escapes).
44
45       5.  Otherwise, for EBCDIC systems, output without doing any encoding
46           and hope this works.
47
48       One caveat: Pod::Text has to commit to an output encoding the first
49       time it outputs a non-ASCII character, and then has to stick with it
50       for consistency.  However, "=encoding" commands don't have to be at the
51       beginning of a POD document.  If someone uses a non-ASCII character
52       early in a document with an escape, such as E<0xEF>, and then puts
53       "=encoding iso-8859-1" later, ideally Pod::Text would follow rule 3 and
54       output the entire document as ISO 8859-1.  Instead, it will commit to
55       UTF-8 following rule 4 as soon as it sees that escape, and then stick
56       with that encoding for the rest of the document.
57
58       Unfortunately, there's no universally good choice for an output
59       encoding.  Each choice will be incorrect in some circumstances.  This
60       approach was chosen primarily for backwards compatibility.  Callers
61       should consider forcing the output encoding via "encoding" if they have
62       any knowledge about what encoding the user may expect.
63
64       In particular, consider importing the Encode::Locale module, if
65       available, and setting "encoding" to "locale" to use an output encoding
66       appropriate to the user's locale.  But be aware that if the user is not
67       using locales or is using a locale of "C", Encode::Locale will set the
68       output encoding to US-ASCII.  This will cause all non-ASCII characters
69       will be replaced with "?"  and produce a flurry of warnings about
70       unsupported characters, which may or may not be what you want.
71

CLASS METHODS

73       new(ARGS)
74           Create a new Pod::Text object.  ARGS should be a list of key/value
75           pairs, where the keys are chosen from the following.  Each option
76           is annotated with the version of Pod::Text in which that option was
77           added with its current meaning.
78
79           alt [2.00] If set to a true value, selects an alternate output
80               format that, among other things, uses a different heading style
81               and marks "=item" entries with a colon in the left margin.
82               Defaults to false.
83
84           code
85               [2.13] If set to a true value, the non-POD parts of the input
86               file will be included in the output.  Useful for viewing code
87               documented with POD blocks with the POD rendered and the code
88               left intact.
89
90           encoding
91               [5.00] Specifies the encoding of the output.  The value must be
92               an encoding recognized by the Encode module (see
93               Encode::Supported).  If the output contains characters that
94               cannot be represented in this encoding, that is an error that
95               will be reported as configured by the "errors" option.  If
96               error handling is other than "die", the unrepresentable
97               character will be replaced with the Encode substitution
98               character (normally "?").
99
100               If the output file handle has a PerlIO encoding layer set, this
101               parameter will be ignored and no encoding will be done by
102               Pod::Man.  It will instead rely on the encoding layer to make
103               whatever output encoding transformations are desired.
104
105               WARNING: The input encoding of the POD source is independent
106               from the output encoding, and setting this option does not
107               affect the interpretation of the POD input.  Unless your POD
108               source is US-ASCII, its encoding should be declared with the
109               "=encoding" command in the source, as near to the top of the
110               file as possible.  If this is not done, Pod::Simple will will
111               attempt to guess the encoding and may be successful if it's
112               Latin-1 or UTF-8, but it will produce warnings.  See perlpod(1)
113               for more information.
114
115           errors
116               [3.17] How to report errors.  "die" says to throw an exception
117               on any POD formatting error.  "stderr" says to report errors on
118               standard error, but not to throw an exception.  "pod" says to
119               include a POD ERRORS section in the resulting documentation
120               summarizing the errors.  "none" ignores POD errors entirely, as
121               much as possible.
122
123               The default is "pod".
124
125           guesswork
126               [5.01] By default, Pod::Text applies some default formatting
127               rules based on guesswork and regular expressions that are
128               intended to make writing Perl documentation easier and require
129               less explicit markup.  These rules may not always be
130               appropriate, particularly for documentation that isn't about
131               Perl.  This option allows turning all or some of it off.
132
133               The special value "all" enables all guesswork.  This is also
134               the default for backward compatibility reasons.  The special
135               value "none" disables all guesswork.  Otherwise, the value of
136               this option should be a comma-separated list of one or more of
137               the following keywords:
138
139               quoting
140                   If no guesswork is enabled, any text enclosed in C<> is
141                   surrounded by double quotes in nroff (terminal) output
142                   unless the contents are already quoted.  When this
143                   guesswork is enabled, quote marks will also be suppressed
144                   for Perl variables, function names, function calls,
145                   numbers, and hex constants.
146
147               Any unknown guesswork name is silently ignored (for potential
148               future compatibility), so be careful about spelling.
149
150           indent
151               [2.00] The number of spaces to indent regular text, and the
152               default indentation for "=over" blocks.  Defaults to 4.
153
154           loose
155               [2.00] If set to a true value, a blank line is printed after a
156               "=head1" heading.  If set to false (the default), no blank line
157               is printed after "=head1", although one is still printed after
158               "=head2".  This is the default because it's the expected
159               formatting for manual pages; if you're formatting arbitrary
160               text documents, setting this to true may result in more
161               pleasing output.
162
163           margin
164               [2.21] The width of the left margin in spaces.  Defaults to 0.
165               This is the margin for all text, including headings, not the
166               amount by which regular text is indented; for the latter, see
167               the indent option.  To set the right margin, see the width
168               option.
169
170           nourls
171               [3.17] Normally, L<> formatting codes with a URL but anchor
172               text are formatted to show both the anchor text and the URL.
173               In other words:
174
175                   L<foo|http://example.com/>
176
177               is formatted as:
178
179                   foo <http://example.com/>
180
181               This option, if set to a true value, suppresses the URL when
182               anchor text is given, so this example would be formatted as
183               just "foo".  This can produce less cluttered output in cases
184               where the URLs are not particularly important.
185
186           quotes
187               [4.00] Sets the quote marks used to surround C<> text.  If the
188               value is a single character, it is used as both the left and
189               right quote.  Otherwise, it is split in half, and the first
190               half of the string is used as the left quote and the second is
191               used as the right quote.
192
193               This may also be set to the special value "none", in which case
194               no quote marks are added around C<> text.
195
196           sentence
197               [3.00] If set to a true value, Pod::Text will assume that each
198               sentence ends in two spaces, and will try to preserve that
199               spacing.  If set to false, all consecutive whitespace in non-
200               verbatim paragraphs is compressed into a single space.
201               Defaults to false.
202
203           stderr
204               [3.10] Send error messages about invalid POD to standard error
205               instead of appending a POD ERRORS section to the generated
206               output.  This is equivalent to setting "errors" to "stderr" if
207               "errors" is not already set.  It is supported for backward
208               compatibility.
209
210           utf8
211               [3.12] If this option is set to a true value, the output
212               encoding is set to UTF-8.  This is equivalent to setting
213               "encoding" to "UTF-8" if "encoding" is not already set.  It is
214               supported for backward compatibility.
215
216           width
217               [2.00] The column at which to wrap text on the right-hand side.
218               Defaults to 76.
219

INSTANCE METHODS

221       As a derived class from Pod::Simple, Pod::Text supports the same
222       methods and interfaces.  See Pod::Simple for all the details.  This
223       section summarizes the most-frequently-used methods and the ones added
224       by Pod::Text.
225
226       output_fh(FH)
227           Direct the output from parse_file(), parse_lines(), or
228           parse_string_document() to the file handle FH instead of "STDOUT".
229
230       output_string(REF)
231           Direct the output from parse_file(), parse_lines(), or
232           parse_string_document() to the scalar variable pointed to by REF,
233           rather than "STDOUT".  For example:
234
235               my $man = Pod::Man->new();
236               my $output;
237               $man->output_string(\$output);
238               $man->parse_file('/some/input/file');
239
240           Be aware that the output in that variable will already be encoded
241           (see "Encoding").
242
243       parse_file(PATH)
244           Read the POD source from PATH and format it.  By default, the
245           output is sent to "STDOUT", but this can be changed with the
246           output_fh() or output_string() methods.
247
248       parse_from_file(INPUT, OUTPUT)
249       parse_from_filehandle(FH, OUTPUT)
250           Read the POD source from INPUT, format it, and output the results
251           to OUTPUT.
252
253           parse_from_filehandle() is provided for backward compatibility with
254           older versions of Pod::Man.  parse_from_file() should be used
255           instead.
256
257       parse_lines(LINES[, ...[, undef]])
258           Parse the provided lines as POD source, writing the output to
259           either "STDOUT" or the file handle set with the output_fh() or
260           output_string() methods.  This method can be called repeatedly to
261           provide more input lines.  An explicit "undef" should be passed to
262           indicate the end of input.
263
264           This method expects raw bytes, not decoded characters.
265
266       parse_string_document(INPUT)
267           Parse the provided scalar variable as POD source, writing the
268           output to either "STDOUT" or the file handle set with the
269           output_fh() or output_string() methods.
270
271           This method expects raw bytes, not decoded characters.
272

FUNCTIONS

274       Pod::Text exports one function for backward compatibility with older
275       versions.  This function is deprecated; instead, use the object-
276       oriented interface described above.
277
278       pod2text([[-a,] [-NNN,]] INPUT[, OUTPUT])
279           Convert the POD source from INPUT to text and write it to OUTPUT.
280           If OUTPUT is not given, defaults to "STDOUT".  INPUT can be any
281           expression supported as the second argument to two-argument open().
282
283           If "-a" is given as an initial argument, pass the "alt" option to
284           the Pod::Text constructor.  This enables alternative formatting.
285
286           If "-NNN" is given as an initial argument, pass the "width" option
287           to the Pod::Text constructor with the number "NNN" as its argument.
288           This sets the wrap line width to NNN.
289

DIAGNOSTICS

291       Bizarre space in item
292       Item called without tag
293           (W) Something has gone wrong in internal "=item" processing.  These
294           messages indicate a bug in Pod::Text; you should never see them.
295
296       Can't open %s for reading: %s
297           (F) Pod::Text was invoked via the compatibility mode pod2text()
298           interface and the input file it was given could not be opened.
299
300       Invalid errors setting "%s"
301           (F) The "errors" parameter to the constructor was set to an unknown
302           value.
303
304       Invalid quote specification "%s"
305           (F) The quote specification given (the "quotes" option to the
306           constructor) was invalid.  A quote specification must be either one
307           character long or an even number (greater than one) characters
308           long.
309
310       POD document had syntax errors
311           (F) The POD document being formatted had syntax errors and the
312           "errors" option was set to "die".
313

COMPATIBILITY

315       Pod::Text 2.03 (based on Pod::Parser) was the first version of this
316       module included with Perl, in Perl 5.6.0.  Earlier versions of Perl had
317       a different Pod::Text module, with a different API.
318
319       The current API based on Pod::Simple was added in Pod::Text 3.00.
320       Pod::Text 3.01 was included in Perl 5.9.3, the first version of Perl to
321       incorporate those changes.  This is the first version that correctly
322       supports all modern POD syntax.  The parse_from_filehandle() method was
323       re-added for backward compatibility in Pod::Text 3.07, included in Perl
324       5.9.4.
325
326       Pod::Text 3.12, included in Perl 5.10.1, first implemented the current
327       practice of attempting to match the default output encoding with the
328       input encoding of the POD source, unless overridden by the "utf8"
329       option or (added later) the "encoding" option.
330
331       Support for anchor text in L<> links of type URL was added in Pod::Text
332       3.14, included in Perl 5.11.5.
333
334       parse_lines(), parse_string_document(), and parse_file() set a default
335       output file handle of "STDOUT" if one was not already set as of
336       Pod::Text 3.18, included in Perl 5.19.5.
337
338       Pod::Text 4.00, included in Perl 5.23.7, aligned the module version and
339       the version of the podlators distribution.  All modules included in
340       podlators, and the podlators distribution itself, share the same
341       version number from this point forward.
342
343       Pod::Text 4.09, included in Perl 5.25.7, fixed a serious bug on EBCDIC
344       systems, present in all versions back to 3.00, that would cause opening
345       brackets to disappear.
346
347       Pod::Text 5.00 now defaults, on non-EBCDIC systems, to UTF-8 encoding
348       if it sees a non-ASCII character in the input and the input encoding is
349       not specified.  It also commits to an encoding with the first non-ASCII
350       character and does not change the output encoding if the input encoding
351       changes.  The Encode module is now used for all output encoding rather
352       than PerlIO layers, which fixes earlier problems with output to
353       scalars.
354

AUTHOR

356       Russ Allbery <rra@cpan.org>, based very heavily on the original
357       Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion
358       to Pod::Parser by Brad Appleton <bradapp@enteract.com>.  Sean Burke's
359       initial conversion of Pod::Man to use Pod::Simple provided much-needed
360       guidance on how to use Pod::Simple.
361

COPYRIGHT AND LICENSE

363       Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022
364       Russ Allbery <rra@cpan.org>
365
366       This program is free software; you may redistribute it and/or modify it
367       under the same terms as Perl itself.
368