Debian Codegraph @

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