Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

import Pod::Simple 0.96 from CPAN

git-cpan-module: Pod::Simple
git-cpan-version: 0.96
git-cpan-authorid: SBURKE
  • Loading branch information...
commit 67346fe0724120436df6bb9022e2705db53b9b73 1 parent 48d7dcf
authored November 19, 2002 schwern committed December 03, 2009
16  ChangeLog
... ...
@@ -1,5 +1,19 @@
1  
-# ChangeLog for Pod::Simple dist     # Time-stamp: "2002-11-10 01:47:14 MST"
  1
+# ChangeLog for Pod::Simple dist     # Time-stamp: "2002-11-20 00:28:53 MST"
2 2
 
  3
+2002-11-19  Sean M. Burke <sburke@cpan.org>
  4
+	* Release 0.96
  5
+	* Still kinda sorta beta.
  6
+
  7
+	* Much much more docs in this version.  Only a few feature
  8
+	changes:
  9
+
  10
+	* Added any_errata_seen to Pod::Simple.  Should've been in there
  11
+	ages ago.  Oops!
  12
+	* Fixed some errors in the experimental VerbatimFormatted code.
  13
+	* Added is_tagname / is_tag to Pod::Simple::PullParserStartToken
  14
+	and Pod::Simple::PullParserEndToken
  15
+	* Added RTFDEFLANG stuff to Pod::Simple::RTF.
  16
+	
3 17
 2002-11-10  Sean M. Burke <sburke@cpan.org>
4 18
 	* Release 0.95
5 19
 	* Beta release.  Much documentation still to write, many features
9  lib/Pod/Simple.pm
@@ -16,7 +16,7 @@ use vars qw(
16 16
 );
17 17
 
18 18
 @ISA = ('Pod::Simple::BlackBox');
19  
-$VERSION = '0.95';
  19
+$VERSION = '0.96';
20 20
 
21 21
 @Known_formatting_codes = qw(I B C L E F S X Z); 
22 22
 %Known_formatting_codes = map(($_=>1), @Known_formatting_codes);
@@ -89,6 +89,12 @@ __PACKAGE__->_accessorize(
89 89
 );
90 90
 
91 91
 #@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  92
+
  93
+sub any_errata_seen {  # good for using as an exit() value...
  94
+  return shift->{'errors_seen'} || 0;
  95
+}
  96
+
  97
+#@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
92 98
 # Pull in some functions that, for some reason, I expect to see here too:
93 99
 BEGIN {
94 100
   *pretty        = \&Pod::Simple::BlackBox::pretty;
@@ -321,6 +327,7 @@ sub parse_file {
321 327
 
322 328
 sub parse_from_file {
323 329
   # An emulation of Pod::Parser's interface, for the sake of Perldoc.
  330
+  # Basically just a wrapper around parse_file.
324 331
 
325 332
   my($self, $source, $to) = @_;
326 333
   $self = $self->new unless ref($self); # so we tolerate being a class method
24  lib/Pod/Simple/BlackBox.pm
@@ -1050,9 +1050,24 @@ sub _verbatim_format {
1050 1050
   for(my $i = $#$p; $i > 2; $i--) {
1051 1051
     # work backwards over the lines, except the first (#2)
1052 1052
     
1053  
-    next unless $p->[$i]   =~ m{^#:([ \^\/\%]*)\n?$}s
1054  
-            and $p->[$i-1] !~ m{^#:[ \^\/\%]*\n?$}s;
  1053
+    #next unless $p->[$i]   =~ m{^#:([ \^\/\%]*)\n?$}s
  1054
+    #        and $p->[$i-1] !~ m{^#:[ \^\/\%]*\n?$}s;
1055 1055
      # look at a formatty line preceding a nonformatty one
  1056
+    DEBUG > 5 and print "Scrutinizing line $i: $$p[$i]\n";
  1057
+    if($p->[$i]   =~ m{^#:([ \^\/\%]*)\n?$}s) {
  1058
+      DEBUG > 5 and print "  It's a formatty line.  ",
  1059
+       "Peeking at previous line ", $i-1, ": $$p[$i-1]: \n";
  1060
+      
  1061
+      if( $p->[$i-1] =~ m{^#:[ \^\/\%]*\n?$}s ) {
  1062
+        DEBUG > 5 and print "  Previous line is formatty!  Skipping this one.\n";
  1063
+        next;
  1064
+      } else {
  1065
+        DEBUG > 5 and print "  Previous line is non-formatty!  Yay!\n";
  1066
+      }
  1067
+    } else {
  1068
+      DEBUG > 5 and print "  It's not a formatty line.  Ignoring\n";
  1069
+      next;
  1070
+    }
1056 1071
 
1057 1072
     # A formatty line has to have #: in the first two columns, and uses
1058 1073
     # "^" to mean bold, "/" to mean underline, and "%" to mean bold italic.
@@ -1102,7 +1117,10 @@ sub _verbatim_format {
1102 1117
       }
1103 1118
     }
1104 1119
     splice @$p, $i-1, 2, @new_line; # replace myself and the next line
1105  
-    $i -= @new_line; # Skip however many things we've just added!
  1120
+    DEBUG > 6 and print "New tokens: ", map( ref($_)?"<@$_> ":"<$_>", @new_line ), "\n";
  1121
+    $i -= @new_line - 2
  1122
+      # Skip however many things we've just added,
  1123
+      #  minus the two tokens we just nixed.
1106 1124
   }
1107 1125
 
1108 1126
   $p->[0] = 'VerbatimFormatted';
17  lib/Pod/Simple/Checker.pm
@@ -9,7 +9,7 @@ use Carp ();
9 9
 use Pod::Simple::Methody ();
10 10
 use Pod::Simple ();
11 11
 use vars qw( @ISA $VERSION );
12  
-$VERSION = '1.01';
  12
+$VERSION = '1.02';
13 13
 @ISA = ('Pod::Simple::Methody');
14 14
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
15 15
           ? \&Pod::Simple::DEBUG
@@ -131,27 +131,26 @@ __END__
131 131
 
132 132
 =head1 NAME
133 133
 
134  
-TODO - TODO
  134
+Pod::Simple::Checker -- check the Pod syntax of a document
135 135
 
136 136
 =head1 SYNOPSIS
137 137
 
138  
- TODO
139  
-
140 138
   perl -MPod::Simple::Checker -e \
141 139
    "exit Pod::Simple::Checker->filter(shift)->any_errata_seen" \
142 140
    thingy.pod
143 141
 
144  
-
145 142
 =head1 DESCRIPTION
146 143
 
147  
-This class is for TODO.
148  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  144
+This class is for checking the syntactic validity of Pod.
  145
+It works by basically acting like a simple-minded version of
  146
+L<Pod::Simple::Text> that formats only the "Pod Errors" section
  147
+(if Pod::Simple even generates one for the given document).
149 148
 
150  
-TODO
  149
+This is a subclass of L<Pod::Simple> and inherits all its methods.
151 150
 
152 151
 =head1 SEE ALSO
153 152
 
154  
-L<Pod::Simple>
  153
+L<Pod::Simple>, L<Pod::Simple::Text>, L<Pod::Checker>
155 154
 
156 155
 =head1 COPYRIGHT AND DISCLAIMERS
157 156
 
62  lib/Pod/Simple/Debug.pm
@@ -63,23 +63,75 @@ __END__
63 63
 
64 64
 =head1 NAME
65 65
 
66  
-TODO - TODO
  66
+Pod::Simple::Debug -- put Pod::Simple into trace/debug mode
67 67
 
68 68
 =head1 SYNOPSIS
69 69
 
70  
- TODO
  70
+ use Pod::Simple::Debug (5);  # or some integer
  71
+
  72
+Or:
  73
+
  74
+ my $debuglevel;
  75
+ use Pod::Simple::Debug (\$debuglevel, 0);
  76
+ ...some stuff that uses Pod::Simple to do stuff, but which
  77
+  you don't want debug output from...
  78
+
  79
+ $debug_level = 4;
  80
+ ...some stuff that uses Pod::Simple to do stuff, but which
  81
+  you DO want debug output from...
  82
+
  83
+ $debug_level = 0;
71 84
 
72 85
 =head1 DESCRIPTION
73 86
 
74  
-This class is for TODO.
75  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  87
+This is an internal module for controlling the debug level (a.k.a. trace
  88
+level) of Pod::Simple.  This is of interest only to Pod::Simple
  89
+developers.
  90
+
  91
+
  92
+=head1 CAVEATS
  93
+
  94
+Note that you should load this module I<before> loading Pod::Simple (or
  95
+any Pod::Simple-based class).  If you try loading Pod::Simple::Debug
  96
+after &Pod::Simple::DEBUG is already defined, Pod::Simple::Debug will
  97
+throw a fatal error to the effect that
  98
+"it's s too late to call Pod::Simple::Debug".
  99
+
  100
+Note that the C<use Pod::Simple::Debug (\$x, I<somenum>)> mode will make
  101
+Pod::Simple (et al) run rather slower, since &Pod::Simple::DEBUG won't
  102
+be a constant sub anymore, and so Pod::Simple (et al) won't compile with
  103
+constant-folding.
  104
+
76 105
 
77  
-TODO
  106
+=head1 GUTS
  107
+
  108
+Doing this:
  109
+
  110
+  use Pod::Simple::Debug (5);  # or some integer
  111
+
  112
+is basically equivalent to:
  113
+
  114
+  BEGIN { sub Pod::Simple::DEBUG () {5} }  # or some integer
  115
+  use Pod::Simple ();
  116
+
  117
+And this:
  118
+
  119
+  use Pod::Simple::Debug (\$debug_level,0);  # or some integer
  120
+
  121
+is basically equivalent to this:
  122
+
  123
+  my $debug_level;
  124
+  BEGIN { $debug_level = 0 }
  125
+  BEGIN { sub Pod::Simple::DEBUG () { $debug_level }
  126
+  use Pod::Simple ();
78 127
 
79 128
 =head1 SEE ALSO
80 129
 
81 130
 L<Pod::Simple>
82 131
 
  132
+The article "Constants in Perl", in I<The Perl Journal> issue
  133
+21.  See L<http://www.sysadminmag.com/tpj/issues/vol5_5/>
  134
+
83 135
 =head1 COPYRIGHT AND DISCLAIMERS
84 136
 
85 137
 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
15  lib/Pod/Simple/DumpAsText.pm
... ...
@@ -1,7 +1,7 @@
1 1
 
2 2
 require 5;
3 3
 package Pod::Simple::DumpAsText;
4  
-$VERSION = '1.01';
  4
+$VERSION = '1.02';
5 5
 use Pod::Simple ();
6 6
 BEGIN {@ISA = ('Pod::Simple')}
7 7
 
@@ -15,6 +15,7 @@ sub new {
15 15
   my $self = shift;
16 16
   my $new = $self->SUPER::new(@_);
17 17
   $new->{'output_fh'} ||= *STDOUT{IO};
  18
+  $new->accept_codes('VerbatimFormatted');
18 19
   return $new;
19 20
 }
20 21
 
@@ -87,7 +88,7 @@ __END__
87 88
 
88 89
 =head1 NAME
89 90
 
90  
-TODO - TODO
  91
+Pod::Simple::DumpAsText -- dump Pod-parsing events as text
91 92
 
92 93
 =head1 SYNOPSIS
93 94
 
@@ -97,13 +98,17 @@ TODO - TODO
97 98
 
98 99
 =head1 DESCRIPTION
99 100
 
100  
-This class is for TODO.
101  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  101
+This class is for dumping, as text, the events gotten from parsing a Pod
  102
+document.  This class is of interest to people writing Pod formatters
  103
+based on Pod::Simple. It is useful for seeing exactly what events you
  104
+get out of some Pod that you feed in.
102 105
 
103  
-TODO
  106
+This is a subclass of L<Pod::Simple> and inherits all its methods.
104 107
 
105 108
 =head1 SEE ALSO
106 109
 
  110
+L<Pod::Simple::DumpAsXML>
  111
+
107 112
 L<Pod::Simple>
108 113
 
109 114
 =head1 COPYRIGHT AND DISCLAIMERS
35  lib/Pod/Simple/DumpAsXML.pm
... ...
@@ -1,7 +1,7 @@
1 1
 
2 2
 require 5;
3 3
 package Pod::Simple::DumpAsXML;
4  
-$VERSION = '1.02';
  4
+$VERSION = '1.01';
5 5
 use Pod::Simple ();
6 6
 BEGIN {@ISA = ('Pod::Simple')}
7 7
 
@@ -9,10 +9,6 @@ use strict;
9 9
 
10 10
 use Carp ();
11 11
 
12  
-# TODO: note that this is padding with WS
13  
-# TODO: make a setting for leaving off the line number attributes?
14  
-
15  
-
16 12
 BEGIN { *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG }
17 13
 
18 14
 sub new {
@@ -95,26 +91,41 @@ __END__
95 91
 
96 92
 =head1 NAME
97 93
 
98  
-TODO - TODO
  94
+Pod::Simple::DumpAsXML -- turn Pod into XML
99 95
 
100 96
 =head1 SYNOPSIS
101 97
 
102  
- TODO
103  
-
104 98
   perl -MPod::Simple::DumpAsXML -e \
105 99
    "exit Pod::Simple::DumpAsXML->filter(shift)->any_errata_seen" \
106 100
    thingy.pod
107 101
 
108 102
 =head1 DESCRIPTION
109 103
 
110  
-This class is for TODO.
111  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  104
+Pod::Simple::DumpAsXML is a subclass of L<Pod::Simple> that parses Pod
  105
+and turns it into indented and wrapped XML.  This class is of
  106
+interest to people writing Pod formatters based on Pod::Simple.
  107
+
  108
+Pod::Simple::DumpAsXML inherits methods from
  109
+L<Pod::Simple>.
112 110
 
113  
-TODO
114 111
 
115 112
 =head1 SEE ALSO
116 113
 
117  
-L<Pod::Simple>
  114
+L<Pod::Simple::XMLOutStream> is rather like this class.
  115
+Pod::Simple::XMLOutStream's output is space-padded in a way
  116
+that's better for sending to an XML processor (that is, it has
  117
+no ignoreable whitespace). But
  118
+Pod::Simple::DumpAsXML's output is much more human-readable, being
  119
+(more-or-less) one token per line, with line-wrapping.
  120
+
  121
+L<Pod::Simple::DumpAsText> is rather like this class,
  122
+except that it doesn't dump with XML syntax.  Try them and see
  123
+which one you like best!
  124
+
  125
+L<Pod::Simple>, L<Pod::Simple::DumpAsXML>
  126
+
  127
+The older libraries L<Pod::PXML>, L<Pod::XML>, L<Pod::SAX>
  128
+
118 129
 
119 130
 =head1 COPYRIGHT AND DISCLAIMERS
120 131
 
49  lib/Pod/Simple/LinkSection.pm
@@ -70,18 +70,57 @@ __END__
66  lib/Pod/Simple/Methody.pm
@@ -3,9 +3,13 @@ require 5;
3 3
 package Pod::Simple::Methody;
4 4
 use strict;
5 5
 use Pod::Simple ();
6  
-use vars qw(@ISA);
  6
+use vars qw(@ISA $VERSION);
  7
+$VERSION = 1.02;
7 8
 @ISA = ('Pod::Simple');
8 9
 
  10
+# Yes, we could use named variables, but I want this to be impose
  11
+# as little an additional performance hit as possible.
  12
+
9 13
 sub _handle_element_start {
10 14
   $_[1] =~ tr/-:./__/;
11 15
   ( $_[0]->can( 'start_' . $_[1] )
@@ -39,22 +43,70 @@ __END__
39 43
 
40 44
 =head1 NAME
41 45
 
42  
-TODO - TODO
  46
+Pod::Simple::Methody -- turn Pod::Simple events into method calls
43 47
 
44 48
 =head1 SYNOPSIS
45 49
 
46  
- TODO
  50
+ require 5;
  51
+ use strict;
  52
+ package SomePodFormatter;
  53
+ use base qw(Pod::Simple::Methody);
  54
+ 
  55
+ sub handle_text {
  56
+   my($self, $text) = @_;
  57
+   ...
  58
+ }
  59
+ 
  60
+ sub start_head1 {
  61
+   my($self, $attrs) = @_;
  62
+   ...
  63
+ }
  64
+ sub end_head1 {
  65
+   my($self) = @_;
  66
+   ...
  67
+ }
  68
+ 
  69
+...and start_/end_ methods for whatever other events you want to catch.
47 70
 
48 71
 =head1 DESCRIPTION
49 72
 
50  
-This class is for TODO.
51  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  73
+This class is of
  74
+interest to people writing Pod formatters based on Pod::Simple.
  75
+
  76
+This class (which is very small -- read the source) overrides
  77
+Pod::Simple's _handle_element_start, _handle_text, and
  78
+_handle_element_end methods so that parser events are turned into method
  79
+calls. (Otherwise, this is a subclass of L<Pod::Simple> and inherits all
  80
+its methods.)
  81
+
  82
+You can use this class as the base class for a Pod formatter/processor.
  83
+
  84
+=head1 METHOD CALLING
  85
+
  86
+When Pod::Simple sees a "=head1 Hi there", for example, it basically does
  87
+this:
  88
+
  89
+  $parser->_handle_element_start( "head1", \%attributes );
  90
+  $parser->_handle_text( "Hi there" );
  91
+  $parser->_handle_element_end( "head1" );
  92
+
  93
+But if you subclass Pod::Simple::Methody, it will instead do this
  94
+when it sees a "=head1 Hi there":
  95
+
  96
+  $parser->start_head1( \%attributes ) if $parser->can('start_head1');
  97
+  $parser->handle_text( "Hi there" )   if $parser->can('handle_text');
  98
+  $parser->end_head1()                 if $parser->can('end_head1');
  99
+
  100
+If Pod::Simple sends an event where the element name has a dash,
  101
+period, or colon, the corresponding method name will have a underscore
  102
+in its place.  For example, "foo.bar:baz" becomes start_foo_bar_baz
  103
+and end_foo_bar_baz.
52 104
 
53  
-TODO
  105
+See the source for Pod::Simple::Text for an example of using this class.
54 106
 
55 107
 =head1 SEE ALSO
56 108
 
57  
-L<Pod::Simple>
  109
+L<Pod::Simple>, L<Pod::Simple::Subclassing>
58 110
 
59 111
 =head1 COPYRIGHT AND DISCLAIMERS
60 112
 
191  lib/Pod/Simple/PullParser.pm
... ...
@@ -1,7 +1,7 @@
1 1
 
2 2
 require 5;
3 3
 package Pod::Simple::PullParser;
4  
-$VERSION = '1.01';
  4
+$VERSION = '1.02';
5 5
 use Pod::Simple ();
6 6
 BEGIN {@ISA = ('Pod::Simple')}
7 7
 
@@ -54,6 +54,18 @@ sub parse_file {
54 54
 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
55 55
 #  In case anyone tries to use them:
56 56
 
  57
+sub run {
  58
+  use Carp ();
  59
+  if( __PACKAGE__ eq ref($_[0]) || $_[0]) { # I'm not being subclassed!
  60
+    Carp::croak "You can call run() only on subclasses of "
  61
+     . __PACKAGE__;
  62
+  } else {
  63
+    Carp::croak join '',
  64
+      "You can't call run() because ",
  65
+      ref($_[0]) || $_[0], " didn't define a run() method";
  66
+  }
  67
+}
  68
+
57 69
 sub parse_lines {
58 70
   use Carp ();
59 71
   Carp::croak "Use set_source with ", __PACKAGE__,
@@ -247,13 +259,13 @@ sub get_title_short {  shift->get_short_title(@_)  } # alias
247 259
 
248 260
 sub get_short_title {
249 261
   my $title = shift->get_title(@_);
250  
-  $title = $1 if $title =~ m/^(\S+)\s+--?\s+./s;
  262
+  $title = $1 if $title =~ m/^(\S{1,60})\s+--?\s+./s;
251 263
     # turn "Foo::Bar -- bars for your foo" into "Foo::Bar"
252 264
   return $title;
253 265
 }
254 266
 
255 267
 
256  
-sub get_title {
  268
+sub get_title {  # some witchery in here
257 269
   my $self = $_[0];
258 270
   my $title;
259 271
   my @to_unget;
@@ -361,23 +373,188 @@ __END__
361 373
 
362 374
 =head1 NAME
363 375
 
364  
-TODO - TODO
  376
+Pod::Simple::PullParser -- a pull-parser interface to parsing Pod
365 377
 
366 378
 =head1 SYNOPSIS
367 379
 
368  
- TODO
  380
+ my $parser = SomePodProcessor->new;
  381
+ $parser->set_source( "whatever.pod" );
  382
+ $parser->run;
  383
+
  384
+Or:
  385
+
  386
+ my $parser = SomePodProcessor->new;
  387
+ $parser->set_source( $some_filehandle_object );
  388
+ $parser->run;
  389
+
  390
+Or:
  391
+
  392
+ my $parser = SomePodProcessor->new;
  393
+ $parser->set_source( \$document_source );
  394
+ $parser->run;
  395
+
  396
+Or:
  397
+
  398
+ my $parser = SomePodProcessor->new;
  399
+ $parser->set_source( \@document_lines );
  400
+ $parser->run;
  401
+
  402
+And elsewhere:
  403
+
  404
+ require 5;
  405
+ package SomePodProcessor;
  406
+ use strict;
  407
+ use base qw(Pod::Simple::PullParser);
  408
+ 
  409
+ sub run {
  410
+   my $self = shift;
  411
+  Token:
  412
+   while(my $token = $self->get_token) {
  413
+     ...process each token...
  414
+   }
  415
+ }
369 416
 
370 417
 =head1 DESCRIPTION
371 418
 
372  
-This class is for TODO.
  419
+This class is for using Pod::Simple to build a Pod processor -- but
  420
+one that uses an interface based on a stream of token objects,
  421
+instead of based on events.
  422
+
373 423
 This is a subclass of L<Pod::Simple> and inherits all its methods.
374 424
 
375  
-TODO
  425
+A subclass of Pod::Simple::PullParser should define a C<run> method
  426
+that calls C<< $token = $parser->get_token >> to pull tokens.
  427
+
  428
+See the source for Pod::Simple::RTF for an example of a formatter
  429
+that uses Pod::Simple::PullParser.
  430
+
  431
+=head1 METHODS
  432
+
  433
+=over
  434
+
  435
+=item my $token = $parser->get_token
  436
+
  437
+This returns the next token object (which will be of a subclass of
  438
+L<Pod::Simple::PullParserToken>), or undef if the parser-stream has hit
  439
+the end of the document.
  440
+
  441
+=item $parser->unget_token( $token )
  442
+
  443
+=item $parser->unget_token( $token1, $token2, ... )
  444
+
  445
+This restores the token object(s) to the front of the parser stream.
  446
+
  447
+=back
  448
+
  449
+The source has to be set before you can parse anything.  The lowest-level
  450
+way is to call C<set_source>:
  451
+
  452
+=over
  453
+
  454
+=item $parser->set_source( $filename )
  455
+
  456
+=item $parser->set_source( $filehandle_object )
  457
+
  458
+=item $parser->set_source( \$document_source )
  459
+
  460
+=item $parser->set_source( \@document_lines )
  461
+
  462
+=back
  463
+
  464
+Or you can call these methods, which Pod::Simple::PullParser has defined
  465
+to work just like Pod::Simple's same-named methods:
  466
+
  467
+=over
  468
+
  469
+=item $parser->parse_file(...)
  470
+
  471
+=item $parser->parse_string_document(...)
  472
+
  473
+=item $parser->filter(...)
  474
+
  475
+=item $parser->parse_from_file(...)
  476
+
  477
+=back
  478
+
  479
+For those to work, the Pod-processing subclass of
  480
+Pod::Simple::PullParser has to have defined a $parser->run method --
  481
+so it is advised that all Pod::Simple::PullParser subclasses do so.
  482
+See the Synopsis above, or the source for Pod::Simple::RTF.
  483
+
  484
+Authors of formatter subclasses might find these methods useful to
  485
+call on a parser object that you haven't started pulling tokens
  486
+from yet:
  487
+
  488
+=over
  489
+
  490
+=item my $title_string = $parser->get_title
  491
+
  492
+This tries to get the title string out of $parser, by getting some tokens,
  493
+and scanning them for the title, and then ungetting them so that you can
  494
+process the token-stream from the beginning.
  495
+
  496
+For example, suppose you have a document that starts out:
  497
+
  498
+  =head1 NAME
  499
+  
  500
+  Hoo::Boy::Wowza -- Stuff B<wow> yeah!
  501
+
  502
+$parser->get_title on that document will return "Hoo::Boy::Wowza --
  503
+Stuff wow yeah!".
  504
+
  505
+In cases where get_title can't find the title, it will return empty-string
  506
+("").
  507
+
  508
+=item my $title_string = $parser->get_short_title
  509
+
  510
+This is just like get_title, except that it returns just the modulename, if
  511
+the title seems to be of the form "SomeModuleName -- description".
  512
+
  513
+For example, suppose you have a document that starts out:
  514
+
  515
+  =head1 NAME
  516
+  
  517
+  Hoo::Boy::Wowza -- Stuff B<wow> yeah!
  518
+
  519
+then $parser->get_short_title on that document will return
  520
+"Hoo::Boy::Wowza".
  521
+
  522
+But if the document starts out:
  523
+
  524
+  =head1 NAME
  525
+  
  526
+  Hooboy, stuff B<wow> yeah!
  527
+
  528
+then $parser->get_short_title on that document will return "Hooboy,
  529
+stuff wow yeah!".
  530
+
  531
+If the title can't be found, then get_short_title returns empty-string
  532
+("").
  533
+
  534
+=back
  535
+
  536
+=head1 NOTE
  537
+
  538
+You don't actually I<have> to define a C<run> method.  If you're
  539
+writing a Pod-formatter class, you should define a C<run> just so
  540
+that users can call C<parse_file> etc, but you don't I<have> to.
  541
+
  542
+And if you're not writing a formatter class, but are instead just
  543
+writing a program that does something simple with a Pod::PullParser
  544
+object (and not an object of a subclass), then there's no reason to
  545
+bother subclassing to add a C<run> method.
376 546
 
377 547
 =head1 SEE ALSO
378 548
 
379 549
 L<Pod::Simple>
380 550
 
  551
+L<Pod::Simple::PullParserToken> -- and its subclasses
  552
+L<Pod::Simple::PullParserStartToken>,
  553
+L<Pod::Simple::PullParserTextToken>, and
  554
+L<Pod::Simple::PullParserEndToken>.
  555
+
  556
+L<HTML::TokeParser>, which inspired this.
  557
+
381 558
 =head1 COPYRIGHT AND DISCLAIMERS
382 559
 
383 560
 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
46  lib/Pod/Simple/PullParserEndToken.pm
@@ -15,6 +15,9 @@ sub new {  # Class->new(tagname);
15 15
 sub tagname { (@_ == 2) ? ($_[0][1] = $_[1]) : $_[0][1] }
16 16
 sub tag { shift->tagname(@_) }
17 17
 
  18
+# shortcut:
  19
+sub is_tagname { $_[0][1] eq $_[1] }
  20
+sub is_tag { shift->is_tagname(@_) }
18 21
 
19 22
 1;
20 23
 
@@ -23,22 +26,53 @@ __END__
23 26
 
24 27
 =head1 NAME
25 28
 
26  
-TODO - TODO
  29
+Pod::Simple::PullParserEndToken -- end-tokens from Pod::Simple::PullParser
27 30
 
28 31
 =head1 SYNOPSIS
29 32
 
30  
- TODO
  33
+(See L<Pod::Simple::PullParser>)
31 34
 
32 35
 =head1 DESCRIPTION
33 36
 
34  
-This class is for TODO.
35  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  37
+When you do $parser->get_token on a L<Pod::Simple::PullParser>, you might
  38
+get an object of this class.
36 39
 
37  
-TODO
  40
+This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
  41
+and adds these methods:
  42
+
  43
+=over
  44
+
  45
+=item $token->tagname
  46
+
  47
+This returns the tagname for this end-token object.
  48
+For example, parsing a "=head1 ..." line will give you
  49
+a start-token with the tagname of "head1", token(s) for its
  50
+content, and then an end-token with the tagname of "head1".
  51
+
  52
+=item $token->tagname(I<somestring>)
  53
+
  54
+This changes the tagname for this end-token object.
  55
+You probably won't need to do this.
  56
+
  57
+=item $token->tag(...)
  58
+
  59
+A shortcut for $token->tagname(...)
  60
+
  61
+=item $token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>)
  62
+
  63
+These are shortcuts for C<< $token->tag() eq I<somestring> >>
  64
+
  65
+=back
  66
+
  67
+You're unlikely to ever need to construct an object of this class for
  68
+yourself, but if you want to, call
  69
+C<<
  70
+Pod::Simple::PullParserEndToken->new( I<tagname> )
  71
+>>
38 72
 
39 73
 =head1 SEE ALSO
40 74
 
41  
-L<Pod::Simple>
  75
+L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
42 76
 
43 77
 =head1 COPYRIGHT AND DISCLAIMERS
44 78
 
69  lib/Pod/Simple/PullParserStartToken.pm
@@ -15,6 +15,10 @@ sub new {  # Class->new(tagname, optional_attrhash);
15 15
 sub tagname   { (@_ == 2) ? ($_[0][1] = $_[1]) : $_[0][1] }
16 16
 sub tag { shift->tagname(@_) }
17 17
 
  18
+sub is_tagname { $_[0][1] eq $_[1] }
  19
+sub is_tag { shift->is_tagname(@_) }
  20
+
  21
+
18 22
 sub attr_hash { $_[0][2] ||= {} }
19 23
 
20 24
 sub attr      {
@@ -37,22 +41,75 @@ __END__
37 41
 
38 42
 =head1 NAME
39 43
 
40  
-TODO - TODO
  44
+Pod::Simple::PullParserStartToken -- start-tokens from Pod::Simple::PullParser
41 45
 
42 46
 =head1 SYNOPSIS
43 47
 
44  
- TODO
  48
+(See L<Pod::Simple::PullParser>)
45 49
 
46 50
 =head1 DESCRIPTION
47 51
 
48  
-This class is for TODO.
49  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  52
+When you do $parser->get_token on a L<Pod::Simple::PullParser> object, you might
  53
+get an object of this class.
  54
+
  55
+This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
  56
+and adds these methods:
  57
+
  58
+=over
  59
+
  60
+=item $token->tagname
  61
+
  62
+This returns the tagname for this start-token object.
  63
+For example, parsing a "=head1 ..." line will give you
  64
+a start-token with the tagname of "head1", token(s) for its
  65
+content, and then an end-token with the tagname of "head1".
  66
+
  67
+=item $token->tagname(I<somestring>)
  68
+
  69
+This changes the tagname for this start-token object.
  70
+You probably won't need
  71
+to do this.
  72
+
  73
+=item $token->tag(...)
  74
+
  75
+A shortcut for $token->tagname(...)
  76
+
  77
+=item $token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>)
  78
+
  79
+These are shortcuts for C<< $token->tag() eq I<somestring> >>
  80
+
  81
+=item $token->attr(I<attrname>)
  82
+
  83
+This returns the value of the I<attrname> attribute for this start-token
  84
+object, or undef.
  85
+
  86
+For example, parsing a LZ<><Foo/"Bar"> link will produce a start-token
  87
+with a "to" attribute with the value "Foo", a "type" attribute with the
  88
+value "pod", and a "section" attribute with the value "Bar".
  89
+
  90
+=item $token->attr(I<attrname>, I<newvalue>)
  91
+
  92
+This sets the I<attrname> attribute for this start-token object to
  93
+I<newvalue>.  You probably won't need to do this.
  94
+
  95
+=item $token->attr_hash
  96
+
  97
+This returns the hashref that is the attribute set for this start-token.
  98
+This is useful if (for example) you want to ask what all the attributes
  99
+are -- you can just do C<< keys %{$token->attr_hash} >>
  100
+
  101
+=back
  102
+
50 103
 
51  
-TODO
  104
+You're unlikely to ever need to construct an object of this class for
  105
+yourself, but if you want to, call
  106
+C<<
  107
+Pod::Simple::PullParserStartToken->new( I<tagname>, I<attrhash> )
  108
+>>
52 109
 
53 110
 =head1 SEE ALSO
54 111
 
55  
-L<Pod::Simple>
  112
+L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
56 113
 
57 114
 =head1 COPYRIGHT AND DISCLAIMERS
58 115
 
55  lib/Pod/Simple/PullParserTextToken.pm
@@ -22,22 +22,65 @@ __END__
22 22
 
23 23
 =head1 NAME
24 24
 
25  
-TODO - TODO
  25
+Pod::Simple::PullParserTextToken -- text-tokens from Pod::Simple::PullParser
26 26
 
27 27
 =head1 SYNOPSIS
28 28
 
29  
- TODO
  29
+(See L<Pod::Simple::PullParser>)
30 30
 
31 31
 =head1 DESCRIPTION
32 32
 
33  
-This class is for TODO.
34  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  33
+When you do $parser->get_token on a L<Pod::Simple::PullParser>, you might
  34
+get an object of this class.
35 35
 
36  
-TODO
  36
+This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
  37
+and adds these methods:
  38
+
  39
+=over
  40
+
  41
+=item $token->text
  42
+
  43
+This returns the text that this token holds.  For example, parsing
  44
+CZ<><foo> will return a C start-token, a text-token, and a C end-token.  And
  45
+if you want to get the "foo" out of the text-token, call C<< $token->text >>
  46
+
  47
+=item $token->text(I<somestring>)
  48
+
  49
+This changes the string that this token holds.  You probably won't need
  50
+to do this.
  51
+
  52
+=item $token->text_r()
  53
+
  54
+This returns a scalar reference to the string that this token holds.
  55
+This can be useful if you don't want to memory-copy the potentially
  56
+large text value (well, as large as a paragraph or a verbatim block)
  57
+as calling $token->text would do.
  58
+
  59
+Or, if you want to alter the value, you can even do things like this:
  60
+
  61
+  for ( ${  $token->text_r  } ) {  # Aliases it with $_ !!
  62
+  
  63
+    s/ The / the /g; # just for example
  64
+    
  65
+    if( 'A' eq chr(65) ) {  # (if in an ASCII world)
  66
+      tr/\xA0/ /;
  67
+      tr/\xAD//d;
  68
+    }
  69
+    
  70
+    ...or however you want to alter the value...
  71
+  }
  72
+
  73
+=back
  74
+
  75
+You're unlikely to ever need to construct an object of this class for
  76
+yourself, but if you want to, call
  77
+C<<
  78
+Pod::Simple::PullParserTextToken->new( I<text> )
  79
+>>
37 80
 
38 81
 =head1 SEE ALSO
39 82
 
40  
-L<Pod::Simple>
  83
+L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
41 84
 
42 85
 =head1 COPYRIGHT AND DISCLAIMERS
43 86
 
72  lib/Pod/Simple/PullParserToken.pm
@@ -44,22 +44,82 @@ __END__
44 44
 
45 45
 =head1 NAME
46 46
 
47  
-TODO - TODO
  47
+Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
48 48
 
49 49
 =head1 SYNOPSIS
50 50
 
51  
- TODO
  51
+Given a $parser that's an object of class Pod::Simple::PullParser
  52
+(or a subclass)...
  53
+
  54
+  while(my $token = $parser->get_token) {
  55
+    $DEBUG and print "Token: ", $token->dump, "\n";
  56
+    if($token->is_start) {
  57
+      ...access $token->tagname, $token->attr, etc...
  58
+
  59
+    } elsif($token->is_text) {
  60
+      ...access $token->text, $token->text_r, etc...
  61
+    
  62
+    } elsif($token->is_end) {
  63
+      ...access $token->tagname...
  64
+    
  65
+    }
  66
+  }
  67
+
  68
+(Also see L<Pod::Simple::PullParser>)
52 69
 
53 70
 =head1 DESCRIPTION
54 71
 
55  
-This class is for TODO.
56  
-This is a subclass of L<Pod::Simple> and inherits all its methods.
  72
+When you do $parser->get_token on a L<Pod::Simple::PullParser>, you should
  73
+get an object of a subclass of Pod::Simple::PullParserToken.
  74
+
  75
+Subclasses will add methods, and will also inherit these methods:
  76
+
  77
+=over
  78
+
  79
+=item $token->type
  80
+
  81
+This returns the type of the token.  This will be either the string
  82
+"start", the string "text", or the string "end".
  83
+
  84
+Once you know what the type of an object is, you then know what
  85
+subclass it belongs to, and therefore what methods it supports.
  86
+
  87
+Yes, you could probably do the same thing with code like
  88
+$token->isa('Pod::Simple::PullParserEndToken'), but that's not so
  89
+pretty as using just $token->type, or even the following shortcuts:
  90
+
  91
+=item $token->is_start
  92
+
  93
+This is a shortcut for C<< $token->type() eq "start" >>
57 94
 
58  
-TODO
  95
+=item $token->is_text
  96
+
  97
+This is a shortcut for C<< $token->type() eq "text" >>
  98
+
  99
+=item $token->is_end
  100
+
  101
+This is a shortcut for C<< $token->type() eq "end" >>
  102
+
  103
+=item $token->dump
  104
+
  105
+This returns a handy stringified value of this object.  This
  106
+is useful for debugging, as in:
  107
+
  108
+  while(my $token = $parser->get_token) {
  109
+    $DEBUG and print "Token: ", $token->dump, "\n";
  110
+    ...
  111
+  }
  112
+
  113
+=back
59 114
 
60 115
 =head1 SEE ALSO
61 116
 
62  
-L<Pod::Simple>
  117
+My subclasses:
  118
+L<Pod::Simple::PullParserStartToken>,
  119
+L<Pod::Simple::PullParserTextToken>, and
  120
+L<Pod::Simple::PullParserEndToken>.
  121
+
  122
+L<Pod::Simple::PullParser> and L<Pod::Simple>
63 123
 
64 124
 =head1 COPYRIGHT AND DISCLAIMERS
65 125
 
141  lib/Pod/Simple/RTF.pm
@@ -10,7 +10,7 @@ package Pod::Simple::RTF;
10 10
 
11 11
 use strict;
12 12
 use vars qw($VERSION @ISA %Escape $WRAP %Tagmap);
13  
-$VERSION = '1.02';
  13
+$VERSION = '1.03';
14 14
 use Pod::Simple::PullParser ();
15 15
 BEGIN {@ISA = ('Pod::Simple::PullParser')}
16 16
 
@@ -104,6 +104,14 @@ sub new {
104 104
   $new->accept_codes(@_to_accept);
105 105
   $new->accept_codes('VerbatimFormatted');
106 106
   DEBUG > 2 and print "To accept: ", join(' ',@_to_accept), "\n";
  107
+  $new->doc_lang(
  108
+    (  $ENV{'RTFDEFLANG'} || '') =~ m/^(\d{1,10})$/s ? $1
  109
+    : ($ENV{'RTFDEFLANG'} || '') =~ m/^0?x([a-fA-F0-9]{1,10})$/s ? hex($1)
  110
+                                      # yes, tolerate hex!
  111
+    : ($ENV{'RTFDEFLANG'} || '') =~ m/^([a-fA-F0-9]{4})$/s ? hex($1)
  112
+                                      # yes, tolerate even more hex!
  113
+    : '1033'
  114
+  );
107 115
 
108 116
   $new->head1_halfpoint_size(32);
109 117
   $new->head2_halfpoint_size(28);
@@ -118,9 +126,8 @@ sub new {
118 126
 
119 127
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120 128
 
121  
-# TODO: document these
122  
-
123 129
 __PACKAGE__->_accessorize(
  130
+ 'doc_lang',
124 131
  'head1_halfpoint_size',
125 132
  'head2_halfpoint_size',
126 133
  'head3_halfpoint_size',
@@ -454,14 +461,14 @@ sub doc_start {
454 461
    if $is_obviously_module_name;
455 462
 
456 463
   return sprintf <<'END', 
457  
-\deflang1033\widowctrl
  464
+\deflang%s\plain\lang%s\widowctrl
458 465
 {\header\pard\qr\plain\f2\fs%s
459 466
 %s
460 467
 p.\chpgn\par}
461 468
 \fs%s
462 469
 
463 470
 END
464  
-
  471
+    ($self->doc_lang) x 2,
465 472
     $self->header_halfpoint_size,
466 473
     $title,
467 474
     $self->normal_halfpoint_size,
@@ -471,7 +478,6 @@ END
471 478
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472 479
 #-------------------------------------------------------------------------
473 480
 
474  
-# TODO: escaping Unicode characters?
475 481
 use integer;
476 482
 sub rtf_esc {
477 483
   my $x; # scratch
@@ -497,7 +503,11 @@ sub rtf_esc {
497 503
 }
498 504
 
499 505
 sub rtf_esc_codely {
500  
-  # Doesn't change "-" to hard-hyphen, nor apply computerese style
  506
+  # Doesn't change "-" to hard-hyphen, nor apply computerese style-smarts.
  507
+  # We don't want to change the "-" to hard-hyphen, because we want to
  508
+  #  be able to paste this into a file and run it without there being
  509
+  #  dire screaming about the mysterious hard-hyphen character (which
  510
+  #  looks just like a normal dash character).
501 511