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 notes information on writing a Pod parser (which has been
51 largely taken care of by Pod::Simple), but also a lot of requirements
52 and 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 -- the basic interface via Pod::Simple or Pod::Simple::Methody is
60 event-based, sort of like HTML::Parser's interface, or sort of like
61 XML::Parser's "Handlers" interface), but Pod::Simple::PullParser
62 provides a token-stream interface, sort of like HTML::TokeParser's
63 interface; Pod::Simple::SimpleTree provides a simple tree interface,
64 rather like XML::Parser's "Tree" interface. Users familiar with XML-
65 handling will find one of these styles relatively familiar; but if you
66 would be even more at home with XML, there are classes that produce an
67 XML representation of the Pod stream, notably
68 Pod::Simple::XMLOutStream; you can feed the output of such a class to
69 whatever XML parsing system you are most at home with.
70 The last step is to write your code based on how the events (or tokens,
72 or tree-nodes, or the XML, or however you're parsing) will map to
73 constructs in the output format. Also sure to consider how to escape
74 text nodes containing arbitrary text, and also what to do with text
75 nodes that represent preformatted text (from verbatim sections).
76
78 TODO intro... mention that events are supplied for implicits, like for
79 missing >'s
80 In the following section, we use XML to represent the event structure
82 associated with a particular construct. That is, TODO
83 "$parser->_handle_element_start( element_name, attr_hashref )"
85 "$parser->_handle_element_end( element_name )"
86 "$parser->_handle_text( text_string )"
87 TODO describe
89 events with an element_name of Document
91 Parsing a document produces this event structure:
92 <Document start_line="543">
94 ...all events...
95 </Document>
96 The value of the start_line attribute will be the line number of
98 the first Pod directive in the document.
99 If there is no Pod in the given document, then the event structure
101 will be this:
102 <Document contentless="1" start_line="543">
104 </Document>
105 In that case, the value of the start_line attribute will not be
107 meaningful; under current implementations, it will probably be the
108 line number of the last line in the file.
109 events with an element_name of Para
111 Parsing a plain (non-verbatim, non-directive, non-data) paragraph
112 in a Pod document produces this event structure:
113 <Para start_line="543">
115 ...all events in this paragraph...
116 </Para>
117 The value of the start_line attribute will be the line number of
119 the start of the paragraph.
120 For example, parsing this paragraph of Pod:
122 The value of the I<start_line> attribute will be the
124 line number of the start of the paragraph.
125 produces this event structure:
127 <Para start_line="129">
129 The value of the
130 <I>
131 start_line
132 </I>
133 attribute will be the line number of the first Pod directive
134 in the document.
135 </Para>
136 events with an element_name of B, C, F, or I.
138 Parsing a B<...> formatting code (or of course any of its
139 semantically identical syntactic variants B<< ... >>, or
140 B<<<< ... >>>>, etc.) produces this event structure:
141 <B>
143 ...stuff...
144 </B>
145 Currently, there are no attributes conveyed.
147 Parsing C, F, or I codes produce the same structure, with only a
149 different element name.
150 If your parser object has been set to accept other formatting
152 codes, then they will be presented like these B/C/F/I codes --
153 i.e., without any attributes.
154 events with an element_name of S
156 Normally, parsing an S<...> sequence produces this event structure,
157 just as if it were a B/C/F/I code:
158 <S>
160 ...stuff...
161 </S>
162 However, Pod::Simple (and presumably all derived parsers) offers
164 the "nbsp_for_S" option which, if enabled, will suppress all S
165 events, and instead change all spaces in the content to non-
166 breaking spaces. This is intended for formatters that output to a
167 format that has no code that means the same as S<...>, but which
168 has a code/character that means non-breaking space.
169 events with an element_name of X
171 Normally, parsing an X<...> sequence produces this event structure,
172 just as if it were a B/C/F/I code:
173 <X>
175 ...stuff...
176 </X>
177 However, Pod::Simple (and presumably all derived parsers) offers
179 the "nix_X_codes" option which, if enabled, will suppress all X
180 events and ignore their content. For formatters/processors that
181 don't use X events, this is presumably quite useful.
182 events with an element_name of L
184 Because the L<...> is the most complex construct in the language,
185 it should not surprise you that the events it generates are the
186 most complex in the language. Most of complexity is hidden away in
187 the attribute values, so for those of you writing a Pod formatter
188 that produces a non-hypertextual format, you can just ignore the
189 attributes and treat an L event structure like a formatting element
190 that (presumably) doesn't actually produce a change in formatting.
191 That is, the content of the L event structure (as opposed to its
192 attributes) is always what text should be displayed.
193 There are, at first glance, three kinds of L links: URL, man, and
195 pod.
196 When a L<some_url> code is parsed, it produces this event
198 structure:
199 <L content-implicit="yes" raw="that_url" to="that_url" type="url">
201 that_url
202 </L>
203 The "type="url"" attribute is always specified for this type of L
205 code.
206 For example, this Pod source:
208 L<http://www.perl.com/CPAN/authors/>
210 produces this event structure:
212 <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
214 http://www.perl.com/CPAN/authors/
215 </L>
216 When a L<manpage(section)> code is parsed (and these are fairly
218 rare and not terribly useful), it produces this event structure:
219 <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
221 manpage(section)
222 </L>
223 The "type="man"" attribute is always specified for this type of L
225 code.
226 For example, this Pod source:
228 L<crontab(5)>
230 produces this event structure:
232 <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
234 crontab(5)
235 </L>
236 In the rare cases where a man page link has a specified, that text
238 appears in a section attribute. For example, this Pod source:
239 L<crontab(5)/"ENVIRONMENT">
241 will produce this event structure:
243 <L content-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man">
245 "ENVIRONMENT" in crontab(5)
246 </L>
247 In the rare case where the Pod document has code like
249 L<sometext|manpage(section)>, then the sometext will appear as the
250 content of the element, the manpage(section) text will appear only
251 as the value of the to attribute, and there will be no
252 "content-implicit="yes"" attribute (whose presence means that the
253 Pod parser had to infer what text should appear as the link text --
254 as opposed to cases where that attribute is absent, which means
255 that the Pod parser did not have to infer the link text, because
256 that L code explicitly specified some link text.)
257 For example, this Pod source:
259 L<hell itself!|crontab(5)>
261 will produce this event structure:
263 <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
265 hell itself!
266 </L>
267 The last type of L structure is for links to/within Pod documents.
269 It is the most complex because it can have a to attribute, or a
270 section attribute, or both. The "type="pod"" attribute is always
271 specified for this type of L code.
272 In the most common case, the simple case of a L<podpage> code
274 produces this event structure:
275 <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
277 podpage
278 </L>
279 For example, this Pod source:
281 L<Net::Ping>
283 produces this event structure:
285 <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
287 Net::Ping
288 </L>
289 In cases where there is link-text explicitly specified, it is to be
291 found in the content of the element (and not the attributes), just
292 as with the L<sometext|manpage(section)> case discussed above. For
293 example, this Pod source:
294 L<Perl Error Messages|perldiag>
296 produces this event structure:
298 <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
300 Perl Error Messages
301 </L>
302 In cases of links to a section in the current Pod document, there
304 is a section attribute instead of a to attribute. For example,
305 this Pod source:
306 L</"Member Data">
308 produces this event structure:
310 <L content-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod">
312 "Member Data"
313 </L>
314 As another example, this Pod source:
316 L<the various attributes|/"Member Data">
318 produces this event structure:
320 <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod">
322 the various attributes
323 </L>
324 In cases of links to a section in a different Pod document, there
326 are both a section attribute and a to attribute. For example, this
327 Pod source:
328 L<perlsyn/"Basic BLOCKs and Switch Statements">
330 produces this event structure:
332 <L content-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
334 "Basic BLOCKs and Switch Statements" in perlsyn
335 </L>
336 As another example, this Pod source:
338 L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
340 produces this event structure:
342 <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
344 SWITCH statements
345 </L>
346 Incidentally, note that we do not distinguish between these
348 syntaxes:
349 L</"Member Data">
351 L<"Member Data">
352 L</Member Data>
353 L<Member Data> [deprecated syntax]
354 That is, they all produce the same event structure (for the most
356 part), namely:
357 <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
359 "Member Data"
360 </L>
361 The raw attribute depends on what the raw content of the "L<>" is,
363 so that is why the event structure is the same "for the most part".
364 If you have not guessed it yet, the raw attribute contains the raw,
366 original, unescaped content of the "L<>" formatting code. In
367 addition to the examples above, take notice of the following event
368 structure produced by the following "L<>" formatting code.
369 L<click B<here>|page/About the C<-M> switch>
371 <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
373 click B<here>
374 </L>
375 Specifically, notice that the formatting codes are present and
377 unescaped in raw.
378 There is a known bug in the raw attribute where any surrounding
380 whitespace is condensed into a single ' '. For example, given L<
381 link>, raw will be " link".
382 events with an element_name of E or Z
384 While there are Pod codes E<...> and Z<>, these do not produce any
385 E or Z events -- that is, there are no such events as E or Z.
386 events with an element_name of Verbatim
388 When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
389 produces this event structure:
390 <Verbatim start_line="543" xml:space="preserve">
392 ...text...
393 </Verbatim>
394 The value of the start_line attribute will be the line number of
396 the first line of this verbatim block. The xml:space attribute is
397 always present, and always has the value "preserve".
398 The text content will have tabs already expanded.
400 events with an element_name of head1 .. head4
402 When a "=head1 ..." directive is parsed, it produces this event
403 structure:
404 <head1>
406 ...stuff...
407 </head1>
408 For example, a directive consisting of this:
410 =head1 Options to C<new> et al.
412 will produce this event structure:
414 <head1 start_line="543">
416 Options to
417 <C>
418 new
419 </C>
420 et al.
421 </head1>
422 "=head2" thru "=head4" directives are the same, except for the
424 element names in the event structure.
425 events with an element_name of encoding
427 In the default case, the events corresponding to "=encoding"
428 directives are not emitted. They are emitted if
429 "keep_encoding_directive" is true. In that case they produce event
430 structures like "events with an element_name of head1 .. head4"
431 above.
432 events with an element_name of over-bullet
434 When an "=over ... =back" block is parsed where the items are a
435 bulleted list, it will produce this event structure:
436 <over-bullet indent="4" start_line="543">
438 <item-bullet start_line="545">
439 ...Stuff...
440 </item-bullet>
441 ...more item-bullets...
442 </over-bullet fake-closer="1">
443 The attribute fake-closer is only present if it is a true value; it
445 is not present if it is a false value. It is shown in the above
446 example to illustrate where the attribute is (in the closing tag).
447 It signifies that the "=over" did not have a matching "=back", and
448 thus Pod::Simple had to create a fake closer.
449 For example, this Pod source:
451 =over
453 =item *
455 Something
457 =back
459 Would produce an event structure that does not have the fake-closer
461 attribute, whereas this Pod source:
462 =over
464 =item *
466 Gasp! An unclosed =over block!
468 would. The rest of the over-* examples will not demonstrate this
470 attribute, but they all can have it. See Pod::Checker's source for
471 an example of this attribute being used.
472 The value of the indent attribute is whatever value is after the
474 "=over" directive, as in "=over 8". If no such value is specified
475 in the directive, then the indent attribute has the value "4".
476 For example, this Pod source:
478 =over
480 =item *
482 Stuff
484 =item *
486 Bar I<baz>!
488 =back
490 produces this event structure:
492 <over-bullet indent="4" start_line="10">
494 <item-bullet start_line="12">
495 Stuff
496 </item-bullet>
497 <item-bullet start_line="14">
498 Bar <I>baz</I>!
499 </item-bullet>
500 </over-bullet>
501 events with an element_name of over-number
503 When an "=over ... =back" block is parsed where the items are a
504 numbered list, it will produce this event structure:
505 <over-number indent="4" start_line="543">
507 <item-number number="1" start_line="545">
508 ...Stuff...
509 </item-number>
510 ...more item-number...
511 </over-bullet>
512 This is like the "over-bullet" event structure; but note that the
514 contents are "item-number" instead of "item-bullet", and note that
515 they will have a "number" attribute, which some
516 formatters/processors may ignore (since, for example, there's no
517 need for it in HTML when producing an "<UL><LI>...</LI>...</UL>"
518 structure), but which any processor may use.
519 Note that the values for the number attributes of "item-number"
521 elements in a given "over-number" area will start at 1 and go up by
522 one each time. If the Pod source doesn't follow that order (even
523 though it really should should!), whatever numbers it has will be
524 ignored (with the correct values being put in the number
525 attributes), and an error message might be issued to the user.
526 events with an element_name of over-text
528 These events are somewhat unlike the other over-* structures, as
529 far as what their contents are. When an "=over ... =back" block is
530 parsed where the items are a list of text "subheadings", it will
531 produce this event structure:
532 <over-text indent="4" start_line="543">
534 <item-text>
535 ...stuff...
536 </item-text>
537 ...stuff (generally Para or Verbatim elements)...
538 <item-text>
539 ...more item-text and/or stuff...
540 </over-text>
541 The indent and fake-closer attributes are as with the other over-*
543 events.
544 For example, this Pod source:
546 =over
548 =item Foo
550 Stuff
552 =item Bar I<baz>!
554 Quux
556 =back
558 produces this event structure:
560 <over-text indent="4" start_line="20">
562 <item-text start_line="22">
563 Foo
564 </item-text>
565 <Para start_line="24">
566 Stuff
567 </Para>
568 <item-text start_line="26">
569 Bar
570 <I>
571 baz
572 </I>
573 !
574 </item-text>
575 <Para start_line="28">
576 Quux
577 </Para>
578 </over-text>
579 events with an element_name of over-block
581 These events are somewhat unlike the other over-* structures, as
582 far as what their contents are. When an "=over ... =back" block is
583 parsed where there are no items, it will produce this event
584 structure:
585 <over-block indent="4" start_line="543">
587 ...stuff (generally Para or Verbatim elements)...
588 </over-block>
589 The indent and fake-closer attributes are as with the other over-*
591 events.
592 For example, this Pod source:
594 =over
596 For cutting off our trade with all parts of the world
598 For transporting us beyond seas to be tried for pretended offenses
600 He is at this time transporting large armies of foreign mercenaries to
602 complete the works of death, desolation and tyranny, already begun with
603 circumstances of cruelty and perfidy scarcely paralleled in the most
604 barbarous ages, and totally unworthy the head of a civilized nation.
605 =back
607 will produce this event structure:
609 <over-block indent="4" start_line="2">
611 <Para start_line="4">
612 For cutting off our trade with all parts of the world
613 </Para>
614 <Para start_line="6">
615 For transporting us beyond seas to be tried for pretended offenses
616 </Para>
617 <Para start_line="8">
618 He is at this time transporting large armies of [...more text...]
619 </Para>
620 </over-block>
621 events with an element_name of over-empty
623 Note: These events are only triggered if "parse_empty_lists()" is
624 set to a true value.
625 These events are somewhat unlike the other over-* structures, as
627 far as what their contents are. When an "=over ... =back" block is
628 parsed where there is no content, it will produce this event
629 structure:
630 <over-empty indent="4" start_line="543">
632 </over-empty>
633 The indent and fake-closer attributes are as with the other over-*
635 events.
636 For example, this Pod source:
638 =over
640 =over
642 =back
644 =back
646 will produce this event structure:
648 <over-block indent="4" start_line="1">
650 <over-empty indent="4" start_line="3">
651 </over-empty>
652 </over-block>
653 Note that the outer "=over" is a block because it has no "=item"s
655 but still has content: the inner "=over". The inner "=over", in
656 turn, is completely empty, and is treated as such.
657 events with an element_name of item-bullet
659 See "events with an element_name of over-bullet", above.
660 events with an element_name of item-number
662 See "events with an element_name of over-number", above.
663 events with an element_name of item-text
665 See "events with an element_name of over-text", above.
666 events with an element_name of for
668 TODO...
669 events with an element_name of Data
671 TODO...
672
674 Pod::Simple provides a lot of methods that aren't generally interesting
675 to the end user of an existing Pod formatter, but some of which you
676 might find useful in writing a Pod formatter. They are listed below.
677 The first several methods (the accept_* methods) are for declaring the
678 capabilities of your parser, notably what "=for targetname" sections
679 it's interested in, what extra N<...> codes it accepts beyond the ones
680 described in the perlpod.
681 "$parser->accept_targets( SOMEVALUE )"
683 As the parser sees sections like:
684 =for html <img src="fig1.jpg">
686 or
688 =begin html
690 <img src="fig1.jpg">
692 =end html
694 ...the parser will ignore these sections unless your subclass has
696 specified that it wants to see sections targeted to "html" (or
697 whatever the formatter name is).
698 If you want to process all sections, even if they're not targeted
700 for you, call this before you start parsing:
701 $parser->accept_targets('*');
703 "$parser->accept_targets_as_text( SOMEVALUE )"
705 This is like accept_targets, except that it specifies also that the
706 content of sections for this target should be treated as Pod text
707 even if the target name in "=for targetname" doesn't start with a
708 ":".
709 At time of writing, I don't think you'll need to use this.
711 "$parser->accept_codes( Codename, Codename... )"
713 This tells the parser that you accept additional formatting codes,
714 beyond just the standard ones (I B C L F S X, plus the two weird
715 ones you don't actually see in the parse tree, Z and E). For
716 example, to also accept codes "N", "R", and "W":
717 $parser->accept_codes( qw( N R W ) );
719 TODO: document how this interacts with =extend, and long element
721 names
722 "$parser->accept_directive_as_data( directive_name )"
724 "$parser->accept_directive_as_verbatim( directive_name )"
725 "$parser->accept_directive_as_processed( directive_name )"
726 In the unlikely situation that you need to tell the parser that you
727 will accept additional directives ("=foo" things), you need to
728 first set the parser to treat its content as data (i.e., not really
729 processed at all), or as verbatim (mostly just expanding tabs), or
730 as processed text (parsing formatting codes like B<...>).
731 For example, to accept a new directive "=method", you'd presumably
733 use:
734 $parser->accept_directive_as_processed("method");
736 so that you could have Pod lines like:
738 =method I<$whatever> thing B<um>
740 Making up your own directives breaks compatibility with other Pod
742 formatters, in a way that using "=for target ..." lines doesn't;
743 however, you may find this useful if you're making a Pod superset
744 format where you don't need to worry about compatibility.
745 "$parser->nbsp_for_S( BOOLEAN );"
747 Setting this attribute to a true value (and by default it is false)
748 will turn "S<...>" sequences into sequences of words separated by
749 "\xA0" (non-breaking space) characters. For example, it will take
750 this:
751 I like S<Dutch apple pie>, don't you?
753 and treat it as if it were:
755 I like DutchE<nbsp>appleE<nbsp>pie, don't you?
757 This is handy for output formats that don't have anything quite
759 like an "S<...>" code, but which do have a code for non-breaking
760 space.
761 There is currently no method for going the other way; but I can
763 probably provide one upon request.
764 "$parser->version_report()"
766 This returns a string reporting the $VERSION value from your module
767 (and its classname) as well as the $VERSION value of Pod::Simple.
768 Note that perlpodspec requires output formats (wherever possible)
769 to note this detail in a comment in the output format. For
770 example, for some kind of SGML output format:
771 print OUT "<!-- \n", $parser->version_report, "\n -->";
773 "$parser->pod_para_count()"
775 This returns the count of Pod paragraphs seen so far.
776 "$parser->line_count()"
778 This is the current line number being parsed. But you might find
779 the "line_number" event attribute more accurate, when it is
780 present.
781 "$parser->nix_X_codes( SOMEVALUE )"
783 This attribute, when set to a true value (and it is false by
784 default) ignores any "X<...>" sequences in the document being
785 parsed. Many formats don't actually use the content of these
786 codes, so have no reason to process them.
787 "$parser->keep_encoding_directive( SOMEVALUE )"
789 This attribute, when set to a true value (it is false by default)
790 will keep "=encoding" and its content in the event structure. Most
791 formats don't actually need to process the content of an
792 "=encoding" directive, even when this directive sets the encoding
793 and the processor makes use of the encoding information. Indeed, it
794 is possible to know the encoding without processing the directive
795 content.
796 "$parser->merge_text( SOMEVALUE )"
798 This attribute, when set to a true value (and it is false by
799 default) makes sure that only one event (or token, or node) will be
800 created for any single contiguous sequence of text. For example,
801 consider this somewhat contrived example:
802 I just LOVE Z<>hotE<32>apple pie!
804 When that is parsed and events are about to be called on it, it may
806 actually seem to be four different text events, one right after
807 another: one event for "I just LOVE ", one for "hot", one for " ",
808 and one for "apple pie!". But if you have merge_text on, then
809 you're guaranteed that it will be fired as one text event: "I just
810 LOVE hot apple pie!".
811 "$parser->code_handler( CODE_REF )"
813 This specifies code that should be called when a code line is seen
814 (i.e., a line outside of the Pod). Normally this is undef, meaning
815 that no code should be called. If you provide a routine, it should
816 start out like this:
817 sub get_code_line { # or whatever you'll call it
819 my($line, $line_number, $parser) = @_;
820 ...
821 }
822 Note, however, that sometimes the Pod events aren't processed in
824 exactly the same order as the code lines are -- i.e., if you have a
825 file with Pod, then code, then more Pod, sometimes the code will be
826 processed (via whatever you have code_handler call) before the all
827 of the preceding Pod has been processed.
828 "$parser->cut_handler( CODE_REF )"
830 This is just like the code_handler attribute, except that it's for
831 "=cut" lines, not code lines. The same caveats apply. "=cut" lines
832 are unlikely to be interesting, but this is included for
833 completeness.
834 "$parser->pod_handler( CODE_REF )"
836 This is just like the code_handler attribute, except that it's for
837 "=pod" lines, not code lines. The same caveats apply. "=pod" lines
838 are unlikely to be interesting, but this is included for
839 completeness.
840 "$parser->whiteline_handler( CODE_REF )"
842 This is just like the code_handler attribute, except that it's for
843 lines that are seemingly blank but have whitespace (" " and/or
844 "\t") on them, not code lines. The same caveats apply. These lines
845 are unlikely to be interesting, but this is included for
846 completeness.
847 "$parser->whine( linenumber, complaint string )"
849 This notes a problem in the Pod, which will be reported to in the
850 "Pod Errors" section of the document and/or send to STDERR,
851 depending on the values of the attributes "no_whining",
852 "no_errata_section", and "complain_stderr".
853 "$parser->scream( linenumber, complaint string )"
855 This notes an error like "whine" does, except that it is not
856 suppressible with "no_whining". This should be used only for very
857 serious errors.
858 "$parser->source_dead(1)"
860 This aborts parsing of the current document, by switching on the
861 flag that indicates that EOF has been seen. In particularly
862 drastic cases, you might want to do this. It's rather nicer than
863 just calling "die"!
864 "$parser->hide_line_numbers( SOMEVALUE )"
866 Some subclasses that indiscriminately dump event attributes (well,
867 except for ones beginning with "~") can use this object attribute
868 for refraining to dump the "start_line" attribute.
869 "$parser->no_whining( SOMEVALUE )"
871 This attribute, if set to true, will suppress reports of non-fatal
872 error messages. The default value is false, meaning that
873 complaints are reported. How they get reported depends on the
874 values of the attributes "no_errata_section" and "complain_stderr".
875 "$parser->no_errata_section( SOMEVALUE )"
877 This attribute, if set to true, will suppress generation of an
878 errata section. The default value is false -- i.e., an errata
879 section will be generated.
880 "$parser->complain_stderr( SOMEVALUE )"
882 This attribute, if set to true will send complaints to STDERR. The
883 default value is false -- i.e., complaints do not go to STDERR.
884 "$parser->bare_output( SOMEVALUE )"
886 Some formatter subclasses use this as a flag for whether output
887 should have prologue and epilogue code omitted. For example,
888 setting this to true for an HTML formatter class should omit the
889 "<html><head><title>...</title><body>..." prologue and the
890 "</body></html>" epilogue.
891 If you want to set this to true, you should probably also set
893 "no_whining" or at least "no_errata_section" to true.
894 "$parser->preserve_whitespace( SOMEVALUE )"
896 If you set this attribute to a true value, the parser will try to
897 preserve whitespace in the output. This means that such formatting
898 conventions as two spaces after periods will be preserved by the
899 parser. This is primarily useful for output formats that treat
900 whitespace as significant (such as text or *roff, but not HTML).
901 "$parser->parse_empty_lists( SOMEVALUE )"
903 If this attribute is set to true, the parser will not ignore empty
904 "=over"/"=back" blocks. The type of "=over" will be empty,
905 documented above, "events with an element_name of over-empty".
906
908 Pod::Simple -- event-based Pod-parsing framework
909 Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls
911 its own method (like "start_head3")
912 Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple,
914 but with a token-stream interface
915 Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple,
917 but with a tree interface
918 Pod::Simple::Checker -- a simple Pod::Simple subclass that reads
920 documents, and then makes a plaintext report of any errors found in the
921 document
922 Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented
924 XML, showing each event on its own line
925 Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without
927 introducing extra whitespace as Pod::Simple::DumpAsXML does).
928 Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented
930 text, showing each event on its own line
931 Pod::Simple::LinkSection -- class for objects representing the values
933 of the TODO and TODO attributes of L<...> elements
934 Pod::Escapes -- the module the Pod::Simple uses for evaluating E<...>
936 content
937 Pod::Simple::Text -- a simple plaintext formatter for Pod
939 Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort
941 for indent or wrap the text being formatted
942 Pod::Simple::HTML -- a simple HTML formatter for Pod
944 perlpod
946 perlpodspec
948 perldoc
950
952 Questions or discussion about POD and Pod::Simple should be sent to the
953 pod-people@perl.org mail list. Send an empty email to
954 pod-people-subscribe@perl.org to subscribe.
955 This module is managed in an open GitHub repository,
957 <https://github.com/theory/pod-simple/>. Feel free to fork and
958 contribute, or to clone <git://github.com/theory/pod-simple.git> and
959 send patches!
960 Patches against Pod::Simple are welcome. Please send bug reports to
962 <bug-pod-simple@rt.cpan.org>.
963
965 Copyright (c) 2002 Sean M. Burke.
966 This library is free software; you can redistribute it and/or modify it
968 under the same terms as Perl itself.
969 This program is distributed in the hope that it will be useful, but
971 without any warranty; without even the implied warranty of
972 merchantability or fitness for a particular purpose.
973
975 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
976 bother him, he's retired.
977 Pod::Simple is maintained by:
979 · Allison Randal "allison@perl.org"
981 · Hans Dieter Pearcey "hdp@cpan.org"
983 · David E. Wheeler "dwheeler@cpan.org"
985perl v5.16.3 2013-05-03 Pod::Simple::Subclassing(3)