lib/Pod/Text.pm

   1 # Pod::Text -- Convert POD data to formatted ASCII text.
   2 # $Id: Text.pm,v 2.5 2000/09/03 09:23:29 eagle Exp $
   3 #
   4 # Copyright 1999, 2000 by Russ Allbery <rra@stanford.edu>
   5 #
   6 # This program is free software; you can redistribute it and/or modify it
   7 # under the same terms as Perl itself.
   8 #
   9 # This module is intended to be a replacement for Pod::Text, and attempts to
  10 # match its output except for some specific circumstances where other
  11 # decisions seemed to produce better output.  It uses Pod::Parser and is
  12 # designed to be very easy to subclass.
  13
  14 ############################################################################
  15 # Modules and declarations
  16 ############################################################################
  17
  18 package Pod::Text;
  19
  20 require 5.004;
  21
  22 use Carp qw(carp croak);
  23 use Exporter ();
  24 use Pod::Select ();
  25
  26 use strict;
  27 use vars qw(@ISA @EXPORT %ESCAPES $VERSION);
  28
  29 # We inherit from Pod::Select instead of Pod::Parser so that we can be used
  30 # by Pod::Usage.
  31 @ISA = qw(Pod::Select Exporter);
  32
  33 # We have to export pod2text for backward compatibility.
  34 @EXPORT = qw(pod2text);
  35
  36 # Don't use the CVS revision as the version, since this module is also in
  37 # Perl core and too many things could munge CVS magic revision strings.
  38 # This number should ideally be the same as the CVS revision in podlators,
  39 # however.
  40 $VERSION = 2.05;
  41
  42
  43 ############################################################################
  44 # Table of supported E<> escapes
  45 ############################################################################
  46
  47 # This table is taken near verbatim from Pod::PlainText in Pod::Parser,
  48 # which got it near verbatim from the original Pod::Text.  It is therefore
  49 # credited to Tom Christiansen, and I'm glad I didn't have to write it.  :)
  50 # "iexcl" to "divide" added by Tim Jenness.
  51 %ESCAPES = (
  52     'amp'       =>    '&',      # ampersand
  53     'lt'        =>    '<',      # left chevron, less-than
  54     'gt'        =>    '>',      # right chevron, greater-than
  55     'quot'      =>    '"',      # double quote
  56     'sol'       =>    '/',      # solidus (forward slash)
  57     'verbar'    =>    '|',      # vertical bar
  58
  59     "Aacute"    =>    "\xC1",   # capital A, acute accent
  60     "aacute"    =>    "\xE1",   # small a, acute accent
  61     "Acirc"     =>    "\xC2",   # capital A, circumflex accent
  62     "acirc"     =>    "\xE2",   # small a, circumflex accent
  63     "AElig"     =>    "\xC6",   # capital AE diphthong (ligature)
  64     "aelig"     =>    "\xE6",   # small ae diphthong (ligature)
  65     "Agrave"    =>    "\xC0",   # capital A, grave accent
  66     "agrave"    =>    "\xE0",   # small a, grave accent
  67     "Aring"     =>    "\xC5",   # capital A, ring
  68     "aring"     =>    "\xE5",   # small a, ring
  69     "Atilde"    =>    "\xC3",   # capital A, tilde
  70     "atilde"    =>    "\xE3",   # small a, tilde
  71     "Auml"      =>    "\xC4",   # capital A, dieresis or umlaut mark
  72     "auml"      =>    "\xE4",   # small a, dieresis or umlaut mark
  73     "Ccedil"    =>    "\xC7",   # capital C, cedilla
  74     "ccedil"    =>    "\xE7",   # small c, cedilla
  75     "Eacute"    =>    "\xC9",   # capital E, acute accent
  76     "eacute"    =>    "\xE9",   # small e, acute accent
  77     "Ecirc"     =>    "\xCA",   # capital E, circumflex accent
  78     "ecirc"     =>    "\xEA",   # small e, circumflex accent
  79     "Egrave"    =>    "\xC8",   # capital E, grave accent
  80     "egrave"    =>    "\xE8",   # small e, grave accent
  81     "ETH"       =>    "\xD0",   # capital Eth, Icelandic
  82     "eth"       =>    "\xF0",   # small eth, Icelandic
  83     "Euml"      =>    "\xCB",   # capital E, dieresis or umlaut mark
  84     "euml"      =>    "\xEB",   # small e, dieresis or umlaut mark
  85     "Iacute"    =>    "\xCD",   # capital I, acute accent
  86     "iacute"    =>    "\xED",   # small i, acute accent
  87     "Icirc"     =>    "\xCE",   # capital I, circumflex accent
  88     "icirc"     =>    "\xEE",   # small i, circumflex accent
  89     "Igrave"    =>    "\xCD",   # capital I, grave accent
  90     "igrave"    =>    "\xED",   # small i, grave accent
  91     "Iuml"      =>    "\xCF",   # capital I, dieresis or umlaut mark
  92     "iuml"      =>    "\xEF",   # small i, dieresis or umlaut mark
  93     "Ntilde"    =>    "\xD1",   # capital N, tilde
  94     "ntilde"    =>    "\xF1",   # small n, tilde
  95     "Oacute"    =>    "\xD3",   # capital O, acute accent
  96     "oacute"    =>    "\xF3",   # small o, acute accent
  97     "Ocirc"     =>    "\xD4",   # capital O, circumflex accent
  98     "ocirc"     =>    "\xF4",   # small o, circumflex accent
  99     "Ograve"    =>    "\xD2",   # capital O, grave accent
 100     "ograve"    =>    "\xF2",   # small o, grave accent
 101     "Oslash"    =>    "\xD8",   # capital O, slash
 102     "oslash"    =>    "\xF8",   # small o, slash
 103     "Otilde"    =>    "\xD5",   # capital O, tilde
 104     "otilde"    =>    "\xF5",   # small o, tilde
 105     "Ouml"      =>    "\xD6",   # capital O, dieresis or umlaut mark
 106     "ouml"      =>    "\xF6",   # small o, dieresis or umlaut mark
 107     "szlig"     =>    "\xDF",   # small sharp s, German (sz ligature)
 108     "THORN"     =>    "\xDE",   # capital THORN, Icelandic
 109     "thorn"     =>    "\xFE",   # small thorn, Icelandic
 110     "Uacute"    =>    "\xDA",   # capital U, acute accent
 111     "uacute"    =>    "\xFA",   # small u, acute accent
 112     "Ucirc"     =>    "\xDB",   # capital U, circumflex accent
 113     "ucirc"     =>    "\xFB",   # small u, circumflex accent
 114     "Ugrave"    =>    "\xD9",   # capital U, grave accent
 115     "ugrave"    =>    "\xF9",   # small u, grave accent
 116     "Uuml"      =>    "\xDC",   # capital U, dieresis or umlaut mark
 117     "uuml"      =>    "\xFC",   # small u, dieresis or umlaut mark
 118     "Yacute"    =>    "\xDD",   # capital Y, acute accent
 119     "yacute"    =>    "\xFD",   # small y, acute accent
 120     "yuml"      =>    "\xFF",   # small y, dieresis or umlaut mark
 121
 122     "laquo"     =>    "\xAB",   # left pointing double angle quotation mark
 123     "lchevron"  =>    "\xAB",   #  synonym (backwards compatibility)
 124     "raquo"     =>    "\xBB",   # right pointing double angle quotation mark
 125     "rchevron"  =>    "\xBB",   #  synonym (backwards compatibility)
 126
 127     "iexcl"     =>    "\xA1",   # inverted exclamation mark
 128     "cent"      =>    "\xA2",   # cent sign
 129     "pound"     =>    "\xA3",   # (UK) pound sign
 130     "curren"    =>    "\xA4",   # currency sign
 131     "yen"       =>    "\xA5",   # yen sign
 132     "brvbar"    =>    "\xA6",   # broken vertical bar
 133     "sect"      =>    "\xA7",   # section sign
 134     "uml"       =>    "\xA8",   # diaresis
 135     "copy"      =>    "\xA9",   # Copyright symbol
 136     "ordf"      =>    "\xAA",   # feminine ordinal indicator
 137     "not"       =>    "\xAC",   # not sign
 138     "shy"       =>    "\xAD",   # soft hyphen
 139     "reg"       =>    "\xAE",   # registered trademark
 140     "macr"      =>    "\xAF",   # macron, overline
 141     "deg"       =>    "\xB0",   # degree sign
 142     "plusmn"    =>    "\xB1",   # plus-minus sign
 143     "sup2"      =>    "\xB2",   # superscript 2
 144     "sup3"      =>    "\xB3",   # superscript 3
 145     "acute"     =>    "\xB4",   # acute accent
 146     "micro"     =>    "\xB5",   # micro sign
 147     "para"      =>    "\xB6",   # pilcrow sign = paragraph sign
 148     "middot"    =>    "\xB7",   # middle dot = Georgian comma
 149     "cedil"     =>    "\xB8",   # cedilla
 150     "sup1"      =>    "\xB9",   # superscript 1
 151     "ordm"      =>    "\xBA",   # masculine ordinal indicator
 152     "frac14"    =>    "\xBC",   # vulgar fraction one quarter
 153     "frac12"    =>    "\xBD",   # vulgar fraction one half
 154     "frac34"    =>    "\xBE",   # vulgar fraction three quarters
 155     "iquest"    =>    "\xBF",   # inverted question mark
 156     "times"     =>    "\xD7",   # multiplication sign
 157     "divide"    =>    "\xF7",   # division sign
 158 );
 159
 160
 161 ############################################################################
 162 # Initialization
 163 ############################################################################
 164
 165 # Initialize the object.  Must be sure to call our parent initializer.
 166 sub initialize {
 167     my $self = shift;
 168
 169     $$self{alt}      = 0  unless defined $$self{alt};
 170     $$self{indent}   = 4  unless defined $$self{indent};
 171     $$self{loose}    = 0  unless defined $$self{loose};
 172     $$self{sentence} = 0  unless defined $$self{sentence};
 173     $$self{width}    = 76 unless defined $$self{width};
 174
 175     # Figure out what quotes we'll be using for C<> text.
 176     $$self{quotes} ||= "'";
 177     if ($$self{quotes} eq 'none') {
 178         $$self{LQUOTE} = $$self{RQUOTE} = '';
 179     } elsif (length ($$self{quotes}) == 1) {
 180         $$self{LQUOTE} = $$self{RQUOTE} = $$self{quotes};
 181     } elsif ($$self{quotes} =~ /^(.)(.)$/
 182              || $$self{quotes} =~ /^(..)(..)$/) {
 183         $$self{LQUOTE} = $1;
 184         $$self{RQUOTE} = $2;
 185     } else {
 186         croak qq(Invalid quote specification "$$self{quotes}");
 187     }
 188
 189     $$self{INDENTS}  = [];              # Stack of indentations.
 190     $$self{MARGIN}   = $$self{indent};  # Current left margin in spaces.
 191
 192     $self->SUPER::initialize;
 193 }
 194
 195
 196 ############################################################################
 197 # Core overrides
 198 ############################################################################
 199
 200 # Called for each command paragraph.  Gets the command, the associated
 201 # paragraph, the line number, and a Pod::Paragraph object.  Just dispatches
 202 # the command to a method named the same as the command.  =cut is handled
 203 # internally by Pod::Parser.
 204 sub command {
 205     my $self = shift;
 206     my $command = shift;
 207     return if $command eq 'pod';
 208     return if ($$self{EXCLUDE} && $command ne 'end');
 209     $self->item ("\n") if defined $$self{ITEM};
 210     if ($self->can ('cmd_' . $command)) {
 211         $command = 'cmd_' . $command;
 212         $self->$command (@_);
 213     } else {
 214         my ($text, $line, $paragraph) = @_;
 215         my ($file, $line) = $paragraph->file_line;
 216         $text =~ s/\n+\z//;
 217         $text = " $text" if ($text =~ /^\S/);
 218         warn qq($file:$line: Unknown command paragraph "=$command$text"\n);
 219         return;
 220     }
 221 }
 222
 223 # Called for a verbatim paragraph.  Gets the paragraph, the line number, and
 224 # a Pod::Paragraph object.  Just output it verbatim, but with tabs converted
 225 # to spaces.
 226 sub verbatim {
 227     my $self = shift;
 228     return if $$self{EXCLUDE};
 229     $self->item if defined $$self{ITEM};
 230     local $_ = shift;
 231     return if /^\s*$/;
 232     s/^(\s*\S+)/(' ' x $$self{MARGIN}) . $1/gme;
 233     $self->output ($_);
 234 }
 235
 236 # Called for a regular text block.  Gets the paragraph, the line number, and
 237 # a Pod::Paragraph object.  Perform interpolation and output the results.
 238 sub textblock {
 239     my $self = shift;
 240     return if $$self{EXCLUDE};
 241     $self->output ($_[0]), return if $$self{VERBATIM};
 242     local $_ = shift;
 243     my $line = shift;
 244
 245     # Perform a little magic to collapse multiple L<> references.  This is
 246     # here mostly for backwards-compatibility.  We'll just rewrite the whole
 247     # thing into actual text at this part, bypassing the whole internal
 248     # sequence parsing thing.
 249     s{
 250         (
 251           L<                    # A link of the form L</something>.
 252               /
 253               (
 254                   [:\w]+        # The item has to be a simple word...
 255                   (\(\))?       # ...or simple function.
 256               )
 257           >
 258           (
 259               ,?\s+(and\s+)?    # Allow lots of them, conjuncted.
 260               L<
 261                   /
 262                   (
 263                       [:\w]+
 264                       (\(\))?
 265                   )
 266               >
 267           )+
 268         )
 269     } {
 270         local $_ = $1;
 271         s%L</([^>]+)>%$1%g;
 272         my @items = split /(?:,?\s+(?:and\s+)?)/;
 273         my $string = "the ";
 274         my $i;
 275         for ($i = 0; $i < @items; $i++) {
 276             $string .= $items[$i];
 277             $string .= ", " if @items > 2 && $i != $#items;
 278             $string .= " and " if ($i == $#items - 1);
 279         }
 280         $string .= " entries elsewhere in this document";
 281         $string;
 282     }gex;
 283
 284     # Now actually interpolate and output the paragraph.
 285     $_ = $self->interpolate ($_, $line);
 286     s/\s+$/\n/;
 287     if (defined $$self{ITEM}) {
 288         $self->item ($_ . "\n");
 289     } else {
 290         $self->output ($self->reformat ($_ . "\n"));
 291     }
 292 }
 293
 294 # Called for an interior sequence.  Gets the command, argument, and a
 295 # Pod::InteriorSequence object and is expected to return the resulting text.
 296 # Calls code, bold, italic, file, and link to handle those types of
 297 # sequences, and handles S<>, E<>, X<>, and Z<> directly.
 298 sub interior_sequence {
 299     my $self = shift;
 300     my $command = shift;
 301     local $_ = shift;
 302     return '' if ($command eq 'X' || $command eq 'Z');
 303
 304     # Expand escapes into the actual character now, carping if invalid.
 305     if ($command eq 'E') {
 306         if (/^\d+$/) {
 307             return chr;
 308         } else {
 309             return $ESCAPES{$_} if defined $ESCAPES{$_};
 310             carp "Unknown escape: E<$_>";
 311             return "E<$_>";
 312         }
 313     }
 314
 315     # For all the other sequences, empty content produces no output.
 316     return if $_ eq '';
 317
 318     # For S<>, compress all internal whitespace and then map spaces to \01.
 319     # When we output the text, we'll map this back.
 320     if ($command eq 'S') {
 321         s/\s{2,}/ /g;
 322         tr/ /\01/;
 323         return $_;
 324     }
 325
 326     # Anything else needs to get dispatched to another method.
 327     if    ($command eq 'B') { return $self->seq_b ($_) }
 328     elsif ($command eq 'C') { return $self->seq_c ($_) }
 329     elsif ($command eq 'F') { return $self->seq_f ($_) }
 330     elsif ($command eq 'I') { return $self->seq_i ($_) }
 331     elsif ($command eq 'L') { return $self->seq_l ($_) }
 332     else { carp "Unknown sequence $command<$_>" }
 333 }
 334
 335 # Called for each paragraph that's actually part of the POD.  We take
 336 # advantage of this opportunity to untabify the input.
 337 sub preprocess_paragraph {
 338     my $self = shift;
 339     local $_ = shift;
 340     1 while s/^(.*?)(\t+)/$1 . ' ' x (length ($2) * 8 - length ($1) % 8)/me;
 341     $_;
 342 }
 343
 344
 345 ############################################################################
 346 # Command paragraphs
 347 ############################################################################
 348
 349 # All command paragraphs take the paragraph and the line number.
 350
 351 # First level heading.
 352 sub cmd_head1 {
 353     my $self = shift;
 354     local $_ = shift;
 355     s/\s+$//;
 356     $_ = $self->interpolate ($_, shift);
 357     if ($$self{alt}) {
 358         $self->output ("\n==== $_ ====\n\n");
 359     } else {
 360         $_ .= "\n" if $$self{loose};
 361         $self->output ($_ . "\n");
 362     }
 363 }
 364
 365 # Second level heading.
 366 sub cmd_head2 {
 367     my $self = shift;
 368     local $_ = shift;
 369     s/\s+$//;
 370     $_ = $self->interpolate ($_, shift);
 371     if ($$self{alt}) {
 372         $self->output ("\n==   $_   ==\n\n");
 373     } else {
 374         $self->output (' ' x ($$self{indent} / 2) . $_ . "\n\n");
 375     }
 376 }
 377
 378 # Start a list.
 379 sub cmd_over {
 380     my $self = shift;
 381     local $_ = shift;
 382     unless (/^[-+]?\d+\s+$/) { $_ = $$self{indent} }
 383     push (@{ $$self{INDENTS} }, $$self{MARGIN});
 384     $$self{MARGIN} += ($_ + 0);
 385 }
 386
 387 # End a list.
 388 sub cmd_back {
 389     my $self = shift;
 390     $$self{MARGIN} = pop @{ $$self{INDENTS} };
 391     unless (defined $$self{MARGIN}) {
 392         carp "Unmatched =back";
 393         $$self{MARGIN} = $$self{indent};
 394     }
 395 }
 396
 397 # An individual list item.
 398 sub cmd_item {
 399     my $self = shift;
 400     if (defined $$self{ITEM}) { $self->item }
 401     local $_ = shift;
 402     s/\s+$//;
 403     $$self{ITEM} = $self->interpolate ($_);
 404 }
 405
 406 # Begin a block for a particular translator.  Setting VERBATIM triggers
 407 # special handling in textblock().
 408 sub cmd_begin {
 409     my $self = shift;
 410     local $_ = shift;
 411     my ($kind) = /^(\S+)/ or return;
 412     if ($kind eq 'text') {
 413         $$self{VERBATIM} = 1;
 414     } else {
 415         $$self{EXCLUDE} = 1;
 416     }
 417 }
 418
 419 # End a block for a particular translator.  We assume that all =begin/=end
 420 # pairs are properly closed.
 421 sub cmd_end {
 422     my $self = shift;
 423     $$self{EXCLUDE} = 0;
 424     $$self{VERBATIM} = 0;
 425 }
 426
 427 # One paragraph for a particular translator.  Ignore it unless it's intended
 428 # for text, in which case we treat it as a verbatim text block.
 429 sub cmd_for {
 430     my $self = shift;
 431     local $_ = shift;
 432     my $line = shift;
 433     return unless s/^text\b[ \t]*\n?//;
 434     $self->verbatim ($_, $line);
 435 }
 436
 437
 438 ############################################################################
 439 # Interior sequences
 440 ############################################################################
 441
 442 # The simple formatting ones.  These are here mostly so that subclasses can
 443 # override them and do more complicated things.
 444 sub seq_b { return $_[0]{alt} ? "``$_[1]''" : $_[1] }
 445 sub seq_f { return $_[0]{alt} ? "\"$_[1]\"" : $_[1] }
 446 sub seq_i { return '*' . $_[1] . '*' }
 447 sub seq_c {
 448     return $_[0]{alt} ? "``$_[1]''" : "$_[0]{LQUOTE}$_[1]$_[0]{RQUOTE}"
 449 }
 450
 451 # The complicated one.  Handle links.  Since this is plain text, we can't
 452 # actually make any real links, so this is all to figure out what text we
 453 # print out.
 454 sub seq_l {
 455     my $self = shift;
 456     local $_ = shift;
 457
 458     # Smash whitespace in case we were split across multiple lines.
 459     s/\s+/ /g;
 460
 461     # If we were given any explicit text, just output it.
 462     if (/^([^|]+)\|/) { return $1 }
 463
 464     # Okay, leading and trailing whitespace isn't important; get rid of it.
 465     s/^\s+//;
 466     s/\s+$//;
 467
 468     # Default to using the whole content of the link entry as a section
 469     # name.  Note that L<manpage/> forces a manpage interpretation, as does
 470     # something looking like L<manpage(section)>.  The latter is an
 471     # enhancement over the original Pod::Text.
 472     my ($manpage, $section) = ('', $_);
 473     if (/^"\s*(.*?)\s*"$/) {
 474         $section = '"' . $1 . '"';
 475     } elsif (m/^[-:.\w]+(?:\(\S+\))?$/) {
 476         ($manpage, $section) = ($_, '');
 477     } elsif (m%/%) {
 478         ($manpage, $section) = split (/\s*\/\s*/, $_, 2);
 479     }
 480
 481     # Now build the actual output text.
 482     my $text = '';
 483     if (!length $section) {
 484         $text = "the $manpage manpage" if length $manpage;
 485     } elsif ($section =~ /^[:\w]+(?:\(\))?/) {
 486         $text .= 'the ' . $section . ' entry';
 487         $text .= (length $manpage) ? " in the $manpage manpage"
 488                                    : " elsewhere in this document";
 489     } else {
 490         $section =~ s/^\"\s*//;
 491         $section =~ s/\s*\"$//;
 492         $text .= 'the section on "' . $section . '"';
 493         $text .= " in the $manpage manpage" if length $manpage;
 494     }
 495     $text;
 496 }
 497
 498
 499 ############################################################################
 500 # List handling
 501 ############################################################################
 502
 503 # This method is called whenever an =item command is complete (in other
 504 # words, we've seen its associated paragraph or know for certain that it
 505 # doesn't have one).  It gets the paragraph associated with the item as an
 506 # argument.  If that argument is empty, just output the item tag; if it
 507 # contains a newline, output the item tag followed by the newline.
 508 # Otherwise, see if there's enough room for us to output the item tag in the
 509 # margin of the text or if we have to put it on a separate line.
 510 sub item {
 511     my $self = shift;
 512     local $_ = shift;
 513     my $tag = $$self{ITEM};
 514     unless (defined $tag) {
 515         carp "item called without tag";
 516         return;
 517     }
 518     undef $$self{ITEM};
 519     my $indent = $$self{INDENTS}[-1];
 520     unless (defined $indent) { $indent = $$self{indent} }
 521     my $space = ' ' x $indent;
 522     $space =~ s/^ /:/ if $$self{alt};
 523     if (!$_ || /^\s+$/ || ($$self{MARGIN} - $indent < length ($tag) + 1)) {
 524         my $margin = $$self{MARGIN};
 525         $$self{MARGIN} = $indent;
 526         my $output = $self->reformat ($tag);
 527         $output =~ s/\n*$/\n/;
 528         $self->output ($output);
 529         $$self{MARGIN} = $margin;
 530         $self->output ($self->reformat ($_)) if /\S/;
 531     } else {
 532         $_ = $self->reformat ($_);
 533         s/^ /:/ if ($$self{alt} && $indent > 0);
 534         my $tagspace = ' ' x length $tag;
 535         s/^($space)$tagspace/$1$tag/ or warn "Bizarre space in item";
 536         $self->output ($_);
 537     }
 538 }
 539
 540
 541 ############################################################################
 542 # Output formatting
 543 ############################################################################
 544
 545 # Wrap a line, indenting by the current left margin.  We can't use
 546 # Text::Wrap because it plays games with tabs.  We can't use formline, even
 547 # though we'd really like to, because it screws up non-printing characters.
 548 # So we have to do the wrapping ourselves.
 549 sub wrap {
 550     my $self = shift;
 551     local $_ = shift;
 552     my $output = '';
 553     my $spaces = ' ' x $$self{MARGIN};
 554     my $width = $$self{width} - $$self{MARGIN};
 555     while (length > $width) {
 556         if (s/^([^\n]{0,$width})\s+// || s/^([^\n]{$width})//) {
 557             $output .= $spaces . $1 . "\n";
 558         } else {
 559             last;
 560         }
 561     }
 562     $output .= $spaces . $_;
 563     $output =~ s/\s+$/\n\n/;
 564     $output;
 565 }
 566
 567 # Reformat a paragraph of text for the current margin.  Takes the text to
 568 # reformat and returns the formatted text.
 569 sub reformat {
 570     my $self = shift;
 571     local $_ = shift;
 572
 573     # If we're trying to preserve two spaces after sentences, do some
 574     # munging to support that.  Otherwise, smash all repeated whitespace.
 575     if ($$self{sentence}) {
 576         s/ +$//mg;
 577         s/\.\n/. \n/g;
 578         s/\n/ /g;
 579         s/   +/  /g;
 580     } else {
 581         s/\s+/ /g;
 582     }
 583     $self->wrap ($_);
 584 }
 585
 586 # Output text to the output device.
 587 sub output { $_[1] =~ tr/\01/ /; print { $_[0]->output_handle } $_[1] }
 588
 589
 590 ############################################################################
 591 # Backwards compatibility
 592 ############################################################################
 593
 594 # The old Pod::Text module did everything in a pod2text() function.  This
 595 # tries to provide the same interface for legacy applications.
 596 sub pod2text {
 597     my @args;
 598
 599     # This is really ugly; I hate doing option parsing in the middle of a
 600     # module.  But the old Pod::Text module supported passing flags to its
 601     # entry function, so handle -a and -<number>.
 602     while ($_[0] =~ /^-/) {
 603         my $flag = shift;
 604         if    ($flag eq '-a')       { push (@args, alt => 1)    }
 605         elsif ($flag =~ /^-(\d+)$/) { push (@args, width => $1) }
 606         else {
 607             unshift (@_, $flag);
 608             last;
 609         }
 610     }
 611
 612     # Now that we know what arguments we're using, create the parser.
 613     my $parser = Pod::Text->new (@args);
 614
 615     # If two arguments were given, the second argument is going to be a file
 616     # handle.  That means we want to call parse_from_filehandle(), which
 617     # means we need to turn the first argument into a file handle.  Magic
 618     # open will handle the <&STDIN case automagically.
 619     if (defined $_[1]) {
 620         my @fhs = @_;
 621         local *IN;
 622         unless (open (IN, $fhs[0])) {
 623             croak ("Can't open $fhs[0] for reading: $!\n");
 624             return;
 625         }
 626         $fhs[0] = \*IN;
 627         return $parser->parse_from_filehandle (@fhs);
 628     } else {
 629         return $parser->parse_from_file (@_);
 630     }
 631 }
 632
 633
 634 ############################################################################
 635 # Module return value and documentation
 636 ############################################################################
 637
 638 1;
 639 __END__
 640
 641 =head1 NAME
 642
 643 Pod::Text - Convert POD data to formatted ASCII text
 644
 645 =head1 SYNOPSIS
 646
 647     use Pod::Text;
 648     my $parser = Pod::Text->new (sentence => 0, width => 78);
 649
 650     # Read POD from STDIN and write to STDOUT.
 651     $parser->parse_from_filehandle;
 652
 653     # Read POD from file.pod and write to file.txt.
 654     $parser->parse_from_file ('file.pod', 'file.txt');
 655
 656 =head1 DESCRIPTION
 657
 658 Pod::Text is a module that can convert documentation in the POD format (the
 659 preferred language for documenting Perl) into formatted ASCII.  It uses no
 660 special formatting controls or codes whatsoever, and its output is therefore
 661 suitable for nearly any device.
 662
 663 As a derived class from Pod::Parser, Pod::Text supports the same methods and
 664 interfaces.  See L<Pod::Parser> for all the details; briefly, one creates a
 665 new parser with C<Pod::Text-E<gt>new()> and then calls either
 666 parse_from_filehandle() or parse_from_file().
 667
 668 new() can take options, in the form of key/value pairs, that control the
 669 behavior of the parser.  The currently recognized options are:
 670
 671 =over 4
 672
 673 =item alt
 674
 675 If set to a true value, selects an alternate output format that, among other
 676 things, uses a different heading style and marks C<=item> entries with a
 677 colon in the left margin.  Defaults to false.
 678
 679 =item indent
 680
 681 The number of spaces to indent regular text, and the default indentation for
 682 C<=over> blocks.  Defaults to 4.
 683
 684 =item loose
 685
 686 If set to a true value, a blank line is printed after a C<=head1> heading.
 687 If set to false (the default), no blank line is printed after C<=head1>,
 688 although one is still printed after C<=head2>.  This is the default because
 689 it's the expected formatting for manual pages; if you're formatting
 690 arbitrary text documents, setting this to true may result in more pleasing
 691 output.
 692
 693 =item quotes
 694
 695 Sets the quote marks used to surround CE<lt>> text.  If the value is a
 696 single character, it is used as both the left and right quote; if it is two
 697 characters, the first character is used as the left quote and the second as
 698 the right quoted; and if it is four characters, the first two are used as
 699 the left quote and the second two as the right quote.
 700
 701 This may also be set to the special value C<none>, in which case no quote
 702 marks are added around CE<lt>> text.
 703
 704 =item sentence
 705
 706 If set to a true value, Pod::Text will assume that each sentence ends in two
 707 spaces, and will try to preserve that spacing.  If set to false, all
 708 consecutive whitespace in non-verbatim paragraphs is compressed into a
 709 single space.  Defaults to true.
 710
 711 =item width
 712
 713 The column at which to wrap text on the right-hand side.  Defaults to 76.
 714
 715 =back
 716
 717 The standard Pod::Parser method parse_from_filehandle() takes up to two
 718 arguments, the first being the file handle to read POD from and the second
 719 being the file handle to write the formatted output to.  The first defaults
 720 to STDIN if not given, and the second defaults to STDOUT.  The method
 721 parse_from_file() is almost identical, except that its two arguments are the
 722 input and output disk files instead.  See L<Pod::Parser> for the specific
 723 details.
 724
 725 =head1 DIAGNOSTICS
 726
 727 =over 4
 728
 729 =item Bizarre space in item
 730
 731 (W) Something has gone wrong in internal C<=item> processing.  This message
 732 indicates a bug in Pod::Text; you should never see it.
 733
 734 =item Can't open %s for reading: %s
 735
 736 (F) Pod::Text was invoked via the compatibility mode pod2text() interface
 737 and the input file it was given could not be opened.
 738
 739 =item Invalid quote specification "%s"
 740
 741 (F) The quote specification given (the quotes option to the constructor) was
 742 invalid.  A quote specification must be one, two, or four characters long.
 743
 744 =item %s:%d: Unknown command paragraph "%s".
 745
 746 (W) The POD source contained a non-standard command paragraph (something of
 747 the form C<=command args>) that Pod::Man didn't know about.  It was ignored.
 748
 749 =item Unknown escape: %s
 750
 751 (W) The POD source contained an C<EE<lt>E<gt>> escape that Pod::Text didn't
 752 know about.
 753
 754 =item Unknown sequence: %s
 755
 756 (W) The POD source contained a non-standard internal sequence (something of
 757 the form C<XE<lt>E<gt>>) that Pod::Text didn't know about.
 758
 759 =item Unmatched =back
 760
 761 (W) Pod::Text encountered a C<=back> command that didn't correspond to an
 762 C<=over> command.
 763
 764 =back
 765
 766 =head1 RESTRICTIONS
 767
 768 Embedded Ctrl-As (octal 001) in the input will be mapped to spaces on
 769 output, due to an internal implementation detail.
 770
 771 =head1 NOTES
 772
 773 This is a replacement for an earlier Pod::Text module written by Tom
 774 Christiansen.  It has a revamped interface, since it now uses Pod::Parser,
 775 but an interface roughly compatible with the old Pod::Text::pod2text()
 776 function is still available.  Please change to the new calling convention,
 777 though.
 778
 779 The original Pod::Text contained code to do formatting via termcap
 780 sequences, although it wasn't turned on by default and it was problematic to
 781 get it to work at all.  This rewrite doesn't even try to do that, but a
 782 subclass of it does.  Look for L<Pod::Text::Termcap|Pod::Text::Termcap>.
 783
 784 =head1 SEE ALSO
 785
 786 L<Pod::Parser|Pod::Parser>, L<Pod::Text::Termcap|Pod::Text::Termcap>,
 787 pod2text(1)
 788
 789 =head1 AUTHOR
 790
 791 Russ Allbery E<lt>rra@stanford.eduE<gt>, based I<very> heavily on the
 792 original Pod::Text by Tom Christiansen E<lt>tchrist@mox.perl.comE<gt> and
 793 its conversion to Pod::Parser by Brad Appleton
 794 E<lt>bradapp@enteract.comE<gt>.
 795
 796 =cut