1Pod::Simple::SubclassinUgs(e3r)Contributed Perl DocumentPaotdi:o:nSimple::Subclassing(3)
2
6 Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
7
9 package Pod::SomeFormatter;
10 use Pod::Simple;
11 @ISA = qw(Pod::Simple);
12 $VERSION = '1.01';
13 use strict;
14 sub _handle_element_start {
16 my($parser, $element_name, $attr_hash_r) = @_;
17 ...
18 }
19 sub _handle_element_end {
21 my($parser, $element_name, $attr_hash_r) = @_;
22 # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
23 # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
24 # mostly useless. It is documented where "over-*" and "begin" events are
25 # documented.
26 ...
27 }
28 sub _handle_text {
30 my($parser, $text) = @_;
31 ...
32 }
33 1;
34
36 This document is about using Pod::Simple to write a Pod processor,
37 generally a Pod formatter. If you just want to know about using an
38 existing Pod formatter, instead see its documentation and see also the
39 docs in Pod::Simple.
40 The zeroeth step in writing a Pod formatter is to make sure that there
42 isn't already a decent one in CPAN. See <http://search.cpan.org/>, and
43 run a search on the name of the format you want to render to. Also
44 consider joining the Pod People list
45 <http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether
46 anyone has a formatter for that format -- maybe someone cobbled one
47 together but just hasn't released it.
48 The first step in writing a Pod processor is to read perlpodspec, which
50 contains information on writing a Pod parser (which has been largely
51 taken care of by Pod::Simple), but also a lot of requirements and
52 recommendations for writing a formatter.
53 The second step is to actually learn the format you're planning to
55 format to -- or at least as much as you need to know to represent Pod,
56 which probably isn't much.
57 The third step is to pick which of Pod::Simple's interfaces you want to
59 use:
60 Pod::Simple
62 The basic Pod::Simple interface that uses _handle_element_start(),
63 _handle_element_end() and _handle_text().
64 Pod::Simple::Methody
66 The Pod::Simple::Methody interface is event-based, similar to that
67 of HTML::Parser or XML::Parser's "Handlers".
68 Pod::Simple::PullParser
70 Pod::Simple::PullParser provides a token-stream interface, sort of
71 like HTML::TokeParser's interface.
72 Pod::Simple::SimpleTree
74 Pod::Simple::SimpleTree provides a simple tree interface, rather
75 like XML::Parser's "Tree" interface. Users familiar with XML
76 handling will be comfortable with this interface. Users interested
77 in outputting XML, should look into the modules that produce an XML
78 representation of the Pod stream, notably
79 Pod::Simple::XMLOutStream; you can feed the output of such a class
80 to whatever XML parsing system you are most at home with.
81 The last step is to write your code based on how the events (or tokens,
83 or tree-nodes, or the XML, or however you're parsing) will map to
84 constructs in the output format. Also be sure to consider how to escape
85 text nodes containing arbitrary text, and what to do with text nodes
86 that represent preformatted text (from verbatim sections).
87
89 TODO intro... mention that events are supplied for implicits, like for
90 missing >'s
91 In the following section, we use XML to represent the event structure
93 associated with a particular construct. That is, an opening tag
94 represents the element start, the attributes of that opening tag are
95 the attributes given to the callback, and the closing tag represents
96 the end element.
97 Three callback methods must be supplied by a class extending
99 Pod::Simple to receive the corresponding event:
100 "$parser->_handle_element_start( element_name, attr_hashref )"
102 "$parser->_handle_element_end( element_name )"
103 "$parser->_handle_text( text_string )"
104 Here's the comprehensive list of values you can expect as element_name
106 in your implementation of "_handle_element_start" and
107 "_handle_element_end"::
108 events with an element_name of Document
110 Parsing a document produces this event structure:
111 <Document start_line="543">
113 ...all events...
114 </Document>
115 The value of the start_line attribute will be the line number of
117 the first Pod directive in the document.
118 If there is no Pod in the given document, then the event structure
120 will be this:
121 <Document contentless="1" start_line="543">
123 </Document>
124 In that case, the value of the start_line attribute will not be
126 meaningful; under current implementations, it will probably be the
127 line number of the last line in the file.
128 events with an element_name of Para
130 Parsing a plain (non-verbatim, non-directive, non-data) paragraph
131 in a Pod document produces this event structure:
132 <Para start_line="543">
134 ...all events in this paragraph...
135 </Para>
136 The value of the start_line attribute will be the line number of
138 the start of the paragraph.
139 For example, parsing this paragraph of Pod:
141 The value of the I<start_line> attribute will be the
143 line number of the start of the paragraph.
144 produces this event structure:
146 <Para start_line="129">
148 The value of the
149 <I>
150 start_line
151 </I>
152 attribute will be the line number of the first Pod directive
153 in the document.
154 </Para>
155 events with an element_name of B, C, F, or I.
157 Parsing a B<...> formatting code (or of course any of its
158 semantically identical syntactic variants B<< ... >>, or
159 B<<<< ... >>>>, etc.) produces this event structure:
160 <B>
162 ...stuff...
163 </B>
164 Currently, there are no attributes conveyed.
166 Parsing C, F, or I codes produce the same structure, with only a
168 different element name.
169 If your parser object has been set to accept other formatting
171 codes, then they will be presented like these B/C/F/I codes --
172 i.e., without any attributes.
173 events with an element_name of S
175 Normally, parsing an S<...> sequence produces this event structure,
176 just as if it were a B/C/F/I code:
177 <S>
179 ...stuff...
180 </S>
181 However, Pod::Simple (and presumably all derived parsers) offers
183 the "nbsp_for_S" option which, if enabled, will suppress all S
184 events, and instead change all spaces in the content to non-
185 breaking spaces. This is intended for formatters that output to a
186 format that has no code that means the same as S<...>, but which
187 has a code/character that means non-breaking space.
188 events with an element_name of X
190 Normally, parsing an X<...> sequence produces this event structure,
191 just as if it were a B/C/F/I code:
192 <X>
194 ...stuff...
195 </X>
196 However, Pod::Simple (and presumably all derived parsers) offers
198 the "nix_X_codes" option which, if enabled, will suppress all X
199 events and ignore their content. For formatters/processors that
200 don't use X events, this is presumably quite useful.
201 events with an element_name of L
203 Because the L<...> is the most complex construct in the language,
204 it should not surprise you that the events it generates are the
205 most complex in the language. Most of complexity is hidden away in
206 the attribute values, so for those of you writing a Pod formatter
207 that produces a non-hypertextual format, you can just ignore the
208 attributes and treat an L event structure like a formatting element
209 that (presumably) doesn't actually produce a change in formatting.
210 That is, the content of the L event structure (as opposed to its
211 attributes) is always what text should be displayed.
212 There are, at first glance, three kinds of L links: URL, man, and
214 pod.
215 When a L<some_url> code is parsed, it produces this event
217 structure:
218 <L content-implicit="yes" raw="that_url" to="that_url" type="url">
220 that_url
221 </L>
222 The "type="url"" attribute is always specified for this type of L
224 code.
225 For example, this Pod source:
227 L<http://www.perl.com/CPAN/authors/>
229 produces this event structure:
231 <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
233 http://www.perl.com/CPAN/authors/
234 </L>
235 When a L<manpage(section)> code is parsed (and these are fairly
237 rare and not terribly useful), it produces this event structure:
238 <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
240 manpage(section)
241 </L>
242 The "type="man"" attribute is always specified for this type of L
244 code.
245 For example, this Pod source:
247 L<crontab(5)>
249 produces this event structure:
251 <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
253 crontab(5)
254 </L>
255 In the rare cases where a man page link has a section specified,
257 that text appears in a section attribute. For example, this Pod
258 source:
259 L<crontab(5)/"ENVIRONMENT">
261 will produce this event structure:
263 <L content-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man">
265 "ENVIRONMENT" in crontab(5)
266 </L>
267 In the rare case where the Pod document has code like
269 L<sometext|manpage(section)>, then the sometext will appear as the
270 content of the element, the manpage(section) text will appear only
271 as the value of the to attribute, and there will be no
272 "content-implicit="yes"" attribute (whose presence means that the
273 Pod parser had to infer what text should appear as the link text --
274 as opposed to cases where that attribute is absent, which means
275 that the Pod parser did not have to infer the link text, because
276 that L code explicitly specified some link text.)
277 For example, this Pod source:
279 L<hell itself!|crontab(5)>
281 will produce this event structure:
283 <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
285 hell itself!
286 </L>
287 The last type of L structure is for links to/within Pod documents.
289 It is the most complex because it can have a to attribute, or a
290 section attribute, or both. The "type="pod"" attribute is always
291 specified for this type of L code.
292 In the most common case, the simple case of a L<podpage> code
294 produces this event structure:
295 <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
297 podpage
298 </L>
299 For example, this Pod source:
301 L<Net::Ping>
303 produces this event structure:
305 <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
307 Net::Ping
308 </L>
309 In cases where there is link-text explicitly specified, it is to be
311 found in the content of the element (and not the attributes), just
312 as with the L<sometext|manpage(section)> case discussed above. For
313 example, this Pod source:
314 L<Perl Error Messages|perldiag>
316 produces this event structure:
318 <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
320 Perl Error Messages
321 </L>
322 In cases of links to a section in the current Pod document, there
324 is a section attribute instead of a to attribute. For example,
325 this Pod source:
326 L</"Member Data">
328 produces this event structure:
330 <L content-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod">
332 "Member Data"
333 </L>
334 As another example, this Pod source:
336 L<the various attributes|/"Member Data">
338 produces this event structure:
340 <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod">
342 the various attributes
343 </L>
344 In cases of links to a section in a different Pod document, there
346 are both a section attribute and a to attribute. For example, this
347 Pod source:
348 L<perlsyn/"Basic BLOCKs and Switch Statements">
350 produces this event structure:
352 <L content-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
354 "Basic BLOCKs and Switch Statements" in perlsyn
355 </L>
356 As another example, this Pod source:
358 L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
360 produces this event structure:
362 <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
364 SWITCH statements
365 </L>
366 Incidentally, note that we do not distinguish between these
368 syntaxes:
369 L</"Member Data">
371 L<"Member Data">
372 L</Member Data>
373 L<Member Data> [deprecated syntax]
374 That is, they all produce the same event structure (for the most
376 part), namely:
377 <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
379 "Member Data"
380 </L>
381 The raw attribute depends on what the raw content of the "L<>" is,
383 so that is why the event structure is the same "for the most part".
384 If you have not guessed it yet, the raw attribute contains the raw,
386 original, unescaped content of the "L<>" formatting code. In
387 addition to the examples above, take notice of the following event
388 structure produced by the following "L<>" formatting code.
389 L<click B<here>|page/About the C<-M> switch>
391 <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
393 click B<here>
394 </L>
395 Specifically, notice that the formatting codes are present and
397 unescaped in raw.
398 There is a known bug in the raw attribute where any surrounding
400 whitespace is condensed into a single ' '. For example, given L<
401 link>, raw will be " link".
402 events with an element_name of E or Z
404 While there are Pod codes E<...> and Z<>, these do not produce any
405 E or Z events -- that is, there are no such events as E or Z.
406 events with an element_name of Verbatim
408 When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
409 produces this event structure:
410 <Verbatim start_line="543" xml:space="preserve">
412 ...text...
413 </Verbatim>
414 The value of the start_line attribute will be the line number of
416 the first line of this verbatim block. The xml:space attribute is
417 always present, and always has the value "preserve".
418 The text content will have tabs already expanded.
420 events with an element_name of head1 .. head4
422 When a "=head1 ..." directive is parsed, it produces this event
423 structure:
424 <head1>
426 ...stuff...
427 </head1>
428 For example, a directive consisting of this:
430 =head1 Options to C<new> et al.
432 will produce this event structure:
434 <head1 start_line="543">
436 Options to
437 <C>
438 new
439 </C>
440 et al.
441 </head1>
442 "=head2" through "=head4" directives are the same, except for the
444 element names in the event structure.
445 events with an element_name of encoding
447 In the default case, the events corresponding to "=encoding"
448 directives are not emitted. They are emitted if
449 "keep_encoding_directive" is true. In that case they produce event
450 structures like "events with an element_name of head1 .. head4"
451 above.
452 events with an element_name of over-bullet
454 When an "=over ... =back" block is parsed where the items are a
455 bulleted list, it will produce this event structure:
456 <over-bullet indent="4" start_line="543">
458 <item-bullet start_line="545">
459 ...Stuff...
460 </item-bullet>
461 ...more item-bullets...
462 </over-bullet fake-closer="1">
463 The attribute fake-closer is only present if it is a true value; it
465 is not present if it is a false value. It is shown in the above
466 example to illustrate where the attribute is (in the closing tag).
467 It signifies that the "=over" did not have a matching "=back", and
468 thus Pod::Simple had to create a fake closer.
469 For example, this Pod source:
471 =over
473 =item *
475 Something
477 =back
479 Would produce an event structure that does not have the fake-closer
481 attribute, whereas this Pod source:
482 =over
484 =item *
486 Gasp! An unclosed =over block!
488 would. The rest of the over-* examples will not demonstrate this
490 attribute, but they all can have it. See Pod::Checker's source for
491 an example of this attribute being used.
492 The value of the indent attribute is whatever value is after the
494 "=over" directive, as in "=over 8". If no such value is specified
495 in the directive, then the indent attribute has the value "4".
496 For example, this Pod source:
498 =over
500 =item *
502 Stuff
504 =item *
506 Bar I<baz>!
508 =back
510 produces this event structure:
512 <over-bullet indent="4" start_line="10">
514 <item-bullet start_line="12">
515 Stuff
516 </item-bullet>
517 <item-bullet start_line="14">
518 Bar <I>baz</I>!
519 </item-bullet>
520 </over-bullet>
521 events with an element_name of over-number
523 When an "=over ... =back" block is parsed where the items are a
524 numbered list, it will produce this event structure:
525 <over-number indent="4" start_line="543">
527 <item-number number="1" start_line="545">
528 ...Stuff...
529 </item-number>
530 ...more item-number...
531 </over-bullet>
532 This is like the "over-bullet" event structure; but note that the
534 contents are "item-number" instead of "item-bullet", and note that
535 they will have a "number" attribute, which some
536 formatters/processors may ignore (since, for example, there's no
537 need for it in HTML when producing an "<UL><LI>...</LI>...</UL>"
538 structure), but which any processor may use.
539 Note that the values for the number attributes of "item-number"
541 elements in a given "over-number" area will start at 1 and go up by
542 one each time. If the Pod source doesn't follow that order (even
543 though it really should!), whatever numbers it has will be ignored
544 (with the correct values being put in the number attributes), and
545 an error message might be issued to the user.
546 events with an element_name of over-text
548 These events are somewhat unlike the other over-* structures, as
549 far as what their contents are. When an "=over ... =back" block is
550 parsed where the items are a list of text "subheadings", it will
551 produce this event structure:
552 <over-text indent="4" start_line="543">
554 <item-text>
555 ...stuff...
556 </item-text>
557 ...stuff (generally Para or Verbatim elements)...
558 <item-text>
559 ...more item-text and/or stuff...
560 </over-text>
561 The indent and fake-closer attributes are as with the other over-*
563 events.
564 For example, this Pod source:
566 =over
568 =item Foo
570 Stuff
572 =item Bar I<baz>!
574 Quux
576 =back
578 produces this event structure:
580 <over-text indent="4" start_line="20">
582 <item-text start_line="22">
583 Foo
584 </item-text>
585 <Para start_line="24">
586 Stuff
587 </Para>
588 <item-text start_line="26">
589 Bar
590 <I>
591 baz
592 </I>
593 !
594 </item-text>
595 <Para start_line="28">
596 Quux
597 </Para>
598 </over-text>
599 events with an element_name of over-block
601 These events are somewhat unlike the other over-* structures, as
602 far as what their contents are. When an "=over ... =back" block is
603 parsed where there are no items, it will produce this event
604 structure:
605 <over-block indent="4" start_line="543">
607 ...stuff (generally Para or Verbatim elements)...
608 </over-block>
609 The indent and fake-closer attributes are as with the other over-*
611 events.
612 For example, this Pod source:
614 =over
616 For cutting off our trade with all parts of the world
618 For transporting us beyond seas to be tried for pretended offenses
620 He is at this time transporting large armies of foreign mercenaries to
622 complete the works of death, desolation and tyranny, already begun with
623 circumstances of cruelty and perfidy scarcely paralleled in the most
624 barbarous ages, and totally unworthy the head of a civilized nation.
625 =back
627 will produce this event structure:
629 <over-block indent="4" start_line="2">
631 <Para start_line="4">
632 For cutting off our trade with all parts of the world
633 </Para>
634 <Para start_line="6">
635 For transporting us beyond seas to be tried for pretended offenses
636 </Para>
637 <Para start_line="8">
638 He is at this time transporting large armies of [...more text...]
639 </Para>
640 </over-block>
641 events with an element_name of over-empty
643 Note: These events are only triggered if parse_empty_lists() is set
644 to a true value.
645 These events are somewhat unlike the other over-* structures, as
647 far as what their contents are. When an "=over ... =back" block is
648 parsed where there is no content, it will produce this event
649 structure:
650 <over-empty indent="4" start_line="543">
652 </over-empty>
653 The indent and fake-closer attributes are as with the other over-*
655 events.
656 For example, this Pod source:
658 =over
660 =over
662 =back
664 =back
666 will produce this event structure:
668 <over-block indent="4" start_line="1">
670 <over-empty indent="4" start_line="3">
671 </over-empty>
672 </over-block>
673 Note that the outer "=over" is a block because it has no "=item"s
675 but still has content: the inner "=over". The inner "=over", in
676 turn, is completely empty, and is treated as such.
677 events with an element_name of item-bullet
679 See "events with an element_name of over-bullet", above.
680 events with an element_name of item-number
682 See "events with an element_name of over-number", above.
683 events with an element_name of item-text
685 See "events with an element_name of over-text", above.
686 events with an element_name of for
688 TODO...
689 events with an element_name of Data
691 TODO...
692
694 Pod::Simple provides a lot of methods that aren't generally interesting
695 to the end user of an existing Pod formatter, but some of which you
696 might find useful in writing a Pod formatter. They are listed below.
697 The first several methods (the accept_* methods) are for declaring the
698 capabilities of your parser, notably what "=for targetname" sections
699 it's interested in, what extra N<...> codes it accepts beyond the ones
700 described in the perlpod.
701 "$parser->accept_targets( SOMEVALUE )"
703 As the parser sees sections like:
704 =for html <img src="fig1.jpg">
706 or
708 =begin html
710 <img src="fig1.jpg">
712 =end html
714 ...the parser will ignore these sections unless your subclass has
716 specified that it wants to see sections targeted to "html" (or
717 whatever the formatter name is).
718 If you want to process all sections, even if they're not targeted
720 for you, call this before you start parsing:
721 $parser->accept_targets('*');
723 "$parser->accept_targets_as_text( SOMEVALUE )"
725 This is like accept_targets, except that it specifies also that the
726 content of sections for this target should be treated as Pod text
727 even if the target name in "=for targetname" doesn't start with a
728 ":".
729 At time of writing, I don't think you'll need to use this.
731 "$parser->accept_codes( Codename, Codename... )"
733 This tells the parser that you accept additional formatting codes,
734 beyond just the standard ones (I B C L F S X, plus the two weird
735 ones you don't actually see in the parse tree, Z and E). For
736 example, to also accept codes "N", "R", and "W":
737 $parser->accept_codes( qw( N R W ) );
739 TODO: document how this interacts with =extend, and long element
741 names
742 "$parser->accept_directive_as_data( directive_name )"
744 "$parser->accept_directive_as_verbatim( directive_name )"
745 "$parser->accept_directive_as_processed( directive_name )"
746 In the unlikely situation that you need to tell the parser that you
747 will accept additional directives ("=foo" things), you need to
748 first set the parser to treat its content as data (i.e., not really
749 processed at all), or as verbatim (mostly just expanding tabs), or
750 as processed text (parsing formatting codes like B<...>).
751 For example, to accept a new directive "=method", you'd presumably
753 use:
754 $parser->accept_directive_as_processed("method");
756 so that you could have Pod lines like:
758 =method I<$whatever> thing B<um>
760 Making up your own directives breaks compatibility with other Pod
762 formatters, in a way that using "=for target ..." lines doesn't;
763 however, you may find this useful if you're making a Pod superset
764 format where you don't need to worry about compatibility.
765 "$parser->nbsp_for_S( BOOLEAN );"
767 Setting this attribute to a true value (and by default it is false)
768 will turn "S<...>" sequences into sequences of words separated by
769 "\xA0" (non-breaking space) characters. For example, it will take
770 this:
771 I like S<Dutch apple pie>, don't you?
773 and treat it as if it were:
775 I like DutchE<nbsp>appleE<nbsp>pie, don't you?
777 This is handy for output formats that don't have anything quite
779 like an "S<...>" code, but which do have a code for non-breaking
780 space.
781 There is currently no method for going the other way; but I can
783 probably provide one upon request.
784 "$parser->version_report()"
786 This returns a string reporting the $VERSION value from your module
787 (and its classname) as well as the $VERSION value of Pod::Simple.
788 Note that perlpodspec requires output formats (wherever possible)
789 to note this detail in a comment in the output format. For
790 example, for some kind of SGML output format:
791 print OUT "<!-- \n", $parser->version_report, "\n -->";
793 "$parser->pod_para_count()"
795 This returns the count of Pod paragraphs seen so far.
796 "$parser->line_count()"
798 This is the current line number being parsed. But you might find
799 the "line_number" event attribute more accurate, when it is
800 present.
801 "$parser->nix_X_codes( SOMEVALUE )"
803 This attribute, when set to a true value (and it is false by
804 default) ignores any "X<...>" sequences in the document being
805 parsed. Many formats don't actually use the content of these
806 codes, so have no reason to process them.
807 "$parser->keep_encoding_directive( SOMEVALUE )"
809 This attribute, when set to a true value (it is false by default)
810 will keep "=encoding" and its content in the event structure. Most
811 formats don't actually need to process the content of an
812 "=encoding" directive, even when this directive sets the encoding
813 and the processor makes use of the encoding information. Indeed, it
814 is possible to know the encoding without processing the directive
815 content.
816 "$parser->merge_text( SOMEVALUE )"
818 This attribute, when set to a true value (and it is false by
819 default) makes sure that only one event (or token, or node) will be
820 created for any single contiguous sequence of text. For example,
821 consider this somewhat contrived example:
822 I just LOVE Z<>hotE<32>apple pie!
824 When that is parsed and events are about to be called on it, it may
826 actually seem to be four different text events, one right after
827 another: one event for "I just LOVE ", one for "hot", one for " ",
828 and one for "apple pie!". But if you have merge_text on, then
829 you're guaranteed that it will be fired as one text event: "I just
830 LOVE hot apple pie!".
831 "$parser->code_handler( CODE_REF )"
833 This specifies code that should be called when a code line is seen
834 (i.e., a line outside of the Pod). Normally this is undef, meaning
835 that no code should be called. If you provide a routine, it should
836 start out like this:
837 sub get_code_line { # or whatever you'll call it
839 my($line, $line_number, $parser) = @_;
840 ...
841 }
842 Note, however, that sometimes the Pod events aren't processed in
844 exactly the same order as the code lines are -- i.e., if you have a
845 file with Pod, then code, then more Pod, sometimes the code will be
846 processed (via whatever you have code_handler call) before the all
847 of the preceding Pod has been processed.
848 "$parser->cut_handler( CODE_REF )"
850 This is just like the code_handler attribute, except that it's for
851 "=cut" lines, not code lines. The same caveats apply. "=cut" lines
852 are unlikely to be interesting, but this is included for
853 completeness.
854 "$parser->pod_handler( CODE_REF )"
856 This is just like the code_handler attribute, except that it's for
857 "=pod" lines, not code lines. The same caveats apply. "=pod" lines
858 are unlikely to be interesting, but this is included for
859 completeness.
860 "$parser->whiteline_handler( CODE_REF )"
862 This is just like the code_handler attribute, except that it's for
863 lines that are seemingly blank but have whitespace (" " and/or
864 "\t") on them, not code lines. The same caveats apply. These lines
865 are unlikely to be interesting, but this is included for
866 completeness.
867 "$parser->whine( linenumber, complaint string )"
869 This notes a problem in the Pod, which will be reported in the "Pod
870 Errors" section of the document and/or sent to STDERR, depending on
871 the values of the attributes "no_whining", "no_errata_section", and
872 "complain_stderr".
873 "$parser->scream( linenumber, complaint string )"
875 This notes an error like "whine" does, except that it is not
876 suppressible with "no_whining". This should be used only for very
877 serious errors.
878 "$parser->source_dead(1)"
880 This aborts parsing of the current document, by switching on the
881 flag that indicates that EOF has been seen. In particularly
882 drastic cases, you might want to do this. It's rather nicer than
883 just calling "die"!
884 "$parser->hide_line_numbers( SOMEVALUE )"
886 Some subclasses that indiscriminately dump event attributes (well,
887 except for ones beginning with "~") can use this object attribute
888 for refraining to dump the "start_line" attribute.
889 "$parser->no_whining( SOMEVALUE )"
891 This attribute, if set to true, will suppress reports of non-fatal
892 error messages. The default value is false, meaning that
893 complaints are reported. How they get reported depends on the
894 values of the attributes "no_errata_section" and "complain_stderr".
895 "$parser->no_errata_section( SOMEVALUE )"
897 This attribute, if set to true, will suppress generation of an
898 errata section. The default value is false -- i.e., an errata
899 section will be generated.
900 "$parser->complain_stderr( SOMEVALUE )"
902 This attribute, if set to true will send complaints to STDERR. The
903 default value is false -- i.e., complaints do not go to STDERR.
904 "$parser->bare_output( SOMEVALUE )"
906 Some formatter subclasses use this as a flag for whether output
907 should have prologue and epilogue code omitted. For example,
908 setting this to true for an HTML formatter class should omit the
909 "<html><head><title>...</title><body>..." prologue and the
910 "</body></html>" epilogue.
911 If you want to set this to true, you should probably also set
913 "no_whining" or at least "no_errata_section" to true.
914 "$parser->preserve_whitespace( SOMEVALUE )"
916 If you set this attribute to a true value, the parser will try to
917 preserve whitespace in the output. This means that such formatting
918 conventions as two spaces after periods will be preserved by the
919 parser. This is primarily useful for output formats that treat
920 whitespace as significant (such as text or *roff, but not HTML).
921 "$parser->parse_empty_lists( SOMEVALUE )"
923 If this attribute is set to true, the parser will not ignore empty
924 "=over"/"=back" blocks. The type of "=over" will be empty,
925 documented above, "events with an element_name of over-empty".
926
928 Pod::Simple -- event-based Pod-parsing framework
929 Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls
931 its own method (like "start_head3")
932 Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple,
934 but with a token-stream interface
935 Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple,
937 but with a tree interface
938 Pod::Simple::Checker -- a simple Pod::Simple subclass that reads
940 documents, and then makes a plaintext report of any errors found in the
941 document
942 Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented
944 XML, showing each event on its own line
945 Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without
947 introducing extra whitespace as Pod::Simple::DumpAsXML does).
948 Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented
950 text, showing each event on its own line
951 Pod::Simple::LinkSection -- class for objects representing the values
953 of the TODO and TODO attributes of L<...> elements
954 Pod::Escapes -- the module that Pod::Simple uses for evaluating E<...>
956 content
957 Pod::Simple::Text -- a simple plaintext formatter for Pod
959 Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort
961 for indent or wrap the text being formatted
962 Pod::Simple::HTML -- a simple HTML formatter for Pod
964 perlpod
966 perlpodspec
968 perldoc
970
972 Questions or discussion about POD and Pod::Simple should be sent to the
973 pod-people@perl.org mail list. Send an empty email to
974 pod-people-subscribe@perl.org to subscribe.
975 This module is managed in an open GitHub repository,
977 <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
978 contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
979 send patches!
980 Patches against Pod::Simple are welcome. Please send bug reports to
982 <bug-pod-simple@rt.cpan.org>.
983
985 Copyright (c) 2002 Sean M. Burke.
986 This library is free software; you can redistribute it and/or modify it
988 under the same terms as Perl itself.
989 This program is distributed in the hope that it will be useful, but
991 without any warranty; without even the implied warranty of
992 merchantability or fitness for a particular purpose.
993
995 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
996 bother him, he's retired.
997 Pod::Simple is maintained by:
999 • Allison Randal "allison@perl.org"
1001 • Hans Dieter Pearcey "hdp@cpan.org"
1003 • David E. Wheeler "dwheeler@cpan.org"
1005perl v5.36.0 2023-01-20 Pod::Simple::Subclassing(3)