1Pod::Simple::SubclassinUgs(e3r)Contributed Perl DocumentPaotdi:o:nSimple::Subclassing(3)
2
3
4

NAME

6       Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
7

SYNOPSIS

9         package Pod::SomeFormatter;
10         use Pod::Simple;
11         @ISA = qw(Pod::Simple);
12         $VERSION = '1.01';
13         use strict;
14
15         sub _handle_element_start {
16               my($parser, $element_name, $attr_hash_r) = @_;
17               ...
18         }
19
20         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
29         sub _handle_text {
30               my($parser, $text) = @_;
31               ...
32         }
33         1;
34

DESCRIPTION

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
41       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
49       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
54       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
58       The third step is to pick which of Pod::Simple's interfaces you want to
59       use:
60
61       Pod::Simple
62           The basic Pod::Simple interface that uses
63           "_handle_element_start()", "_handle_element_end()" and
64           "_handle_text()".
65
66       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
70       Pod::Simple::PullParser
71           Pod::Simple::PullParser provides a token-stream interface, sort of
72           like HTML::TokeParser's interface.
73
74       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
83       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

Events

90       TODO intro... mention that events are supplied for implicits, like for
91       missing >'s
92
93       In the following section, we use XML to represent the event structure
94       associated with a particular construct.  That is, TODO
95
96       "$parser->_handle_element_start( element_name, attr_hashref )"
97       "$parser->_handle_element_end( element_name  )"
98       "$parser->_handle_text(  text_string  )"
99
100       TODO describe
101
102       events with an element_name of Document
103           Parsing a document produces this event structure:
104
105             <Document start_line="543">
106                   ...all events...
107             </Document>
108
109           The value of the start_line attribute will be the line number of
110           the first Pod directive in the document.
111
112           If there is no Pod in the given document, then the event structure
113           will be this:
114
115             <Document contentless="1" start_line="543">
116             </Document>
117
118           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
122       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
126                   <Para start_line="543">
127                     ...all events in this paragraph...
128                   </Para>
129
130           The value of the start_line attribute will be the line number of
131           the start of the paragraph.
132
133           For example, parsing this paragraph of Pod:
134
135             The value of the I<start_line> attribute will be the
136             line number of the start of the paragraph.
137
138           produces this event structure:
139
140                   <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
149       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
154                     <B>
155                           ...stuff...
156                     </B>
157
158           Currently, there are no attributes conveyed.
159
160           Parsing C, F, or I codes produce the same structure, with only a
161           different element name.
162
163           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
167       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
171                     <S>
172                           ...stuff...
173                     </S>
174
175           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
182       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
186                     <X>
187                           ...stuff...
188                     </X>
189
190           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
195       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
206           There are, at first glance, three kinds of L links: URL, man, and
207           pod.
208
209           When a L<some_url> code is parsed, it produces this event
210           structure:
211
212             <L content-implicit="yes" raw="that_url" to="that_url" type="url">
213                   that_url
214             </L>
215
216           The "type="url"" attribute is always specified for this type of L
217           code.
218
219           For example, this Pod source:
220
221             L<http://www.perl.com/CPAN/authors/>
222
223           produces this event structure:
224
225             <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
229           When a L<manpage(section)> code is parsed (and these are fairly
230           rare and not terribly useful), it produces this event structure:
231
232             <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
233                   manpage(section)
234             </L>
235
236           The "type="man"" attribute is always specified for this type of L
237           code.
238
239           For example, this Pod source:
240
241             L<crontab(5)>
242
243           produces this event structure:
244
245             <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
246                   crontab(5)
247             </L>
248
249           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
253             L<crontab(5)/"ENVIRONMENT">
254
255           will produce this event structure:
256
257             <L content-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
258                   "ENVIRONMENT" in crontab(5)
259             </L>
260
261           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
271           For example, this Pod source:
272
273             L<hell itself!|crontab(5)>
274
275           will produce this event structure:
276
277             <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
278                   hell itself!
279             </L>
280
281           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
286           In the most common case, the simple case of a L<podpage> code
287           produces this event structure:
288
289             <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
290                   podpage
291             </L>
292
293           For example, this Pod source:
294
295             L<Net::Ping>
296
297           produces this event structure:
298
299             <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
300                   Net::Ping
301             </L>
302
303           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
308             L<Perl Error Messages|perldiag>
309
310           produces this event structure:
311
312             <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
313                   Perl Error Messages
314             </L>
315
316           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
320             L</"Member Data">
321
322           produces this event structure:
323
324             <L content-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
325                   "Member Data"
326             </L>
327
328           As another example, this Pod source:
329
330             L<the various attributes|/"Member Data">
331
332           produces this event structure:
333
334             <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
335                   the various attributes
336             </L>
337
338           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
342             L<perlsyn/"Basic BLOCKs and Switch Statements">
343
344           produces this event structure:
345
346             <L content-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
347                   "Basic BLOCKs and Switch Statements" in perlsyn
348             </L>
349
350           As another example, this Pod source:
351
352             L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
353
354           produces this event structure:
355
356             <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
357                   SWITCH statements
358             </L>
359
360           Incidentally, note that we do not distinguish between these
361           syntaxes:
362
363             L</"Member Data">
364             L<"Member Data">
365             L</Member Data>
366             L<Member Data>    [deprecated syntax]
367
368           That is, they all produce the same event structure (for the most
369           part), namely:
370
371             <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
372                   &#34;Member Data&#34;
373             </L>
374
375           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
378           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
383             L<click B<here>|page/About the C<-M> switch>
384
385             <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
389           Specifically, notice that the formatting codes are present and
390           unescaped in raw.
391
392           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
396       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
400       events with an element_name of Verbatim
401           When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
402           produces this event structure:
403
404             <Verbatim start_line="543" xml:space="preserve">
405                   ...text...
406             </Verbatim>
407
408           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
412           The text content will have tabs already expanded.
413
414       events with an element_name of head1 .. head4
415           When a "=head1 ..." directive is parsed, it produces this event
416           structure:
417
418             <head1>
419                   ...stuff...
420             </head1>
421
422           For example, a directive consisting of this:
423
424             =head1 Options to C<new> et al.
425
426           will produce this event structure:
427
428             <head1 start_line="543">
429                   Options to
430                   <C>
431                     new
432                   </C>
433                    et al.
434             </head1>
435
436           "=head2" through "=head4" directives are the same, except for the
437           element names in the event structure.
438
439       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
446       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
450             <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
457           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
463           For example, this Pod source:
464
465             =over
466
467             =item *
468
469             Something
470
471             =back
472
473           Would produce an event structure that does not have the fake-closer
474           attribute, whereas this Pod source:
475
476             =over
477
478             =item *
479
480             Gasp! An unclosed =over block!
481
482           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
486           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
490           For example, this Pod source:
491
492             =over
493
494             =item *
495
496             Stuff
497
498             =item *
499
500             Bar I<baz>!
501
502             =back
503
504           produces this event structure:
505
506             <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
515       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
519             <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
526           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
533           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
540       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
546             <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
555           The indent and fake-closer attributes are as with the other over-*
556           events.
557
558           For example, this Pod source:
559
560             =over
561
562             =item Foo
563
564             Stuff
565
566             =item Bar I<baz>!
567
568             Quux
569
570             =back
571
572           produces this event structure:
573
574             <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
593       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
599             <over-block indent="4" start_line="543">
600                   ...stuff (generally Para or Verbatim elements)...
601             </over-block>
602
603           The indent and fake-closer attributes are as with the other over-*
604           events.
605
606           For example, this Pod source:
607
608             =over
609
610             For cutting off our trade with all parts of the world
611
612             For transporting us beyond seas to be tried for pretended offenses
613
614             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
619             =back
620
621           will produce this event structure:
622
623             <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
635       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
639           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
644             <over-empty indent="4" start_line="543">
645             </over-empty>
646
647           The indent and fake-closer attributes are as with the other over-*
648           events.
649
650           For example, this Pod source:
651
652             =over
653
654             =over
655
656             =back
657
658             =back
659
660           will produce this event structure:
661
662             <over-block indent="4" start_line="1">
663                   <over-empty indent="4" start_line="3">
664                   </over-empty>
665             </over-block>
666
667           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
671       events with an element_name of item-bullet
672           See "events with an element_name of over-bullet", above.
673
674       events with an element_name of item-number
675           See "events with an element_name of over-number", above.
676
677       events with an element_name of item-text
678           See "events with an element_name of over-text", above.
679
680       events with an element_name of for
681           TODO...
682
683       events with an element_name of Data
684           TODO...
685

More Pod::Simple Methods

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
695       "$parser->accept_targets( SOMEVALUE )"
696           As the parser sees sections like:
697
698                   =for html  <img src="fig1.jpg">
699
700           or
701
702                   =begin html
703
704                     <img src="fig1.jpg">
705
706                   =end html
707
708           ...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
712           If you want to process all sections, even if they're not targeted
713           for you, call this before you start parsing:
714
715             $parser->accept_targets('*');
716
717       "$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
723           At time of writing, I don't think you'll need to use this.
724
725       "$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
731                   $parser->accept_codes( qw( N R W ) );
732
733           TODO: document how this interacts with =extend, and long element
734           names
735
736       "$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
745           For example, to accept a new directive "=method", you'd presumably
746           use:
747
748                   $parser->accept_directive_as_processed("method");
749
750           so that you could have Pod lines like:
751
752                   =method I<$whatever> thing B<um>
753
754           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
759       "$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
765                   I like S<Dutch apple pie>, don't you?
766
767           and treat it as if it were:
768
769                   I like DutchE<nbsp>appleE<nbsp>pie, don't you?
770
771           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
775           There is currently no method for going the other way; but I can
776           probably provide one upon request.
777
778       "$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
785                   print OUT "<!-- \n", $parser->version_report, "\n -->";
786
787       "$parser->pod_para_count()"
788           This returns the count of Pod paragraphs seen so far.
789
790       "$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
795       "$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
801       "$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
810       "$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
816                   I just LOVE Z<>hotE<32>apple pie!
817
818           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
825       "$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
831                   sub get_code_line {  # or whatever you'll call it
832                     my($line, $line_number, $parser) = @_;
833                     ...
834                   }
835
836           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
842       "$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
848       "$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
854       "$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
861       "$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
867       "$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
872       "$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
878       "$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
883       "$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
889       "$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
894       "$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
898       "$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
905           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
908       "$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
915       "$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

SEE ALSO

921       Pod::Simple -- event-based Pod-parsing framework
922
923       Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls
924       its own method (like "start_head3")
925
926       Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple,
927       but with a token-stream interface
928
929       Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple,
930       but with a tree interface
931
932       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
936       Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented
937       XML, showing each event on its own line
938
939       Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without
940       introducing extra whitespace as Pod::Simple::DumpAsXML does).
941
942       Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented
943       text, showing each event on its own line
944
945       Pod::Simple::LinkSection -- class for objects representing the values
946       of the TODO and TODO attributes of L<...> elements
947
948       Pod::Escapes -- the module that Pod::Simple uses for evaluating E<...>
949       content
950
951       Pod::Simple::Text -- a simple plaintext formatter for Pod
952
953       Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort
954       for indent or wrap the text being formatted
955
956       Pod::Simple::HTML -- a simple HTML formatter for Pod
957
958       perlpod
959
960       perlpodspec
961
962       perldoc
963

SUPPORT

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
969       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
974       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
980       This library is free software; you can redistribute it and/or modify it
981       under the same terms as Perl itself.
982
983       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

AUTHOR

988       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
989       bother him, he's retired.
990
991       Pod::Simple is maintained by:
992
993       ·   Allison Randal "allison@perl.org"
994
995       ·   Hans Dieter Pearcey "hdp@cpan.org"
996
997       ·   David E. Wheeler "dwheeler@cpan.org"
998
999
1000
1001perl v5.28.0                      2016-11-29       Pod::Simple::Subclassing(3)
Impressum