podlators version 0.06
            (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.

                                               Russ Allbery
                                               [email protected]

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.