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 _handle_element_start(),
63           _handle_element_end() and _handle_text().
64
65       Pod::Simple::Methody
66           The Pod::Simple::Methody interface is event-based, similar to that
67           of HTML::Parser or XML::Parser's "Handlers".
68
69       Pod::Simple::PullParser
70           Pod::Simple::PullParser provides a token-stream interface, sort of
71           like HTML::TokeParser's interface.
72
73       Pod::Simple::SimpleTree
74           Pod::Simple::SimpleTree provides a simple tree interface, rather
75           like XML::Parser's "Tree" interface. Users familiar with XML
76           handling will be comfortable with this interface. Users interested
77           in outputting XML, should look into the modules that produce an XML
78           representation of the Pod stream, notably
79           Pod::Simple::XMLOutStream; you can feed the output of such a class
80           to whatever XML parsing system you are most at home with.
81
82       The last step is to write your code based on how the events (or tokens,
83       or tree-nodes, or the XML, or however you're parsing) will map to
84       constructs in the output format. Also be sure to consider how to escape
85       text nodes containing arbitrary text, and what to do with text nodes
86       that represent preformatted text (from verbatim sections).
87

Events

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

More Pod::Simple Methods

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

SEE ALSO

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

SUPPORT

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

AUTHOR

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