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