...

attribute. For example, this Pod source: Lwill produce this event structure: "ENVIRONMENT" in crontab(5) In the rare case where the Pod document has code likeLEI|IE, then the I will appearas the content of the element, the I text will appearonly as the value of the I attribute, and there will be noC attribute (whose presence means that the Pod parserhad to infer what text should appear as the link text -- as opposed tocases where that attribute is absent, which means that the Pod parser didI have to infer the link text, because that L code explicitly specifiedsome link text.)For example, this Pod source: Lwill produce this event structure: hell itself! The last type of L structure is for links to/within Pod documents. It isthe most complex because it can have a I attribute, I aI

attribute, or both. The C attribute is alwaysspecified for this type of L code.In the most common case, the simple case of a LEpodpageE codeproduces this event structure: podpage For example, this Pod source: Lproduces this event structure: Net::Ping In cases where there is link-text explicitly specified, itis to be found in the content of the element (and not theattributes), just as with the LEI|IEcase discussed above. For example, this Pod source: Lproduces this event structure: Perl Error Messages In cases of links to a section in the current Pod document,there is a I

attribute instead of a I attribute.For example, this Pod source: Lproduces this event structure: "Member Data" As another example, this Pod source: Lproduces this event structure: the various attributes In cases of links to a section in a different Pod document,there are both a I

attribute and a I attribute.For example, this Pod source: Lproduces this event structure: "Basic BLOCKs and Switch Statements" in perlsyn As another example, this Pod source: Lproduces this event structure: SWITCH statements Incidentally, note that we do not distinguish between these syntaxes: L L<"Member Data"> L L [deprecated syntax]That is, they all produce the same event structure (for the most part), namely: "Member Data" The I attribute depends on what the raw content of the CE> is,so that is why the event structure is the same "for the most part".If you have not guessed it yet, the I attribute contains the raw,original, unescaped content of the CE> formatting code. In additionto the examples above, take notice of the following event structure producedby the following CE> formatting code. L|page/About the C<-M> switch> click B Specifically, notice that the formatting codes are present and unescapedin I.There is a known bug in the I attribute where any surrounding whitespaceis condensed into a single ' '. For example, given LE<60> linkE<62>, Iwill be " link".=item events with an element_name of E or ZWhile there are Pod codes EE...E and ZEE, theseI produce any E or Z events -- that is, there are no suchevents as E or Z.=item events with an element_name of VerbatimWhen a Pod verbatim paragraph (AKA "codeblock") is parsed, itproduces this event structure: ...text... The value of the I attribute will be the line number of thefirst line of this verbatim block. The I attribute is alwayspresent, and always has the value "preserve".The text content will have tabs already expanded.=item events with an element_name of head1 .. head4When a "=head1 ..." directive is parsed, it produces this eventstructure: ...stuff... For example, a directive consisting of this: =head1 Options to C et al.will produce this event structure: Options to new et al. "=head2" through "=head4" directives are the same, except for the elementnames in the event structure.=item events with an element_name of encodingIn the default case, the events corresponding to C<=encoding> directivesare not emitted. They are emitted if C is true.In that case they produce event structures likeL above.=item events with an element_name of over-bulletWhen an "=over ... Z<>=back" block is parsed where the items area bulleted list, it will produce this event structure: ...Stuff... ...more item-bullets... The attribute I is only present if it is a true value; it is notpresent if it is a false value. It is shown in the above example to illustratewhere the attribute is (in the B tag). It signifies that the C<=over>did not have a matching C<=back>, and thus Pod::Simple had to create a fakecloser.For example, this Pod source: =over =item * Something =backWould produce an event structure that does B have the Iattribute, whereas this Pod source: =over =item * Gasp! An unclosed =over block!would. The rest of the over-* examples will not demonstrate this attribute,but they all can have it. See L's source for an example of thisattribute being used.The value of the I attribute is whatever value is after the"=over" directive, as in "=over 8". If no such value is specifiedin the directive, then the I attribute has the value "4".For example, this Pod source: =over =item * Stuff =item * Bar I! =backproduces this event structure:

Stuff

Bar baz!

=item events with an element_name of over-numberWhen an "=over ... Z<>=back" block is parsed where the items area numbered list, it will produce this event structure: ...Stuff... ...more item-number... This is like the "over-bullet" event structure; but note that the contentsare "item-number" instead of "item-bullet", and note that they will havea "number" attribute, which some formatters/processors may ignore(since, for example, there's no need for it in HTML when producingan "

" structure), but which any processor may use.Note that the values for the I attributes of "item-number"elements in a given "over-number" area I start at 1 and go up byone each time. If the Pod source doesn't follow that order (even thoughit really should!), whatever numbers it has will be ignored (withthe correct values being put in the I attributes), and an errormessage might be issued to the user.=item events with an element_name of over-textThese events are somewhat unlike the other over-*structures, as far as what their contents are. Whenan "=over ... Z<>=back" block is parsed where the items area list of text "subheadings", it will produce this event structure: ...stuff... ...stuff (generally Para or Verbatim elements)... ...more item-text and/or stuff... The I and I attributes are as with the other over-* events.For example, this Pod source: =over =item Foo Stuff =item Bar I! Quux =backproduces this event structure:

Foo

Stuff

Bar baz !

Quux =item events with an element_name of over-blockThese events are somewhat unlike the other over-*structures, as far as what their contents are. Whenan "=over ... Z<>=back" block is parsed where there are no items,it will produce this event structure: ...stuff (generally Para or Verbatim elements)... The I and I attributes are as with the other over-* events.For example, this Pod source: =over For cutting off our trade with all parts of the world For transporting us beyond seas to be tried for pretended offenses He is at this time transporting large armies of foreign mercenaries to complete the works of death, desolation and tyranny, already begun with circumstances of cruelty and perfidy scarcely paralleled in the most barbarous ages, and totally unworthy the head of a civilized nation. =backwill produce this event structure: For cutting off our trade with all parts of the world For transporting us beyond seas to be tried for pretended offenses He is at this time transporting large armies of [...more text...] =item events with an element_name of over-emptyB is set to atrue value.>These events are somewhat unlike the other over-* structures, as far as whattheir contents are. When an "=over ... Z<>=back" block is parsed where thereis no content, it will produce this event structure: The I and I attributes are as with the other over-* events.For example, this Pod source: =over =over =back =backwill produce this event structure:

Note that the outer C<=over> is a block because it has no C<=item>s but stillhas content: the inner C<=over>. The inner C<=over>, in turn, is completelyempty, and is treated as such.=item events with an element_name of item-bulletSee L, above.=item events with an element_name of item-numberSee L, above.=item events with an element_name of item-textSee L, above.=item events with an element_name of forTODO...=item events with an element_name of DataTODO...=back=head1 More Pod::Simple MethodsPod::Simple provides a lot of methods that aren't generally interestingto the end user of an existing Pod formatter, but some of which youmight find useful in writing a Pod formatter. They are listed below. Thefirst several methods (the accept_* methods) are for declaring thecapabilities of your parser, notably what C<=for I> sectionsit's interested in, what extra NE...E codes it accepts beyondthe ones described in the I.=over=item C<< $parser->accept_targets( I ) >>As the parser sees sections like: =for html

or =begin html

=end html...the parser will ignore these sections unless your subclass hasspecified that it wants to see sections targeted to "html" (or whateverthe formatter name is).If you want to process all sections, even if they're not targeted for you,call this before you start parsing: $parser->accept_targets('*');=item C<< $parser->accept_targets_as_text( I ) >>This is like accept_targets, except that it specifies also that thecontent of sections for this target should be treated as Pod text evenif the target name in "=for I" doesn't start with a ":".At time of writing, I don't think you'll need to use this.=item C<< $parser->accept_codes( I, I... ) >>This tells the parser that you accept additional formatting codes,beyond just the standard ones (I B C L F S U X, plus the two weird onesyou don't actually see in the parse tree, Z and E). For example, to alsoaccept codes "N", "R", and "W": $parser->accept_codes( qw( N R W ) );B=item C<< $parser->accept_directive_as_data( I ) >>=item C<< $parser->accept_directive_as_verbatim( I ) >>=item C<< $parser->accept_directive_as_processed( I ) >>In the unlikely situation that you need to tell the parser that you willaccept additional directives ("=foo" things), you need to first set theparser to treat its content as data (i.e., not really processed atall), or as verbatim (mostly just expanding tabs), or as processed text(parsing formatting codes like BE...E).For example, to accept a new directive "=method", you'd presumablyuse: $parser->accept_directive_as_processed("method");so that you could have Pod lines like: =method I<$whatever> thing BMaking up your own directives breaks compatibility with other Podformatters, in a way that using "=for I ..." lines doesn't;however, you may find this useful if you're making a Pod supersetformat where you don't need to worry about compatibility.=item C<< $parser->nbsp_for_S( I ); >>Setting this attribute to a true value (and by default it is false) willturn "SE...E" sequences into sequences of words separated byC<\xA0> (non-breaking space) characters. For example, it will take this: I like S, don't you?and treat it as if it were: I like DutchEappleEpie, don't you?This is handy for output formats that don't have anything quite like an"SE...E" code, but which do have a code for non-breaking space.There is currently no method for going the other way; but I canprobably provide one upon request.=item C<< $parser->version_report() >>This returns a string reporting the $VERSION value from your module (andits classname) as well as the $VERSION value of Pod::Simple. Note thatL requires output formats (wherever possible) to notethis detail in a comment in the output format. For example, forsome kind of SGML output format: print OUT "";=item C<< $parser->pod_para_count() >>This returns the count of Pod paragraphs seen so far.=item C<< $parser->line_count() >>This is the current line number being parsed. But you might find the"line_number" event attribute more accurate, when it is present.=item C<< $parser->nix_X_codes( I ) >>This attribute, when set to a true value (and it is false by default)ignores any "XE...E" sequences in the document being parsed.Many formats don't actually use the content of these codes, so haveno reason to process them.=item C<< $parser->keep_encoding_directive( I ) >>This attribute, when set to a true value (it is false by default)will keep C<=encoding> and its content in the event structure. Mostformats don't actually need to process the content of an C<=encoding>directive, even when this directive sets the encoding and theprocessor makes use of the encoding information. Indeed, it ispossible to know the encoding without processing the directivecontent.=item C<< $parser->merge_text( I ) >>This attribute, when set to a true value (and it is false by default)makes sure that only one event (or token, or node) will be createdfor any single contiguous sequence of text. For example, considerthis somewhat contrived example: I just LOVE Z<>hotE<32>apple pie!When that is parsed and events are about to be called on it, it mayactually seem to be four different text events, one right after another:one event for "I just LOVE ", one for "hot", one for " ", and one for"apple pie!". But if you have merge_text on, then you're guaranteedthat it will be fired as one text event: "I just LOVE hot apple pie!".=item C<< $parser->code_handler( I ) >>This specifies code that should be called when a code line is seen(i.e., a line outside of the Pod). Normally this is undef, meaningthat no code should be called. If you provide a routine, it shouldstart out like this: sub get_code_line { # or whatever you'll call it my($line, $line_number, $parser) = @_; ... }Note, however, that sometimes the Pod events aren't processed in exactlythe same order as the code lines are -- i.e., if you have a file withPod, then code, then more Pod, sometimes the code will be processed (viawhatever you have code_handler call) before the all of the preceding Podhas been processed.=item C<< $parser->cut_handler( I ) >>This is just like the code_handler attribute, except that it's for"=cut" lines, not code lines. The same caveats apply. "=cut" lines areunlikely to be interesting, but this is included for completeness.=item C<< $parser->pod_handler( I ) >>This is just like the code_handler attribute, except that it's for"=pod" lines, not code lines. The same caveats apply. "=pod" lines areunlikely to be interesting, but this is included for completeness.=item C<< $parser->whiteline_handler( I ) >>This is just like the code_handler attribute, except that it's forlines that are seemingly blank but have whitespace (" " and/or "\t") on them,not code lines. The same caveats apply. These lines are unlikely to beinteresting, but this is included for completeness.=item C<< $parser->whine( I, I ) >>This notes a problem in the Pod, which will be reported in the "PodErrors" section of the document and/or sent to STDERR, depending on thevalues of the attributes C, C, andC.=item C<< $parser->scream( I, I ) >>This notes an error like C does, except that it is notsuppressible with C. This should be used only for veryserious errors.=item C<< $parser->source_dead(1) >>This aborts parsing of the current document, by switching on the flagthat indicates that EOF has been seen. In particularly drastic cases,you might want to do this. It's rather nicer than just callingC!=item C<< $parser->hide_line_numbers( I ) >>Some subclasses that indiscriminately dump event attributes (well,except for ones beginning with "~") can use this object attribute forrefraining to dump the "start_line" attribute.=item C<< $parser->no_whining( I ) >>This attribute, if set to true, will suppress reports of non-fatalerror messages. The default value is false, meaning that complaintsI reported. How they get reported depends on the values ofthe attributes C and C.=item C<< $parser->no_errata_section( I ) >>This attribute, if set to true, will suppress generation of an erratasection. The default value is false -- i.e., an errata section will begenerated.=item C<< $parser->complain_stderr( I ) >>This attribute, if set to true will send complaints to STDERR. Thedefault value is false -- i.e., complaints do not go to STDERR.=item C<< $parser->bare_output( I ) >>Some formatter subclasses use this as a flag for whether output shouldhave prologue and epilogue code omitted. For example, setting this totrue for an HTML formatter class should omit the"......" prologue and the"" epilogue.If you want to set this to true, you should probably also setC or at least C to true.=item C<< $parser->preserve_whitespace( I ) >>If you set this attribute to a true value, the parser will try topreserve whitespace in the output. This means that such formattingconventions as two spaces after periods will be preserved by the parser.This is primarily useful for output formats that treat whitespace assignificant (such as text or *roff, but not HTML).=item C<< $parser->parse_empty_lists( I ) >>If this attribute is set to true, the parser will not ignore emptyC<=over>/C<=back> blocks. The type of C<=over> will be I, documentedabove, L.=back=head1 SEE ALSOL -- event-based Pod-parsing frameworkL -- like Pod::Simple, but each sort of eventcalls its own method (like C)L -- a Pod-parsing framework like Pod::Simple,but with a token-stream interfaceL -- a Pod-parsing framework like Pod::Simple,but with a tree interfaceL -- a simple Pod::Simple subclass that readsdocuments, and then makes a plaintext report of any errors found in thedocumentL -- for dumping Pod documents as tidilyindented XML, showing each event on its own lineL -- dumps a Pod document as XML (withoutintroducing extra whitespace as Pod::Simple::DumpAsXML does).L -- for dumping Pod documents as tidilyindented text, showing each event on its own lineL -- class for objects representing the valuesof the TODO and TODO attributes of LE...E elementsL -- the module that Pod::Simple uses for evaluatingEE...E contentL -- a simple plaintext formatter for PodL -- like Pod::Simple::Text, butmakes no effort for indent or wrap the text being formattedL -- a simple HTML formatter for PodLLL=head1 SUPPORTQuestions or discussion about POD and Pod::Simple should be sent to thepod-people@perl.org mail list. Send an empty email topod-people-subscribe@perl.org to subscribe.This module is managed in an open GitHub repository,L. Feel free to fork and contribute, orto clone L and send patches!Patches against Pod::Simple are welcome. Please send bug reports to.=head1 COPYRIGHT AND DISCLAIMERSCopyright (c) 2002 Sean M. Burke.This library is free software; you can redistribute it and/or modify itunder the same terms as Perl itself.This program is distributed in the hope that it will be useful, butwithout any warranty; without even the implied warranty ofmerchantability or fitness for a particular purpose.=head1 AUTHORPod::Simple was created by Sean M. Burke .But don't bother him, he's retired.Pod::Simple is maintained by:=over=item * Allison Randal C=item * Hans Dieter Pearcey C=item * David E. Wheeler C=back=for notesHm, my old podchecker version (1.2) says: *** WARNING: node 'http://search.cpan.org/' contains non-escaped | or / at line 38 in file Subclassing.pod *** WARNING: node 'http://lists.perl.org/showlist.cgi?name=pod-people' contains non-escaped | or / at line 41 in file Subclassing.podYes, L<...> is hard.=cut