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