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, an opening tag
95       represents the element start, the attributes of that opening tag are
96       the attributes given to the callback, and the closing tag represents
97       the end element.
98
99       Three callback methods must be supplied by a class extending
100       Pod::Simple to receive the corresponding event:
101
102       "$parser->_handle_element_start( element_name, attr_hashref )"
103       "$parser->_handle_element_end( element_name  )"
104       "$parser->_handle_text(  text_string  )"
105
106       Here's the comprehensive list of values you can expect as element_name
107       in your implementation of "_handle_element_start" and
108       "_handle_element_end"::
109
110       events with an element_name of Document
111           Parsing a document produces this event structure:
112
113             <Document start_line="543">
114                   ...all events...
115             </Document>
116
117           The value of the start_line attribute will be the line number of
118           the first Pod directive in the document.
119
120           If there is no Pod in the given document, then the event structure
121           will be this:
122
123             <Document contentless="1" start_line="543">
124             </Document>
125
126           In that case, the value of the start_line attribute will not be
127           meaningful; under current implementations, it will probably be the
128           line number of the last line in the file.
129
130       events with an element_name of Para
131           Parsing a plain (non-verbatim, non-directive, non-data) paragraph
132           in a Pod document produces this event structure:
133
134                   <Para start_line="543">
135                     ...all events in this paragraph...
136                   </Para>
137
138           The value of the start_line attribute will be the line number of
139           the start of the paragraph.
140
141           For example, parsing this paragraph of Pod:
142
143             The value of the I<start_line> attribute will be the
144             line number of the start of the paragraph.
145
146           produces this event structure:
147
148                   <Para start_line="129">
149                     The value of the
150                     <I>
151                           start_line
152                     </I>
153                      attribute will be the line number of the first Pod directive
154                     in the document.
155                   </Para>
156
157       events with an element_name of B, C, F, or I.
158           Parsing a B<...> formatting code (or of course any of its
159           semantically identical syntactic variants B<< ... >>, or
160           B<<<< ... >>>>, etc.)  produces this event structure:
161
162                     <B>
163                           ...stuff...
164                     </B>
165
166           Currently, there are no attributes conveyed.
167
168           Parsing C, F, or I codes produce the same structure, with only a
169           different element name.
170
171           If your parser object has been set to accept other formatting
172           codes, then they will be presented like these B/C/F/I codes --
173           i.e., without any attributes.
174
175       events with an element_name of S
176           Normally, parsing an S<...> sequence produces this event structure,
177           just as if it were a B/C/F/I code:
178
179                     <S>
180                           ...stuff...
181                     </S>
182
183           However, Pod::Simple (and presumably all derived parsers) offers
184           the "nbsp_for_S" option which, if enabled, will suppress all S
185           events, and instead change all spaces in the content to non-
186           breaking spaces. This is intended for formatters that output to a
187           format that has no code that means the same as S<...>, but which
188           has a code/character that means non-breaking space.
189
190       events with an element_name of X
191           Normally, parsing an X<...> sequence produces this event structure,
192           just as if it were a B/C/F/I code:
193
194                     <X>
195                           ...stuff...
196                     </X>
197
198           However, Pod::Simple (and presumably all derived parsers) offers
199           the "nix_X_codes" option which, if enabled, will suppress all X
200           events and ignore their content.  For formatters/processors that
201           don't use X events, this is presumably quite useful.
202
203       events with an element_name of L
204           Because the L<...> is the most complex construct in the language,
205           it should not surprise you that the events it generates are the
206           most complex in the language. Most of complexity is hidden away in
207           the attribute values, so for those of you writing a Pod formatter
208           that produces a non-hypertextual format, you can just ignore the
209           attributes and treat an L event structure like a formatting element
210           that (presumably) doesn't actually produce a change in formatting.
211           That is, the content of the L event structure (as opposed to its
212           attributes) is always what text should be displayed.
213
214           There are, at first glance, three kinds of L links: URL, man, and
215           pod.
216
217           When a L<some_url> code is parsed, it produces this event
218           structure:
219
220             <L content-implicit="yes" raw="that_url" to="that_url" type="url">
221                   that_url
222             </L>
223
224           The "type="url"" attribute is always specified for this type of L
225           code.
226
227           For example, this Pod source:
228
229             L<http://www.perl.com/CPAN/authors/>
230
231           produces this event structure:
232
233             <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
234                   http://www.perl.com/CPAN/authors/
235             </L>
236
237           When a L<manpage(section)> code is parsed (and these are fairly
238           rare and not terribly useful), it produces this event structure:
239
240             <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
241                   manpage(section)
242             </L>
243
244           The "type="man"" attribute is always specified for this type of L
245           code.
246
247           For example, this Pod source:
248
249             L<crontab(5)>
250
251           produces this event structure:
252
253             <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
254                   crontab(5)
255             </L>
256
257           In the rare cases where a man page link has a section specified,
258           that text appears in a section attribute. For example, this Pod
259           source:
260
261             L<crontab(5)/"ENVIRONMENT">
262
263           will produce this event structure:
264
265             <L content-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
266                   "ENVIRONMENT" in crontab(5)
267             </L>
268
269           In the rare case where the Pod document has code like
270           L<sometext|manpage(section)>, then the sometext will appear as the
271           content of the element, the manpage(section) text will appear only
272           as the value of the to attribute, and there will be no
273           "content-implicit="yes"" attribute (whose presence means that the
274           Pod parser had to infer what text should appear as the link text --
275           as opposed to cases where that attribute is absent, which means
276           that the Pod parser did not have to infer the link text, because
277           that L code explicitly specified some link text.)
278
279           For example, this Pod source:
280
281             L<hell itself!|crontab(5)>
282
283           will produce this event structure:
284
285             <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
286                   hell itself!
287             </L>
288
289           The last type of L structure is for links to/within Pod documents.
290           It is the most complex because it can have a to attribute, or a
291           section attribute, or both. The "type="pod"" attribute is always
292           specified for this type of L code.
293
294           In the most common case, the simple case of a L<podpage> code
295           produces this event structure:
296
297             <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
298                   podpage
299             </L>
300
301           For example, this Pod source:
302
303             L<Net::Ping>
304
305           produces this event structure:
306
307             <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
308                   Net::Ping
309             </L>
310
311           In cases where there is link-text explicitly specified, it is to be
312           found in the content of the element (and not the attributes), just
313           as with the L<sometext|manpage(section)> case discussed above.  For
314           example, this Pod source:
315
316             L<Perl Error Messages|perldiag>
317
318           produces this event structure:
319
320             <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
321                   Perl Error Messages
322             </L>
323
324           In cases of links to a section in the current Pod document, there
325           is a section attribute instead of a to attribute.  For example,
326           this Pod source:
327
328             L</"Member Data">
329
330           produces this event structure:
331
332             <L content-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
333                   "Member Data"
334             </L>
335
336           As another example, this Pod source:
337
338             L<the various attributes|/"Member Data">
339
340           produces this event structure:
341
342             <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
343                   the various attributes
344             </L>
345
346           In cases of links to a section in a different Pod document, there
347           are both a section attribute and a to attribute.  For example, this
348           Pod source:
349
350             L<perlsyn/"Basic BLOCKs and Switch Statements">
351
352           produces this event structure:
353
354             <L content-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
355                   "Basic BLOCKs and Switch Statements" in perlsyn
356             </L>
357
358           As another example, this Pod source:
359
360             L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
361
362           produces this event structure:
363
364             <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
365                   SWITCH statements
366             </L>
367
368           Incidentally, note that we do not distinguish between these
369           syntaxes:
370
371             L</"Member Data">
372             L<"Member Data">
373             L</Member Data>
374             L<Member Data>    [deprecated syntax]
375
376           That is, they all produce the same event structure (for the most
377           part), namely:
378
379             <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
380                   &#34;Member Data&#34;
381             </L>
382
383           The raw attribute depends on what the raw content of the "L<>" is,
384           so that is why the event structure is the same "for the most part".
385
386           If you have not guessed it yet, the raw attribute contains the raw,
387           original, unescaped content of the "L<>" formatting code. In
388           addition to the examples above, take notice of the following event
389           structure produced by the following "L<>" formatting code.
390
391             L<click B<here>|page/About the C<-M> switch>
392
393             <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
394                   click B<here>
395             </L>
396
397           Specifically, notice that the formatting codes are present and
398           unescaped in raw.
399
400           There is a known bug in the raw attribute where any surrounding
401           whitespace is condensed into a single ' '. For example, given L<
402           link>, raw will be " link".
403
404       events with an element_name of E or Z
405           While there are Pod codes E<...> and Z<>, these do not produce any
406           E or Z events -- that is, there are no such events as E or Z.
407
408       events with an element_name of Verbatim
409           When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
410           produces this event structure:
411
412             <Verbatim start_line="543" xml:space="preserve">
413                   ...text...
414             </Verbatim>
415
416           The value of the start_line attribute will be the line number of
417           the first line of this verbatim block.  The xml:space attribute is
418           always present, and always has the value "preserve".
419
420           The text content will have tabs already expanded.
421
422       events with an element_name of head1 .. head4
423           When a "=head1 ..." directive is parsed, it produces this event
424           structure:
425
426             <head1>
427                   ...stuff...
428             </head1>
429
430           For example, a directive consisting of this:
431
432             =head1 Options to C<new> et al.
433
434           will produce this event structure:
435
436             <head1 start_line="543">
437                   Options to
438                   <C>
439                     new
440                   </C>
441                    et al.
442             </head1>
443
444           "=head2" through "=head4" directives are the same, except for the
445           element names in the event structure.
446
447       events with an element_name of encoding
448           In the default case, the events corresponding to "=encoding"
449           directives are not emitted. They are emitted if
450           "keep_encoding_directive" is true.  In that case they produce event
451           structures like "events with an element_name of head1 .. head4"
452           above.
453
454       events with an element_name of over-bullet
455           When an "=over ... =back" block is parsed where the items are a
456           bulleted list, it will produce this event structure:
457
458             <over-bullet indent="4" start_line="543">
459                   <item-bullet start_line="545">
460                     ...Stuff...
461                   </item-bullet>
462                   ...more item-bullets...
463             </over-bullet fake-closer="1">
464
465           The attribute fake-closer is only present if it is a true value; it
466           is not present if it is a false value. It is shown in the above
467           example to illustrate where the attribute is (in the closing tag).
468           It signifies that the "=over" did not have a matching "=back", and
469           thus Pod::Simple had to create a fake closer.
470
471           For example, this Pod source:
472
473             =over
474
475             =item *
476
477             Something
478
479             =back
480
481           Would produce an event structure that does not have the fake-closer
482           attribute, whereas this Pod source:
483
484             =over
485
486             =item *
487
488             Gasp! An unclosed =over block!
489
490           would. The rest of the over-* examples will not demonstrate this
491           attribute, but they all can have it. See Pod::Checker's source for
492           an example of this attribute being used.
493
494           The value of the indent attribute is whatever value is after the
495           "=over" directive, as in "=over 8".  If no such value is specified
496           in the directive, then the indent attribute has the value "4".
497
498           For example, this Pod source:
499
500             =over
501
502             =item *
503
504             Stuff
505
506             =item *
507
508             Bar I<baz>!
509
510             =back
511
512           produces this event structure:
513
514             <over-bullet indent="4" start_line="10">
515                   <item-bullet start_line="12">
516                     Stuff
517                   </item-bullet>
518                   <item-bullet start_line="14">
519                     Bar <I>baz</I>!
520                   </item-bullet>
521             </over-bullet>
522
523       events with an element_name of over-number
524           When an "=over ... =back" block is parsed where the items are a
525           numbered list, it will produce this event structure:
526
527             <over-number indent="4" start_line="543">
528                   <item-number number="1" start_line="545">
529                     ...Stuff...
530                   </item-number>
531                   ...more item-number...
532             </over-bullet>
533
534           This is like the "over-bullet" event structure; but note that the
535           contents are "item-number" instead of "item-bullet", and note that
536           they will have a "number" attribute, which some
537           formatters/processors may ignore (since, for example, there's no
538           need for it in HTML when producing an "<UL><LI>...</LI>...</UL>"
539           structure), but which any processor may use.
540
541           Note that the values for the number attributes of "item-number"
542           elements in a given "over-number" area will start at 1 and go up by
543           one each time.  If the Pod source doesn't follow that order (even
544           though it really should!), whatever numbers it has will be ignored
545           (with the correct values being put in the number attributes), and
546           an error message might be issued to the user.
547
548       events with an element_name of over-text
549           These events are somewhat unlike the other over-* structures, as
550           far as what their contents are.  When an "=over ... =back" block is
551           parsed where the items are a list of text "subheadings", it will
552           produce this event structure:
553
554             <over-text indent="4" start_line="543">
555                   <item-text>
556                     ...stuff...
557                   </item-text>
558                   ...stuff (generally Para or Verbatim elements)...
559                   <item-text>
560                   ...more item-text and/or stuff...
561             </over-text>
562
563           The indent and fake-closer attributes are as with the other over-*
564           events.
565
566           For example, this Pod source:
567
568             =over
569
570             =item Foo
571
572             Stuff
573
574             =item Bar I<baz>!
575
576             Quux
577
578             =back
579
580           produces this event structure:
581
582             <over-text indent="4" start_line="20">
583                   <item-text start_line="22">
584                     Foo
585                   </item-text>
586                   <Para start_line="24">
587                     Stuff
588                   </Para>
589                   <item-text start_line="26">
590                     Bar
591                           <I>
592                             baz
593                           </I>
594                     !
595                   </item-text>
596                   <Para start_line="28">
597                     Quux
598                   </Para>
599             </over-text>
600
601       events with an element_name of over-block
602           These events are somewhat unlike the other over-* structures, as
603           far as what their contents are.  When an "=over ... =back" block is
604           parsed where there are no items, it will produce this event
605           structure:
606
607             <over-block indent="4" start_line="543">
608                   ...stuff (generally Para or Verbatim elements)...
609             </over-block>
610
611           The indent and fake-closer attributes are as with the other over-*
612           events.
613
614           For example, this Pod source:
615
616             =over
617
618             For cutting off our trade with all parts of the world
619
620             For transporting us beyond seas to be tried for pretended offenses
621
622             He is at this time transporting large armies of foreign mercenaries to
623             complete the works of death, desolation and tyranny, already begun with
624             circumstances of cruelty and perfidy scarcely paralleled in the most
625             barbarous ages, and totally unworthy the head of a civilized nation.
626
627             =back
628
629           will produce this event structure:
630
631             <over-block indent="4" start_line="2">
632                   <Para start_line="4">
633                     For cutting off our trade with all parts of the world
634                   </Para>
635                   <Para start_line="6">
636                     For transporting us beyond seas to be tried for pretended offenses
637                   </Para>
638                   <Para start_line="8">
639                     He is at this time transporting large armies of [...more text...]
640                   </Para>
641             </over-block>
642
643       events with an element_name of over-empty
644           Note: These events are only triggered if "parse_empty_lists()" is
645           set to a true value.
646
647           These events are somewhat unlike the other over-* structures, as
648           far as what their contents are.  When an "=over ... =back" block is
649           parsed where there is no content, it will produce this event
650           structure:
651
652             <over-empty indent="4" start_line="543">
653             </over-empty>
654
655           The indent and fake-closer attributes are as with the other over-*
656           events.
657
658           For example, this Pod source:
659
660             =over
661
662             =over
663
664             =back
665
666             =back
667
668           will produce this event structure:
669
670             <over-block indent="4" start_line="1">
671                   <over-empty indent="4" start_line="3">
672                   </over-empty>
673             </over-block>
674
675           Note that the outer "=over" is a block because it has no "=item"s
676           but still has content: the inner "=over". The inner "=over", in
677           turn, is completely empty, and is treated as such.
678
679       events with an element_name of item-bullet
680           See "events with an element_name of over-bullet", above.
681
682       events with an element_name of item-number
683           See "events with an element_name of over-number", above.
684
685       events with an element_name of item-text
686           See "events with an element_name of over-text", above.
687
688       events with an element_name of for
689           TODO...
690
691       events with an element_name of Data
692           TODO...
693

More Pod::Simple Methods

695       Pod::Simple provides a lot of methods that aren't generally interesting
696       to the end user of an existing Pod formatter, but some of which you
697       might find useful in writing a Pod formatter. They are listed below.
698       The first several methods (the accept_* methods) are for declaring the
699       capabilities of your parser, notably what "=for targetname" sections
700       it's interested in, what extra N<...> codes it accepts beyond the ones
701       described in the perlpod.
702
703       "$parser->accept_targets( SOMEVALUE )"
704           As the parser sees sections like:
705
706                   =for html  <img src="fig1.jpg">
707
708           or
709
710                   =begin html
711
712                     <img src="fig1.jpg">
713
714                   =end html
715
716           ...the parser will ignore these sections unless your subclass has
717           specified that it wants to see sections targeted to "html" (or
718           whatever the formatter name is).
719
720           If you want to process all sections, even if they're not targeted
721           for you, call this before you start parsing:
722
723             $parser->accept_targets('*');
724
725       "$parser->accept_targets_as_text(  SOMEVALUE  )"
726           This is like accept_targets, except that it specifies also that the
727           content of sections for this target should be treated as Pod text
728           even if the target name in "=for targetname" doesn't start with a
729           ":".
730
731           At time of writing, I don't think you'll need to use this.
732
733       "$parser->accept_codes( Codename, Codename...  )"
734           This tells the parser that you accept additional formatting codes,
735           beyond just the standard ones (I B C L F S X, plus the two weird
736           ones you don't actually see in the parse tree, Z and E). For
737           example, to also accept codes "N", "R", and "W":
738
739                   $parser->accept_codes( qw( N R W ) );
740
741           TODO: document how this interacts with =extend, and long element
742           names
743
744       "$parser->accept_directive_as_data( directive_name )"
745       "$parser->accept_directive_as_verbatim( directive_name )"
746       "$parser->accept_directive_as_processed( directive_name )"
747           In the unlikely situation that you need to tell the parser that you
748           will accept additional directives ("=foo" things), you need to
749           first set the parser to treat its content as data (i.e., not really
750           processed at all), or as verbatim (mostly just expanding tabs), or
751           as processed text (parsing formatting codes like B<...>).
752
753           For example, to accept a new directive "=method", you'd presumably
754           use:
755
756                   $parser->accept_directive_as_processed("method");
757
758           so that you could have Pod lines like:
759
760                   =method I<$whatever> thing B<um>
761
762           Making up your own directives breaks compatibility with other Pod
763           formatters, in a way that using "=for target ..." lines doesn't;
764           however, you may find this useful if you're making a Pod superset
765           format where you don't need to worry about compatibility.
766
767       "$parser->nbsp_for_S( BOOLEAN );"
768           Setting this attribute to a true value (and by default it is false)
769           will turn "S<...>" sequences into sequences of words separated by
770           "\xA0" (non-breaking space) characters. For example, it will take
771           this:
772
773                   I like S<Dutch apple pie>, don't you?
774
775           and treat it as if it were:
776
777                   I like DutchE<nbsp>appleE<nbsp>pie, don't you?
778
779           This is handy for output formats that don't have anything quite
780           like an "S<...>" code, but which do have a code for non-breaking
781           space.
782
783           There is currently no method for going the other way; but I can
784           probably provide one upon request.
785
786       "$parser->version_report()"
787           This returns a string reporting the $VERSION value from your module
788           (and its classname) as well as the $VERSION value of Pod::Simple.
789           Note that perlpodspec requires output formats (wherever possible)
790           to note this detail in a comment in the output format.  For
791           example, for some kind of SGML output format:
792
793                   print OUT "<!-- \n", $parser->version_report, "\n -->";
794
795       "$parser->pod_para_count()"
796           This returns the count of Pod paragraphs seen so far.
797
798       "$parser->line_count()"
799           This is the current line number being parsed. But you might find
800           the "line_number" event attribute more accurate, when it is
801           present.
802
803       "$parser->nix_X_codes(  SOMEVALUE  )"
804           This attribute, when set to a true value (and it is false by
805           default) ignores any "X<...>" sequences in the document being
806           parsed.  Many formats don't actually use the content of these
807           codes, so have no reason to process them.
808
809       "$parser->keep_encoding_directive(  SOMEVALUE  )"
810           This attribute, when set to a true value (it is false by default)
811           will keep "=encoding" and its content in the event structure. Most
812           formats don't actually need to process the content of an
813           "=encoding" directive, even when this directive sets the encoding
814           and the processor makes use of the encoding information. Indeed, it
815           is possible to know the encoding without processing the directive
816           content.
817
818       "$parser->merge_text(  SOMEVALUE  )"
819           This attribute, when set to a true value (and it is false by
820           default) makes sure that only one event (or token, or node) will be
821           created for any single contiguous sequence of text.  For example,
822           consider this somewhat contrived example:
823
824                   I just LOVE Z<>hotE<32>apple pie!
825
826           When that is parsed and events are about to be called on it, it may
827           actually seem to be four different text events, one right after
828           another: one event for "I just LOVE ", one for "hot", one for " ",
829           and one for "apple pie!". But if you have merge_text on, then
830           you're guaranteed that it will be fired as one text event:  "I just
831           LOVE hot apple pie!".
832
833       "$parser->code_handler(  CODE_REF  )"
834           This specifies code that should be called when a code line is seen
835           (i.e., a line outside of the Pod).  Normally this is undef, meaning
836           that no code should be called.  If you provide a routine, it should
837           start out like this:
838
839                   sub get_code_line {  # or whatever you'll call it
840                     my($line, $line_number, $parser) = @_;
841                     ...
842                   }
843
844           Note, however, that sometimes the Pod events aren't processed in
845           exactly the same order as the code lines are -- i.e., if you have a
846           file with Pod, then code, then more Pod, sometimes the code will be
847           processed (via whatever you have code_handler call) before the all
848           of the preceding Pod has been processed.
849
850       "$parser->cut_handler(  CODE_REF  )"
851           This is just like the code_handler attribute, except that it's for
852           "=cut" lines, not code lines. The same caveats apply. "=cut" lines
853           are unlikely to be interesting, but this is included for
854           completeness.
855
856       "$parser->pod_handler(  CODE_REF  )"
857           This is just like the code_handler attribute, except that it's for
858           "=pod" lines, not code lines. The same caveats apply. "=pod" lines
859           are unlikely to be interesting, but this is included for
860           completeness.
861
862       "$parser->whiteline_handler(  CODE_REF  )"
863           This is just like the code_handler attribute, except that it's for
864           lines that are seemingly blank but have whitespace (" " and/or
865           "\t") on them, not code lines. The same caveats apply. These lines
866           are unlikely to be interesting, but this is included for
867           completeness.
868
869       "$parser->whine( linenumber, complaint string )"
870           This notes a problem in the Pod, which will be reported in the "Pod
871           Errors" section of the document and/or sent to STDERR, depending on
872           the values of the attributes "no_whining", "no_errata_section", and
873           "complain_stderr".
874
875       "$parser->scream( linenumber, complaint string )"
876           This notes an error like "whine" does, except that it is not
877           suppressible with "no_whining". This should be used only for very
878           serious errors.
879
880       "$parser->source_dead(1)"
881           This aborts parsing of the current document, by switching on the
882           flag that indicates that EOF has been seen.  In particularly
883           drastic cases, you might want to do this.  It's rather nicer than
884           just calling "die"!
885
886       "$parser->hide_line_numbers( SOMEVALUE )"
887           Some subclasses that indiscriminately dump event attributes (well,
888           except for ones beginning with "~") can use this object attribute
889           for refraining to dump the "start_line" attribute.
890
891       "$parser->no_whining( SOMEVALUE )"
892           This attribute, if set to true, will suppress reports of non-fatal
893           error messages.  The default value is false, meaning that
894           complaints are reported.  How they get reported depends on the
895           values of the attributes "no_errata_section" and "complain_stderr".
896
897       "$parser->no_errata_section( SOMEVALUE )"
898           This attribute, if set to true, will suppress generation of an
899           errata section.  The default value is false -- i.e., an errata
900           section will be generated.
901
902       "$parser->complain_stderr( SOMEVALUE )"
903           This attribute, if set to true will send complaints to STDERR.  The
904           default value is false -- i.e., complaints do not go to STDERR.
905
906       "$parser->bare_output( SOMEVALUE )"
907           Some formatter subclasses use this as a flag for whether output
908           should have prologue and epilogue code omitted. For example,
909           setting this to true for an HTML formatter class should omit the
910           "<html><head><title>...</title><body>..." prologue and the
911           "</body></html>" epilogue.
912
913           If you want to set this to true, you should probably also set
914           "no_whining" or at least "no_errata_section" to true.
915
916       "$parser->preserve_whitespace( SOMEVALUE )"
917           If you set this attribute to a true value, the parser will try to
918           preserve whitespace in the output.  This means that such formatting
919           conventions as two spaces after periods will be preserved by the
920           parser.  This is primarily useful for output formats that treat
921           whitespace as significant (such as text or *roff, but not HTML).
922
923       "$parser->parse_empty_lists( SOMEVALUE )"
924           If this attribute is set to true, the parser will not ignore empty
925           "=over"/"=back" blocks. The type of "=over" will be empty,
926           documented above, "events with an element_name of over-empty".
927

SEE ALSO

929       Pod::Simple -- event-based Pod-parsing framework
930
931       Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls
932       its own method (like "start_head3")
933
934       Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple,
935       but with a token-stream interface
936
937       Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple,
938       but with a tree interface
939
940       Pod::Simple::Checker -- a simple Pod::Simple subclass that reads
941       documents, and then makes a plaintext report of any errors found in the
942       document
943
944       Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented
945       XML, showing each event on its own line
946
947       Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without
948       introducing extra whitespace as Pod::Simple::DumpAsXML does).
949
950       Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented
951       text, showing each event on its own line
952
953       Pod::Simple::LinkSection -- class for objects representing the values
954       of the TODO and TODO attributes of L<...> elements
955
956       Pod::Escapes -- the module that Pod::Simple uses for evaluating E<...>
957       content
958
959       Pod::Simple::Text -- a simple plaintext formatter for Pod
960
961       Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort
962       for indent or wrap the text being formatted
963
964       Pod::Simple::HTML -- a simple HTML formatter for Pod
965
966       perlpod
967
968       perlpodspec
969
970       perldoc
971

SUPPORT

973       Questions or discussion about POD and Pod::Simple should be sent to the
974       pod-people@perl.org mail list. Send an empty email to
975       pod-people-subscribe@perl.org to subscribe.
976
977       This module is managed in an open GitHub repository,
978       <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
979       contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
980       send patches!
981
982       Patches against Pod::Simple are welcome. Please send bug reports to
983       <bug-pod-simple@rt.cpan.org>.
984
986       Copyright (c) 2002 Sean M. Burke.
987
988       This library is free software; you can redistribute it and/or modify it
989       under the same terms as Perl itself.
990
991       This program is distributed in the hope that it will be useful, but
992       without any warranty; without even the implied warranty of
993       merchantability or fitness for a particular purpose.
994

AUTHOR

996       Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.  But don't
997       bother him, he's retired.
998
999       Pod::Simple is maintained by:
1000
1001       ·   Allison Randal "allison@perl.org"
1002
1003       ·   Hans Dieter Pearcey "hdp@cpan.org"
1004
1005       ·   David E. Wheeler "dwheeler@cpan.org"
1006
1007
1008
1009perl v5.30.1                      2020-01-30       Pod::Simple::Subclassing(3)
Impressum