lib/Pod/Text.pm

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