Debian Codegraph @

upstream/debian-unstable/man3/Pod::Simple.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::Simple 3perl"
58 .TH Pod::Simple 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::Simple \- framework for parsing Pod
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& TODO
69 .Ve
70 .SH DESCRIPTION
71 .IX Header "DESCRIPTION"
72 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
73 documentation") markup language that is typically used for writing
74 documentation for Perl and for Perl modules. The Pod format is explained
75 in perlpod; the most common formatter is called \f(CW\*(C`perldoc\*(C'\fR.
76 .PP
77 Be sure to read "ENCODING" if your Pod contains non-ASCII characters.
78 .PP
79 Pod formatters can use Pod::Simple to parse Pod documents and render them into
80 plain text, HTML, or any number of other formats. Typically, such formatters
81 will be subclasses of Pod::Simple, and so they will inherit its methods, like
82 \&\f(CW\*(C`parse_file\*(C'\fR. But note that Pod::Simple doesn't understand and
83 properly parse Perl itself, so if you have a file which contains a Perl
84 program that has a multi-line quoted string which has lines that look
85 like pod, Pod::Simple will treat them as pod. This can be avoided if
86 the file makes these into indented here documents instead.
87 .PP
88 If you're reading this document just because you have a Pod-processing
89 subclass that you want to use, this document (plus the documentation for the
90 subclass) is probably all you need to read.
91 .PP
92 If you're reading this document because you want to write a formatter
93 subclass, continue reading it and then read Pod::Simple::Subclassing, and
94 then possibly even read perlpodspec (some of which is for parser-writers,
95 but much of which is notes to formatter-writers).
96 .SH "MAIN METHODS"
97 .IX Header "MAIN METHODS"
98 .ie n .IP """$parser = \fISomeClass\fR\->new();""" 4
99 .el .IP "\f(CW$parser = \fR\f(CISomeClass\fR\f(CW\->new();\fR" 4
100 .IX Item "$parser = SomeClass->new();"
101 This returns a new parser object, where \fR\f(CI\*(C`SomeClass\*(C'\fR\fI\fR is a subclass
102 of Pod::Simple.
103 .ie n .IP """$parser\->output_fh( *OUT );""" 4
104 .el .IP "\f(CW$parser\->output_fh( *OUT );\fR" 4
105 .IX Item "$parser->output_fh( *OUT );"
106 This sets the filehandle that \f(CW$parser\fR's output will be written to.
107 You can pass \f(CW*STDOUT\fR or \f(CW*STDERR\fR, otherwise you should probably do
108 something like this:
109 .Sp
110 .Vb 3
111 \& my $outfile = "output.txt";
112 \& open TXTOUT, ">$outfile" or die "Can\*(Aqt write to $outfile: $!";
113 \& $parser\->output_fh(*TXTOUT);
114 .Ve
115 .Sp
116 \&...before you call one of the \f(CW\*(C`$parser\->parse_\fR\f(CIwhatever\fR\f(CW\*(C'\fR methods.
117 .ie n .IP """$parser\->output_string( \e$somestring );""" 4
118 .el .IP "\f(CW$parser\->output_string( \e$somestring );\fR" 4
119 .IX Item "$parser->output_string( $somestring );"
120 This sets the string that \f(CW$parser\fR's output will be sent to,
121 instead of any filehandle.
122 .ie n .IP """$parser\->parse_file( \fI$some_filename\fR );""" 4
123 .el .IP "\f(CW$parser\->parse_file( \fR\f(CI$some_filename\fR\f(CW );\fR" 4
124 .IX Item "$parser->parse_file( $some_filename );"
125 .PD 0
126 .ie n .IP """$parser\->parse_file( *INPUT_FH );""" 4
127 .el .IP "\f(CW$parser\->parse_file( *INPUT_FH );\fR" 4
128 .IX Item "$parser->parse_file( *INPUT_FH );"
129 .PD
130 This reads the Pod content of the file (or filehandle) that you specify,
131 and processes it with that \f(CW$parser\fR object, according to however
132 \&\f(CW$parser\fR's class works, and according to whatever parser options you
133 have set up for this \f(CW$parser\fR object.
134 .ie n .IP """$parser\->parse_string_document( \fI$all_content\fR );""" 4
135 .el .IP "\f(CW$parser\->parse_string_document( \fR\f(CI$all_content\fR\f(CW );\fR" 4
136 .IX Item "$parser->parse_string_document( $all_content );"
137 This works just like \f(CW\*(C`parse_file\*(C'\fR except that it reads the Pod
138 content not from a file, but from a string that you have already
139 in memory.
140 .ie n .IP """$parser\->parse_lines( \fI...@lines...\fR, undef );""" 4
141 .el .IP "\f(CW$parser\->parse_lines( \fR\f(CI...@lines...\fR\f(CW, undef );\fR" 4
142 .IX Item "$parser->parse_lines( ...@lines..., undef );"
143 This processes the lines in \f(CW@lines\fR (where each list item must be a
144 defined value, and must contain exactly one line of content \-\- so no
145 items like \f(CW"foo\enbar"\fR are allowed). The final \f(CW\*(C`undef\*(C'\fR is used to
146 indicate the end of document being parsed.
147 .Sp
148 The other \f(CW\*(C`parser_\fR\f(CIwhatever\fR\f(CW\*(C'\fR methods are meant to be called only once
149 per \f(CW$parser\fR object; but \f(CW\*(C`parse_lines\*(C'\fR can be called as many times per
150 \&\f(CW$parser\fR object as you want, as long as the last call (and only
151 the last call) ends with an \f(CW\*(C`undef\*(C'\fR value.
152 .ie n .IP """$parser\->content_seen""" 4
153 .el .IP \f(CW$parser\->content_seen\fR 4
154 .IX Item "$parser->content_seen"
155 This returns true only if there has been any real content seen for this
156 document. Returns false in cases where the document contains content,
157 but does not make use of any Pod markup.
158 .ie n .IP """\fISomeClass\fR\->filter( \fI$filename\fR );""" 4
159 .el .IP "\f(CW\fR\f(CISomeClass\fR\f(CW\->filter( \fR\f(CI$filename\fR\f(CW );\fR" 4
160 .IX Item "SomeClass->filter( $filename );"
161 .PD 0
162 .ie n .IP """\fISomeClass\fR\->filter( \fI*INPUT_FH\fR );""" 4
163 .el .IP "\f(CW\fR\f(CISomeClass\fR\f(CW\->filter( \fR\f(CI*INPUT_FH\fR\f(CW );\fR" 4
164 .IX Item "SomeClass->filter( *INPUT_FH );"
165 .ie n .IP """\fISomeClass\fR\->filter( \fI\e$document_content\fR );""" 4
166 .el .IP "\f(CW\fR\f(CISomeClass\fR\f(CW\->filter( \fR\f(CI\e$document_content\fR\f(CW );\fR" 4
167 .IX Item "SomeClass->filter( $document_content );"
168 .PD
169 This is a shortcut method for creating a new parser object, setting the
170 output handle to STDOUT, and then processing the specified file (or
171 filehandle, or in-memory document). This is handy for one-liners like
172 this:
173 .Sp
174 .Vb 1
175 \& perl \-MPod::Simple::Text \-e "Pod::Simple::Text\->filter(\*(Aqthingy.pod\*(Aq)"
176 .Ve
177 .SH "SECONDARY METHODS"
178 .IX Header "SECONDARY METHODS"
179 Some of these methods might be of interest to general users, as
180 well as of interest to formatter-writers.
181 .PP
182 Note that the general pattern here is that the accessor-methods
183 read the attribute's value with \f(CW\*(C`$value = $parser\->\fR\f(CIattribute\fR\f(CW\*(C'\fR
184 and set the attribute's value with
185 \&\f(CW\*(C`$parser\->\fR\f(CIattribute\fR\f(CW(\fR\f(CInewvalue\fR\f(CW)\*(C'\fR. For each accessor, I typically
186 only mention one syntax or another, based on which I think you are actually
187 most likely to use.
188 .ie n .IP """$parser\->parse_characters( \fISOMEVALUE\fR )""" 4
189 .el .IP "\f(CW$parser\->parse_characters( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
190 .IX Item "$parser->parse_characters( SOMEVALUE )"
191 The Pod parser normally expects to read octets and to convert those octets
192 to characters based on the \f(CW\*(C`=encoding\*(C'\fR declaration in the Pod source. Set
193 this option to a true value to indicate that the Pod source is already a Perl
194 character stream. This tells the parser to ignore any \f(CW\*(C`=encoding\*(C'\fR command
195 and to skip all the code paths involving decoding octets.
196 .ie n .IP """$parser\->no_whining( \fISOMEVALUE\fR )""" 4
197 .el .IP "\f(CW$parser\->no_whining( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
198 .IX Item "$parser->no_whining( SOMEVALUE )"
199 If you set this attribute to a true value, you will suppress the
200 parser's complaints about irregularities in the Pod coding. By default,
201 this attribute's value is false, meaning that irregularities will
202 be reported.
203 .Sp
204 Note that turning this attribute to true won't suppress one or two kinds
205 of complaints about rarely occurring unrecoverable errors.
206 .ie n .IP """$parser\->no_errata_section( \fISOMEVALUE\fR )""" 4
207 .el .IP "\f(CW$parser\->no_errata_section( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
208 .IX Item "$parser->no_errata_section( SOMEVALUE )"
209 If you set this attribute to a true value, you will stop the parser from
210 generating a "POD ERRORS" section at the end of the document. By
211 default, this attribute's value is false, meaning that an errata section
212 will be generated, as necessary.
213 .ie n .IP """$parser\->complain_stderr( \fISOMEVALUE\fR )""" 4
214 .el .IP "\f(CW$parser\->complain_stderr( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
215 .IX Item "$parser->complain_stderr( SOMEVALUE )"
216 If you set this attribute to a true value, it will send reports of
217 parsing errors to STDERR. By default, this attribute's value is false,
218 meaning that no output is sent to STDERR.
219 .Sp
220 Setting \f(CW\*(C`complain_stderr\*(C'\fR also sets \f(CW\*(C`no_errata_section\*(C'\fR.
221 .ie n .IP """$parser\->source_filename""" 4
222 .el .IP \f(CW$parser\->source_filename\fR 4
223 .IX Item "$parser->source_filename"
224 This returns the filename that this parser object was set to read from.
225 .ie n .IP """$parser\->doc_has_started""" 4
226 .el .IP \f(CW$parser\->doc_has_started\fR 4
227 .IX Item "$parser->doc_has_started"
228 This returns true if \f(CW$parser\fR has read from a source, and has seen
229 Pod content in it.
230 .ie n .IP """$parser\->source_dead""" 4
231 .el .IP \f(CW$parser\->source_dead\fR 4
232 .IX Item "$parser->source_dead"
233 This returns true if \f(CW$parser\fR has read from a source, and come to the
234 end of that source.
235 .ie n .IP """$parser\->strip_verbatim_indent( \fISOMEVALUE\fR )""" 4
236 .el .IP "\f(CW$parser\->strip_verbatim_indent( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
237 .IX Item "$parser->strip_verbatim_indent( SOMEVALUE )"
238 The perlpod spec for a Verbatim paragraph is "It should be reproduced
239 exactly...", which means that the whitespace you've used to indent your
240 verbatim blocks will be preserved in the output. This can be annoying for
241 outputs such as HTML, where that whitespace will remain in front of every
242 line. It's an unfortunate case where syntax is turned into semantics.
243 .Sp
244 If the POD you're parsing adheres to a consistent indentation policy, you can
245 have such indentation stripped from the beginning of every line of your
246 verbatim blocks. This method tells Pod::Simple what to strip. For two-space
247 indents, you'd use:
248 .Sp
249 .Vb 1
250 \& $parser\->strip_verbatim_indent(\*(Aq \*(Aq);
251 .Ve
252 .Sp
253 For tab indents, you'd use a tab character:
254 .Sp
255 .Vb 1
256 \& $parser\->strip_verbatim_indent("\et");
257 .Ve
258 .Sp
259 If the POD is inconsistent about the indentation of verbatim blocks, but you
260 have figured out a heuristic to determine how much a particular verbatim block
261 is indented, you can pass a code reference instead. The code reference will be
262 executed with one argument, an array reference of all the lines in the
263 verbatim block, and should return the value to be stripped from each line. For
264 example, if you decide that you're fine to use the first line of the verbatim
265 block to set the standard for indentation of the rest of the block, you can
266 look at the first line and return the appropriate value, like so:
267 .Sp
268 .Vb 5
269 \& $new\->strip_verbatim_indent(sub {
270 \& my $lines = shift;
271 \& (my $indent = $lines\->[0]) =~ s/\eS.*//;
272 \& return $indent;
273 \& });
274 .Ve
275 .Sp
276 If you'd rather treat each line individually, you can do that, too, by just
277 transforming them in-place in the code reference and returning \f(CW\*(C`undef\*(C'\fR. Say
278 that you don't want \fIany\fR lines indented. You can do something like this:
279 .Sp
280 .Vb 5
281 \& $new\->strip_verbatim_indent(sub {
282 \& my $lines = shift;
283 \& sub { s/^\es+// for @{ $lines },
284 \& return undef;
285 \& });
286 .Ve
287 .ie n .IP """$parser\->expand_verbatim_tabs( \fIn\fR )""" 4
288 .el .IP "\f(CW$parser\->expand_verbatim_tabs( \fR\f(CIn\fR\f(CW )\fR" 4
289 .IX Item "$parser->expand_verbatim_tabs( n )"
290 Default: 8
291 .Sp
292 If after any stripping of indentation in verbatim blocks, there remain
293 tabs, this method call indicates what to do with them. \f(CW0\fR
294 means leave them as tabs, any other number indicates that each tab is to
295 be translated so as to have tab stops every \f(CW\*(C`n\*(C'\fR columns.
296 .Sp
297 This is independent of other methods (except that it operates after any
298 verbatim input stripping is done).
299 .Sp
300 Like the other methods, the input parameter is not checked for validity.
301 \&\f(CW\*(C`undef\*(C'\fR or containing non-digits has the same effect as 8.
302 .SH "TERTIARY METHODS"
303 .IX Header "TERTIARY METHODS"
304 .ie n .IP """$parser\->abandon_output_fh()""" 4
305 .el .IP \f(CW$parser\->abandon_output_fh()\fR 4
306 .IX Xref "abandon_output_fh"
307 .IX Item "$parser->abandon_output_fh()"
308 Cancel output to the file handle. Any POD read by the \f(CW$parser\fR is not
309 effected.
310 .ie n .IP """$parser\->abandon_output_string()""" 4
311 .el .IP \f(CW$parser\->abandon_output_string()\fR 4
312 .IX Xref "abandon_output_string"
313 .IX Item "$parser->abandon_output_string()"
314 Cancel output to the output string. Any POD read by the \f(CW$parser\fR is not
315 effected.
316 .ie n .IP """$parser\->accept_code( @codes )""" 4
317 .el .IP "\f(CW$parser\->accept_code( @codes )\fR" 4
318 .IX Xref "accept_code"
319 .IX Item "$parser->accept_code( @codes )"
320 Alias for accept_codes.
321 .ie n .IP """$parser\->accept_codes( @codes )""" 4
322 .el .IP "\f(CW$parser\->accept_codes( @codes )\fR" 4
323 .IX Xref "accept_codes"
324 .IX Item "$parser->accept_codes( @codes )"
325 Allows \f(CW$parser\fR to accept a list of "Formatting Codes" in perlpod. This can be
326 used to implement user-defined codes.
327 .ie n .IP """$parser\->accept_directive_as_data( @directives )""" 4
328 .el .IP "\f(CW$parser\->accept_directive_as_data( @directives )\fR" 4
329 .IX Xref "accept_directive_as_data"
330 .IX Item "$parser->accept_directive_as_data( @directives )"
331 Allows \f(CW$parser\fR to accept a list of directives for data paragraphs. A
332 directive is the label of a "Command Paragraph" in perlpod. A data paragraph is
333 one delimited by \f(CW\*(C`=begin/=for/=end\*(C'\fR directives. This can be used to
334 implement user-defined directives.
335 .ie n .IP """$parser\->accept_directive_as_processed( @directives )""" 4
336 .el .IP "\f(CW$parser\->accept_directive_as_processed( @directives )\fR" 4
337 .IX Xref "accept_directive_as_processed"
338 .IX Item "$parser->accept_directive_as_processed( @directives )"
339 Allows \f(CW$parser\fR to accept a list of directives for processed paragraphs. A
340 directive is the label of a "Command Paragraph" in perlpod. A processed
341 paragraph is also known as "Ordinary Paragraph" in perlpod. This can be used to
342 implement user-defined directives.
343 .ie n .IP """$parser\->accept_directive_as_verbatim( @directives )""" 4
344 .el .IP "\f(CW$parser\->accept_directive_as_verbatim( @directives )\fR" 4
345 .IX Xref "accept_directive_as_verbatim"
346 .IX Item "$parser->accept_directive_as_verbatim( @directives )"
347 Allows \f(CW$parser\fR to accept a list of directives for "Verbatim
348 Paragraph" in perlpod. A directive is the label of a "Command Paragraph" in perlpod. This
349 can be used to implement user-defined directives.
350 .ie n .IP """$parser\->accept_target( @targets )""" 4
351 .el .IP "\f(CW$parser\->accept_target( @targets )\fR" 4
352 .IX Xref "accept_target"
353 .IX Item "$parser->accept_target( @targets )"
354 Alias for accept_targets.
355 .ie n .IP """$parser\->accept_target_as_text( @targets )""" 4
356 .el .IP "\f(CW$parser\->accept_target_as_text( @targets )\fR" 4
357 .IX Xref "accept_target_as_text"
358 .IX Item "$parser->accept_target_as_text( @targets )"
359 Alias for accept_targets_as_text.
360 .ie n .IP """$parser\->accept_targets( @targets )""" 4
361 .el .IP "\f(CW$parser\->accept_targets( @targets )\fR" 4
362 .IX Xref "accept_targets"
363 .IX Item "$parser->accept_targets( @targets )"
364 Accepts targets for \f(CW\*(C`=begin/=for/=end\*(C'\fR sections of the POD.
365 .ie n .IP """$parser\->accept_targets_as_text( @targets )""" 4
366 .el .IP "\f(CW$parser\->accept_targets_as_text( @targets )\fR" 4
367 .IX Xref "accept_targets_as_text"
368 .IX Item "$parser->accept_targets_as_text( @targets )"
369 Accepts targets for \f(CW\*(C`=begin/=for/=end\*(C'\fR sections that should be parsed as
370 POD. For details, see "About Data Paragraphs" in perlpodspec.
371 .ie n .IP """$parser\->any_errata_seen()""" 4
372 .el .IP \f(CW$parser\->any_errata_seen()\fR 4
373 .IX Xref "any_errata_seen"
374 .IX Item "$parser->any_errata_seen()"
375 Used to check if any errata was seen.
376 .Sp
377 \&\fIExample:\fR
378 .Sp
379 .Vb 1
380 \& die "too many errors\en" if $parser\->any_errata_seen();
381 .Ve
382 .ie n .IP """$parser\->errata_seen()""" 4
383 .el .IP \f(CW$parser\->errata_seen()\fR 4
384 .IX Xref "errata_seen"
385 .IX Item "$parser->errata_seen()"
386 Returns a hash reference of all errata seen, both whines and screams. The hash reference's keys are the line number and the value is an array reference of the errors for that line.
387 .Sp
388 \&\fIExample:\fR
389 .Sp
390 .Vb 3
391 \& if ( $parser\->any_errata_seen() ) {
392 \& $logger\->log( $parser\->errata_seen() );
393 \& }
394 .Ve
395 .ie n .IP """$parser\->detected_encoding()""" 4
396 .el .IP \f(CW$parser\->detected_encoding()\fR 4
397 .IX Xref "detected_encoding"
398 .IX Item "$parser->detected_encoding()"
399 Return the encoding corresponding to \f(CW\*(C`=encoding\*(C'\fR, but only if the
400 encoding was recognized and handled.
401 .ie n .IP """$parser\->encoding()""" 4
402 .el .IP \f(CW$parser\->encoding()\fR 4
403 .IX Xref "encoding"
404 .IX Item "$parser->encoding()"
405 Return encoding of the document, even if the encoding is not correctly
406 handled.
407 .ie n .IP """$parser\->parse_from_file( $source, $to )""" 4
408 .el .IP "\f(CW$parser\->parse_from_file( $source, $to )\fR" 4
409 .IX Xref "parse_from_file"
410 .IX Item "$parser->parse_from_file( $source, $to )"
411 Parses from \f(CW$source\fR file to \f(CW$to\fR file. Similar to "parse_from_file" in Pod::Parser.
412 .ie n .IP """$parser\->scream( @error_messages )""" 4
413 .el .IP "\f(CW$parser\->scream( @error_messages )\fR" 4
414 .IX Xref "scream"
415 .IX Item "$parser->scream( @error_messages )"
416 Log an error that can't be ignored.
417 .ie n .IP """$parser\->unaccept_code( @codes )""" 4
418 .el .IP "\f(CW$parser\->unaccept_code( @codes )\fR" 4
419 .IX Xref "unaccept_code"
420 .IX Item "$parser->unaccept_code( @codes )"
421 Alias for unaccept_codes.
422 .ie n .IP """$parser\->unaccept_codes( @codes )""" 4
423 .el .IP "\f(CW$parser\->unaccept_codes( @codes )\fR" 4
424 .IX Xref "unaccept_codes"
425 .IX Item "$parser->unaccept_codes( @codes )"
426 Removes \f(CW@codes\fR as valid codes for the parse.
427 .ie n .IP """$parser\->unaccept_directive( @directives )""" 4
428 .el .IP "\f(CW$parser\->unaccept_directive( @directives )\fR" 4
429 .IX Xref "unaccept_directive"
430 .IX Item "$parser->unaccept_directive( @directives )"
431 Alias for unaccept_directives.
432 .ie n .IP """$parser\->unaccept_directives( @directives )""" 4
433 .el .IP "\f(CW$parser\->unaccept_directives( @directives )\fR" 4
434 .IX Xref "unaccept_directives"
435 .IX Item "$parser->unaccept_directives( @directives )"
436 Removes \f(CW@directives\fR as valid directives for the parse.
437 .ie n .IP """$parser\->unaccept_target( @targets )""" 4
438 .el .IP "\f(CW$parser\->unaccept_target( @targets )\fR" 4
439 .IX Xref "unaccept_target"
440 .IX Item "$parser->unaccept_target( @targets )"
441 Alias for unaccept_targets.
442 .ie n .IP """$parser\->unaccept_targets( @targets )""" 4
443 .el .IP "\f(CW$parser\->unaccept_targets( @targets )\fR" 4
444 .IX Xref "unaccept_targets"
445 .IX Item "$parser->unaccept_targets( @targets )"
446 Removes \f(CW@targets\fR as valid targets for the parse.
447 .ie n .IP """$parser\->version_report()""" 4
448 .el .IP \f(CW$parser\->version_report()\fR 4
449 .IX Xref "version_report"
450 .IX Item "$parser->version_report()"
451 Returns a string describing the version.
452 .ie n .IP """$parser\->whine( @error_messages )""" 4
453 .el .IP "\f(CW$parser\->whine( @error_messages )\fR" 4
454 .IX Xref "whine"
455 .IX Item "$parser->whine( @error_messages )"
456 Log an error unless \f(CW\*(C`$parser\->no_whining( TRUE );\*(C'\fR.
457 .SH ENCODING
458 .IX Header "ENCODING"
459 The Pod::Simple parser expects to read \fBoctets\fR. The parser will decode the
460 octets into Perl's internal character string representation using the value of
461 the \f(CW\*(C`=encoding\*(C'\fR declaration in the POD source.
462 .PP
463 If the POD source does not include an \f(CW\*(C`=encoding\*(C'\fR declaration, the parser will
464 attempt to guess the encoding (selecting one of UTF\-8 or CP 1252) by examining
465 the first non-ASCII bytes and applying the heuristic described in
466 perlpodspec. (If the POD source contains only ASCII bytes, the
467 encoding is assumed to be ASCII.)
468 .PP
469 If you set the \f(CW\*(C`parse_characters\*(C'\fR option to a true value the parser will
470 expect characters rather than octets; will ignore any \f(CW\*(C`=encoding\*(C'\fR; and will
471 make no attempt to decode the input.
472 .SH "SEE ALSO"
473 .IX Header "SEE ALSO"
474 Pod::Simple::Subclassing
475 .PP
476 perlpod
477 .PP
478 perlpodspec
479 .PP
480 Pod::Escapes
481 .PP
482 perldoc
483 .SH SUPPORT
484 .IX Header "SUPPORT"
485 Questions or discussion about POD and Pod::Simple should be sent to the
486 pod\[email protected] mail list. Send an empty email to
487 pod\-people\[email protected] to subscribe.
488 .PP
489 This module is managed in an open GitHub repository,
490 <https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or
491 to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches!
492 .PP
493 Please use <https://github.com/perl\-pod/pod\-simple/issues/new> to file a bug
494 report.
495 .SH "COPYRIGHT AND DISCLAIMERS"
496 .IX Header "COPYRIGHT AND DISCLAIMERS"
497 Copyright (c) 2002 Sean M. Burke.
498 .PP
499 This library is free software; you can redistribute it and/or modify it
500 under the same terms as Perl itself.
501 .PP
502 This program is distributed in the hope that it will be useful, but
503 without any warranty; without even the implied warranty of
504 merchantability or fitness for a particular purpose.
505 .SH AUTHOR
506 .IX Header "AUTHOR"
507 Pod::Simple was created by Sean M. Burke <[email protected]>.
508 But don't bother him, he's retired.
509 .PP
510 Pod::Simple is maintained by:
511 .IP \(bu 4
512 Allison Randal \f(CW\*(C`[email protected]\*(C'\fR
513 .IP \(bu 4
514 Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR
515 .IP \(bu 4
516 David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR
517 .IP \(bu 4
518 Karl Williamson \f(CW\*(C`[email protected]\*(C'\fR
519 .PP
520 Documentation has been contributed by:
521 .IP \(bu 4
522 Gabor Szabo \f(CW\*(C`[email protected]\*(C'\fR
523 .IP \(bu 4
524 Shawn H Corey \f(CW\*(C`SHCOREY at cpan.org\*(C'\fR