podlators version 4.06
(Format POD source into various output formats)
Maintained by Russ Allbery <rra@cpan.org>
Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
2009, 2010, 2012, 2013, 2014, 2015, 2016 Russ Allbery <rra@cpan.org>.
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
BLURB
podlators contains Pod::Man and Pod::Text modules which convert POD
input to *roff source output, suitable for man pages, or plain text. It
also includes several subclasses of Pod::Text for formatted output to
terminals with various capabilities. It is the source package for the
Pod::Man and Pod::Text modules included with Perl.
DESCRIPTION
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::Simple 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.
Both Pod::Text and Pod::Man provide a variety of options for fine-tuning
their output. Pod::Man also tries to massage input text where
appropriate to produce better output when run through nroff or troff,
such as distinguishing between different types of hyphens and using
slightly smaller case for acronyms.
A general parser utility module for L<> formatting code parsing is also
included, Pod::ParseLink. This implements only the simple parse
described in perlpodspec. It is no longer used by the modules here
(Pod::Simple has a separate implementation of the same concept), but is
included in case others find it useful.
REQUIREMENTS
Perl 5.6.0 or later and Module::Build are required to build this module.
Both Pod::Man and Pod::Text are built on Pod::Simple, which handles the
basic POD parsing and character set conversion. Pod::Simple 3.06 or
later is required (and Pod::Simple 3.07 is recommended). It is
available from CPAN and part of Perl core as of 5.10.0. Encode is also
required (included in Perl core since 5.8.0).
To run the test suite, Test::More is required. It is available from
CPAN and part of Perl core as of 5.6.2.
To enable tests that don't detect functionality problems but are used to
sanity-check the release, set the environment variable RELEASE_TESTING
to a true value. To enable tests that may be sensitive to the local
environment or that produce a lot of false positives without uncovering
many problems, set the environment variable AUTHOR_TESTING to a true
value. For these tests, the additional Perl modules:
Test::MinimumVersion
Test::Pod
Test::Spelling
Test::Strict
Test::Synopsis
and their dependencies as well as a spell-checking program (several are
supported by Test::Spelling) are required. These modules are all
available from CPAN.
BUILDING AND INSTALLATION
Installation of this package will shadow the Pod::Man, Pod::Text, and
subclasses that come with Perl. The ones from Perl will not be
overwritten, but the ones installed by this package will generally take
precendent. This may result in different behavior than using the
versions in Perl. It will probably also shadow the perlpodstyle man
page.
Normally, the pod2man and pod2text scripts installed by this package
will go into a directory like /usr/local/bin. Be sure that this
directory is earlier in your PATH than the directory containing the
modules installed by Perl itself (often /usr/bin). Otherwise, you will
call the new modules with the old driver scripts, which may cause
various problems.
Follow the standard installation procedure for Perl modules using
ExtUtils::MakeMaker, which is to type the following commands:
perl Makefile.PL
make
make test
make install
You'll probably need to do the last step as root. This will also
install driver scripts named pod2text and pod2man and the perlpodstyle
man page.
SUPPORT
The podlators web page at:
http://www.eyrie.org/~eagle/software/podlators/
will always have the current version of this package, the current
documentation, and pointers to any additional resources.
For bug tracking, this package uses the CPAN bug tracker at:
https://rt.cpan.org/Dist/Display.html?Name=podlators
I welcome bug reports and patches for this package at rra@cpan.org
or via the CPAN bug tracker. However, please be aware that I tend to be
extremely busy and work projects often take priority. I'll save your
mail and get to it as soon as I can, but it may take me a couple of
months.
SOURCE REPOSITORY
podlators is maintained using Git. You can access the current source
by cloning the repository at:
git://git.eyrie.org/perl/podlators.git
or view the repository on the web at:
http://git.eyrie.org/?p=perl/podlators.git
You can also use GitHub via:
http://github.com/rra/podlators
The eyrie.org repository is the canonical one, maintained by the author,
but using GitHub is probably more convenient for most purposes. Pull
requests are gratefully reviewed and normally accepted. It's probably
better to use the CPAN bug tracker than GitHub issues, though, to keep
all Perl module issues in the same place.
LICENSE
The podlators package as a whole covered by the following copyright
statement and license:
Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
2009, 2010, 2012, 2013, 2014, 2015, 2016 Russ Allbery <rra@cpan.org>
This program is free software; you may redistribute it and/or modify
it under the same terms as Perl itself. This means that you may
choose between the two licenses that Perl is released under: the GNU
GPL and the Artistic License. Please see your Perl distribution for
the details and copies of the licenses.
All individual files without an explicit exception below are released
under this license. Some files may have additional copyright holders as
noted in those files. There is detailed information about the licensing
of each file in the LICENSE file in this distribution.
Some files in this distribution are individually released under
different licenses, all of which are compatible with the above general
package license but which may require preservation of additional
notices. All required notices are preserved in the LICENSE file.