                          podlators version 1.00
             (Format POD source into various output formats)

  Copyright 1999, 2000 Russ Allbery <rra@stanford.edu>.  This program is
  free software; you can redistribute it and/or modify it under the same
  terms as Perl itself.


INTRODUCTION

  WARNING: Installation of this package will replace the pod2text and
  pod2man scripts that come with Perl, but the new version of Pod::Text
  won't actually be useable unless you overwrite the version that comes
  with Perl with it (since Perl looks in its own directories before it
  looks in site_perl).  That means that most of the pod2text options will
  fail unless you do that, since it will try to pass them to the old
  Pod::Text.  Note also that the version in this package attempts to be
  backwards-compatible but is not bug compatible, and some things like the
  default wrap margin have changed.  The version contained in this package
  is the default version for Perl 5.5.560 or thereabouts and higher, but
  may be slightly newer depending on how updates have been synchronized.

  WARNING: This package requires Pod::Parser be installed.

  This package contains the replacement for pod2text and Pod::Text in
  versions of Perl 5.005 and earlier.  It also contains Pod::Man and
  pod2man, the replacement for pod2man found in Perl distributions prior
  to 5.6.0.  The modules contained in it use Pod::Parser rather than doing
  the POD parsing themselves, and are designed to be object-oriented and
  to subclass.  As an example, two useful subclasses of Pod::Text are also
  included: Pod::Text::Color, which uses ANSI color escape sequences to
  highlight text, and Pod::Text::Termcap, which determines the correct
  control sequences to embolden and underline text from terminal termcap
  information.


Pod::Text

  The default output of Pod::Text should be mostly identical to the output
  of the original Pod::Text module, except for fixed bugs.  This has been
  tested by comparing the output of both modules when run on perlfunc.pod
  from the Perl 5.005_02 distribution, by comparing output for several
  other shorter pages, and by using the Pod::Parser test suite.

  Known bugs fixed relative to the original Pod::Text:  The first line of
  text after an =item command is wrapped correctly, various problems with
  L<> text have been fixed, and if you use Pod::Text::Termcap, the termcap
  sequences work correctly and use POSIX termios to determine the terminal
  speed.

  There are also a number of additional features, mostly finer control of
  the output of the module under a variety of circumstances.  The
  programmatic interface is also cleaner.


Pod::Man

  The output of Pod::Man should be mostly identical to the output of
  pod2man except for fixed bugs and added new features.  This has been
  tested by comparing the output of both modules given a variety of
  different input.

  Known bugs fixed relative to pod2man:  Nested fonts now work correctly,
  nested =over/=back pairs now work correctly, double quotes are now
  correct in headings and =item tags, hyphens and en dashes are now more
  frequently correct, use of small caps is now more consistent and
  correct, em dashes are now more frequently correct and double dashes for
  things like long options are no longer converted to em dashes, various
  hyphenation problems have been fixed by always turning off hyphenation,
  and index entries no longer cause trailing whitespace and are emitted
  close to the relevant text.

  Additional features over pod2man include a shorter and better documented
  prelude, inclusion of `' quotes around sections marked with C<> when
  viewed using nroff, and a better programmatic interface.


INSTALLATION

  Follow the standard installation procedure for Perl modules, which is to
  type the following commands:

          perl Makefile.PL
          make
          make install

  WARNING: As mentioned above, this will install Pod::Text in a location
  that won't be seen by Perl by default, and will probably overwrite
  Perl's pod2text and pod2man with the version that comes with this
  package.  Save backup copies of pod2text and pod2man if you do this, and
  make sure this is what you want.  If you do this, you probably will also
  want to replace Pod::Text in your Perl module area with the version
  installed by this package, saving a backup copy.

  You'll probably need to do the "make install" as root.  This will also
  install driver scripts named pod2text and pod2man; see their man pages
  for more information.

  Note that in order to use Pod::Text::Color, you have to have the module
  Term::ANSIColor (available from CPAN and part of Perl core as of 5.6.0)
  installed.


THANKS

  To Tom Christiansen, for writing the original Pod::Text and pod2man.
  These modules are based very heavily on those, particularly the termcap
  handling and pretty much all of Pod::Man.

  To Brad Appleton, for writing Pod::Parser, which made writing Pod::Text
  the work of a single Saturday and Pod::Man the work of another single
  Saturday, and for finding lots of bugs in the first try.

  To Gurusamy Sarathy, for pointing out the need for a pod2text()
  compatibility interface for older applications, and for being willing to
  roll this code into the next Perl distribution.

  To Larry Virden, for feedback on the section on writing a man page in
  pod2roff and lots of good suggestions for improving it.

  To Michael Schwern, for pointing out that pod2text() needs to be
  exported for backwards compatibility and for pointing out a bug in the
  collapsing of adjacent L</foo> links in Pod::Man.

  To Marek Rochal, for pointing out a bug in handling of Z<> in Pod::Man,
  that even periods preceded by font escapes need protection at the
  beginning of lines from *roff, and that the handling of =item text with
  embedded newlines was buggy in a previous version of Pod::Man.

  To Tim Jenness, for providing the remaining ISO 8859-1 escapes for
  Pod::Text.  Volunteers to implement the same for Pod::Man are welcome.

                                                Russ Allbery
                                                rra@stanford.edu
