← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libpod-simple-perl/trusty

« back to all changes in this revision

Viewing changes to .pc/fix-pod-spelling.patch/lib/Pod/Simple/Subclassing.pod

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Yu
  • Date: 2010-05-01 23:28:32 UTC
  • mfrom: (1.1.9 upstream)
  • Revision ID: james.westby@ubuntu.com-20100501232832-uhsd4zwmusp12z65
Tags: 3.14-1
* New upstream release
* Use new 3.0 (quilt) source format
* Standards-Version 3.8.4 (no changes)
* Add a patch to fix POD spelling errors
* Update copyright information to DEP5 format

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/fix-pod-spelling.patch/lib/Pod/Simple/Subclassing.pod
 
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
=head1 SUPPORT
 
897
 
 
898
Questions or discussion about POD and Pod::Simple should be sent to the
 
899
pod-people@perl.org mail list. Send an empty email to
 
900
pod-people-subscribe@perl.org to subscribe.
 
901
 
 
902
This module is managed in an open GitHub repository,
 
903
L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
 
904
to clone L<git://github.com/theory/pod-simple.git> and send patches!
 
905
 
 
906
Patches against Pod::Simple are welcome. Please send bug reports to
 
907
<bug-pod-simple@rt.cpan.org>.
 
908
 
 
909
=head1 COPYRIGHT AND DISCLAIMERS
 
910
 
 
911
Copyright (c) 2002 Sean M. Burke.
 
912
 
 
913
This library is free software; you can redistribute it and/or modify it
 
914
under the same terms as Perl itself.
 
915
 
 
916
This program is distributed in the hope that it will be useful, but
 
917
without any warranty; without even the implied warranty of
 
918
merchantability or fitness for a particular purpose.
 
919
 
 
920
=head1 AUTHOR
 
921
 
 
922
Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
 
923
But don't bother him, he's retired.
 
924
 
 
925
Pod::Simple is maintained by:
 
926
 
 
927
=over
 
928
 
 
929
=item * Allison Randal C<allison@perl.org>
 
930
 
 
931
=item * Hans Dieter Pearcey C<hdp@cpan.org>
 
932
 
 
933
=item * David E. Wheeler C<dwheeler@cpan.org>
 
934
 
 
935
=back
 
936
 
 
937
=for notes
 
938
Hm, my old podchecker version (1.2) says:
 
939
 *** WARNING: node 'http://search.cpan.org/' contains non-escaped | or / at line 38 in file Subclassing.pod
 
940
 *** WARNING: node 'http://lists.perl.org/showlist.cgi?name=pod-people' contains non-escaped | or / at line 41 in file Subclassing.pod
 
941
Yes, L<...> is hard.
 
942
 
 
943
 
 
944
=cut
 
945
 
 
946