[Summary view] [Print] [Text view]

   1  
   2  =head1 NAME
   3  
   4  Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
   5  
   6  =head1 SYNOPSIS
   7  
   8    package Pod::SomeFormatter;
   9    use Pod::Simple;
  10    @ISA = qw(Pod::Simple);
  11    $VERSION = '1.01';
  12    use strict;
  13  
  14    sub _handle_element_start {
  15      my($parser, $element_name, $attr_hash_r) = @_;
  16      ...
  17    }
  18  
  19    sub _handle_element_end {
  20      my($parser, $element_name) = @_;
  21      ...
  22    }
  23  
  24    sub _handle_text {
  25      my($parser, $text) = @_;
  26      ...
  27    }
  28    1;
  29  
  30  =head1 DESCRIPTION
  31  
  32  This document is about using Pod::Simple to write a Pod processor,
  33  generally a Pod formatter. If you just want to know about using an
  34  existing Pod formatter, instead see its documentation and see also the
  35  docs in L<Pod::Simple>.
  36  
  37  The zeroeth step in writing a Pod formatter is to make sure that there
  38  isn't already a decent one in CPAN. See L<http://search.cpan.org/>, and
  39  run a search on the name of the format you want to render to. Also
  40  consider joining the Pod People list
  41  L<http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether
  42  anyone has a formatter for that format -- maybe someone cobbled one
  43  together but just hasn't released it.
  44  
  45  The first step in writing a Pod processor is to read L<perlpodspec>,
  46  which contains notes information on writing a Pod parser (which has been
  47  largely taken care of by Pod::Simple), but also a lot of requirements
  48  and recommendations for writing a formatter.
  49  
  50  The second step is to actually learn the format you're planning to
  51  format to -- or at least as much as you need to know to represent Pod,
  52  which probably isn't much.
  53  
  54  The third step is to pick which of Pod::Simple's interfaces you want to
  55  use -- the basic interface via Pod::Simple or L<Pod::Simple::Methody> is
  56  event-based, sort of like L<HTML::Parser>'s interface, or sort of like
  57  L<XML::Parser>'s "Handlers" interface), but L<Pod::Simple::PullParser>
  58  provides a token-stream interface, sort of like L<HTML::TokeParser>'s
  59  interface; L<Pod::Simple::SimpleTree> provides a simple tree interface,
  60  rather like XML::Parser's "Tree" interface. Users familiar with
  61  XML-handling will find one of these styles relatively familiar; but if
  62  you would be even more at home with XML, there are classes that produce
  63  an XML representation of the Pod stream, notably
  64  L<Pod::Simple::XMLOutStream>; you can feed the output of such a class to
  65  whatever XML parsing system you are most at home with.
  66  
  67  The last step is to write your code based on how the events (or tokens,
  68  or tree-nodes, or the XML, or however you're parsing) will map to
  69  constructs in the output format. Also sure to consider how to escape
  70  text nodes containing arbitrary text, and also what to do with text
  71  nodes that represent preformatted text (from verbatim sections).
  72  
  73  
  74  
  75  =head1 Events
  76  
  77  TODO intro... mention that events are supplied for implicits, like for
  78  missing >'s
  79  
  80  
  81  In the following section, we use XML to represent the event structure
  82  associated with a particular construct.  That is, TODO
  83  
  84  =over
  85  
  86  =item C<< $parser->_handle_element_start( I<element_name>, I<attr_hashref> ) >>
  87  
  88  =item C<< $parser->_handle_element_end( I<element_name>  ) >>
  89  
  90  =item C<< $parser->_handle_text(  I<text_string>  ) >>
  91  
  92  =back
  93  
  94  TODO describe
  95  
  96  
  97  =over
  98  
  99  =item events with an element_name of Document
 100  
 101  Parsing a document produces this event structure:
 102  
 103    <Document start_line="543">
 104      ...all events...
 105    </Document>
 106  
 107  The value of the I<start_line> attribute will be the line number of the first
 108  Pod directive in the document.
 109  
 110  If there is no Pod in the given document, then the 
 111  event structure will be this:
 112  
 113    <Document contentless="1" start_line="543">
 114    </Document>
 115  
 116  In that case, the value of the I<start_line> attribute will not be meaningful;
 117  under current implementations, it will probably be the line number of the
 118  last line in the file.
 119  
 120  =item events with an element_name of Para
 121  
 122  Parsing a plain (non-verbatim, non-directive, non-data) paragraph in
 123  a Pod document produces this event structure:
 124  
 125      <Para start_line="543">
 126        ...all events in this paragraph...
 127      </Para>
 128  
 129  The value of the I<start_line> attribute will be the line number of the start
 130  of the paragraph.
 131  
 132  For example, parsing this paragraph of Pod:
 133  
 134    The value of the I<start_line> attribute will be the
 135    line number of the start of the paragraph.
 136  
 137  produces this event structure:
 138  
 139      <Para start_line="129">
 140        The value of the 
 141        <I>
 142          start_line
 143        </I>
 144         attribute will be the line number of the first Pod directive
 145        in the document.
 146      </Para>
 147  
 148  =item events with an element_name of B, C, F, or I.
 149  
 150  Parsing a BE<lt>...E<gt> formatting code (or of course any of its
 151  semantically identical syntactic variants
 152  S<BE<lt>E<lt> ... E<gt>E<gt>>,
 153  or S<BE<lt>E<lt>E<lt>E<lt> ... E<gt>E<gt>E<gt>E<gt>>, etc.)
 154  produces this event structure:
 155  
 156        <B>
 157          ...stuff...
 158        </B>
 159  
 160  Currently, there are no attributes conveyed.
 161  
 162  Parsing C, F, or I codes produce the same structure, with only a
 163  different element name.
 164  
 165  If your parser object has been set to accept other formatting codes,
 166  then they will be presented like these B/C/F/I codes -- i.e., without
 167  any attributes.
 168  
 169  =item events with an element_name of S
 170  
 171  Normally, parsing an SE<lt>...E<gt> sequence produces this event
 172  structure, just as if it were a B/C/F/I code:
 173  
 174        <S>
 175          ...stuff...
 176        </S>
 177  
 178  However, Pod::Simple (and presumably all derived parsers) offers the
 179  C<nbsp_for_S> option which, if enabled, will suppress all S events, and
 180  instead change all spaces in the content to non-breaking spaces. This is
 181  intended for formatters that output to a format that has no code that
 182  means the same as SE<lt>...E<gt>, but which has a code/character that
 183  means non-breaking space.
 184  
 185  =item events with an element_name of X
 186  
 187  Normally, parsing an XE<lt>...E<gt> sequence produces this event
 188  structure, just as if it were a B/C/F/I code:
 189  
 190        <X>
 191          ...stuff...
 192        </X>
 193  
 194  However, Pod::Simple (and presumably all derived parsers) offers the
 195  C<nix_X_codes> option which, if enabled, will suppress all X events
 196  and ignore their content.  For formatters/processors that don't use
 197  X events, this is presumably quite useful.
 198  
 199  
 200  =item events with an element_name of L
 201  
 202  Because the LE<lt>...E<gt> is the most complex construct in the
 203  language, it should not surprise you that the events it generates are
 204  the most complex in the language. Most of complexity is hidden away in
 205  the attribute values, so for those of you writing a Pod formatter that
 206  produces a non-hypertextual format, you can just ignore the attributes
 207  and treat an L event structure like a formatting element that
 208  (presumably) doesn't actually produce a change in formatting.  That is,
 209  the content of the L event structure (as opposed to its
 210  attributes) is always what text should be displayed.
 211  
 212  There are, at first glance, three kinds of L links: URL, man, and pod.
 213  
 214  When a LE<lt>I<some_url>E<gt> code is parsed, it produces this event
 215  structure:
 216  
 217    <L content-implicit="yes" to="that_url" type="url">
 218      that_url
 219    </L>
 220  
 221  The C<type="url"> attribute is always specified for this type of
 222  L code.
 223  
 224  For example, this Pod source:
 225  
 226    L<http://www.perl.com/CPAN/authors/>
 227  
 228  produces this event structure:
 229  
 230    <L content-implicit="yes" to="http://www.perl.com/CPAN/authors/" type="url">
 231      http://www.perl.com/CPAN/authors/
 232    </L>
 233  
 234  When a LE<lt>I<manpage(section)>E<gt> code is parsed (and these are
 235  fairly rare and not terribly useful), it produces this event structure:
 236  
 237    <L content-implicit="yes" to="manpage(section)" type="man">
 238      manpage(section)
 239    </L>
 240  
 241  The C<type="man"> attribute is always specified for this type of
 242  L code.
 243  
 244  For example, this Pod source:
 245  
 246    L<crontab(5)>
 247  
 248  produces this event structure:
 249  
 250    <L content-implicit="yes" to="crontab(5)" type="man">
 251      crontab(5)
 252    </L>
 253  
 254  In the rare cases where a man page link has a specified, that text appears
 255  in a I<section> attribute. For example, this Pod source:
 256  
 257    L<crontab(5)/"ENVIRONMENT">
 258  
 259  will produce this event structure:
 260  
 261    <L content-implicit="yes" section="ENVIRONMENT" to="crontab(5)" type="man">
 262      "ENVIRONMENT" in crontab(5)
 263    </L>
 264  
 265  In the rare case where the Pod document has code like
 266  LE<lt>I<sometext>|I<manpage(section)>E<gt>, then the I<sometext> will appear
 267  as the content of the element, the I<manpage(section)> text will appear
 268  only as the value of the I<to> attribute, and there will be no
 269  C<content-implicit="yes"> attribute (whose presence means that the Pod parser
 270  had to infer what text should appear as the link text -- as opposed to
 271  cases where that attribute is absent, which means that the Pod parser did
 272  I<not> have to infer the link text, because that L code explicitly specified
 273  some link text.)
 274  
 275  For example, this Pod source:
 276  
 277    L<hell itself!|crontab(5)>
 278    
 279  will produce this event structure:
 280  
 281    <L to="crontab(5)" type="man">
 282      hell itself!
 283    </L>
 284  
 285  The last type of L structure is for links to/within Pod documents. It is
 286  the most complex because it can have a I<to> attribute, I<or> a
 287  I<section> attribute, or both. The C<type="pod"> attribute is always
 288  specified for this type of L code.
 289  
 290  In the most common case, the simple case of a LE<lt>podpageE<gt> code
 291  produces this event structure:
 292  
 293    <L content-implicit="yes" to="Net::Ping" type="pod">
 294      podpage
 295    </L>
 296  
 297  For example, this Pod source:
 298  
 299    L<Net::Ping>
 300  
 301  produces this event structure:
 302  
 303    <L content-implicit="yes" to="Net::Ping" type="pod">
 304      Net::Ping
 305    </L>
 306  
 307  In cases where there is link-text explicitly specified, it
 308  is to be found in the content of the element (and not the
 309  attributes), just as with the LE<lt>I<sometext>|I<manpage(section)>E<gt>
 310  case discussed above.  For example, this Pod source:
 311  
 312    L<Perl Error Messages|perldiag>
 313  
 314  produces this event structure:
 315  
 316    <L to="perldiag" type="pod">
 317      Perl Error Messages
 318    </L>
 319  
 320  In cases of links to a section in the current Pod document,
 321  there is a I<section> attribute instead of a I<to> attribute.
 322  For example, this Pod source:
 323  
 324    L</"Member Data">
 325  
 326  produces this event structure:
 327  
 328    <L content-implicit="yes" section="Member Data" type="pod">
 329      "Member Data"
 330    </L>
 331  
 332  As another example, this Pod source:
 333  
 334    L<the various attributes|/"Member Data">
 335  
 336  produces this event structure:
 337  
 338    <L section="Member Data" type="pod">
 339      the various attributes
 340    </L>
 341  
 342  In cases of links to a section in a different Pod document,
 343  there are both a I<section> attribute and a L<to> attribute.
 344  For example, this Pod source:
 345  
 346    L<perlsyn/"Basic BLOCKs and Switch Statements">
 347  
 348  produces this event structure:
 349  
 350    <L content-implicit="yes" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
 351      "Basic BLOCKs and Switch Statements" in perlsyn
 352    </L>
 353  
 354  As another example, this Pod source:
 355  
 356    L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
 357  
 358  produces this event structure:
 359  
 360    <L section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
 361      SWITCH statements
 362    </L>
 363  
 364  Incidentally, note that we do not distinguish between these syntaxes:
 365  
 366    L</"Member Data">
 367    L<"Member Data">
 368    L</Member Data>
 369    L<Member Data>    [deprecated syntax]
 370  
 371  That is, they all produce the same event structure, namely:
 372  
 373    <L content-implicit="yes" section="Member Data" type="pod">
 374      &#34;Member Data&#34;
 375    </L>
 376  
 377  =item events with an element_name of E or Z
 378  
 379  While there are Pod codes EE<lt>...E<gt> and ZE<lt>E<gt>, these
 380  I<do not> produce any E or Z events -- that is, there are no such
 381  events as E or Z.
 382  
 383  =item events with an element_name of Verbatim
 384  
 385  When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
 386  produces this event structure:
 387  
 388    <Verbatim start_line="543" xml:space="preserve">
 389      ...text...
 390    </Verbatim>
 391  
 392  The value of the I<start_line> attribute will be the line number of the
 393  first line of this verbatim block.  The I<xml:space> attribute is always
 394  present, and always has the value "preserve".
 395  
 396  The text content will have tabs already expanded.
 397  
 398  
 399  =item events with an element_name of head1 .. head4
 400  
 401  When a "=head1 ..." directive is parsed, it produces this event
 402  structure:
 403  
 404    <head1>
 405      ...stuff...
 406    </head1>
 407  
 408  For example, a directive consisting of this:
 409  
 410    =head1 Options to C<new> et al.
 411  
 412  will produce this event structure:
 413  
 414    <head1 start_line="543">
 415      Options to 
 416      <C>
 417        new
 418      </C>
 419       et al.
 420    </head1>
 421  
 422  "=head2" thru "=head4" directives are the same, except for the element
 423  names in the event structure.
 424  
 425  =item events with an element_name of over-bullet
 426  
 427  When an "=over ... Z<>=back" block is parsed where the items are
 428  a bulletted list, it will produce this event structure:
 429  
 430    <over-bullet indent="4" start_line="543">
 431      <item-bullet start_line="545">
 432        ...Stuff...
 433      </item-bullet>
 434      ...more item-bullets...
 435    </over-bullet>
 436  
 437  The value of the I<indent> attribute is whatever value is after the
 438  "=over" directive, as in "=over 8".  If no such value is specified
 439  in the directive, then the I<indent> attribute has the value "4".
 440  
 441  For example, this Pod source:
 442  
 443    =over
 444  
 445    =item *
 446  
 447    Stuff
 448  
 449    =item *
 450  
 451    Bar I<baz>!
 452  
 453    =back
 454  
 455  produces this event structure:
 456  
 457    <over-bullet indent="4" start_line="10">
 458      <item-bullet start_line="12">
 459        Stuff
 460      </item-bullet>
 461      <item-bullet start_line="14">
 462        Bar <I>baz</I>!
 463      </item-bullet>
 464    </over-bullet>
 465  
 466  =item events with an element_name of over-number
 467  
 468  When an "=over ... Z<>=back" block is parsed where the items are
 469  a numbered list, it will produce this event structure:
 470  
 471    <over-number indent="4" start_line="543">
 472      <item-number number="1" start_line="545">
 473        ...Stuff...
 474      </item-number>
 475      ...more item-number...
 476    </over-bullet>
 477  
 478  This is like the "over-bullet" event structure; but note that the contents
 479  are "item-number" instead of "item-bullet", and note that they will have
 480  a "number" attribute, which some formatters/processors may ignore
 481  (since, for example, there's no need for it in HTML when producing
 482  an "<UL><LI>...</LI>...</UL>" structure), but which any processor may use.
 483  
 484  Note that the values for the I<number> attributes of "item-number"
 485  elements in a given "over-number" area I<will> start at 1 and go up by
 486  one each time.  If the Pod source doesn't follow that order (even though
 487  it really should should!), whatever numbers it has will be ignored (with
 488  the correct values being put in the I<number> attributes), and an error
 489  message might be issued to the user.
 490  
 491  =item events with an element_name of over-text
 492  
 493  These events are are somewhat unlike the other over-*
 494  structures, as far as what their contents are.  When
 495  an "=over ... Z<>=back" block is parsed where the items are
 496  a list of text "subheadings", it will produce this event structure:
 497  
 498    <over-text indent="4" start_line="543">
 499      <item-text>
 500        ...stuff...
 501      </item-text>
 502      ...stuff (generally Para or Verbatim elements)...
 503      <item-text>
 504      ...more item-text and/or stuff...
 505    </over-text>
 506  
 507  The I<indent> attribute is as with the other over-* events.
 508  
 509  For example, this Pod source:
 510  
 511    =over
 512    
 513    =item Foo
 514    
 515    Stuff
 516    
 517    =item Bar I<baz>!
 518    
 519    Quux
 520    
 521    =back
 522  
 523  produces this event structure:
 524  
 525    <over-text indent="4" start_line="20">
 526      <item-text start_line="22">
 527        Foo
 528      </item-text>
 529      <Para start_line="24">
 530        Stuff
 531      </Para>
 532      <item-text start_line="26">
 533        Bar
 534          <I>
 535            baz
 536          </I>
 537        !
 538      </item-text>
 539      <Para start_line="28">
 540        Quux
 541      </Para>
 542    </over-text>
 543  
 544  
 545  
 546  =item events with an element_name of over-block
 547  
 548  These events are are somewhat unlike the other over-*
 549  structures, as far as what their contents are.  When
 550  an "=over ... Z<>=back" block is parsed where there are no items,
 551  it will produce this event structure:
 552  
 553    <over-block indent="4" start_line="543">
 554      ...stuff (generally Para or Verbatim elements)...
 555    </over-block>
 556  
 557  The I<indent> attribute is as with the other over-* events.
 558  
 559  For example, this Pod source:
 560  
 561    =over
 562    
 563    For cutting off our trade with all parts of the world
 564    
 565    For transporting us beyond seas to be tried for pretended offenses
 566    
 567    He is at this time transporting large armies of foreign mercenaries to
 568    complete the works of death, desolation and tyranny, already begun with
 569    circumstances of cruelty and perfidy scarcely paralleled in the most
 570    barbarous ages, and totally unworthy the head of a civilized nation.
 571    
 572    =cut
 573    
 574  will produce this event structure:
 575  
 576    <over-block indent="4" start_line="2">
 577      <Para start_line="4">
 578        For cutting off our trade with all parts of the world
 579      </Para>
 580      <Para start_line="6">
 581        For transporting us beyond seas to be tried for pretended offenses
 582      </Para>
 583      <Para start_line="8">
 584        He is at this time transporting large armies of [...more text...]
 585      </Para>
 586    </over-block>
 587  
 588  =item events with an element_name of item-bullet
 589  
 590  See L</"events with an element_name of over-bullet">, above.
 591  
 592  =item events with an element_name of item-number
 593  
 594  See L</"events with an element_name of over-number">, above.
 595  
 596  =item events with an element_name of item-text
 597  
 598  See L</"events with an element_name of over-text">, above.
 599  
 600  =item events with an element_name of for
 601  
 602  TODO...
 603  
 604  =item events with an element_name of Data
 605  
 606  TODO...
 607  
 608  =back
 609  
 610  
 611  
 612  =head1 More Pod::Simple Methods
 613  
 614  Pod::Simple provides a lot of methods that aren't generally interesting
 615  to the end user of an existing Pod formatter, but some of which you
 616  might find useful in writing a Pod formatter. They are listed below. The
 617  first several methods (the accept_* methods) are for declaring the
 618  capabilites of your parser, notably what C<=for I<targetname>> sections
 619  it's interested in, what extra NE<lt>...E<gt> codes it accepts beyond
 620  the ones described in the I<perlpod>.
 621  
 622  =over
 623  
 624  =item C<< $parser->accept_targets( I<SOMEVALUE> ) >>
 625  
 626  As the parser sees sections like:
 627  
 628      =for html  <img src="fig1.jpg">
 629  
 630  or
 631  
 632      =begin html
 633  
 634        <img src="fig1.jpg">
 635  
 636      =end html
 637  
 638  ...the parser will ignore these sections unless your subclass has
 639  specified that it wants to see sections targetted to "html" (or whatever
 640  the formatter name is).
 641  
 642  If you want to process all sections, even if they're not targetted for you,
 643  call this before you start parsing:
 644  
 645    $parser->accept_targets('*');
 646  
 647  =item C<< $parser->accept_targets_as_text(  I<SOMEVALUE>  ) >>
 648  
 649  This is like accept_targets, except that it specifies also that the
 650  content of sections for this target should be treated as Pod text even
 651  if the target name in "=for I<targetname>" doesn't start with a ":".
 652  
 653  At time of writing, I don't think you'll need to use this.
 654  
 655  
 656  =item C<< $parser->accept_codes( I<Codename>, I<Codename>...  ) >>
 657  
 658  This tells the parser that you accept additional formatting codes,
 659  beyond just the standard ones (I B C L F S X, plus the two weird ones
 660  you don't actually see in the parse tree, Z and E). For example, to also
 661  accept codes "N", "R", and "W":
 662  
 663      $parser->accept_codes( qw( N R W ) );
 664  
 665  B<TODO: document how this interacts with =extend, and long element names>
 666  
 667  
 668  =item C<< $parser->accept_directive_as_data( I<directive_name> ) >>
 669  
 670  =item C<< $parser->accept_directive_as_verbatim( I<directive_name> ) >>
 671  
 672  =item C<< $parser->accept_directive_as_processed( I<directive_name> ) >>
 673  
 674  In the unlikely situation that you need to tell the parser that you will
 675  accept additional directives ("=foo" things), you need to first set the
 676  parset to treat its content as data (i.e., not really processed at
 677  all), or as verbatim (mostly just expanding tabs), or as processed text
 678  (parsing formatting codes like BE<lt>...E<gt>).
 679  
 680  For example, to accept a new directive "=method", you'd presumably
 681  use:
 682  
 683      $parser->accept_directive_as_processed("method");
 684  
 685  so that you could have Pod lines like:
 686  
 687      =method I<$whatever> thing B<um>
 688  
 689  Making up your own directives breaks compatibility with other Pod
 690  formatters, in a way that using "=for I<target> ..." lines doesn't;
 691  however, you may find this useful if you're making a Pod superset
 692  format where you don't need to worry about compatibility.
 693  
 694  
 695  =item C<< $parser->nbsp_for_S( I<BOOLEAN> ); >>
 696  
 697  Setting this attribute to a true value (and by default it is false) will
 698  turn "SE<lt>...E<gt>" sequences into sequences of words separated by
 699  C<\xA0> (non-breaking space) characters. For example, it will take this:
 700  
 701      I like S<Dutch apple pie>, don't you?
 702  
 703  and treat it as if it were:
 704  
 705      I like DutchE<nbsp>appleE<nbsp>pie, don't you?
 706  
 707  This is handy for output formats that don't have anything quite like an
 708  "SE<lt>...E<gt>" code, but which do have a code for non-breaking space.
 709  
 710  There is currently no method for going the other way; but I can
 711  probably provide one upon request.
 712  
 713  
 714  =item C<< $parser->version_report() >>
 715  
 716  This returns a string reporting the $VERSION value from your module (and
 717  its classname) as well as the $VERSION value of Pod::Simple.  Note that
 718  L<perlpodspec> requires output formats (wherever possible) to note
 719  this detail in a comment in the output format.  For example, for
 720  some kind of SGML output format:
 721  
 722      print OUT "<!-- \n", $parser->version_report, "\n -->";
 723  
 724  
 725  =item C<< $parser->pod_para_count() >>
 726  
 727  This returns the count of Pod paragraphs seen so far.
 728  
 729  
 730  =item C<< $parser->line_count() >>
 731  
 732  This is the current line number being parsed. But you might find the
 733  "line_number" event attribute more accurate, when it is present.
 734  
 735  
 736  =item C<< $parser->nix_X_codes(  I<SOMEVALUE>  ) >>
 737  
 738  This attribute, when set to a true value (and it is false by default)
 739  ignores any "XE<lt>...E<gt>" sequences in the document being parsed.
 740  Many formats don't actually use the content of these codes, so have
 741  no reason to process them.
 742  
 743  
 744  =item C<< $parser->merge_text(  I<SOMEVALUE>  ) >>
 745  
 746  This attribute, when set to a true value (and it is false by default)
 747  makes sure that only one event (or token, or node) will be created
 748  for any single contiguous sequence of text.  For example, consider
 749  this somewhat contrived example:
 750  
 751      I just LOVE Z<>hotE<32>apple pie!
 752  
 753  When that is parsed and events are about to be called on it, it may
 754  actually seem to be four different text events, one right after another:
 755  one event for "I just LOVE ", one for "hot", one for " ", and one for
 756  "apple pie!". But if you have merge_text on, then you're guaranteed
 757  that it will be fired as one text event:  "I just LOVE hot apple pie!".
 758  
 759  
 760  =item C<< $parser->code_handler(  I<CODE_REF>  ) >>
 761  
 762  This specifies code that should be called when a code line is seen
 763  (i.e., a line outside of the Pod).  Normally this is undef, meaning
 764  that no code should be called.  If you provide a routine, it should
 765  start out like this:
 766  
 767      sub get_code_line {  # or whatever you'll call it
 768        my($line, $line_number, $parser) = @_;
 769        ...
 770      }
 771  
 772  Note, however, that sometimes the Pod events aren't processed in exactly
 773  the same order as the code lines are -- i.e., if you have a file with
 774  Pod, then code, then more Pod, sometimes the code will be processed (via
 775  whatever you have code_handler call) before the all of the preceding Pod
 776  has been processed.
 777  
 778  
 779  =item C<< $parser->cut_handler(  I<CODE_REF>  ) >>
 780  
 781  This is just like the code_handler attribute, except that it's for
 782  "=cut" lines, not code lines. The same caveats apply. "=cut" lines are
 783  unlikely to be interesting, but this is included for completeness.
 784  
 785  
 786  =item C<< $parser->whine( I<linenumber>, I<complaint string> ) >>
 787  
 788  This notes a problem in the Pod, which will be reported to in the "Pod
 789  Errors" section of the document and/or send to STDERR, depending on the
 790  values of the attributes C<no_whining>, C<no_errata_section>, and
 791  C<complain_stderr>.
 792  
 793  =item C<< $parser->scream( I<linenumber>, I<complaint string> ) >>
 794  
 795  This notes an error like C<whine> does, except that it is not
 796  suppressable with C<no_whining>. This should be used only for very
 797  serious errors.
 798  
 799  
 800  =item C<< $parser->source_dead(1) >>
 801  
 802  This aborts parsing of the current document, by switching on the flag
 803  that indicates that EOF has been seen.  In particularly drastic cases,
 804  you might want to do this.  It's rather nicer than just calling
 805  C<die>!
 806  
 807  =item C<< $parser->hide_line_numbers( I<SOMEVALUE> ) >>
 808  
 809  Some subclasses that indescriminately dump event attributes (well,
 810  except for ones beginning with "~") can use this object attribute for
 811  refraining to dump the "start_line" attribute.
 812  
 813  =item C<< $parser->no_whining( I<SOMEVALUE> ) >>
 814  
 815  This attribute, if set to true, will suppress reports of non-fatal
 816  error messages.  The default value is false, meaning that complaints
 817  I<are> reported.  How they get reported depends on the values of
 818  the attributes C<no_errata_section> and C<complain_stderr>.
 819  
 820  =item C<< $parser->no_errata_section( I<SOMEVALUE> ) >>
 821  
 822  This attribute, if set to true, will suppress generation of an errata
 823  section.  The default value is false -- i.e., an errata section will be
 824  generated.
 825  
 826  =item C<< $parser->complain_stderr( I<SOMEVALUE> ) >>
 827  
 828  This attribute, if set to true will send complaints to STDERR.  The
 829  default value is false -- i.e., complaints do not go to STDERR.
 830  
 831  =item C<< $parser->bare_output( I<SOMEVALUE> ) >>
 832  
 833  Some formatter subclasses use this as a flag for whether output should
 834  have prologue and epilogue code omitted. For example, setting this to
 835  true for an HTML formatter class should omit the
 836  "<html><head><title>...</title><body>..." prologue and the
 837  "</body></html>" epilogue.
 838  
 839  If you want to set this to true, you should probably also set
 840  C<no_whining> or at least C<no_errata_section> to true.
 841  
 842  =item C<< $parser->preserve_whitespace( I<SOMEVALUE> ) >>
 843  
 844  If you set this attribute to a true value, the parser will try to
 845  preserve whitespace in the output.  This means that such formatting
 846  conventions as two spaces after periods will be preserved by the parser.
 847  This is primarily useful for output formats that treat whitespace as
 848  significant (such as text or *roff, but not HTML).
 849  
 850  =back
 851  
 852  
 853  =head1 SEE ALSO
 854  
 855  L<Pod::Simple> -- event-based Pod-parsing framework
 856  
 857  L<Pod::Simple::Methody> -- like Pod::Simple, but each sort of event
 858  calls its own method (like C<start_head3>)
 859  
 860  L<Pod::Simple::PullParser> -- a Pod-parsing framework like Pod::Simple,
 861  but with a token-stream interface
 862  
 863  L<Pod::Simple::SimpleTree> -- a Pod-parsing framework like Pod::Simple,
 864  but with a tree interface
 865  
 866  L<Pod::Simple::Checker> -- a simple Pod::Simple subclass that reads
 867  documents, and then makes a plaintext report of any errors found in the
 868  document
 869  
 870  L<Pod::Simple::DumpAsXML> -- for dumping Pod documents as tidily
 871  indented XML, showing each event on its own line
 872  
 873  L<Pod::Simple::XMLOutStream> -- dumps a Pod document as XML (without
 874  introducing extra whitespace as Pod::Simple::DumpAsXML does).
 875  
 876  L<Pod::Simple::DumpAsText> -- for dumping Pod documents as tidily
 877  indented text, showing each event on its own line
 878  
 879  L<Pod::Simple::LinkSection> -- class for objects representing the values
 880  of the TODO and TODO attributes of LE<lt>...E<gt> elements
 881  
 882  L<Pod::Escapes> -- the module the Pod::Simple uses for evaluating
 883  EE<lt>...E<gt> content
 884  
 885  L<Pod::Simple::Text> -- a simple plaintext formatter for Pod
 886  
 887  L<Pod::Simple::TextContent> -- like Pod::Simple::Text, but
 888  makes no effort for indent or wrap the text being formatted
 889  
 890  L<perlpod|perlpod>
 891  
 892  L<perlpodspec|perlpodspec>
 893  
 894  L<perldoc>
 895  
 896  
 897  =head1 COPYRIGHT AND DISCLAIMERS
 898  
 899  Copyright (c) 2002 Sean M. Burke.  All rights reserved.
 900  
 901  This library is free software; you can redistribute it and/or modify it
 902  under the same terms as Perl itself.
 903  
 904  This program is distributed in the hope that it will be useful, but
 905  without any warranty; without even the implied warranty of
 906  merchantability or fitness for a particular purpose.
 907  
 908  =head1 AUTHOR
 909  
 910  Sean M. Burke C<sburke@cpan.org>
 911  
 912  
 913  =for notes
 914  Hm, my old podchecker version (1.2) says:
 915   *** WARNING: node 'http://search.cpan.org/' contains non-escaped | or / at line 38 in file Subclassing.pod
 916   *** WARNING: node 'http://lists.perl.org/showlist.cgi?name=pod-people' contains non-escaped | or / at line 41 in file Subclassing.pod
 917  Yes, L<...> is hard.
 918  
 919  
 920  =cut
 921  
 922