5 Pod::Text - convert POD data to formatted ASCII text
11 pod2text("perlfunc.pod");
19 Pod::Text is a module that can convert documentation in the POD format (such
20 as can be found throughout the Perl distribution) into formatted ASCII.
21 Termcap is optionally supported for boldface/underline, and can enabled via
22 C<$Pod::Text::termcap=1>. If termcap has not been enabled, then backspaces
23 will be used to simulate bold and underlined text.
25 A separate F<pod2text> program is included that is primarily a wrapper for
28 The single function C<pod2text()> can take one or two arguments. The first
29 should be the name of a file to read the pod from, or "E<lt>&STDIN" to read from
30 STDIN. A second argument, if provided, should be a filehandle glob where
31 output should be sent.
35 Tom Christiansen E<lt>F<tchrist@mox.perl.com>E<gt>
39 Cleanup work. The input and output locations need to be more flexible,
40 termcap shouldn't be a global variable, and the terminal speed needs to
41 be properly calculated.
48 @EXPORT = qw(pod2text);
50 use vars qw($VERSION);
63 local($file,*OUTPUT) = @_;
64 *OUTPUT = *STDOUT if @_<2;
66 if($termcap and !$setuptermcap) {
69 my($term) = Tgetent Term::Cap { TERM => undef, OSPEED => 9600 };
70 $UNDL = $term->{'_us'};
71 $INV = $term->{'_mr'};
72 $BOLD = $term->{'_md'};
73 $NORM = $term->{'_me'};
76 $SCREEN = ($_[0] =~ /^-(\d+)/ && (shift, $1))
78 || ($ENV{TERMCAP} =~ /co#(\d+)/)[0]
79 || (`stty -a 2>/dev/null` =~ /(\d+) columns/)[0]
88 $indent = $DEF_INDENT;
92 open(IN, $file) || die "Couldn't open $file: $!";
94 POD_DIRECTIVE: while (<IN>) {
100 if (/^=end\s+$begun/) {
103 elsif ($begun eq "text") {
108 1 while s{^(.*?)(\t+)(.*)$}{
110 . (' ' x (length($2) * 8 - length($1) % 8))
113 # Translate verbatim paragraph
120 if (/^=for\s+(\S+)\s*(.*)/s) {
128 elsif (/^=begin\s+(\S+)\s*(.*)/s) {
136 sub prepare_for_output {
141 # need to hide E<> first; they're processed in clear_noremap
142 s/(E<[^<>]+>)/noremap($1)/ge;
144 while ($maxnest-- && /[A-Z]</) {
148 s/C<(.*?)>/noremap("E<lchevron>${1}E<rchevron>")/sge;
150 # s/[IF]<(.*?)>/italic($1)/ge;
152 # s/[CB]<(.*?)>/bold($1)/ge;
154 # LREF: a manpage(3f)
155 s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the $1$2 manpage:g;
156 # LREF: an =item on another manpage
166 } {the "$2" entry in the $1 manpage}gx;
168 # LREF: an =item on this manpage
180 } { internal_lrefs($1) }gex;
182 # LREF: a =head2 (head1?), maybe on a manpage, maybe right here
183 # the "func" can disambiguate
193 $1 # if no $1, assume it means on this page.
194 ? "the section on \"$2\" in the $1 manpage"
195 : "the section on \"$2\""
199 s/[A-Z]<(.*?)>/$1/sg;
207 # $needspace = 0; # Assume this.
209 ($Cmd, $_) = split(' ', $_, 2);
214 elsif ($Cmd eq 'head1') {
217 # print OUTPUT uc($_);
219 elsif ($Cmd eq 'head2') {
222 #print ' ' x $DEF_INDENT, $_;
224 s/(\w)/\xA7 $1/ if $FANCY;
225 print OUTPUT ' ' x ($DEF_INDENT/2), $_, "\n";
227 elsif ($Cmd eq 'over') {
228 push(@indent,$indent);
229 $indent += ($_ + 0) || $DEF_INDENT;
231 elsif ($Cmd eq 'back') {
232 $indent = pop(@indent);
233 warn "Unmatched =back\n" unless defined $indent;
236 elsif ($Cmd eq 'item') {
238 # s/\A(\s*)\*/$1\xb7/ if $FANCY;
239 # s/^(\s*\*\s+)/$1 /;
241 if (length() + 3 < $indent) {
244 if (/^=/) { # tricked!
245 local($indent) = $indent[$#index - 1] || $DEF_INDENT;
250 IP_output($paratag, $_);
252 local($indent) = $indent[$#index - 1] || $DEF_INDENT;
258 warn "Unrecognized directive: $Cmd\n";
272 #########################################################################
283 return $line if $use_format;
285 $line = "$BOLD$line$NORM";
287 $line =~ s/(.)/$1\b$1/g;
289 # $line = "$BOLD$line$NORM" if $ansify;
295 return $line if $use_format;
297 $line = "$UNDL$line$NORM";
299 $line =~ s/(.)/$1\b_/g;
301 # $line = "$UNDL$line$NORM" if $ansify;
305 # Fill a paragraph including underlined and overstricken chars.
306 # It's not perfect for words longer than the margin, and it's probably
307 # slow, but it works.
311 my $indent_space = " " x $indent;
312 my $marg = $SCREEN-$indent;
313 my $line = $indent_space;
316 my $word_length = length;
317 $word_length -= 2 while /\010/g; # Subtract backspaces
319 if ($line_length + $word_length > $marg) {
320 $par .= $line . "\n";
321 $line= $indent_space . $_;
322 $line_length = $word_length;
329 $line_length += $word_length;
333 $par .= "$line\n" if $line;
339 local($tag, $_) = @_;
340 local($tag_indent) = $indent[$#index - 1] || $DEF_INDENT;
341 $tag_cols = $SCREEN - $tag_indent;
342 $cols = $SCREEN - $indent;
346 $str = "format OUTPUT = \n"
347 . (" " x ($tag_indent))
348 . '@' . ('<' x ($indent - $tag_indent - 1))
349 . "^" . ("<" x ($cols - 1)) . "\n"
352 . (" " x ($indent-2))
353 . "^" . ("<" x ($cols - 5)) . "\n"
355 #warn $str; warn "tag is $tag, _ is $_";
361 local($_, $reformat) = @_;
363 $cols = $SCREEN - $indent;
366 $str = "format OUTPUT = \n~~"
367 . (" " x ($indent-2))
368 . "^" . ("<" x ($cols - 5)) . "\n"
373 s/^/' ' x $indent/gem;
380 local($thing_to_hide) = shift;
381 $thing_to_hide =~ tr/\000-\177/\200-\377/;
382 return $thing_to_hide;
386 die "unmatched init" if $mapready++;
387 #mask off high bit characters in input stream
388 s/([\200-\377])/"E<".ord($1).">"/ge;
392 my $ready_to_print = $_[0];
393 die "unmatched clear" unless $mapready--;
394 tr/\200-\377/\000-\177/;
395 # now for the E<>s, which have been hidden until now
396 # otherwise the interative \w<> processing would have
397 # been hosed by the E<gt>
410 defined $HTML_Escapes{$3}
411 ? do { $HTML_Escapes{$3} }
413 warn "Unknown escape: E<$1> in $_";
417 }egx if $ready_to_print;
423 my(@items) = split( /(?:,?\s+(?:and\s+)?)/ );
426 for ($i = 0; $i <= $#items; $i++) {
427 $retstr .= "C<$items[$i]>";
428 $retstr .= ", " if @items > 2 && $i != $#items;
429 $retstr .= " and " if $i+2 == @items;
432 $retstr .= " entr" . ( @items > 1 ? "ies" : "y" )
433 . " elsewhere in this document ";
442 'amp' => '&', # ampersand
443 'lt' => '<', # left chevron, less-than
444 'gt' => '>', # right chevron, greater-than
445 'quot' => '"', # double quote
447 "Aacute" => "\xC1", # capital A, acute accent
448 "aacute" => "\xE1", # small a, acute accent
449 "Acirc" => "\xC2", # capital A, circumflex accent
450 "acirc" => "\xE2", # small a, circumflex accent
451 "AElig" => "\xC6", # capital AE diphthong (ligature)
452 "aelig" => "\xE6", # small ae diphthong (ligature)
453 "Agrave" => "\xC0", # capital A, grave accent
454 "agrave" => "\xE0", # small a, grave accent
455 "Aring" => "\xC5", # capital A, ring
456 "aring" => "\xE5", # small a, ring
457 "Atilde" => "\xC3", # capital A, tilde
458 "atilde" => "\xE3", # small a, tilde
459 "Auml" => "\xC4", # capital A, dieresis or umlaut mark
460 "auml" => "\xE4", # small a, dieresis or umlaut mark
461 "Ccedil" => "\xC7", # capital C, cedilla
462 "ccedil" => "\xE7", # small c, cedilla
463 "Eacute" => "\xC9", # capital E, acute accent
464 "eacute" => "\xE9", # small e, acute accent
465 "Ecirc" => "\xCA", # capital E, circumflex accent
466 "ecirc" => "\xEA", # small e, circumflex accent
467 "Egrave" => "\xC8", # capital E, grave accent
468 "egrave" => "\xE8", # small e, grave accent
469 "ETH" => "\xD0", # capital Eth, Icelandic
470 "eth" => "\xF0", # small eth, Icelandic
471 "Euml" => "\xCB", # capital E, dieresis or umlaut mark
472 "euml" => "\xEB", # small e, dieresis or umlaut mark
473 "Iacute" => "\xCD", # capital I, acute accent
474 "iacute" => "\xED", # small i, acute accent
475 "Icirc" => "\xCE", # capital I, circumflex accent
476 "icirc" => "\xEE", # small i, circumflex accent
477 "Igrave" => "\xCD", # capital I, grave accent
478 "igrave" => "\xED", # small i, grave accent
479 "Iuml" => "\xCF", # capital I, dieresis or umlaut mark
480 "iuml" => "\xEF", # small i, dieresis or umlaut mark
481 "Ntilde" => "\xD1", # capital N, tilde
482 "ntilde" => "\xF1", # small n, tilde
483 "Oacute" => "\xD3", # capital O, acute accent
484 "oacute" => "\xF3", # small o, acute accent
485 "Ocirc" => "\xD4", # capital O, circumflex accent
486 "ocirc" => "\xF4", # small o, circumflex accent
487 "Ograve" => "\xD2", # capital O, grave accent
488 "ograve" => "\xF2", # small o, grave accent
489 "Oslash" => "\xD8", # capital O, slash
490 "oslash" => "\xF8", # small o, slash
491 "Otilde" => "\xD5", # capital O, tilde
492 "otilde" => "\xF5", # small o, tilde
493 "Ouml" => "\xD6", # capital O, dieresis or umlaut mark
494 "ouml" => "\xF6", # small o, dieresis or umlaut mark
495 "szlig" => "\xDF", # small sharp s, German (sz ligature)
496 "THORN" => "\xDE", # capital THORN, Icelandic
497 "thorn" => "\xFE", # small thorn, Icelandic
498 "Uacute" => "\xDA", # capital U, acute accent
499 "uacute" => "\xFA", # small u, acute accent
500 "Ucirc" => "\xDB", # capital U, circumflex accent
501 "ucirc" => "\xFB", # small u, circumflex accent
502 "Ugrave" => "\xD9", # capital U, grave accent
503 "ugrave" => "\xF9", # small u, grave accent
504 "Uuml" => "\xDC", # capital U, dieresis or umlaut mark
505 "uuml" => "\xFC", # small u, dieresis or umlaut mark
506 "Yacute" => "\xDD", # capital Y, acute accent
507 "yacute" => "\xFD", # small y, acute accent
508 "yuml" => "\xFF", # small y, dieresis or umlaut mark
510 "lchevron" => "\xAB", # left chevron (double less than)
511 "rchevron" => "\xBB", # right chevron (double greater than)