NAME    [Toc]    [Back]

       pod2text - Convert POD data to formatted ASCII text

SYNOPSIS    [Toc]    [Back]

       pod2text [-aclost] [--code] [-i indent] [-q quotes]
       [-w width] [input [output]]

       pod2text -h

DESCRIPTION    [Toc]    [Back]

       pod2text is a front-end for Pod::Text and its  subclasses.
       It uses them to generate formatted ASCII text from POD
       source.  It can optionally use either termcap sequences or
       ANSI color escape sequences to format the text.

       input is the file to read for POD source (the POD can be
       embedded in code).  If input isn't given, it defaults to
       STDIN.  output, if given, is the file to which to write
       the formatted output.  If output isn't given, the formatted
 output is written to STDOUT.

OPTIONS    [Toc]    [Back]

       -a, --alt
           Use an alternate output format that, among other
           things, uses a different heading style and marks
           "=item" entries with a colon in the left margin.

       --code
           Include any non-POD text from the input file in the
           output as well.  Useful for viewing code documented
           with POD blocks with the POD rendered and the code
           left intact.

       -c, --color
           Format the output with ANSI color escape sequences.
           Using this option requires that Term::ANSIColor be
           installed on your system.

       -i indent, --indent=indent
           Set the number of spaces to indent regular text, and
           the default indentation for "=over" blocks.  Defaults
           to 4 spaces if this option isn't given.

       -h, --help
           Print out usage information and exit.

       -l, --loose
           Print a blank line after a "=head1" heading.  Normally,
 no blank line is printed after "=head1",
           although one is still printed after "=head2", because
           this is the expected formatting for manual pages; if
           you're formatting arbitrary text documents, using this
           option is recommended.
       -m width, --left-margin=width, --margin=width
           The width of the left margin in spaces.  Defaults to
           0.  This is the margin for all text, including headings,
 not the amount by which regular text is
           indented; for the latter, see -i option.

       -o, --overstrike
           Format the output with overstruck printing.  Bold text
           is rendered as character, backspace, character.  Italics
 and file names are rendered as underscore,
           backspace, character.  Many pagers, such as less, know
           how to convert this to bold or underlined text.

       -q quotes, --quotes=quotes
           Sets the quote marks used to surround C<> text to
           quotes.  If quotes is a single character, it is used
           as both the left and right quote; if quotes is two
           characters, the first character is used as the left
           quote and the second as the right quoted; and if
           quotes is four characters, the first two are used as
           the left quote and the second two as the right  quote.

           quotes may also be set to the special value "none", in
           which case no quote marks are added around C<> text.

       -s, --sentence
           Assume each sentence ends with two spaces and try to
           preserve that spacing.  Without this option, all consecutive
 whitespace in non-verbatim paragraphs is compressed
 into a single space.

       -t, --termcap
           Try to determine the width of the screen and the bold
           and underline sequences for the terminal from termcap,
           and use that information in formatting the output.
           Output will be wrapped at two columns less than the
           width of your terminal device.  Using this option
           requires that your system have a termcap file somewhere
 where Term::Cap can find it and requires that
           your system support termios.  With this option, the
           output of pod2text will contain terminal control
           sequences for your current terminal type.

       -w, --width=width, -width
           The column at which to wrap text on the right-hand
           side.  Defaults to 76, unless -t is given, in which
           case it's two columns less than the width of your terminal
 device.

DIAGNOSTICS    [Toc]    [Back]

       If pod2text fails with errors, see Pod::Text and
       Pod::Parser for information about what those errors might
       mean.  Internally, it can also produce the following diagnostics:

       -c (--color) requires Term::ANSIColor be installed
           (F) -c or --color were given, but Term::ANSIColor
           could not be loaded.

       Unknown option: %s
           (F) An unknown command line option was given.

       In addition, other Getopt::Long error messages may result
       from invalid command-line options.

ENVIRONMENT    [Toc]    [Back]

       COLUMNS
           If -t is given, pod2text will take the current width
           of your screen from this environment variable, if
           available.  It overrides terminal width information in
           TERMCAP.

       TERMCAP
           If -t is given, pod2text will use the contents of this
           environment variable if available to determine the
           correct formatting sequences for your current terminal
           device.

SEE ALSO    [Toc]    [Back]

       Pod::Text, Pod::Text::Color, Pod::Text::Overstrike,
       Pod::Text::Termcap, Pod::Parser

       The current version of this script is always available
       from its web site at <http://www.eyrie.org/~eagle/soft-
       ware/podlators/>.  It is also part of the Perl core distribution
 as of 5.6.0.

AUTHOR    [Toc]    [Back]

       Russ Allbery <rra@stanford.edu>.

COPYRIGHT AND LICENSE    [Toc]    [Back]

       Copyright 1999, 2000, 2001 by Russ Allbery <rra@stanford.edu>.


       This program is free software; you may redistribute it
       and/or modify it under the same terms as Perl itself.


perl v5.8.5                 2002-11-06                          3