Debian Codegraph @

upstream/mageia-cauldron/man3pm/Pod::Simple::Subclassing.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::Subclassing 3pm"
61 .TH Pod::Simple::Subclassing 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::Subclassing \-\- write a formatter as a Pod::Simple subclass
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 5
71 \& package Pod::SomeFormatter;
72 \& use Pod::Simple;
73 \& @ISA = qw(Pod::Simple);
74 \& $VERSION = \*(Aq1.01\*(Aq;
75 \& use strict;
76 \&
77 \& sub _handle_element_start {
78 \& my($parser, $element_name, $attr_hash_r) = @_;
79 \& ...
80 \& }
81 \&
82 \& sub _handle_element_end {
83 \& my($parser, $element_name, $attr_hash_r) = @_;
84 \& # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
85 \& # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
86 \& # mostly useless. It is documented where "over\-*" and "begin" events are
87 \& # documented.
88 \& ...
89 \& }
90 \&
91 \& sub _handle_text {
92 \& my($parser, $text) = @_;
93 \& ...
94 \& }
95 \& 1;
96 .Ve
97 .SH DESCRIPTION
98 .IX Header "DESCRIPTION"
99 This document is about using Pod::Simple to write a Pod processor,
100 generally a Pod formatter. If you just want to know about using an
101 existing Pod formatter, instead see its documentation and see also the
102 docs in Pod::Simple.
103 .PP
104 \&\fBThe zeroeth step\fR in writing a Pod formatter is to make sure that there
105 isn\*(Aqt already a decent one in CPAN. See <http://search.cpan.org/>, and
106 run a search on the name of the format you want to render to. Also
107 consider joining the Pod People list
108 <http://lists.perl.org/showlist.cgi?name=pod\-people> and asking whether
109 anyone has a formatter for that format \-\- maybe someone cobbled one
110 together but just hasn\*(Aqt released it.
111 .PP
112 \&\fBThe first step\fR in writing a Pod processor is to read perlpodspec,
113 which contains information on writing a Pod parser (which has been
114 largely taken care of by Pod::Simple), but also a lot of requirements
115 and recommendations for writing a formatter.
116 .PP
117 \&\fBThe second step\fR is to actually learn the format you\*(Aqre planning to
118 format to \-\- or at least as much as you need to know to represent Pod,
119 which probably isn\*(Aqt much.
120 .PP
121 \&\fBThe third step\fR is to pick which of Pod::Simple\*(Aqs interfaces you want to
122 use:
123 .IP Pod::Simple 4
124 .IX Item "Pod::Simple"
125 The basic Pod::Simple interface that uses \f(CW_handle_element_start()\fR,
126 \&\f(CW_handle_element_end()\fR and \f(CW_handle_text()\fR.
127 .IP Pod::Simple::Methody 4
128 .IX Item "Pod::Simple::Methody"
129 The Pod::Simple::Methody interface is event\-based, similar to that of
130 HTML::Parser or XML::Parser\*(Aqs "Handlers".
131 .IP Pod::Simple::PullParser 4
132 .IX Item "Pod::Simple::PullParser"
133 Pod::Simple::PullParser provides a token\-stream interface, sort of
134 like HTML::TokeParser\*(Aqs interface.
135 .IP Pod::Simple::SimpleTree 4
136 .IX Item "Pod::Simple::SimpleTree"
137 Pod::Simple::SimpleTree provides a simple tree interface, rather like
138 XML::Parser\*(Aqs "Tree" interface. Users familiar with XML handling will
139 be comfortable with this interface. Users interested in outputting XML,
140 should look into the modules that produce an XML representation of the
141 Pod stream, notably Pod::Simple::XMLOutStream; you can feed the output
142 of such a class to whatever XML parsing system you are most at home with.
143 .PP
144 \&\fBThe last step\fR is to write your code based on how the events (or tokens,
145 or tree\-nodes, or the XML, or however you\*(Aqre parsing) will map to
146 constructs in the output format. Also be sure to consider how to escape
147 text nodes containing arbitrary text, and what to do with text
148 nodes that represent preformatted text (from verbatim sections).
149 .SH Events
150 .IX Header "Events"
151 TODO intro... mention that events are supplied for implicits, like for
152 missing >\*(Aqs
153 .PP
154 In the following section, we use XML to represent the event structure
155 associated with a particular construct. That is, an opening tag
156 represents the element start, the attributes of that opening tag are
157 the attributes given to the callback, and the closing tag represents
158 the end element.
159 .PP
160 Three callback methods must be supplied by a class extending
161 Pod::Simple to receive the corresponding event:
162 .ie n .IP """$parser\->_handle_element_start( \fIelement_name\fR, \fIattr_hashref\fR )""" 4
163 .el .IP "\f(CW$parser\->_handle_element_start( \fR\f(CIelement_name\fR\f(CW, \fR\f(CIattr_hashref\fR\f(CW )\fR" 4
164 .IX Item "$parser->_handle_element_start( element_name, attr_hashref )"
165 .PD 0
166 .ie n .IP """$parser\->_handle_element_end( \fIelement_name\fR )""" 4
167 .el .IP "\f(CW$parser\->_handle_element_end( \fR\f(CIelement_name\fR\f(CW )\fR" 4
168 .IX Item "$parser->_handle_element_end( element_name )"
169 .ie n .IP """$parser\->_handle_text( \fItext_string\fR )""" 4
170 .el .IP "\f(CW$parser\->_handle_text( \fR\f(CItext_string\fR\f(CW )\fR" 4
171 .IX Item "$parser->_handle_text( text_string )"
172 .PD
173 .PP
174 Here\*(Aqs the comprehensive list of values you can expect as
175 \&\fIelement_name\fR in your implementation of \f(CW\*(C`_handle_element_start\*(C'\fR
176 and \f(CW\*(C`_handle_element_end\*(C'\fR::
177 .IP "events with an element_name of Document" 4
178 .IX Item "events with an element_name of Document"
179 Parsing a document produces this event structure:
180 .Sp
181 .Vb 3
182 \& <Document start_line="543">
183 \& ...all events...
184 \& </Document>
185 .Ve
186 .Sp
187 The value of the \fIstart_line\fR attribute will be the line number of the first
188 Pod directive in the document.
189 .Sp
190 If there is no Pod in the given document, then the
191 event structure will be this:
192 .Sp
193 .Vb 2
194 \& <Document contentless="1" start_line="543">
195 \& </Document>
196 .Ve
197 .Sp
198 In that case, the value of the \fIstart_line\fR attribute will not be meaningful;
199 under current implementations, it will probably be the line number of the
200 last line in the file.
201 .IP "events with an element_name of Para" 4
202 .IX Item "events with an element_name of Para"
203 Parsing a plain (non\-verbatim, non\-directive, non\-data) paragraph in
204 a Pod document produces this event structure:
205 .Sp
206 .Vb 3
207 \& <Para start_line="543">
208 \& ...all events in this paragraph...
209 \& </Para>
210 .Ve
211 .Sp
212 The value of the \fIstart_line\fR attribute will be the line number of the start
213 of the paragraph.
214 .Sp
215 For example, parsing this paragraph of Pod:
216 .Sp
217 .Vb 2
218 \& The value of the I<start_line> attribute will be the
219 \& line number of the start of the paragraph.
220 .Ve
221 .Sp
222 produces this event structure:
223 .Sp
224 .Vb 8
225 \& <Para start_line="129">
226 \& The value of the
227 \& <I>
228 \& start_line
229 \& </I>
230 \& attribute will be the line number of the first Pod directive
231 \& in the document.
232 \& </Para>
233 .Ve
234 .IP "events with an element_name of B, C, F, or I." 4
235 .IX Item "events with an element_name of B, C, F, or I."
236 Parsing a B<...> formatting code (or of course any of its
237 semantically identical syntactic variants
238 B<<\ ...\ >>,
239 or B<<<<\ ...\ >>>>, etc.)
240 produces this event structure:
241 .Sp
242 .Vb 3
243 \& <B>
244 \& ...stuff...
245 \& </B>
246 .Ve
247 .Sp
248 Currently, there are no attributes conveyed.
249 .Sp
250 Parsing C, F, or I codes produce the same structure, with only a
251 different element name.
252 .Sp
253 If your parser object has been set to accept other formatting codes,
254 then they will be presented like these B/C/F/I codes \-\- i.e., without
255 any attributes.
256 .IP "events with an element_name of S" 4
257 .IX Item "events with an element_name of S"
258 Normally, parsing an S<...> sequence produces this event
259 structure, just as if it were a B/C/F/I code:
260 .Sp
261 .Vb 3
262 \& <S>
263 \& ...stuff...
264 \& </S>
265 .Ve
266 .Sp
267 However, Pod::Simple (and presumably all derived parsers) offers the
268 \&\f(CW\*(C`nbsp_for_S\*(C'\fR option which, if enabled, will suppress all S events, and
269 instead change all spaces in the content to non\-breaking spaces. This is
270 intended for formatters that output to a format that has no code that
271 means the same as S<...>, but which has a code/character that
272 means non\-breaking space.
273 .IP "events with an element_name of X" 4
274 .IX Item "events with an element_name of X"
275 Normally, parsing an X<...> sequence produces this event
276 structure, just as if it were a B/C/F/I code:
277 .Sp
278 .Vb 3
279 \& <X>
280 \& ...stuff...
281 \& </X>
282 .Ve
283 .Sp
284 However, Pod::Simple (and presumably all derived parsers) offers the
285 \&\f(CW\*(C`nix_X_codes\*(C'\fR option which, if enabled, will suppress all X events
286 and ignore their content. For formatters/processors that don\*(Aqt use
287 X events, this is presumably quite useful.
288 .IP "events with an element_name of L" 4
289 .IX Item "events with an element_name of L"
290 Because the L<...> is the most complex construct in the
291 language, it should not surprise you that the events it generates are
292 the most complex in the language. Most of complexity is hidden away in
293 the attribute values, so for those of you writing a Pod formatter that
294 produces a non\-hypertextual format, you can just ignore the attributes
295 and treat an L event structure like a formatting element that
296 (presumably) doesn\*(Aqt actually produce a change in formatting. That is,
297 the content of the L event structure (as opposed to its
298 attributes) is always what text should be displayed.
299 .Sp
300 There are, at first glance, three kinds of L links: URL, man, and pod.
301 .Sp
302 When a L<\fIsome_url\fR> code is parsed, it produces this event
303 structure:
304 .Sp
305 .Vb 3
306 \& <L content\-implicit="yes" raw="that_url" to="that_url" type="url">
307 \& that_url
308 \& </L>
309 .Ve
310 .Sp
311 The \f(CW\*(C`type="url"\*(C'\fR attribute is always specified for this type of
312 L code.
313 .Sp
314 For example, this Pod source:
315 .Sp
316 .Vb 1
317 \& L<http://www.perl.com/CPAN/authors/>
318 .Ve
319 .Sp
320 produces this event structure:
321 .Sp
322 .Vb 3
323 \& <L content\-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
324 \& http://www.perl.com/CPAN/authors/
325 \& </L>
326 .Ve
327 .Sp
328 When a L<\fImanpage(section)\fR> code is parsed (and these are
329 fairly rare and not terribly useful), it produces this event structure:
330 .Sp
331 .Vb 3
332 \& <L content\-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
333 \& manpage(section)
334 \& </L>
335 .Ve
336 .Sp
337 The \f(CW\*(C`type="man"\*(C'\fR attribute is always specified for this type of
338 L code.
339 .Sp
340 For example, this Pod source:
341 .Sp
342 .Vb 1
343 \& L<crontab(5)>
344 .Ve
345 .Sp
346 produces this event structure:
347 .Sp
348 .Vb 3
349 \& <L content\-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
350 \& crontab(5)
351 \& </L>
352 .Ve
353 .Sp
354 In the rare cases where a man page link has a section specified, that text appears
355 in a \fIsection\fR attribute. For example, this Pod source:
356 .Sp
357 .Vb 1
358 \& L<crontab(5)/"ENVIRONMENT">
359 .Ve
360 .Sp
361 will produce this event structure:
362 .Sp
363 .Vb 3
364 \& <L content\-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
365 \& "ENVIRONMENT" in crontab(5)
366 \& </L>
367 .Ve
368 .Sp
369 In the rare case where the Pod document has code like
370 L<\fIsometext\fR|\fImanpage(section)\fR>, then the \fIsometext\fR will appear
371 as the content of the element, the \fImanpage(section)\fR text will appear
372 only as the value of the \fIto\fR attribute, and there will be no
373 \&\f(CW\*(C`content\-implicit="yes"\*(C'\fR attribute (whose presence means that the Pod parser
374 had to infer what text should appear as the link text \-\- as opposed to
375 cases where that attribute is absent, which means that the Pod parser did
376 \&\fInot\fR have to infer the link text, because that L code explicitly specified
377 some link text.)
378 .Sp
379 For example, this Pod source:
380 .Sp
381 .Vb 1
382 \& L<hell itself!|crontab(5)>
383 .Ve
384 .Sp
385 will produce this event structure:
386 .Sp
387 .Vb 3
388 \& <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
389 \& hell itself!
390 \& </L>
391 .Ve
392 .Sp
393 The last type of L structure is for links to/within Pod documents. It is
394 the most complex because it can have a \fIto\fR attribute, \fIor\fR a
395 \&\fIsection\fR attribute, or both. The \f(CW\*(C`type="pod"\*(C'\fR attribute is always
396 specified for this type of L code.
397 .Sp
398 In the most common case, the simple case of a L<podpage> code
399 produces this event structure:
400 .Sp
401 .Vb 3
402 \& <L content\-implicit="yes" raw="podpage" to="podpage" type="pod">
403 \& podpage
404 \& </L>
405 .Ve
406 .Sp
407 For example, this Pod source:
408 .Sp
409 .Vb 1
410 \& L<Net::Ping>
411 .Ve
412 .Sp
413 produces this event structure:
414 .Sp
415 .Vb 3
416 \& <L content\-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
417 \& Net::Ping
418 \& </L>
419 .Ve
420 .Sp
421 In cases where there is link\-text explicitly specified, it
422 is to be found in the content of the element (and not the
423 attributes), just as with the L<\fIsometext\fR|\fImanpage(section)\fR>
424 case discussed above. For example, this Pod source:
425 .Sp
426 .Vb 1
427 \& L<Perl Error Messages|perldiag>
428 .Ve
429 .Sp
430 produces this event structure:
431 .Sp
432 .Vb 3
433 \& <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
434 \& Perl Error Messages
435 \& </L>
436 .Ve
437 .Sp
438 In cases of links to a section in the current Pod document,
439 there is a \fIsection\fR attribute instead of a \fIto\fR attribute.
440 For example, this Pod source:
441 .Sp
442 .Vb 1
443 \& L</"Member Data">
444 .Ve
445 .Sp
446 produces this event structure:
447 .Sp
448 .Vb 3
449 \& <L content\-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
450 \& "Member Data"
451 \& </L>
452 .Ve
453 .Sp
454 As another example, this Pod source:
455 .Sp
456 .Vb 1
457 \& L<the various attributes|/"Member Data">
458 .Ve
459 .Sp
460 produces this event structure:
461 .Sp
462 .Vb 3
463 \& <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
464 \& the various attributes
465 \& </L>
466 .Ve
467 .Sp
468 In cases of links to a section in a different Pod document,
469 there are both a \fIsection\fR attribute and a to attribute.
470 For example, this Pod source:
471 .Sp
472 .Vb 1
473 \& L<perlsyn/"Basic BLOCKs and Switch Statements">
474 .Ve
475 .Sp
476 produces this event structure:
477 .Sp
478 .Vb 3
479 \& <L content\-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
480 \& "Basic BLOCKs and Switch Statements" in perlsyn
481 \& </L>
482 .Ve
483 .Sp
484 As another example, this Pod source:
485 .Sp
486 .Vb 1
487 \& L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
488 .Ve
489 .Sp
490 produces this event structure:
491 .Sp
492 .Vb 3
493 \& <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
494 \& SWITCH statements
495 \& </L>
496 .Ve
497 .Sp
498 Incidentally, note that we do not distinguish between these syntaxes:
499 .Sp
500 .Vb 4
501 \& L</"Member Data">
502 \& L<"Member Data">
503 \& L</Member Data>
504 \& L<Member Data> [deprecated syntax]
505 .Ve
506 .Sp
507 That is, they all produce the same event structure (for the most part), namely:
508 .Sp
509 .Vb 3
510 \& <L content\-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
511 \& &#34;Member Data&#34;
512 \& </L>
513 .Ve
514 .Sp
515 The \fIraw\fR attribute depends on what the raw content of the \f(CW\*(C`L<>\*(C'\fR is,
516 so that is why the event structure is the same "for the most part".
517 .Sp
518 If you have not guessed it yet, the \fIraw\fR attribute contains the raw,
519 original, unescaped content of the \f(CW\*(C`L<>\*(C'\fR formatting code. In addition
520 to the examples above, take notice of the following event structure produced
521 by the following \f(CW\*(C`L<>\*(C'\fR formatting code.
522 .Sp
523 .Vb 1
524 \& L<click B<here>|page/About the C<\-M> switch>
525 \&
526 \& <L raw="click B<here>|page/About the C<\-M> switch" section="About the \-M switch" to="page" type="pod">
527 \& click B<here>
528 \& </L>
529 .Ve
530 .Sp
531 Specifically, notice that the formatting codes are present and unescaped
532 in \fIraw\fR.
533 .Sp
534 There is a known bug in the \fIraw\fR attribute where any surrounding whitespace
535 is condensed into a single \*(Aq \*(Aq. For example, given L< link>, \fIraw\fR
536 will be " link".
537 .IP "events with an element_name of E or Z" 4
538 .IX Item "events with an element_name of E or Z"
539 While there are Pod codes E<...> and Z<>, these
540 \&\fIdo not\fR produce any E or Z events \-\- that is, there are no such
541 events as E or Z.
542 .IP "events with an element_name of Verbatim" 4
543 .IX Item "events with an element_name of Verbatim"
544 When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
545 produces this event structure:
546 .Sp
547 .Vb 3
548 \& <Verbatim start_line="543" xml:space="preserve">
549 \& ...text...
550 \& </Verbatim>
551 .Ve
552 .Sp
553 The value of the \fIstart_line\fR attribute will be the line number of the
554 first line of this verbatim block. The \fIxml:space\fR attribute is always
555 present, and always has the value "preserve".
556 .Sp
557 The text content will have tabs already expanded.
558 .IP "events with an element_name of head1 .. head4" 4
559 .IX Item "events with an element_name of head1 .. head4"
560 When a "=head1 ..." directive is parsed, it produces this event
561 structure:
562 .Sp
563 .Vb 3
564 \& <head1>
565 \& ...stuff...
566 \& </head1>
567 .Ve
568 .Sp
569 For example, a directive consisting of this:
570 .Sp
571 .Vb 1
572 \& =head1 Options to C<new> et al.
573 .Ve
574 .Sp
575 will produce this event structure:
576 .Sp
577 .Vb 7
578 \& <head1 start_line="543">
579 \& Options to
580 \& <C>
581 \& new
582 \& </C>
583 \& et al.
584 \& </head1>
585 .Ve
586 .Sp
587 "=head2" through "=head4" directives are the same, except for the element
588 names in the event structure.
589 .IP "events with an element_name of encoding" 4
590 .IX Item "events with an element_name of encoding"
591 In the default case, the events corresponding to \f(CW\*(C`=encoding\*(C'\fR directives
592 are not emitted. They are emitted if \f(CW\*(C`keep_encoding_directive\*(C'\fR is true.
593 In that case they produce event structures like
594 "events with an element_name of head1 .. head4" above.
595 .IP "events with an element_name of over\-bullet" 4
596 .IX Item "events with an element_name of over-bullet"
597 When an "=over ... =back" block is parsed where the items are
598 a bulleted list, it will produce this event structure:
599 .Sp
600 .Vb 6
601 \& <over\-bullet indent="4" start_line="543">
602 \& <item\-bullet start_line="545">
603 \& ...Stuff...
604 \& </item\-bullet>
605 \& ...more item\-bullets...
606 \& </over\-bullet fake\-closer="1">
607 .Ve
608 .Sp
609 The attribute \fIfake\-closer\fR is only present if it is a true value; it is not
610 present if it is a false value. It is shown in the above example to illustrate
611 where the attribute is (in the \fBclosing\fR tag). It signifies that the \f(CW\*(C`=over\*(C'\fR
612 did not have a matching \f(CW\*(C`=back\*(C'\fR, and thus Pod::Simple had to create a fake
613 closer.
614 .Sp
615 For example, this Pod source:
616 .Sp
617 .Vb 1
618 \& =over
619 \&
620 \& =item *
621 \&
622 \& Something
623 \&
624 \& =back
625 .Ve
626 .Sp
627 Would produce an event structure that does \fBnot\fR have the \fIfake\-closer\fR
628 attribute, whereas this Pod source:
629 .Sp
630 .Vb 1
631 \& =over
632 \&
633 \& =item *
634 \&
635 \& Gasp! An unclosed =over block!
636 .Ve
637 .Sp
638 would. The rest of the over\-* examples will not demonstrate this attribute,
639 but they all can have it. See Pod::Checker\*(Aqs source for an example of this
640 attribute being used.
641 .Sp
642 The value of the \fIindent\fR attribute is whatever value is after the
643 "=over" directive, as in "=over 8". If no such value is specified
644 in the directive, then the \fIindent\fR attribute has the value "4".
645 .Sp
646 For example, this Pod source:
647 .Sp
648 .Vb 1
649 \& =over
650 \&
651 \& =item *
652 \&
653 \& Stuff
654 \&
655 \& =item *
656 \&
657 \& Bar I<baz>!
658 \&
659 \& =back
660 .Ve
661 .Sp
662 produces this event structure:
663 .Sp
664 .Vb 8
665 \& <over\-bullet indent="4" start_line="10">
666 \& <item\-bullet start_line="12">
667 \& Stuff
668 \& </item\-bullet>
669 \& <item\-bullet start_line="14">
670 \& Bar <I>baz</I>!
671 \& </item\-bullet>
672 \& </over\-bullet>
673 .Ve
674 .IP "events with an element_name of over\-number" 4
675 .IX Item "events with an element_name of over-number"
676 When an "=over ... =back" block is parsed where the items are
677 a numbered list, it will produce this event structure:
678 .Sp
679 .Vb 6
680 \& <over\-number indent="4" start_line="543">
681 \& <item\-number number="1" start_line="545">
682 \& ...Stuff...
683 \& </item\-number>
684 \& ...more item\-number...
685 \& </over\-bullet>
686 .Ve
687 .Sp
688 This is like the "over\-bullet" event structure; but note that the contents
689 are "item\-number" instead of "item\-bullet", and note that they will have
690 a "number" attribute, which some formatters/processors may ignore
691 (since, for example, there\*(Aqs no need for it in HTML when producing
692 an "<UL><LI>...</LI>...</UL>" structure), but which any processor may use.
693 .Sp
694 Note that the values for the \fInumber\fR attributes of "item\-number"
695 elements in a given "over\-number" area \fIwill\fR start at 1 and go up by
696 one each time. If the Pod source doesn\*(Aqt follow that order (even though
697 it really should!), whatever numbers it has will be ignored (with
698 the correct values being put in the \fInumber\fR attributes), and an error
699 message might be issued to the user.
700 .IP "events with an element_name of over\-text" 4
701 .IX Item "events with an element_name of over-text"
702 These events are somewhat unlike the other over\-*
703 structures, as far as what their contents are. When
704 an "=over ... =back" block is parsed where the items are
705 a list of text "subheadings", it will produce this event structure:
706 .Sp
707 .Vb 8
708 \& <over\-text indent="4" start_line="543">
709 \& <item\-text>
710 \& ...stuff...
711 \& </item\-text>
712 \& ...stuff (generally Para or Verbatim elements)...
713 \& <item\-text>
714 \& ...more item\-text and/or stuff...
715 \& </over\-text>
716 .Ve
717 .Sp
718 The \fIindent\fR and \fIfake\-closer\fR attributes are as with the other over\-* events.
719 .Sp
720 For example, this Pod source:
721 .Sp
722 .Vb 1
723 \& =over
724 \&
725 \& =item Foo
726 \&
727 \& Stuff
728 \&
729 \& =item Bar I<baz>!
730 \&
731 \& Quux
732 \&
733 \& =back
734 .Ve
735 .Sp
736 produces this event structure:
737 .Sp
738 .Vb 10
739 \& <over\-text indent="4" start_line="20">
740 \& <item\-text start_line="22">
741 \& Foo
742 \& </item\-text>
743 \& <Para start_line="24">
744 \& Stuff
745 \& </Para>
746 \& <item\-text start_line="26">
747 \& Bar
748 \& <I>
749 \& baz
750 \& </I>
751 \& !
752 \& </item\-text>
753 \& <Para start_line="28">
754 \& Quux
755 \& </Para>
756 \& </over\-text>
757 .Ve
758 .IP "events with an element_name of over\-block" 4
759 .IX Item "events with an element_name of over-block"
760 These events are somewhat unlike the other over\-*
761 structures, as far as what their contents are. When
762 an "=over ... =back" block is parsed where there are no items,
763 it will produce this event structure:
764 .Sp
765 .Vb 3
766 \& <over\-block indent="4" start_line="543">
767 \& ...stuff (generally Para or Verbatim elements)...
768 \& </over\-block>
769 .Ve
770 .Sp
771 The \fIindent\fR and \fIfake\-closer\fR attributes are as with the other over\-* events.
772 .Sp
773 For example, this Pod source:
774 .Sp
775 .Vb 1
776 \& =over
777 \&
778 \& For cutting off our trade with all parts of the world
779 \&
780 \& For transporting us beyond seas to be tried for pretended offenses
781 \&
782 \& He is at this time transporting large armies of foreign mercenaries to
783 \& complete the works of death, desolation and tyranny, already begun with
784 \& circumstances of cruelty and perfidy scarcely paralleled in the most
785 \& barbarous ages, and totally unworthy the head of a civilized nation.
786 \&
787 \& =back
788 .Ve
789 .Sp
790 will produce this event structure:
791 .Sp
792 .Vb 11
793 \& <over\-block indent="4" start_line="2">
794 \& <Para start_line="4">
795 \& For cutting off our trade with all parts of the world
796 \& </Para>
797 \& <Para start_line="6">
798 \& For transporting us beyond seas to be tried for pretended offenses
799 \& </Para>
800 \& <Para start_line="8">
801 \& He is at this time transporting large armies of [...more text...]
802 \& </Para>
803 \& </over\-block>
804 .Ve
805 .IP "events with an element_name of over\-empty" 4
806 .IX Item "events with an element_name of over-empty"
807 \&\fBNote: These events are only triggered if \fR\f(CBparse_empty_lists()\fR\fB is set to a
808 true value.\fR
809 .Sp
810 These events are somewhat unlike the other over\-* structures, as far as what
811 their contents are. When an "=over ... =back" block is parsed where there
812 is no content, it will produce this event structure:
813 .Sp
814 .Vb 2
815 \& <over\-empty indent="4" start_line="543">
816 \& </over\-empty>
817 .Ve
818 .Sp
819 The \fIindent\fR and \fIfake\-closer\fR attributes are as with the other over\-* events.
820 .Sp
821 For example, this Pod source:
822 .Sp
823 .Vb 1
824 \& =over
825 \&
826 \& =over
827 \&
828 \& =back
829 \&
830 \& =back
831 .Ve
832 .Sp
833 will produce this event structure:
834 .Sp
835 .Vb 4
836 \& <over\-block indent="4" start_line="1">
837 \& <over\-empty indent="4" start_line="3">
838 \& </over\-empty>
839 \& </over\-block>
840 .Ve
841 .Sp
842 Note that the outer \f(CW\*(C`=over\*(C'\fR is a block because it has no \f(CW\*(C`=item\*(C'\fRs but still
843 has content: the inner \f(CW\*(C`=over\*(C'\fR. The inner \f(CW\*(C`=over\*(C'\fR, in turn, is completely
844 empty, and is treated as such.
845 .IP "events with an element_name of item\-bullet" 4
846 .IX Item "events with an element_name of item-bullet"
847 See "events with an element_name of over\-bullet", above.
848 .IP "events with an element_name of item\-number" 4
849 .IX Item "events with an element_name of item-number"
850 See "events with an element_name of over\-number", above.
851 .IP "events with an element_name of item\-text" 4
852 .IX Item "events with an element_name of item-text"
853 See "events with an element_name of over\-text", above.
854 .IP "events with an element_name of for" 4
855 .IX Item "events with an element_name of for"
856 TODO...
857 .IP "events with an element_name of Data" 4
858 .IX Item "events with an element_name of Data"
859 TODO...
860 .SH "More Pod::Simple Methods"
861 .IX Header "More Pod::Simple Methods"
862 Pod::Simple provides a lot of methods that aren\*(Aqt generally interesting
863 to the end user of an existing Pod formatter, but some of which you
864 might find useful in writing a Pod formatter. They are listed below. The
865 first several methods (the accept_* methods) are for declaring the
866 capabilities of your parser, notably what \f(CW\*(C`=for \fR\f(CItargetname\fR\f(CW\*(C'\fR sections
867 it\*(Aqs interested in, what extra N<...> codes it accepts beyond
868 the ones described in the \fIperlpod\fR.
869 .ie n .IP """$parser\->accept_targets( \fISOMEVALUE\fR )""" 4
870 .el .IP "\f(CW$parser\->accept_targets( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
871 .IX Item "$parser->accept_targets( SOMEVALUE )"
872 As the parser sees sections like:
873 .Sp
874 .Vb 1
875 \& =for html <img src="fig1.jpg">
876 .Ve
877 .Sp
878 or
879 .Sp
880 .Vb 1
881 \& =begin html
882 \&
883 \& <img src="fig1.jpg">
884 \&
885 \& =end html
886 .Ve
887 .Sp
888 \&...the parser will ignore these sections unless your subclass has
889 specified that it wants to see sections targeted to "html" (or whatever
890 the formatter name is).
891 .Sp
892 If you want to process all sections, even if they\*(Aqre not targeted for you,
893 call this before you start parsing:
894 .Sp
895 .Vb 1
896 \& $parser\->accept_targets(\*(Aq*\*(Aq);
897 .Ve
898 .ie n .IP """$parser\->accept_targets_as_text( \fISOMEVALUE\fR )""" 4
899 .el .IP "\f(CW$parser\->accept_targets_as_text( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
900 .IX Item "$parser->accept_targets_as_text( SOMEVALUE )"
901 This is like accept_targets, except that it specifies also that the
902 content of sections for this target should be treated as Pod text even
903 if the target name in "=for \fItargetname\fR" doesn\*(Aqt start with a ":".
904 .Sp
905 At time of writing, I don\*(Aqt think you\*(Aqll need to use this.
906 .ie n .IP """$parser\->accept_codes( \fICodename\fR, \fICodename\fR... )""" 4
907 .el .IP "\f(CW$parser\->accept_codes( \fR\f(CICodename\fR\f(CW, \fR\f(CICodename\fR\f(CW... )\fR" 4
908 .IX Item "$parser->accept_codes( Codename, Codename... )"
909 This tells the parser that you accept additional formatting codes,
910 beyond just the standard ones (I B C L F S X, plus the two weird ones
911 you don\*(Aqt actually see in the parse tree, Z and E). For example, to also
912 accept codes "N", "R", and "W":
913 .Sp
914 .Vb 1
915 \& $parser\->accept_codes( qw( N R W ) );
916 .Ve
917 .Sp
918 \&\fBTODO: document how this interacts with =extend, and long element names\fR
919 .ie n .IP """$parser\->accept_directive_as_data( \fIdirective_name\fR )""" 4
920 .el .IP "\f(CW$parser\->accept_directive_as_data( \fR\f(CIdirective_name\fR\f(CW )\fR" 4
921 .IX Item "$parser->accept_directive_as_data( directive_name )"
922 .PD 0
923 .ie n .IP """$parser\->accept_directive_as_verbatim( \fIdirective_name\fR )""" 4
924 .el .IP "\f(CW$parser\->accept_directive_as_verbatim( \fR\f(CIdirective_name\fR\f(CW )\fR" 4
925 .IX Item "$parser->accept_directive_as_verbatim( directive_name )"
926 .ie n .IP """$parser\->accept_directive_as_processed( \fIdirective_name\fR )""" 4
927 .el .IP "\f(CW$parser\->accept_directive_as_processed( \fR\f(CIdirective_name\fR\f(CW )\fR" 4
928 .IX Item "$parser->accept_directive_as_processed( directive_name )"
929 .PD
930 In the unlikely situation that you need to tell the parser that you will
931 accept additional directives ("=foo" things), you need to first set the
932 parser to treat its content as data (i.e., not really processed at
933 all), or as verbatim (mostly just expanding tabs), or as processed text
934 (parsing formatting codes like B<...>).
935 .Sp
936 For example, to accept a new directive "=method", you\*(Aqd presumably
937 use:
938 .Sp
939 .Vb 1
940 \& $parser\->accept_directive_as_processed("method");
941 .Ve
942 .Sp
943 so that you could have Pod lines like:
944 .Sp
945 .Vb 1
946 \& =method I<$whatever> thing B<um>
947 .Ve
948 .Sp
949 Making up your own directives breaks compatibility with other Pod
950 formatters, in a way that using "=for \fItarget\fR ..." lines doesn\*(Aqt;
951 however, you may find this useful if you\*(Aqre making a Pod superset
952 format where you don\*(Aqt need to worry about compatibility.
953 .ie n .IP """$parser\->nbsp_for_S( \fIBOOLEAN\fR );""" 4
954 .el .IP "\f(CW$parser\->nbsp_for_S( \fR\f(CIBOOLEAN\fR\f(CW );\fR" 4
955 .IX Item "$parser->nbsp_for_S( BOOLEAN );"
956 Setting this attribute to a true value (and by default it is false) will
957 turn "S<...>" sequences into sequences of words separated by
958 \&\f(CW\*(C`\exA0\*(C'\fR (non\-breaking space) characters. For example, it will take this:
959 .Sp
960 .Vb 1
961 \& I like S<Dutch apple pie>, don\*(Aqt you?
962 .Ve
963 .Sp
964 and treat it as if it were:
965 .Sp
966 .Vb 1
967 \& I like DutchE<nbsp>appleE<nbsp>pie, don\*(Aqt you?
968 .Ve
969 .Sp
970 This is handy for output formats that don\*(Aqt have anything quite like an
971 "S<...>" code, but which do have a code for non\-breaking space.
972 .Sp
973 There is currently no method for going the other way; but I can
974 probably provide one upon request.
975 .ie n .IP """$parser\->version_report()""" 4
976 .el .IP \f(CW$parser\->version_report()\fR 4
977 .IX Item "$parser->version_report()"
978 This returns a string reporting the \f(CW$VERSION\fR value from your module (and
979 its classname) as well as the \f(CW$VERSION\fR value of Pod::Simple. Note that
980 perlpodspec requires output formats (wherever possible) to note
981 this detail in a comment in the output format. For example, for
982 some kind of SGML output format:
983 .Sp
984 .Vb 1
985 \& print OUT "<!\-\- \en", $parser\->version_report, "\en \-\->";
986 .Ve
987 .ie n .IP """$parser\->pod_para_count()""" 4
988 .el .IP \f(CW$parser\->pod_para_count()\fR 4
989 .IX Item "$parser->pod_para_count()"
990 This returns the count of Pod paragraphs seen so far.
991 .ie n .IP """$parser\->line_count()""" 4
992 .el .IP \f(CW$parser\->line_count()\fR 4
993 .IX Item "$parser->line_count()"
994 This is the current line number being parsed. But you might find the
995 "line_number" event attribute more accurate, when it is present.
996 .ie n .IP """$parser\->nix_X_codes( \fISOMEVALUE\fR )""" 4
997 .el .IP "\f(CW$parser\->nix_X_codes( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
998 .IX Item "$parser->nix_X_codes( SOMEVALUE )"
999 This attribute, when set to a true value (and it is false by default)
1000 ignores any "X<...>" sequences in the document being parsed.
1001 Many formats don\*(Aqt actually use the content of these codes, so have
1002 no reason to process them.
1003 .ie n .IP """$parser\->keep_encoding_directive( \fISOMEVALUE\fR )""" 4
1004 .el .IP "\f(CW$parser\->keep_encoding_directive( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1005 .IX Item "$parser->keep_encoding_directive( SOMEVALUE )"
1006 This attribute, when set to a true value (it is false by default)
1007 will keep \f(CW\*(C`=encoding\*(C'\fR and its content in the event structure. Most
1008 formats don\*(Aqt actually need to process the content of an \f(CW\*(C`=encoding\*(C'\fR
1009 directive, even when this directive sets the encoding and the
1010 processor makes use of the encoding information. Indeed, it is
1011 possible to know the encoding without processing the directive
1012 content.
1013 .ie n .IP """$parser\->merge_text( \fISOMEVALUE\fR )""" 4
1014 .el .IP "\f(CW$parser\->merge_text( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1015 .IX Item "$parser->merge_text( SOMEVALUE )"
1016 This attribute, when set to a true value (and it is false by default)
1017 makes sure that only one event (or token, or node) will be created
1018 for any single contiguous sequence of text. For example, consider
1019 this somewhat contrived example:
1020 .Sp
1021 .Vb 1
1022 \& I just LOVE Z<>hotE<32>apple pie!
1023 .Ve
1024 .Sp
1025 When that is parsed and events are about to be called on it, it may
1026 actually seem to be four different text events, one right after another:
1027 one event for "I just LOVE ", one for "hot", one for " ", and one for
1028 "apple pie!". But if you have merge_text on, then you\*(Aqre guaranteed
1029 that it will be fired as one text event: "I just LOVE hot apple pie!".
1030 .ie n .IP """$parser\->code_handler( \fICODE_REF\fR )""" 4
1031 .el .IP "\f(CW$parser\->code_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4
1032 .IX Item "$parser->code_handler( CODE_REF )"
1033 This specifies code that should be called when a code line is seen
1034 (i.e., a line outside of the Pod). Normally this is undef, meaning
1035 that no code should be called. If you provide a routine, it should
1036 start out like this:
1037 .Sp
1038 .Vb 4
1039 \& sub get_code_line { # or whatever you\*(Aqll call it
1040 \& my($line, $line_number, $parser) = @_;
1041 \& ...
1042 \& }
1043 .Ve
1044 .Sp
1045 Note, however, that sometimes the Pod events aren\*(Aqt processed in exactly
1046 the same order as the code lines are \-\- i.e., if you have a file with
1047 Pod, then code, then more Pod, sometimes the code will be processed (via
1048 whatever you have code_handler call) before the all of the preceding Pod
1049 has been processed.
1050 .ie n .IP """$parser\->cut_handler( \fICODE_REF\fR )""" 4
1051 .el .IP "\f(CW$parser\->cut_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4
1052 .IX Item "$parser->cut_handler( CODE_REF )"
1053 This is just like the code_handler attribute, except that it\*(Aqs for
1054 "=cut" lines, not code lines. The same caveats apply. "=cut" lines are
1055 unlikely to be interesting, but this is included for completeness.
1056 .ie n .IP """$parser\->pod_handler( \fICODE_REF\fR )""" 4
1057 .el .IP "\f(CW$parser\->pod_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4
1058 .IX Item "$parser->pod_handler( CODE_REF )"
1059 This is just like the code_handler attribute, except that it\*(Aqs for
1060 "=pod" lines, not code lines. The same caveats apply. "=pod" lines are
1061 unlikely to be interesting, but this is included for completeness.
1062 .ie n .IP """$parser\->whiteline_handler( \fICODE_REF\fR )""" 4
1063 .el .IP "\f(CW$parser\->whiteline_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4
1064 .IX Item "$parser->whiteline_handler( CODE_REF )"
1065 This is just like the code_handler attribute, except that it\*(Aqs for
1066 lines that are seemingly blank but have whitespace (" " and/or "\et") on them,
1067 not code lines. The same caveats apply. These lines are unlikely to be
1068 interesting, but this is included for completeness.
1069 .ie n .IP """$parser\->whine( \fIlinenumber\fR, \fIcomplaint string\fR )""" 4
1070 .el .IP "\f(CW$parser\->whine( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\fR" 4
1071 .IX Item "$parser->whine( linenumber, complaint string )"
1072 This notes a problem in the Pod, which will be reported in the "Pod
1073 Errors" section of the document and/or sent to STDERR, depending on the
1074 values of the attributes \f(CW\*(C`no_whining\*(C'\fR, \f(CW\*(C`no_errata_section\*(C'\fR, and
1075 \&\f(CW\*(C`complain_stderr\*(C'\fR.
1076 .ie n .IP """$parser\->scream( \fIlinenumber\fR, \fIcomplaint string\fR )""" 4
1077 .el .IP "\f(CW$parser\->scream( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\fR" 4
1078 .IX Item "$parser->scream( linenumber, complaint string )"
1079 This notes an error like \f(CW\*(C`whine\*(C'\fR does, except that it is not
1080 suppressible with \f(CW\*(C`no_whining\*(C'\fR. This should be used only for very
1081 serious errors.
1082 .ie n .IP """$parser\->source_dead(1)""" 4
1083 .el .IP \f(CW$parser\->source_dead(1)\fR 4
1084 .IX Item "$parser->source_dead(1)"
1085 This aborts parsing of the current document, by switching on the flag
1086 that indicates that EOF has been seen. In particularly drastic cases,
1087 you might want to do this. It\*(Aqs rather nicer than just calling
1088 \&\f(CW\*(C`die\*(C'\fR!
1089 .ie n .IP """$parser\->hide_line_numbers( \fISOMEVALUE\fR )""" 4
1090 .el .IP "\f(CW$parser\->hide_line_numbers( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1091 .IX Item "$parser->hide_line_numbers( SOMEVALUE )"
1092 Some subclasses that indiscriminately dump event attributes (well,
1093 except for ones beginning with "~") can use this object attribute for
1094 refraining to dump the "start_line" attribute.
1095 .ie n .IP """$parser\->no_whining( \fISOMEVALUE\fR )""" 4
1096 .el .IP "\f(CW$parser\->no_whining( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1097 .IX Item "$parser->no_whining( SOMEVALUE )"
1098 This attribute, if set to true, will suppress reports of non\-fatal
1099 error messages. The default value is false, meaning that complaints
1100 \&\fIare\fR reported. How they get reported depends on the values of
1101 the attributes \f(CW\*(C`no_errata_section\*(C'\fR and \f(CW\*(C`complain_stderr\*(C'\fR.
1102 .ie n .IP """$parser\->no_errata_section( \fISOMEVALUE\fR )""" 4
1103 .el .IP "\f(CW$parser\->no_errata_section( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1104 .IX Item "$parser->no_errata_section( SOMEVALUE )"
1105 This attribute, if set to true, will suppress generation of an errata
1106 section. The default value is false \-\- i.e., an errata section will be
1107 generated.
1108 .ie n .IP """$parser\->complain_stderr( \fISOMEVALUE\fR )""" 4
1109 .el .IP "\f(CW$parser\->complain_stderr( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1110 .IX Item "$parser->complain_stderr( SOMEVALUE )"
1111 This attribute, if set to true will send complaints to STDERR. The
1112 default value is false \-\- i.e., complaints do not go to STDERR.
1113 .ie n .IP """$parser\->bare_output( \fISOMEVALUE\fR )""" 4
1114 .el .IP "\f(CW$parser\->bare_output( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1115 .IX Item "$parser->bare_output( SOMEVALUE )"
1116 Some formatter subclasses use this as a flag for whether output should
1117 have prologue and epilogue code omitted. For example, setting this to
1118 true for an HTML formatter class should omit the
1119 "<html><head><title>...</title><body>..." prologue and the
1120 "</body></html>" epilogue.
1121 .Sp
1122 If you want to set this to true, you should probably also set
1123 \&\f(CW\*(C`no_whining\*(C'\fR or at least \f(CW\*(C`no_errata_section\*(C'\fR to true.
1124 .ie n .IP """$parser\->preserve_whitespace( \fISOMEVALUE\fR )""" 4
1125 .el .IP "\f(CW$parser\->preserve_whitespace( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1126 .IX Item "$parser->preserve_whitespace( SOMEVALUE )"
1127 If you set this attribute to a true value, the parser will try to
1128 preserve whitespace in the output. This means that such formatting
1129 conventions as two spaces after periods will be preserved by the parser.
1130 This is primarily useful for output formats that treat whitespace as
1131 significant (such as text or *roff, but not HTML).
1132 .ie n .IP """$parser\->parse_empty_lists( \fISOMEVALUE\fR )""" 4
1133 .el .IP "\f(CW$parser\->parse_empty_lists( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4
1134 .IX Item "$parser->parse_empty_lists( SOMEVALUE )"
1135 If this attribute is set to true, the parser will not ignore empty
1136 \&\f(CW\*(C`=over\*(C'\fR/\f(CW\*(C`=back\*(C'\fR blocks. The type of \f(CW\*(C`=over\*(C'\fR will be \fIempty\fR, documented
1137 above, "events with an element_name of over\-empty".
1138 .SH "SEE ALSO"
1139 .IX Header "SEE ALSO"
1140 Pod::Simple \-\- event\-based Pod\-parsing framework
1141 .PP
1142 Pod::Simple::Methody \-\- like Pod::Simple, but each sort of event
1143 calls its own method (like \f(CW\*(C`start_head3\*(C'\fR)
1144 .PP
1145 Pod::Simple::PullParser \-\- a Pod\-parsing framework like Pod::Simple,
1146 but with a token\-stream interface
1147 .PP
1148 Pod::Simple::SimpleTree \-\- a Pod\-parsing framework like Pod::Simple,
1149 but with a tree interface
1150 .PP
1151 Pod::Simple::Checker \-\- a simple Pod::Simple subclass that reads
1152 documents, and then makes a plaintext report of any errors found in the
1153 document
1154 .PP
1155 Pod::Simple::DumpAsXML \-\- for dumping Pod documents as tidily
1156 indented XML, showing each event on its own line
1157 .PP
1158 Pod::Simple::XMLOutStream \-\- dumps a Pod document as XML (without
1159 introducing extra whitespace as Pod::Simple::DumpAsXML does).
1160 .PP
1161 Pod::Simple::DumpAsText \-\- for dumping Pod documents as tidily
1162 indented text, showing each event on its own line
1163 .PP
1164 Pod::Simple::LinkSection \-\- class for objects representing the values
1165 of the TODO and TODO attributes of L<...> elements
1166 .PP
1167 Pod::Escapes \-\- the module that Pod::Simple uses for evaluating
1168 E<...> content
1169 .PP
1170 Pod::Simple::Text \-\- a simple plaintext formatter for Pod
1171 .PP
1172 Pod::Simple::TextContent \-\- like Pod::Simple::Text, but
1173 makes no effort for indent or wrap the text being formatted
1174 .PP
1175 Pod::Simple::HTML \-\- a simple HTML formatter for Pod
1176 .PP
1177 perlpod
1178 .PP
1179 perlpodspec
1180 .PP
1181 perldoc
1182 .SH SUPPORT
1183 .IX Header "SUPPORT"
1184 Questions or discussion about POD and Pod::Simple should be sent to the
1185 pod\[email protected] mail list. Send an empty email to
1186 pod\-people\[email protected] to subscribe.
1187 .PP
1188 This module is managed in an open GitHub repository,
1189 <https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or
1190 to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches!
1191 .PP
1192 Patches against Pod::Simple are welcome. Please send bug reports to
1193 <bug\-pod\[email protected]>.
1194 .SH "COPYRIGHT AND DISCLAIMERS"
1195 .IX Header "COPYRIGHT AND DISCLAIMERS"
1196 Copyright (c) 2002 Sean M. Burke.
1197 .PP
1198 This library is free software; you can redistribute it and/or modify it
1199 under the same terms as Perl itself.
1200 .PP
1201 This program is distributed in the hope that it will be useful, but
1202 without any warranty; without even the implied warranty of
1203 merchantability or fitness for a particular purpose.
1204 .SH AUTHOR
1205 .IX Header "AUTHOR"
1206 Pod::Simple was created by Sean M. Burke <[email protected]>.
1207 But don\*(Aqt bother him, he\*(Aqs retired.
1208 .PP
1209 Pod::Simple is maintained by:
1210 .IP \(bu 4
1211 Allison Randal \f(CW\*(C`[email protected]\*(C'\fR
1212 .IP \(bu 4
1213 Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR
1214 .IP \(bu 4
1215 David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR