pod2text - convert pod data to formatted ASCII text


pod2text [-aclst] [-i indent] [-w width] [input [output]]
pod2text -h


The pod2text(1) utility is a front-end for Pod::Text and its subclasses. The utility uses Pod::Text and its subclasses to generate formatted ASCII text from a pod source. It can optionally use either termcap sequences or American National Standards Institute (ANSI) color escape sequences to format the text.

The input refers to the pod source file (the pod can be embedded in code). If input is not given, it defaults to STDIN. The output, if given, is the file in which to write the formatted output. If output is not given, the formatted output is written to STDOUT.


-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.
-c, --color
Format the output with American National Standards Institute (ANSI) color escape sequences. To use this option you must have Term::ANSIColor 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 four spaces if this option is not 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. This option is recommended if you are formatting arbitrary text documents.
-s, --sentence
Assume each sentence ends with two spaces and try to preserve that spacing. Without this option, all consecutive white space 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 at a location where Term::Cap can find it.It also 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
The column at which to wrap text on the right-hand side. Defaults to 76 unless -t is given, in which case it is two columns less than the width of your terminal device.


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

Using -c (--color) requires that Term::ANSIColor be installed.
(F) Either -c or --color was 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 can result from invalid command-line options.


If -t is given, pod2text(1) will take the current width of your screen from this environment variable, if available. It overrides terminal width information in TERMCAP.
If -t is given, pod2text(1) will use the contents of this environment variable, if available, to determine the correct formatting sequences for your current terminal device.


Russ Allbery