Debian Codegraph @

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