podlators version 0.08
(Format POD source into various output formats)
Copyright 1999 Russ Allbery <
[email protected]>. 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.
To Michael Schwern, for pointing out that pod2text() needs to be
exported for backwards compatibility.
Russ Allbery
[email protected]
