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
63 "_handle_element_start()", "_handle_element_end()" and
64 "_handle_text()".
65 Pod::Simple::Methody
67 The Pod::Simple::Methody interface is event-based, similar to that
68 of HTML::Parser or XML::Parser's "Handlers".
69 Pod::Simple::PullParser
71 Pod::Simple::PullParser provides a token-stream interface, sort of
72 like HTML::TokeParser's interface.
73 Pod::Simple::SimpleTree
75 Pod::Simple::SimpleTree provides a simple tree interface, rather
76 like XML::Parser's "Tree" interface. Users familiar with XML
77 handling will be comfortable with this interface. Users interested
78 in outputting XML, should look into the modules that produce an XML
79 representation of the Pod stream, notably
80 Pod::Simple::XMLOutStream; you can feed the output of such a class
81 to whatever XML parsing system you are most at home with.
82 The last step is to write your code based on how the events (or tokens,
84 or tree-nodes, or the XML, or however you're parsing) will map to
85 constructs in the output format. Also be sure to consider how to escape
86 text nodes containing arbitrary text, and what to do with text nodes
87 that represent preformatted text (from verbatim sections).
88
90 TODO intro... mention that events are supplied for implicits, like for
91 missing >'s
92 In the following section, we use XML to represent the event structure
94 associated with a particular construct. That is, TODO
95 "$parser->_handle_element_start( element_name, attr_hashref )"
97 "$parser->_handle_element_end( element_name )"
98 "$parser->_handle_text( text_string )"
99 TODO describe
101 events with an element_name of Document
103 Parsing a document produces this event structure:
104 <Document start_line="543">
106 ...all events...
107 </Document>
108 The value of the start_line attribute will be the line number of
110 the first Pod directive in the document.
111 If there is no Pod in the given document, then the event structure
113 will be this:
114 <Document contentless="1" start_line="543">
116 </Document>
117 In that case, the value of the start_line attribute will not be
119 meaningful; under current implementations, it will probably be the
120 line number of the last line in the file.
121 events with an element_name of Para
123 Parsing a plain (non-verbatim, non-directive, non-data) paragraph
124 in a Pod document produces this event structure:
125 <Para start_line="543">
127 ...all events in this paragraph...
128 </Para>
129 The value of the start_line attribute will be the line number of
131 the start of the paragraph.
132 For example, parsing this paragraph of Pod:
134 The value of the I<start_line> attribute will be the
136 line number of the start of the paragraph.
137 produces this event structure:
139 <Para start_line="129">
141 The value of the
142 <I>
143 start_line
144 </I>
145 attribute will be the line number of the first Pod directive
146 in the document.
147 </Para>
148 events with an element_name of B, C, F, or I.
150 Parsing a B<...> formatting code (or of course any of its
151 semantically identical syntactic variants B<< ... >>, or
152 B<<<< ... >>>>, etc.) produces this event structure:
153 <B>
155 ...stuff...
156 </B>
157 Currently, there are no attributes conveyed.
159 Parsing C, F, or I codes produce the same structure, with only a
161 different element name.
162 If your parser object has been set to accept other formatting
164 codes, then they will be presented like these B/C/F/I codes --
165 i.e., without any attributes.
166 events with an element_name of S
168 Normally, parsing an S<...> sequence produces this event structure,
169 just as if it were a B/C/F/I code:
170 <S>
172 ...stuff...
173 </S>
174 However, Pod::Simple (and presumably all derived parsers) offers
176 the "nbsp_for_S" option which, if enabled, will suppress all S
177 events, and instead change all spaces in the content to non-
178 breaking spaces. This is intended for formatters that output to a
179 format that has no code that means the same as S<...>, but which
180 has a code/character that means non-breaking space.
181 events with an element_name of X
183 Normally, parsing an X<...> sequence produces this event structure,
184 just as if it were a B/C/F/I code:
185 <X>
187 ...stuff...
188 </X>
189 However, Pod::Simple (and presumably all derived parsers) offers
191 the "nix_X_codes" option which, if enabled, will suppress all X
192 events and ignore their content. For formatters/processors that
193 don't use X events, this is presumably quite useful.
194 events with an element_name of L
196 Because the L<...> is the most complex construct in the language,
197 it should not surprise you that the events it generates are the
198 most complex in the language. Most of complexity is hidden away in
199 the attribute values, so for those of you writing a Pod formatter
200 that produces a non-hypertextual format, you can just ignore the
201 attributes and treat an L event structure like a formatting element
202 that (presumably) doesn't actually produce a change in formatting.
203 That is, the content of the L event structure (as opposed to its
204 attributes) is always what text should be displayed.
205 There are, at first glance, three kinds of L links: URL, man, and
207 pod.
208 When a L<some_url> code is parsed, it produces this event
210 structure:
211 <L content-implicit="yes" raw="that_url" to="that_url" type="url">
213 that_url
214 </L>
215 The "type="url"" attribute is always specified for this type of L
217 code.
218 For example, this Pod source:
220 L<http://www.perl.com/CPAN/authors/>
222 produces this event structure:
224 <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
226 http://www.perl.com/CPAN/authors/
227 </L>
228 When a L<manpage(section)> code is parsed (and these are fairly
230 rare and not terribly useful), it produces this event structure:
231 <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
233 manpage(section)
234 </L>
235 The "type="man"" attribute is always specified for this type of L
237 code.
238 For example, this Pod source:
240 L<crontab(5)>
242 produces this event structure:
244 <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
246 crontab(5)
247 </L>
248 In the rare cases where a man page link has a section specified,
250 that text appears in a section attribute. For example, this Pod
251 source:
252 L<crontab(5)/"ENVIRONMENT">
254 will produce this event structure:
256 <L content-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man">
258 "ENVIRONMENT" in crontab(5)
259 </L>
260 In the rare case where the Pod document has code like
262 L<sometext|manpage(section)>, then the sometext will appear as the
263 content of the element, the manpage(section) text will appear only
264 as the value of the to attribute, and there will be no
265 "content-implicit="yes"" attribute (whose presence means that the
266 Pod parser had to infer what text should appear as the link text --
267 as opposed to cases where that attribute is absent, which means
268 that the Pod parser did not have to infer the link text, because
269 that L code explicitly specified some link text.)
270 For example, this Pod source:
272 L<hell itself!|crontab(5)>
274 will produce this event structure:
276 <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
278 hell itself!
279 </L>
280 The last type of L structure is for links to/within Pod documents.
282 It is the most complex because it can have a to attribute, or a
283 section attribute, or both. The "type="pod"" attribute is always
284 specified for this type of L code.
285 In the most common case, the simple case of a L<podpage> code
287 produces this event structure:
288 <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
290 podpage
291 </L>
292 For example, this Pod source:
294 L<Net::Ping>
296 produces this event structure:
298 <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
300 Net::Ping
301 </L>
302 In cases where there is link-text explicitly specified, it is to be
304 found in the content of the element (and not the attributes), just
305 as with the L<sometext|manpage(section)> case discussed above. For
306 example, this Pod source:
307 L<Perl Error Messages|perldiag>
309 produces this event structure:
311 <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
313 Perl Error Messages
314 </L>
315 In cases of links to a section in the current Pod document, there
317 is a section attribute instead of a to attribute. For example,
318 this Pod source:
319 L</"Member Data">
321 produces this event structure:
323 <L content-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod">
325 "Member Data"
326 </L>
327 As another example, this Pod source:
329 L<the various attributes|/"Member Data">
331 produces this event structure:
333 <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod">
335 the various attributes
336 </L>
337 In cases of links to a section in a different Pod document, there
339 are both a section attribute and a to attribute. For example, this
340 Pod source:
341 L<perlsyn/"Basic BLOCKs and Switch Statements">
343 produces this event structure:
345 <L content-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
347 "Basic BLOCKs and Switch Statements" in perlsyn
348 </L>
349 As another example, this Pod source:
351 L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
353 produces this event structure:
355 <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
357 SWITCH statements
358 </L>
359 Incidentally, note that we do not distinguish between these
361 syntaxes:
362 L</"Member Data">
364 L<"Member Data">
365 L</Member Data>
366 L<Member Data> [deprecated syntax]
367 That is, they all produce the same event structure (for the most
369 part), namely:
370 <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
372 "Member Data"
373 </L>
374 The raw attribute depends on what the raw content of the "L<>" is,
376 so that is why the event structure is the same "for the most part".
377 If you have not guessed it yet, the raw attribute contains the raw,
379 original, unescaped content of the "L<>" formatting code. In
380 addition to the examples above, take notice of the following event
381 structure produced by the following "L<>" formatting code.
382 L<click B<here>|page/About the C<-M> switch>
384 <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
386 click B<here>
387 </L>
388 Specifically, notice that the formatting codes are present and
390 unescaped in raw.
391 There is a known bug in the raw attribute where any surrounding
393 whitespace is condensed into a single ' '. For example, given L<
394 link>, raw will be " link".
395 events with an element_name of E or Z
397 While there are Pod codes E<...> and Z<>, these do not produce any
398 E or Z events -- that is, there are no such events as E or Z.
399 events with an element_name of Verbatim
401 When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
402 produces this event structure:
403 <Verbatim start_line="543" xml:space="preserve">
405 ...text...
406 </Verbatim>
407 The value of the start_line attribute will be the line number of
409 the first line of this verbatim block. The xml:space attribute is
410 always present, and always has the value "preserve".
411 The text content will have tabs already expanded.
413 events with an element_name of head1 .. head4
415 When a "=head1 ..." directive is parsed, it produces this event
416 structure:
417 <head1>
419 ...stuff...
420 </head1>
421 For example, a directive consisting of this:
423 =head1 Options to C<new> et al.
425 will produce this event structure:
427 <head1 start_line="543">
429 Options to
430 <C>
431 new
432 </C>
433 et al.
434 </head1>
435 "=head2" through "=head4" directives are the same, except for the
437 element names in the event structure.
438 events with an element_name of encoding
440 In the default case, the events corresponding to "=encoding"
441 directives are not emitted. They are emitted if
442 "keep_encoding_directive" is true. In that case they produce event
443 structures like "events with an element_name of head1 .. head4"
444 above.
445 events with an element_name of over-bullet
447 When an "=over ... =back" block is parsed where the items are a
448 bulleted list, it will produce this event structure:
449 <over-bullet indent="4" start_line="543">
451 <item-bullet start_line="545">
452 ...Stuff...
453 </item-bullet>
454 ...more item-bullets...
455 </over-bullet fake-closer="1">
456 The attribute fake-closer is only present if it is a true value; it
458 is not present if it is a false value. It is shown in the above
459 example to illustrate where the attribute is (in the closing tag).
460 It signifies that the "=over" did not have a matching "=back", and
461 thus Pod::Simple had to create a fake closer.
462 For example, this Pod source:
464 =over
466 =item *
468 Something
470 =back
472 Would produce an event structure that does not have the fake-closer
474 attribute, whereas this Pod source:
475 =over
477 =item *
479 Gasp! An unclosed =over block!
481 would. The rest of the over-* examples will not demonstrate this
483 attribute, but they all can have it. See Pod::Checker's source for
484 an example of this attribute being used.
485 The value of the indent attribute is whatever value is after the
487 "=over" directive, as in "=over 8". If no such value is specified
488 in the directive, then the indent attribute has the value "4".
489 For example, this Pod source:
491 =over
493 =item *
495 Stuff
497 =item *
499 Bar I<baz>!
501 =back
503 produces this event structure:
505 <over-bullet indent="4" start_line="10">
507 <item-bullet start_line="12">
508 Stuff
509 </item-bullet>
510 <item-bullet start_line="14">
511 Bar <I>baz</I>!
512 </item-bullet>
513 </over-bullet>
514 events with an element_name of over-number
516 When an "=over ... =back" block is parsed where the items are a
517 numbered list, it will produce this event structure:
518 <over-number indent="4" start_line="543">
520 <item-number number="1" start_line="545">
521 ...Stuff...
522 </item-number>
523 ...more item-number...
524 </over-bullet>
525 This is like the "over-bullet" event structure; but note that the
527 contents are "item-number" instead of "item-bullet", and note that
528 they will have a "number" attribute, which some
529 formatters/processors may ignore (since, for example, there's no
530 need for it in HTML when producing an "<UL><LI>...</LI>...</UL>"
531 structure), but which any processor may use.
532 Note that the values for the number attributes of "item-number"
534 elements in a given "over-number" area will start at 1 and go up by
535 one each time. If the Pod source doesn't follow that order (even
536 though it really should!), whatever numbers it has will be ignored
537 (with the correct values being put in the number attributes), and
538 an error message might be issued to the user.
539 events with an element_name of over-text
541 These events are somewhat unlike the other over-* structures, as
542 far as what their contents are. When an "=over ... =back" block is
543 parsed where the items are a list of text "subheadings", it will
544 produce this event structure:
545 <over-text indent="4" start_line="543">
547 <item-text>
548 ...stuff...
549 </item-text>
550 ...stuff (generally Para or Verbatim elements)...
551 <item-text>
552 ...more item-text and/or stuff...
553 </over-text>
554 The indent and fake-closer attributes are as with the other over-*
556 events.
557 For example, this Pod source:
559 =over
561 =item Foo
563 Stuff
565 =item Bar I<baz>!
567 Quux
569 =back
571 produces this event structure:
573 <over-text indent="4" start_line="20">
575 <item-text start_line="22">
576 Foo
577 </item-text>
578 <Para start_line="24">
579 Stuff
580 </Para>
581 <item-text start_line="26">
582 Bar
583 <I>
584 baz
585 </I>
586 !
587 </item-text>
588 <Para start_line="28">
589 Quux
590 </Para>
591 </over-text>
592 events with an element_name of over-block
594 These events are somewhat unlike the other over-* structures, as
595 far as what their contents are. When an "=over ... =back" block is
596 parsed where there are no items, it will produce this event
597 structure:
598 <over-block indent="4" start_line="543">
600 ...stuff (generally Para or Verbatim elements)...
601 </over-block>
602 The indent and fake-closer attributes are as with the other over-*
604 events.
605 For example, this Pod source:
607 =over
609 For cutting off our trade with all parts of the world
611 For transporting us beyond seas to be tried for pretended offenses
613 He is at this time transporting large armies of foreign mercenaries to
615 complete the works of death, desolation and tyranny, already begun with
616 circumstances of cruelty and perfidy scarcely paralleled in the most
617 barbarous ages, and totally unworthy the head of a civilized nation.
618 =back
620 will produce this event structure:
622 <over-block indent="4" start_line="2">
624 <Para start_line="4">
625 For cutting off our trade with all parts of the world
626 </Para>
627 <Para start_line="6">
628 For transporting us beyond seas to be tried for pretended offenses
629 </Para>
630 <Para start_line="8">
631 He is at this time transporting large armies of [...more text...]
632 </Para>
633 </over-block>
634 events with an element_name of over-empty
636 Note: These events are only triggered if "parse_empty_lists()" is
637 set to a true value.
638 These events are somewhat unlike the other over-* structures, as
640 far as what their contents are. When an "=over ... =back" block is
641 parsed where there is no content, it will produce this event
642 structure:
643 <over-empty indent="4" start_line="543">
645 </over-empty>
646 The indent and fake-closer attributes are as with the other over-*
648 events.
649 For example, this Pod source:
651 =over
653 =over
655 =back
657 =back
659 will produce this event structure:
661 <over-block indent="4" start_line="1">
663 <over-empty indent="4" start_line="3">
664 </over-empty>
665 </over-block>
666 Note that the outer "=over" is a block because it has no "=item"s
668 but still has content: the inner "=over". The inner "=over", in
669 turn, is completely empty, and is treated as such.
670 events with an element_name of item-bullet
672 See "events with an element_name of over-bullet", above.
673 events with an element_name of item-number
675 See "events with an element_name of over-number", above.
676 events with an element_name of item-text
678 See "events with an element_name of over-text", above.
679 events with an element_name of for
681 TODO...
682 events with an element_name of Data
684 TODO...
685
687 Pod::Simple provides a lot of methods that aren't generally interesting
688 to the end user of an existing Pod formatter, but some of which you
689 might find useful in writing a Pod formatter. They are listed below.
690 The first several methods (the accept_* methods) are for declaring the
691 capabilities of your parser, notably what "=for targetname" sections
692 it's interested in, what extra N<...> codes it accepts beyond the ones
693 described in the perlpod.
694 "$parser->accept_targets( SOMEVALUE )"
696 As the parser sees sections like:
697 =for html <img src="fig1.jpg">
699 or
701 =begin html
703 <img src="fig1.jpg">
705 =end html
707 ...the parser will ignore these sections unless your subclass has
709 specified that it wants to see sections targeted to "html" (or
710 whatever the formatter name is).
711 If you want to process all sections, even if they're not targeted
713 for you, call this before you start parsing:
714 $parser->accept_targets('*');
716 "$parser->accept_targets_as_text( SOMEVALUE )"
718 This is like accept_targets, except that it specifies also that the
719 content of sections for this target should be treated as Pod text
720 even if the target name in "=for targetname" doesn't start with a
721 ":".
722 At time of writing, I don't think you'll need to use this.
724 "$parser->accept_codes( Codename, Codename... )"
726 This tells the parser that you accept additional formatting codes,
727 beyond just the standard ones (I B C L F S X, plus the two weird
728 ones you don't actually see in the parse tree, Z and E). For
729 example, to also accept codes "N", "R", and "W":
730 $parser->accept_codes( qw( N R W ) );
732 TODO: document how this interacts with =extend, and long element
734 names
735 "$parser->accept_directive_as_data( directive_name )"
737 "$parser->accept_directive_as_verbatim( directive_name )"
738 "$parser->accept_directive_as_processed( directive_name )"
739 In the unlikely situation that you need to tell the parser that you
740 will accept additional directives ("=foo" things), you need to
741 first set the parser to treat its content as data (i.e., not really
742 processed at all), or as verbatim (mostly just expanding tabs), or
743 as processed text (parsing formatting codes like B<...>).
744 For example, to accept a new directive "=method", you'd presumably
746 use:
747 $parser->accept_directive_as_processed("method");
749 so that you could have Pod lines like:
751 =method I<$whatever> thing B<um>
753 Making up your own directives breaks compatibility with other Pod
755 formatters, in a way that using "=for target ..." lines doesn't;
756 however, you may find this useful if you're making a Pod superset
757 format where you don't need to worry about compatibility.
758 "$parser->nbsp_for_S( BOOLEAN );"
760 Setting this attribute to a true value (and by default it is false)
761 will turn "S<...>" sequences into sequences of words separated by
762 "\xA0" (non-breaking space) characters. For example, it will take
763 this:
764 I like S<Dutch apple pie>, don't you?
766 and treat it as if it were:
768 I like DutchE<nbsp>appleE<nbsp>pie, don't you?
770 This is handy for output formats that don't have anything quite
772 like an "S<...>" code, but which do have a code for non-breaking
773 space.
774 There is currently no method for going the other way; but I can
776 probably provide one upon request.
777 "$parser->version_report()"
779 This returns a string reporting the $VERSION value from your module
780 (and its classname) as well as the $VERSION value of Pod::Simple.
781 Note that perlpodspec requires output formats (wherever possible)
782 to note this detail in a comment in the output format. For
783 example, for some kind of SGML output format:
784 print OUT "<!-- \n", $parser->version_report, "\n -->";
786 "$parser->pod_para_count()"
788 This returns the count of Pod paragraphs seen so far.
789 "$parser->line_count()"
791 This is the current line number being parsed. But you might find
792 the "line_number" event attribute more accurate, when it is
793 present.
794 "$parser->nix_X_codes( SOMEVALUE )"
796 This attribute, when set to a true value (and it is false by
797 default) ignores any "X<...>" sequences in the document being
798 parsed. Many formats don't actually use the content of these
799 codes, so have no reason to process them.
800 "$parser->keep_encoding_directive( SOMEVALUE )"
802 This attribute, when set to a true value (it is false by default)
803 will keep "=encoding" and its content in the event structure. Most
804 formats don't actually need to process the content of an
805 "=encoding" directive, even when this directive sets the encoding
806 and the processor makes use of the encoding information. Indeed, it
807 is possible to know the encoding without processing the directive
808 content.
809 "$parser->merge_text( SOMEVALUE )"
811 This attribute, when set to a true value (and it is false by
812 default) makes sure that only one event (or token, or node) will be
813 created for any single contiguous sequence of text. For example,
814 consider this somewhat contrived example:
815 I just LOVE Z<>hotE<32>apple pie!
817 When that is parsed and events are about to be called on it, it may
819 actually seem to be four different text events, one right after
820 another: one event for "I just LOVE ", one for "hot", one for " ",
821 and one for "apple pie!". But if you have merge_text on, then
822 you're guaranteed that it will be fired as one text event: "I just
823 LOVE hot apple pie!".
824 "$parser->code_handler( CODE_REF )"
826 This specifies code that should be called when a code line is seen
827 (i.e., a line outside of the Pod). Normally this is undef, meaning
828 that no code should be called. If you provide a routine, it should
829 start out like this:
830 sub get_code_line { # or whatever you'll call it
832 my($line, $line_number, $parser) = @_;
833 ...
834 }
835 Note, however, that sometimes the Pod events aren't processed in
837 exactly the same order as the code lines are -- i.e., if you have a
838 file with Pod, then code, then more Pod, sometimes the code will be
839 processed (via whatever you have code_handler call) before the all
840 of the preceding Pod has been processed.
841 "$parser->cut_handler( CODE_REF )"
843 This is just like the code_handler attribute, except that it's for
844 "=cut" lines, not code lines. The same caveats apply. "=cut" lines
845 are unlikely to be interesting, but this is included for
846 completeness.
847 "$parser->pod_handler( CODE_REF )"
849 This is just like the code_handler attribute, except that it's for
850 "=pod" lines, not code lines. The same caveats apply. "=pod" lines
851 are unlikely to be interesting, but this is included for
852 completeness.
853 "$parser->whiteline_handler( CODE_REF )"
855 This is just like the code_handler attribute, except that it's for
856 lines that are seemingly blank but have whitespace (" " and/or
857 "\t") on them, not code lines. The same caveats apply. These lines
858 are unlikely to be interesting, but this is included for
859 completeness.
860 "$parser->whine( linenumber, complaint string )"
862 This notes a problem in the Pod, which will be reported in the "Pod
863 Errors" section of the document and/or sent to STDERR, depending on
864 the values of the attributes "no_whining", "no_errata_section", and
865 "complain_stderr".
866 "$parser->scream( linenumber, complaint string )"
868 This notes an error like "whine" does, except that it is not
869 suppressible with "no_whining". This should be used only for very
870 serious errors.
871 "$parser->source_dead(1)"
873 This aborts parsing of the current document, by switching on the
874 flag that indicates that EOF has been seen. In particularly
875 drastic cases, you might want to do this. It's rather nicer than
876 just calling "die"!
877 "$parser->hide_line_numbers( SOMEVALUE )"
879 Some subclasses that indiscriminately dump event attributes (well,
880 except for ones beginning with "~") can use this object attribute
881 for refraining to dump the "start_line" attribute.
882 "$parser->no_whining( SOMEVALUE )"
884 This attribute, if set to true, will suppress reports of non-fatal
885 error messages. The default value is false, meaning that
886 complaints are reported. How they get reported depends on the
887 values of the attributes "no_errata_section" and "complain_stderr".
888 "$parser->no_errata_section( SOMEVALUE )"
890 This attribute, if set to true, will suppress generation of an
891 errata section. The default value is false -- i.e., an errata
892 section will be generated.
893 "$parser->complain_stderr( SOMEVALUE )"
895 This attribute, if set to true will send complaints to STDERR. The
896 default value is false -- i.e., complaints do not go to STDERR.
897 "$parser->bare_output( SOMEVALUE )"
899 Some formatter subclasses use this as a flag for whether output
900 should have prologue and epilogue code omitted. For example,
901 setting this to true for an HTML formatter class should omit the
902 "<html><head><title>...</title><body>..." prologue and the
903 "</body></html>" epilogue.
904 If you want to set this to true, you should probably also set
906 "no_whining" or at least "no_errata_section" to true.
907 "$parser->preserve_whitespace( SOMEVALUE )"
909 If you set this attribute to a true value, the parser will try to
910 preserve whitespace in the output. This means that such formatting
911 conventions as two spaces after periods will be preserved by the
912 parser. This is primarily useful for output formats that treat
913 whitespace as significant (such as text or *roff, but not HTML).
914 "$parser->parse_empty_lists( SOMEVALUE )"
916 If this attribute is set to true, the parser will not ignore empty
917 "=over"/"=back" blocks. The type of "=over" will be empty,
918 documented above, "events with an element_name of over-empty".
919
921 Pod::Simple -- event-based Pod-parsing framework
922 Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls
924 its own method (like "start_head3")
925 Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple,
927 but with a token-stream interface
928 Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple,
930 but with a tree interface
931 Pod::Simple::Checker -- a simple Pod::Simple subclass that reads
933 documents, and then makes a plaintext report of any errors found in the
934 document
935 Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented
937 XML, showing each event on its own line
938 Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without
940 introducing extra whitespace as Pod::Simple::DumpAsXML does).
941 Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented
943 text, showing each event on its own line
944 Pod::Simple::LinkSection -- class for objects representing the values
946 of the TODO and TODO attributes of L<...> elements
947 Pod::Escapes -- the module that Pod::Simple uses for evaluating E<...>
949 content
950 Pod::Simple::Text -- a simple plaintext formatter for Pod
952 Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort
954 for indent or wrap the text being formatted
955 Pod::Simple::HTML -- a simple HTML formatter for Pod
957 perlpod
959 perlpodspec
961 perldoc
963
965 Questions or discussion about POD and Pod::Simple should be sent to the
966 pod-people@perl.org mail list. Send an empty email to
967 pod-people-subscribe@perl.org to subscribe.
968 This module is managed in an open GitHub repository,
970 <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
971 contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
972 send patches!
973 Patches against Pod::Simple are welcome. Please send bug reports to
975 <bug-pod-simple@rt.cpan.org>.
976
978 Copyright (c) 2002 Sean M. Burke.
979 This library is free software; you can redistribute it and/or modify it
981 under the same terms as Perl itself.
982 This program is distributed in the hope that it will be useful, but
984 without any warranty; without even the implied warranty of
985 merchantability or fitness for a particular purpose.
986
988 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
989 bother him, he's retired.
990 Pod::Simple is maintained by:
992 · Allison Randal "allison@perl.org"
994 · Hans Dieter Pearcey "hdp@cpan.org"
996 · David E. Wheeler "dwheeler@cpan.org"
998perl v5.26.3 2016-11-29 Pod::Simple::Subclassing(3)