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

  Copyright 1999, 2000, 2001 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.

  I welcome all bug reports and patches for this package (and in
  particular, if you're looking for a project, see TODO).  However, please
  be aware that I tend to be extremely busy and to get a lot of mail.
  I'll save your mail and get to it as soon as I can, but depending on how
  busy I am it may take me a couple of months.


INTRODUCTION

  WARNING: Installation of this package will replace the pod2text and
  pod2man scripts that come with Perl, and for Perl 5.6.0 or later the
  versions of Pod::Text and Pod::Man installed with Perl.  Make sure that
  you have a version of this package as new as or newer than the modules
  that come with Perl.  For older versions of Perl, pod2text and pod2man
  will still be overwritten, but Pod::Text will not be, making many of the
  options in pod2text not actually 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).  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, three useful subclasses of Pod::Text are
  also included: Pod::Text::Color, which uses ANSI color escape sequences
  to highlight text, Pod::Text::Termcap, which determines the correct
  control sequences to embolden and underline text from terminal termcap
  information, and Pod::Text::Overstrike, which uses the backspacing
  method of underlining and bold also used by the output of nroff.


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: For versions of Perl prior to 5.6.0, as mentioned above, this
  will install Pod::Text in a location that won't be seen by Perl by
  default.  This will also overwrite Perl's pod2text and pod2man with the
  version that comes with this package, and for Perl 5.6.0 or higher will
  replace Pod::Man and Pod::Text that came with Perl.  Save backup copies
  of these files if you do this, and make sure this is what you want.

  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 Perl core 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.  Thanks
  also for finding a bug with C<> in headings confusing nroff.

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

  To Johan Vromans, for pointing out a bug in the filename parsing in
  Pod::Man and help with various packaging problems.

  To Abigail, for better error handling code for unknown command
  paragraphs.

  To Zack Weinberg, for suggesting the right *roff magic to prevent blank
  lines between consecutive =item tags in lists and for explaining \fP and
  how to prevent escapes like C<> from breaking the font in headings.

  To Nicholas Clark, for the original patch to pod2man to allow it to
  process multiple files with one invocation.

  To Joe Smith, for Pod::Text::Overstrike.

  To Robin Barker, for finding problems with multiline =head* headings and
  input filenames containing spaces.

  To Brendan O'Dea and Robin Barker (again!), for finding problems with
  Pod::Man guesswork and function and man page references that contained
  words in all caps and proposing fixes.

                                                Russ Allbery
                                                rra@stanford.edu
