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

  Copyright 1999 Russ Allbery <rra@stanford.edu>.  All rights reserved.
  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 script
  that comes with it, 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.005_56 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
  pod2roff, a proposed replacement for pod2man in the current Perl
  distribution.  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::PlainText
  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 with the version that comes with this package.  Save a
  backup copy of pod2text 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 last as root.  This will also install
  driver scripts named pod2text and pod2roff; 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) installed.

  Pod::Man and pod2roff can be installed without overriding or overwriting
  any part of the standard Perl installation; if you want to install just
  them and not Pod::Text and its driver script, run make and then copy
  blib/lib/Pod/Man.pm and blib/script/pod2roff to the appropriate places
  (your Perl module directory and somewhere on your path, respectively).


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.

                                                Russ Allbery
                                                rra@stanford.edu
