local-lib5/man/man3/Pod::Simple::Subclassing.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Pod::Simple::Subclassing 3"
 132 .TH Pod::Simple::Subclassing 3 "2008-06-03" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Simple::Subclassing \-\- write a formatter as a Pod::Simple subclass
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 5
 138 \&  package Pod::SomeFormatter;
 139 \&  use Pod::Simple;
 140 \&  @ISA = qw(Pod::Simple);
 141 \&  $VERSION = '1.01';
 142 \&  use strict;
 143 .Ve
 144 .PP
 145 .Vb 4
 146 \&  sub _handle_element_start {
 147 \&    my($parser, $element_name, $attr_hash_r) = @_;
 148 \&    ...
 149 \&  }
 150 .Ve
 151 .PP
 152 .Vb 4
 153 \&  sub _handle_element_end {
 154 \&    my($parser, $element_name) = @_;
 155 \&    ...
 156 \&  }
 157 .Ve
 158 .PP
 159 .Vb 5
 160 \&  sub _handle_text {
 161 \&    my($parser, $text) = @_;
 162 \&    ...
 163 \&  }
 164 \&  1;
 165 .Ve
 166 .SH "DESCRIPTION"
 167 .IX Header "DESCRIPTION"
 168 This document is about using Pod::Simple to write a Pod processor,
 169 generally a Pod formatter. If you just want to know about using an
 170 existing Pod formatter, instead see its documentation and see also the
 171 docs in Pod::Simple.
 172 .PP
 173 The zeroeth step in writing a Pod formatter is to make sure that there
 174 isn't already a decent one in \s-1CPAN\s0. See <http://search.cpan.org/>, and
 175 run a search on the name of the format you want to render to. Also
 176 consider joining the Pod People list
 177 <http://lists.perl.org/showlist.cgi?name=pod\-people> and asking whether
 178 anyone has a formatter for that format \*(-- maybe someone cobbled one
 179 together but just hasn't released it.
 180 .PP
 181 The first step in writing a Pod processor is to read perlpodspec,
 182 which contains notes information on writing a Pod parser (which has been
 183 largely taken care of by Pod::Simple), but also a lot of requirements
 184 and recommendations for writing a formatter.
 185 .PP
 186 The second step is to actually learn the format you're planning to
 187 format to \*(-- or at least as much as you need to know to represent Pod,
 188 which probably isn't much.
 189 .PP
 190 The third step is to pick which of Pod::Simple's interfaces you want to
 191 use \*(-- the basic interface via Pod::Simple or Pod::Simple::Methody is
 192 event\-based, sort of like HTML::Parser's interface, or sort of like
 193 XML::Parser's \*(L"Handlers\*(R" interface), but Pod::Simple::PullParser
 194 provides a token-stream interface, sort of like HTML::TokeParser's
 195 interface; Pod::Simple::SimpleTree provides a simple tree interface,
 196 rather like XML::Parser's \*(L"Tree\*(R" interface. Users familiar with
 197 XML-handling will find one of these styles relatively familiar; but if
 198 you would be even more at home with \s-1XML\s0, there are classes that produce
 199 an \s-1XML\s0 representation of the Pod stream, notably
 200 Pod::Simple::XMLOutStream; you can feed the output of such a class to
 201 whatever \s-1XML\s0 parsing system you are most at home with.
 202 .PP
 203 The last step is to write your code based on how the events (or tokens,
 204 or tree\-nodes, or the \s-1XML\s0, or however you're parsing) will map to
 205 constructs in the output format. Also sure to consider how to escape
 206 text nodes containing arbitrary text, and also what to do with text
 207 nodes that represent preformatted text (from verbatim sections).
 208 .SH "Events"
 209 .IX Header "Events"
 210 \&\s-1TODO\s0 intro... mention that events are supplied for implicits, like for
 211 missing >'s
 212 .PP
 213 In the following section, we use \s-1XML\s0 to represent the event structure
 214 associated with a particular construct.  That is, \s-1TODO\s0
 215 .ie n .IP """$parser\->_handle_element_start( \f(CIelement_name\f(CW, \f(CIattr_hashref\f(CW )""" 4
 216 .el .IP "\f(CW$parser\->_handle_element_start( \f(CIelement_name\f(CW, \f(CIattr_hashref\f(CW )\fR" 4
 217 .IX Item "$parser->_handle_element_start( element_name, attr_hashref )"
 218 .PD 0
 219 .ie n .IP """$parser\->_handle_element_end( \f(CIelement_name\f(CW  )""" 4
 220 .el .IP "\f(CW$parser\->_handle_element_end( \f(CIelement_name\f(CW  )\fR" 4
 221 .IX Item "$parser->_handle_element_end( element_name  )"
 222 .ie n .IP """$parser\->_handle_text(  \f(CItext_string\f(CW  )""" 4
 223 .el .IP "\f(CW$parser\->_handle_text(  \f(CItext_string\f(CW  )\fR" 4
 224 .IX Item "$parser->_handle_text(  text_string  )"
 225 .PD
 226 .PP
 227 \&\s-1TODO\s0 describe
 228 .IP "events with an element_name of Document" 4
 229 .IX Item "events with an element_name of Document"
 230 Parsing a document produces this event structure:
 231 .Sp
 232 .Vb 3
 233 \&  <Document start_line="543">
 234 \&    ...all events...
 235 \&  </Document>
 236 .Ve
 237 .Sp
 238 The value of the \fIstart_line\fR attribute will be the line number of the first
 239 Pod directive in the document.
 240 .Sp
 241 If there is no Pod in the given document, then the
 242 event structure will be this:
 243 .Sp
 244 .Vb 2
 245 \&  <Document contentless="1" start_line="543">
 246 \&  </Document>
 247 .Ve
 248 .Sp
 249 In that case, the value of the \fIstart_line\fR attribute will not be meaningful;
 250 under current implementations, it will probably be the line number of the
 251 last line in the file.
 252 .IP "events with an element_name of Para" 4
 253 .IX Item "events with an element_name of Para"
 254 Parsing a plain (non\-verbatim, non\-directive, non\-data) paragraph in
 255 a Pod document produces this event structure:
 256 .Sp
 257 .Vb 3
 258 \&    <Para start_line="543">
 259 \&      ...all events in this paragraph...
 260 \&    </Para>
 261 .Ve
 262 .Sp
 263 The value of the \fIstart_line\fR attribute will be the line number of the start
 264 of the paragraph.
 265 .Sp
 266 For example, parsing this paragraph of Pod:
 267 .Sp
 268 .Vb 2
 269 \&  The value of the I<start_line> attribute will be the
 270 \&  line number of the start of the paragraph.
 271 .Ve
 272 .Sp
 273 produces this event structure:
 274 .Sp
 275 .Vb 8
 276 \&    <Para start_line="129">
 277 \&      The value of the
 278 \&      <I>
 279 \&        start_line
 280 \&      </I>
 281 \&       attribute will be the line number of the first Pod directive
 282 \&      in the document.
 283 \&    </Para>
 284 .Ve
 285 .IP "events with an element_name of B, C, F, or I." 4
 286 .IX Item "events with an element_name of B, C, F, or I."
 287 Parsing a B<...> formatting code (or of course any of its
 288 semantically identical syntactic variants
 289 B<<\ ...\ >>,
 290 or B<<<<\ ...\ >>>>, etc.)
 291 produces this event structure:
 292 .Sp
 293 .Vb 3
 294 \&      <B>
 295 \&        ...stuff...
 296 \&      </B>
 297 .Ve
 298 .Sp
 299 Currently, there are no attributes conveyed.
 300 .Sp
 301 Parsing C, F, or I codes produce the same structure, with only a
 302 different element name.
 303 .Sp
 304 If your parser object has been set to accept other formatting codes,
 305 then they will be presented like these B/C/F/I codes \*(-- i.e., without
 306 any attributes.
 307 .IP "events with an element_name of S" 4
 308 .IX Item "events with an element_name of S"
 309 Normally, parsing an S<...> sequence produces this event
 310 structure, just as if it were a B/C/F/I code:
 311 .Sp
 312 .Vb 3
 313 \&      <S>
 314 \&        ...stuff...
 315 \&      </S>
 316 .Ve
 317 .Sp
 318 However, Pod::Simple (and presumably all derived parsers) offers the
 319 \&\f(CW\*(C`nbsp_for_S\*(C'\fR option which, if enabled, will suppress all S events, and
 320 instead change all spaces in the content to non-breaking spaces. This is
 321 intended for formatters that output to a format that has no code that
 322 means the same as S<...>, but which has a code/character that
 323 means non-breaking space.
 324 .IP "events with an element_name of X" 4
 325 .IX Item "events with an element_name of X"
 326 Normally, parsing an X<...> sequence produces this event
 327 structure, just as if it were a B/C/F/I code:
 328 .Sp
 329 .Vb 3
 330 \&      <X>
 331 \&        ...stuff...
 332 \&      </X>
 333 .Ve
 334 .Sp
 335 However, Pod::Simple (and presumably all derived parsers) offers the
 336 \&\f(CW\*(C`nix_X_codes\*(C'\fR option which, if enabled, will suppress all X events
 337 and ignore their content.  For formatters/processors that don't use
 338 X events, this is presumably quite useful.
 339 .IP "events with an element_name of L" 4
 340 .IX Item "events with an element_name of L"
 341 Because the L<...> is the most complex construct in the
 342 language, it should not surprise you that the events it generates are
 343 the most complex in the language. Most of complexity is hidden away in
 344 the attribute values, so for those of you writing a Pod formatter that
 345 produces a non-hypertextual format, you can just ignore the attributes
 346 and treat an L event structure like a formatting element that
 347 (presumably) doesn't actually produce a change in formatting.  That is,
 348 the content of the L event structure (as opposed to its
 349 attributes) is always what text should be displayed.
 350 .Sp
 351 There are, at first glance, three kinds of L links: \s-1URL\s0, man, and pod.
 352 .Sp
 353 When a L<\fIsome_url\fR> code is parsed, it produces this event
 354 structure:
 355 .Sp
 356 .Vb 3
 357 \&  <L content\-implicit="yes" to="that_url" type="url">
 358 \&    that_url
 359 \&  </L>
 360 .Ve
 361 .Sp
 362 The \f(CW\*(C`type="url"\*(C'\fR attribute is always specified for this type of
 363 L code.
 364 .Sp
 365 For example, this Pod source:
 366 .Sp
 367 .Vb 1
 368 \&  L<http://www.perl.com/CPAN/authors/>
 369 .Ve
 370 .Sp
 371 produces this event structure:
 372 .Sp
 373 .Vb 3
 374 \&  <L content\-implicit="yes" to="http://www.perl.com/CPAN/authors/" type="url">
 375 \&    http://www.perl.com/CPAN/authors/
 376 \&  </L>
 377 .Ve
 378 .Sp
 379 When a L<\fImanpage(section)\fR> code is parsed (and these are
 380 fairly rare and not terribly useful), it produces this event structure:
 381 .Sp
 382 .Vb 3
 383 \&  <L content\-implicit="yes" to="manpage(section)" type="man">
 384 \&    manpage(section)
 385 \&  </L>
 386 .Ve
 387 .Sp
 388 The \f(CW\*(C`type="man"\*(C'\fR attribute is always specified for this type of
 389 L code.
 390 .Sp
 391 For example, this Pod source:
 392 .Sp
 393 .Vb 1
 394 \&  L<crontab(5)>
 395 .Ve
 396 .Sp
 397 produces this event structure:
 398 .Sp
 399 .Vb 3
 400 \&  <L content\-implicit="yes" to="crontab(5)" type="man">
 401 \&    crontab(5)
 402 \&  </L>
 403 .Ve
 404 .Sp
 405 In the rare cases where a man page link has a specified, that text appears
 406 in a \fIsection\fR attribute. For example, this Pod source:
 407 .Sp
 408 .Vb 1
 409 \&  L<crontab(5)/"ENVIRONMENT">
 410 .Ve
 411 .Sp
 412 will produce this event structure:
 413 .Sp
 414 .Vb 3
 415 \&  <L content\-implicit="yes" section="ENVIRONMENT" to="crontab(5)" type="man">
 416 \&    "ENVIRONMENT" in crontab(5)
 417 \&  </L>
 418 .Ve
 419 .Sp
 420 In the rare case where the Pod document has code like
 421 L<\fIsometext\fR|\fImanpage(section)\fR>, then the \fIsometext\fR will appear
 422 as the content of the element, the \fImanpage(section)\fR text will appear
 423 only as the value of the \fIto\fR attribute, and there will be no
 424 \&\f(CW\*(C`content\-implicit="yes"\*(C'\fR attribute (whose presence means that the Pod parser
 425 had to infer what text should appear as the link text \*(-- as opposed to
 426 cases where that attribute is absent, which means that the Pod parser did
 427 \&\fInot\fR have to infer the link text, because that L code explicitly specified
 428 some link text.)
 429 .Sp
 430 For example, this Pod source:
 431 .Sp
 432 .Vb 1
 433 \&  L<hell itself!|crontab(5)>
 434 .Ve
 435 .Sp
 436 will produce this event structure:
 437 .Sp
 438 .Vb 3
 439 \&  <L to="crontab(5)" type="man">
 440 \&    hell itself!
 441 \&  </L>
 442 .Ve
 443 .Sp
 444 The last type of L structure is for links to/within Pod documents. It is
 445 the most complex because it can have a \fIto\fR attribute, \fIor\fR a
 446 \&\fIsection\fR attribute, or both. The \f(CW\*(C`type="pod"\*(C'\fR attribute is always
 447 specified for this type of L code.
 448 .Sp
 449 In the most common case, the simple case of a L<podpage> code
 450 produces this event structure:
 451 .Sp
 452 .Vb 3
 453 \&  <L content\-implicit="yes" to="Net::Ping" type="pod">
 454 \&    podpage
 455 \&  </L>
 456 .Ve
 457 .Sp
 458 For example, this Pod source:
 459 .Sp
 460 .Vb 1
 461 \&  L<Net::Ping>
 462 .Ve
 463 .Sp
 464 produces this event structure:
 465 .Sp
 466 .Vb 3
 467 \&  <L content\-implicit="yes" to="Net::Ping" type="pod">
 468 \&    Net::Ping
 469 \&  </L>
 470 .Ve
 471 .Sp
 472 In cases where there is link-text explicitly specified, it
 473 is to be found in the content of the element (and not the
 474 attributes), just as with the L<\fIsometext\fR|\fImanpage(section)\fR>
 475 case discussed above.  For example, this Pod source:
 476 .Sp
 477 .Vb 1
 478 \&  L<Perl Error Messages|perldiag>
 479 .Ve
 480 .Sp
 481 produces this event structure:
 482 .Sp
 483 .Vb 3
 484 \&  <L to="perldiag" type="pod">
 485 \&    Perl Error Messages
 486 \&  </L>
 487 .Ve
 488 .Sp
 489 In cases of links to a section in the current Pod document,
 490 there is a \fIsection\fR attribute instead of a \fIto\fR attribute.
 491 For example, this Pod source:
 492 .Sp
 493 .Vb 1
 494 \&  L</"Member Data">
 495 .Ve
 496 .Sp
 497 produces this event structure:
 498 .Sp
 499 .Vb 3
 500 \&  <L content\-implicit="yes" section="Member Data" type="pod">
 501 \&    "Member Data"
 502 \&  </L>
 503 .Ve
 504 .Sp
 505 As another example, this Pod source:
 506 .Sp
 507 .Vb 1
 508 \&  L<the various attributes|/"Member Data">
 509 .Ve
 510 .Sp
 511 produces this event structure:
 512 .Sp
 513 .Vb 3
 514 \&  <L section="Member Data" type="pod">
 515 \&    the various attributes
 516 \&  </L>
 517 .Ve
 518 .Sp
 519 In cases of links to a section in a different Pod document,
 520 there are both a \fIsection\fR attribute and a to attribute.
 521 For example, this Pod source:
 522 .Sp
 523 .Vb 1
 524 \&  L<perlsyn/"Basic BLOCKs and Switch Statements">
 525 .Ve
 526 .Sp
 527 produces this event structure:
 528 .Sp
 529 .Vb 3
 530 \&  <L content\-implicit="yes" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
 531 \&    "Basic BLOCKs and Switch Statements" in perlsyn
 532 \&  </L>
 533 .Ve
 534 .Sp
 535 As another example, this Pod source:
 536 .Sp
 537 .Vb 1
 538 \&  L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
 539 .Ve
 540 .Sp
 541 produces this event structure:
 542 .Sp
 543 .Vb 3
 544 \&  <L section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
 545 \&    SWITCH statements
 546 \&  </L>
 547 .Ve
 548 .Sp
 549 Incidentally, note that we do not distinguish between these syntaxes:
 550 .Sp
 551 .Vb 4
 552 \&  L</"Member Data">
 553 \&  L<"Member Data">
 554 \&  L</Member Data>
 555 \&  L<Member Data>    [deprecated syntax]
 556 .Ve
 557 .Sp
 558 That is, they all produce the same event structure, namely:
 559 .Sp
 560 .Vb 3
 561 \&  <L content\-implicit="yes" section="Member Data" type="pod">
 562 \&    &#34;Member Data&#34;
 563 \&  </L>
 564 .Ve
 565 .IP "events with an element_name of E or Z" 4
 566 .IX Item "events with an element_name of E or Z"
 567 While there are Pod codes E<...> and Z<>, these
 568 \&\fIdo not\fR produce any E or Z events \*(-- that is, there are no such
 569 events as E or Z.
 570 .IP "events with an element_name of Verbatim" 4
 571 .IX Item "events with an element_name of Verbatim"
 572 When a Pod verbatim paragraph (\s-1AKA\s0 \*(L"codeblock\*(R") is parsed, it
 573 produces this event structure:
 574 .Sp
 575 .Vb 3
 576 \&  <Verbatim start_line="543" xml:space="preserve">
 577 \&    ...text...
 578 \&  </Verbatim>
 579 .Ve
 580 .Sp
 581 The value of the \fIstart_line\fR attribute will be the line number of the
 582 first line of this verbatim block.  The \fIxml:space\fR attribute is always
 583 present, and always has the value \*(L"preserve\*(R".
 584 .Sp
 585 The text content will have tabs already expanded.
 586 .IP "events with an element_name of head1 .. head4" 4
 587 .IX Item "events with an element_name of head1 .. head4"
 588 When a \*(L"=head1 ...\*(R" directive is parsed, it produces this event
 589 structure:
 590 .Sp
 591 .Vb 3
 592 \&  <head1>
 593 \&    ...stuff...
 594 \&  </head1>
 595 .Ve
 596 .Sp
 597 For example, a directive consisting of this:
 598 .Sp
 599 .Vb 1
 600 \&  =head1 Options to C<new> et al.
 601 .Ve
 602 .Sp
 603 will produce this event structure:
 604 .Sp
 605 .Vb 7
 606 \&  <head1 start_line="543">
 607 \&    Options to
 608 \&    <C>
 609 \&      new
 610 \&    </C>
 611 \&     et al.
 612 \&  </head1>
 613 .Ve
 614 .Sp
 615 \&\*(L"=head2\*(R" thru \*(L"=head4\*(R" directives are the same, except for the element
 616 names in the event structure.
 617 .IP "events with an element_name of over-bullet" 4
 618 .IX Item "events with an element_name of over-bullet"
 619 When an "=over ... \&=back" block is parsed where the items are
 620 a bulletted list, it will produce this event structure:
 621 .Sp
 622 .Vb 6
 623 \&  <over\-bullet indent="4" start_line="543">
 624 \&    <item\-bullet start_line="545">
 625 \&      ...Stuff...
 626 \&    </item\-bullet>
 627 \&    ...more item\-bullets...
 628 \&  </over\-bullet>
 629 .Ve
 630 .Sp
 631 The value of the \fIindent\fR attribute is whatever value is after the
 632 \&\*(L"=over\*(R" directive, as in \*(L"=over 8\*(R".  If no such value is specified
 633 in the directive, then the \fIindent\fR attribute has the value \*(L"4\*(R".
 634 .Sp
 635 For example, this Pod source:
 636 .Sp
 637 .Vb 1
 638 \&  =over
 639 .Ve
 640 .Sp
 641 .Vb 1
 642 \&  =item *
 643 .Ve
 644 .Sp
 645 .Vb 1
 646 \&  Stuff
 647 .Ve
 648 .Sp
 649 .Vb 1
 650 \&  =item *
 651 .Ve
 652 .Sp
 653 .Vb 1
 654 \&  Bar I<baz>!
 655 .Ve
 656 .Sp
 657 .Vb 1
 658 \&  =back
 659 .Ve
 660 .Sp
 661 produces this event structure:
 662 .Sp
 663 .Vb 8
 664 \&  <over\-bullet indent="4" start_line="10">
 665 \&    <item\-bullet start_line="12">
 666 \&      Stuff
 667 \&    </item\-bullet>
 668 \&    <item\-bullet start_line="14">
 669 \&      Bar <I>baz</I>!
 670 \&    </item\-bullet>
 671 \&  </over\-bullet>
 672 .Ve
 673 .IP "events with an element_name of over-number" 4
 674 .IX Item "events with an element_name of over-number"
 675 When an "=over ... \&=back" block is parsed where the items are
 676 a numbered list, it will produce this event structure:
 677 .Sp
 678 .Vb 6
 679 \&  <over\-number indent="4" start_line="543">
 680 \&    <item\-number number="1" start_line="545">
 681 \&      ...Stuff...
 682 \&    </item\-number>
 683 \&    ...more item\-number...
 684 \&  </over\-bullet>
 685 .Ve
 686 .Sp
 687 This is like the \*(L"over\-bullet\*(R" event structure; but note that the contents
 688 are \*(L"item\-number\*(R" instead of \*(L"item\-bullet\*(R", and note that they will have
 689 a \*(L"number\*(R" attribute, which some formatters/processors may ignore
 690 (since, for example, there's no need for it in \s-1HTML\s0 when producing
 691 an \*(L"<\s-1UL\s0><\s-1LI\s0>...</LI>...</UL>\*(R" structure), but which any processor may use.
 692 .Sp
 693 Note that the values for the \fInumber\fR attributes of \*(L"item\-number\*(R"
 694 elements in a given \*(L"over\-number\*(R" area \fIwill\fR start at 1 and go up by
 695 one each time.  If the Pod source doesn't follow that order (even though
 696 it really should should!), whatever numbers it has will be ignored (with
 697 the correct values being put in the \fInumber\fR attributes), and an error
 698 message might be issued to the user.
 699 .IP "events with an element_name of over-text" 4
 700 .IX Item "events with an element_name of over-text"
 701 These events are are somewhat unlike the other over\-*
 702 structures, as far as what their contents are.  When
 703 an "=over ... \&=back\*(L" block is parsed where the items are
 704 a list of text \*(R"subheadings", it will produce this event structure:
 705 .Sp
 706 .Vb 8
 707 \&  <over\-text indent="4" start_line="543">
 708 \&    <item\-text>
 709 \&      ...stuff...
 710 \&    </item\-text>
 711 \&    ...stuff (generally Para or Verbatim elements)...
 712 \&    <item\-text>
 713 \&    ...more item\-text and/or stuff...
 714 \&  </over\-text>
 715 .Ve
 716 .Sp
 717 The \fIindent\fR attribute is as with the other over\-* events.
 718 .Sp
 719 For example, this Pod source:
 720 .Sp
 721 .Vb 1
 722 \&  =over
 723 .Ve
 724 .Sp
 725 .Vb 1
 726 \&  =item Foo
 727 .Ve
 728 .Sp
 729 .Vb 1
 730 \&  Stuff
 731 .Ve
 732 .Sp
 733 .Vb 1
 734 \&  =item Bar I<baz>!
 735 .Ve
 736 .Sp
 737 .Vb 1
 738 \&  Quux
 739 .Ve
 740 .Sp
 741 .Vb 1
 742 \&  =back
 743 .Ve
 744 .Sp
 745 produces this event structure:
 746 .Sp
 747 .Vb 18
 748 \&  <over\-text indent="4" start_line="20">
 749 \&    <item\-text start_line="22">
 750 \&      Foo
 751 \&    </item\-text>
 752 \&    <Para start_line="24">
 753 \&      Stuff
 754 \&    </Para>
 755 \&    <item\-text start_line="26">
 756 \&      Bar
 757 \&        <I>
 758 \&          baz
 759 \&        </I>
 760 \&      !
 761 \&    </item\-text>
 762 \&    <Para start_line="28">
 763 \&      Quux
 764 \&    </Para>
 765 \&  </over\-text>
 766 .Ve
 767 .IP "events with an element_name of over-block" 4
 768 .IX Item "events with an element_name of over-block"
 769 These events are are somewhat unlike the other over\-*
 770 structures, as far as what their contents are.  When
 771 an "=over ... \&=back" block is parsed where there are no items,
 772 it will produce this event structure:
 773 .Sp
 774 .Vb 3
 775 \&  <over\-block indent="4" start_line="543">
 776 \&    ...stuff (generally Para or Verbatim elements)...
 777 \&  </over\-block>
 778 .Ve
 779 .Sp
 780 The \fIindent\fR attribute is as with the other over\-* events.
 781 .Sp
 782 For example, this Pod source:
 783 .Sp
 784 .Vb 1
 785 \&  =over
 786 .Ve
 787 .Sp
 788 .Vb 1
 789 \&  For cutting off our trade with all parts of the world
 790 .Ve
 791 .Sp
 792 .Vb 1
 793 \&  For transporting us beyond seas to be tried for pretended offenses
 794 .Ve
 795 .Sp
 796 .Vb 4
 797 \&  He is at this time transporting large armies of foreign mercenaries to
 798 \&  complete the works of death, desolation and tyranny, already begun with
 799 \&  circumstances of cruelty and perfidy scarcely paralleled in the most
 800 \&  barbarous ages, and totally unworthy the head of a civilized nation.
 801 .Ve
 802 .Sp
 803 .Vb 1
 804 \&  =cut
 805 .Ve
 806 .Sp
 807 will produce this event structure:
 808 .Sp
 809 .Vb 11
 810 \&  <over\-block indent="4" start_line="2">
 811 \&    <Para start_line="4">
 812 \&      For cutting off our trade with all parts of the world
 813 \&    </Para>
 814 \&    <Para start_line="6">
 815 \&      For transporting us beyond seas to be tried for pretended offenses
 816 \&    </Para>
 817 \&    <Para start_line="8">
 818 \&      He is at this time transporting large armies of [...more text...]
 819 \&    </Para>
 820 \&  </over\-block>
 821 .Ve
 822 .IP "events with an element_name of item-bullet" 4
 823 .IX Item "events with an element_name of item-bullet"
 824 See \*(L"events with an element_name of over\-bullet\*(R", above.
 825 .IP "events with an element_name of item-number" 4
 826 .IX Item "events with an element_name of item-number"
 827 See \*(L"events with an element_name of over\-number\*(R", above.
 828 .IP "events with an element_name of item-text" 4
 829 .IX Item "events with an element_name of item-text"
 830 See \*(L"events with an element_name of over\-text\*(R", above.
 831 .IP "events with an element_name of for" 4
 832 .IX Item "events with an element_name of for"
 833 \&\s-1TODO\s0...
 834 .IP "events with an element_name of Data" 4
 835 .IX Item "events with an element_name of Data"
 836 \&\s-1TODO\s0...
 837 .SH "More Pod::Simple Methods"
 838 .IX Header "More Pod::Simple Methods"
 839 Pod::Simple provides a lot of methods that aren't generally interesting
 840 to the end user of an existing Pod formatter, but some of which you
 841 might find useful in writing a Pod formatter. They are listed below. The
 842 first several methods (the accept_* methods) are for declaring the
 843 capabilites of your parser, notably what \f(CW\*(C`=for \f(CItargetname\f(CW\*(C'\fR sections
 844 it's interested in, what extra N<...> codes it accepts beyond
 845 the ones described in the \fIperlpod\fR.
 846 .ie n .IP """$parser\->accept_targets( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
 847 .el .IP "\f(CW$parser\->accept_targets( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
 848 .IX Item "$parser->accept_targets( SOMEVALUE )"
 849 As the parser sees sections like:
 850 .Sp
 851 .Vb 1
 852 \&    =for html  <img src="fig1.jpg">
 853 .Ve
 854 .Sp
 855 or
 856 .Sp
 857 .Vb 1
 858 \&    =begin html
 859 .Ve
 860 .Sp
 861 .Vb 1
 862 \&      <img src="fig1.jpg">
 863 .Ve
 864 .Sp
 865 .Vb 1
 866 \&    =end html
 867 .Ve
 868 .Sp
 869 \&...the parser will ignore these sections unless your subclass has
 870 specified that it wants to see sections targetted to \*(L"html\*(R" (or whatever
 871 the formatter name is).
 872 .Sp
 873 If you want to process all sections, even if they're not targetted for you,
 874 call this before you start parsing:
 875 .Sp
 876 .Vb 1
 877 \&  $parser\->accept_targets('*');
 878 .Ve
 879 .ie n .IP """$parser\->accept_targets_as_text(  \f(CI\s-1SOMEVALUE\s0\f(CW  )""" 4
 880 .el .IP "\f(CW$parser\->accept_targets_as_text(  \f(CI\s-1SOMEVALUE\s0\f(CW  )\fR" 4
 881 .IX Item "$parser->accept_targets_as_text(  SOMEVALUE  )"
 882 This is like accept_targets, except that it specifies also that the
 883 content of sections for this target should be treated as Pod text even
 884 if the target name in "=for \fItargetname\fR\*(L" doesn't start with a \*(R":".
 885 .Sp
 886 At time of writing, I don't think you'll need to use this.
 887 .ie n .IP """$parser\->accept_codes( \f(CICodename\f(CW, \f(CICodename\f(CW...  )""" 4
 888 .el .IP "\f(CW$parser\->accept_codes( \f(CICodename\f(CW, \f(CICodename\f(CW...  )\fR" 4
 889 .IX Item "$parser->accept_codes( Codename, Codename...  )"
 890 This tells the parser that you accept additional formatting codes,
 891 beyond just the standard ones (I B C L F S X, plus the two weird ones
 892 you don't actually see in the parse tree, Z and E). For example, to also
 893 accept codes \*(L"N\*(R", \*(L"R\*(R", and \*(L"W\*(R":
 894 .Sp
 895 .Vb 1
 896 \&    $parser\->accept_codes( qw( N R W ) );
 897 .Ve
 898 .Sp
 899 \&\fB\s-1TODO:\s0 document how this interacts with =extend, and long element names\fR
 900 .ie n .IP """$parser\->accept_directive_as_data( \f(CIdirective_name\f(CW )""" 4
 901 .el .IP "\f(CW$parser\->accept_directive_as_data( \f(CIdirective_name\f(CW )\fR" 4
 902 .IX Item "$parser->accept_directive_as_data( directive_name )"
 903 .PD 0
 904 .ie n .IP """$parser\->accept_directive_as_verbatim( \f(CIdirective_name\f(CW )""" 4
 905 .el .IP "\f(CW$parser\->accept_directive_as_verbatim( \f(CIdirective_name\f(CW )\fR" 4
 906 .IX Item "$parser->accept_directive_as_verbatim( directive_name )"
 907 .ie n .IP """$parser\->accept_directive_as_processed( \f(CIdirective_name\f(CW )""" 4
 908 .el .IP "\f(CW$parser\->accept_directive_as_processed( \f(CIdirective_name\f(CW )\fR" 4
 909 .IX Item "$parser->accept_directive_as_processed( directive_name )"
 910 .PD
 911 In the unlikely situation that you need to tell the parser that you will
 912 accept additional directives (\*(L"=foo\*(R" things), you need to first set the
 913 parset to treat its content as data (i.e., not really processed at
 914 all), or as verbatim (mostly just expanding tabs), or as processed text
 915 (parsing formatting codes like B<...>).
 916 .Sp
 917 For example, to accept a new directive \*(L"=method\*(R", you'd presumably
 918 use:
 919 .Sp
 920 .Vb 1
 921 \&    $parser\->accept_directive_as_processed("method");
 922 .Ve
 923 .Sp
 924 so that you could have Pod lines like:
 925 .Sp
 926 .Vb 1
 927 \&    =method I<$whatever> thing B<um>
 928 .Ve
 929 .Sp
 930 Making up your own directives breaks compatibility with other Pod
 931 formatters, in a way that using "=for \fItarget\fR ..." lines doesn't;
 932 however, you may find this useful if you're making a Pod superset
 933 format where you don't need to worry about compatibility.
 934 .ie n .IP """$parser\->nbsp_for_S( \f(CI\s-1BOOLEAN\s0\f(CW );""" 4
 935 .el .IP "\f(CW$parser\->nbsp_for_S( \f(CI\s-1BOOLEAN\s0\f(CW );\fR" 4
 936 .IX Item "$parser->nbsp_for_S( BOOLEAN );"
 937 Setting this attribute to a true value (and by default it is false) will
 938 turn "S<...>" sequences into sequences of words separated by
 939 \&\f(CW\*(C`\exA0\*(C'\fR (non\-breaking space) characters. For example, it will take this:
 940 .Sp
 941 .Vb 1
 942 \&    I like S<Dutch apple pie>, don't you?
 943 .Ve
 944 .Sp
 945 and treat it as if it were:
 946 .Sp
 947 .Vb 1
 948 \&    I like DutchE<nbsp>appleE<nbsp>pie, don't you?
 949 .Ve
 950 .Sp
 951 This is handy for output formats that don't have anything quite like an
 952 "S<...>" code, but which do have a code for non-breaking space.
 953 .Sp
 954 There is currently no method for going the other way; but I can
 955 probably provide one upon request.
 956 .ie n .IP """$parser\->version_report()""" 4
 957 .el .IP "\f(CW$parser\->version_report()\fR" 4
 958 .IX Item "$parser->version_report()"
 959 This returns a string reporting the \f(CW$VERSION\fR value from your module (and
 960 its classname) as well as the \f(CW$VERSION\fR value of Pod::Simple.  Note that
 961 perlpodspec requires output formats (wherever possible) to note
 962 this detail in a comment in the output format.  For example, for
 963 some kind of \s-1SGML\s0 output format:
 964 .Sp
 965 .Vb 1
 966 \&    print OUT "<!\-\- \en", $parser\->version_report, "\en \-\->";
 967 .Ve
 968 .ie n .IP """$parser\->pod_para_count()""" 4
 969 .el .IP "\f(CW$parser\->pod_para_count()\fR" 4
 970 .IX Item "$parser->pod_para_count()"
 971 This returns the count of Pod paragraphs seen so far.
 972 .ie n .IP """$parser\->line_count()""" 4
 973 .el .IP "\f(CW$parser\->line_count()\fR" 4
 974 .IX Item "$parser->line_count()"
 975 This is the current line number being parsed. But you might find the
 976 \&\*(L"line_number\*(R" event attribute more accurate, when it is present.
 977 .ie n .IP """$parser\->nix_X_codes(  \f(CI\s-1SOMEVALUE\s0\f(CW  )""" 4
 978 .el .IP "\f(CW$parser\->nix_X_codes(  \f(CI\s-1SOMEVALUE\s0\f(CW  )\fR" 4
 979 .IX Item "$parser->nix_X_codes(  SOMEVALUE  )"
 980 This attribute, when set to a true value (and it is false by default)
 981 ignores any "X<...>" sequences in the document being parsed.
 982 Many formats don't actually use the content of these codes, so have
 983 no reason to process them.
 984 .ie n .IP """$parser\->merge_text(  \f(CI\s-1SOMEVALUE\s0\f(CW  )""" 4
 985 .el .IP "\f(CW$parser\->merge_text(  \f(CI\s-1SOMEVALUE\s0\f(CW  )\fR" 4
 986 .IX Item "$parser->merge_text(  SOMEVALUE  )"
 987 This attribute, when set to a true value (and it is false by default)
 988 makes sure that only one event (or token, or node) will be created
 989 for any single contiguous sequence of text.  For example, consider
 990 this somewhat contrived example:
 991 .Sp
 992 .Vb 1
 993 \&    I just LOVE Z<>hotE<32>apple pie!
 994 .Ve
 995 .Sp
 996 When that is parsed and events are about to be called on it, it may
 997 actually seem to be four different text events, one right after another:
 998 one event for \*(L"I just \s-1LOVE\s0 \*(R", one for \*(L"hot\*(R", one for \*(L" \*(R", and one for
 999 \&\*(L"apple pie!\*(R". But if you have merge_text on, then you're guaranteed
1000 that it will be fired as one text event:  \*(L"I just \s-1LOVE\s0 hot apple pie!\*(R".
1001 .ie n .IP """$parser\->code_handler(  \f(CI\s-1CODE_REF\s0\f(CW  )""" 4
1002 .el .IP "\f(CW$parser\->code_handler(  \f(CI\s-1CODE_REF\s0\f(CW  )\fR" 4
1003 .IX Item "$parser->code_handler(  CODE_REF  )"
1004 This specifies code that should be called when a code line is seen
1005 (i.e., a line outside of the Pod).  Normally this is undef, meaning
1006 that no code should be called.  If you provide a routine, it should
1007 start out like this:
1008 .Sp
1009 .Vb 4
1010 \&    sub get_code_line {  # or whatever you'll call it
1011 \&      my($line, $line_number, $parser) = @_;
1012 \&      ...
1013 \&    }
1014 .Ve
1015 .Sp
1016 Note, however, that sometimes the Pod events aren't processed in exactly
1017 the same order as the code lines are \*(-- i.e., if you have a file with
1018 Pod, then code, then more Pod, sometimes the code will be processed (via
1019 whatever you have code_handler call) before the all of the preceding Pod
1020 has been processed.
1021 .ie n .IP """$parser\->cut_handler(  \f(CI\s-1CODE_REF\s0\f(CW  )""" 4
1022 .el .IP "\f(CW$parser\->cut_handler(  \f(CI\s-1CODE_REF\s0\f(CW  )\fR" 4
1023 .IX Item "$parser->cut_handler(  CODE_REF  )"
1024 This is just like the code_handler attribute, except that it's for
1025 \&\*(L"=cut\*(R" lines, not code lines. The same caveats apply. \*(L"=cut\*(R" lines are
1026 unlikely to be interesting, but this is included for completeness.
1027 .ie n .IP """$parser\->whine( \f(CIlinenumber\f(CW, \f(CIcomplaint string\f(CW )""" 4
1028 .el .IP "\f(CW$parser\->whine( \f(CIlinenumber\f(CW, \f(CIcomplaint string\f(CW )\fR" 4
1029 .IX Item "$parser->whine( linenumber, complaint string )"
1030 This notes a problem in the Pod, which will be reported to in the \*(L"Pod
1031 Errors\*(R" section of the document and/or send to \s-1STDERR\s0, depending on the
1032 values of the attributes \f(CW\*(C`no_whining\*(C'\fR, \f(CW\*(C`no_errata_section\*(C'\fR, and
1033 \&\f(CW\*(C`complain_stderr\*(C'\fR.
1034 .ie n .IP """$parser\->scream( \f(CIlinenumber\f(CW, \f(CIcomplaint string\f(CW )""" 4
1035 .el .IP "\f(CW$parser\->scream( \f(CIlinenumber\f(CW, \f(CIcomplaint string\f(CW )\fR" 4
1036 .IX Item "$parser->scream( linenumber, complaint string )"
1037 This notes an error like \f(CW\*(C`whine\*(C'\fR does, except that it is not
1038 suppressable with \f(CW\*(C`no_whining\*(C'\fR. This should be used only for very
1039 serious errors.
1040 .ie n .IP """$parser\->source_dead(1)""" 4
1041 .el .IP "\f(CW$parser\->source_dead(1)\fR" 4
1042 .IX Item "$parser->source_dead(1)"
1043 This aborts parsing of the current document, by switching on the flag
1044 that indicates that \s-1EOF\s0 has been seen.  In particularly drastic cases,
1045 you might want to do this.  It's rather nicer than just calling
1046 \&\f(CW\*(C`die\*(C'\fR!
1047 .ie n .IP """$parser\->hide_line_numbers( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
1048 .el .IP "\f(CW$parser\->hide_line_numbers( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
1049 .IX Item "$parser->hide_line_numbers( SOMEVALUE )"
1050 Some subclasses that indescriminately dump event attributes (well,
1051 except for ones beginning with \*(L"~\*(R") can use this object attribute for
1052 refraining to dump the \*(L"start_line\*(R" attribute.
1053 .ie n .IP """$parser\->no_whining( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
1054 .el .IP "\f(CW$parser\->no_whining( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
1055 .IX Item "$parser->no_whining( SOMEVALUE )"
1056 This attribute, if set to true, will suppress reports of non-fatal
1057 error messages.  The default value is false, meaning that complaints
1058 \&\fIare\fR reported.  How they get reported depends on the values of
1059 the attributes \f(CW\*(C`no_errata_section\*(C'\fR and \f(CW\*(C`complain_stderr\*(C'\fR.
1060 .ie n .IP """$parser\->no_errata_section( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
1061 .el .IP "\f(CW$parser\->no_errata_section( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
1062 .IX Item "$parser->no_errata_section( SOMEVALUE )"
1063 This attribute, if set to true, will suppress generation of an errata
1064 section.  The default value is false \*(-- i.e., an errata section will be
1065 generated.
1066 .ie n .IP """$parser\->complain_stderr( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
1067 .el .IP "\f(CW$parser\->complain_stderr( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
1068 .IX Item "$parser->complain_stderr( SOMEVALUE )"
1069 This attribute, if set to true will send complaints to \s-1STDERR\s0.  The
1070 default value is false \*(-- i.e., complaints do not go to \s-1STDERR\s0.
1071 .ie n .IP """$parser\->bare_output( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
1072 .el .IP "\f(CW$parser\->bare_output( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
1073 .IX Item "$parser->bare_output( SOMEVALUE )"
1074 Some formatter subclasses use this as a flag for whether output should
1075 have prologue and epilogue code omitted. For example, setting this to
1076 true for an \s-1HTML\s0 formatter class should omit the
1077 \&\*(L"<html><head><title>...</title><body>...\*(R" prologue and the
1078 \&\*(L"</body></html>\*(R" epilogue.
1079 .Sp
1080 If you want to set this to true, you should probably also set
1081 \&\f(CW\*(C`no_whining\*(C'\fR or at least \f(CW\*(C`no_errata_section\*(C'\fR to true.
1082 .ie n .IP """$parser\->preserve_whitespace( \f(CI\s-1SOMEVALUE\s0\f(CW )""" 4
1083 .el .IP "\f(CW$parser\->preserve_whitespace( \f(CI\s-1SOMEVALUE\s0\f(CW )\fR" 4
1084 .IX Item "$parser->preserve_whitespace( SOMEVALUE )"
1085 If you set this attribute to a true value, the parser will try to
1086 preserve whitespace in the output.  This means that such formatting
1087 conventions as two spaces after periods will be preserved by the parser.
1088 This is primarily useful for output formats that treat whitespace as
1089 significant (such as text or *roff, but not \s-1HTML\s0).
1090 .SH "SEE ALSO"
1091 .IX Header "SEE ALSO"
1092 Pod::Simple \*(-- event-based Pod-parsing framework
1093 .PP
1094 Pod::Simple::Methody \*(-- like Pod::Simple, but each sort of event
1095 calls its own method (like \f(CW\*(C`start_head3\*(C'\fR)
1096 .PP
1097 Pod::Simple::PullParser \*(-- a Pod-parsing framework like Pod::Simple,
1098 but with a token-stream interface
1099 .PP
1100 Pod::Simple::SimpleTree \*(-- a Pod-parsing framework like Pod::Simple,
1101 but with a tree interface
1102 .PP
1103 Pod::Simple::Checker \*(-- a simple Pod::Simple subclass that reads
1104 documents, and then makes a plaintext report of any errors found in the
1105 document
1106 .PP
1107 Pod::Simple::DumpAsXML \*(-- for dumping Pod documents as tidily
1108 indented \s-1XML\s0, showing each event on its own line
1109 .PP
1110 Pod::Simple::XMLOutStream \*(-- dumps a Pod document as \s-1XML\s0 (without
1111 introducing extra whitespace as Pod::Simple::DumpAsXML does).
1112 .PP
1113 Pod::Simple::DumpAsText \*(-- for dumping Pod documents as tidily
1114 indented text, showing each event on its own line
1115 .PP
1116 Pod::Simple::LinkSection \*(-- class for objects representing the values
1117 of the \s-1TODO\s0 and \s-1TODO\s0 attributes of L<...> elements
1118 .PP
1119 Pod::Escapes \*(-- the module the Pod::Simple uses for evaluating
1120 E<...> content
1121 .PP
1122 Pod::Simple::Text \*(-- a simple plaintext formatter for Pod
1123 .PP
1124 Pod::Simple::TextContent \*(-- like Pod::Simple::Text, but
1125 makes no effort for indent or wrap the text being formatted
1126 .PP
1127 perlpod
1128 .PP
1129 perlpodspec
1130 .PP
1131 perldoc
1132 .SH "COPYRIGHT AND DISCLAIMERS"
1133 .IX Header "COPYRIGHT AND DISCLAIMERS"
1134 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
1135 .PP
1136 This library is free software; you can redistribute it and/or modify it
1137 under the same terms as Perl itself.
1138 .PP
1139 This program is distributed in the hope that it will be useful, but
1140 without any warranty; without even the implied warranty of
1141 merchantability or fitness for a particular purpose.
1142 .SH "AUTHOR"
1143 .IX Header "AUTHOR"
1144 Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR