326 lines
11 KiB
HTML
326 lines
11 KiB
HTML
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<HTML><HEAD><TITLE>Man page of POD2TEXT</TITLE>
|
||
</HEAD><BODY>
|
||
<H1>POD2TEXT</H1>
|
||
Section: Perl Programmers Reference Guide (1)<BR>Updated: 2020-10-19<BR><A HREF="#index">Index</A>
|
||
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<A NAME="lbAB"> </A>
|
||
<H2>NAME</H2>
|
||
|
||
pod2text - Convert POD data to formatted ASCII text
|
||
<A NAME="lbAC"> </A>
|
||
<H2>SYNOPSIS</H2>
|
||
|
||
|
||
|
||
pod2text [<B>-aclostu</B>] [<B>--code</B>] [<B>--errors</B>=<I>style</I>] [<B>-i</B> <I>indent</I>]
|
||
<BR> [<B>-q</B> <I>quotes</I>] [<B>--nourls</B>] [<B>--stderr</B>] [<B>-w</B> <I>width</I>]
|
||
<BR> [<I>input</I> [<I>output</I> ...]]
|
||
<P>
|
||
|
||
pod2text <B>-h</B>
|
||
<A NAME="lbAD"> </A>
|
||
<H2>DESCRIPTION</H2>
|
||
|
||
|
||
|
||
<B>pod2text</B> is a front-end for Pod::Text and its subclasses. It uses them
|
||
to generate formatted <FONT SIZE="-1">ASCII</FONT> text from <FONT SIZE="-1">POD</FONT> source. It can optionally use
|
||
either termcap sequences or <FONT SIZE="-1">ANSI</FONT> color escape sequences to format the text.
|
||
<P>
|
||
|
||
<I>input</I> is the file to read for <FONT SIZE="-1">POD</FONT> source (the <FONT SIZE="-1">POD</FONT> can be embedded in
|
||
code). If <I>input</I> isn't given, it defaults to <TT>"STDIN"</TT>. <I>output</I>, if
|
||
given, is the file to which to write the formatted output. If <I>output</I>
|
||
isn't given, the formatted output is written to <TT>"STDOUT"</TT>. Several <FONT SIZE="-1">POD</FONT>
|
||
files can be processed in the same <B>pod2text</B> invocation (saving module
|
||
load and compile times) by providing multiple pairs of <I>input</I> and
|
||
<I>output</I> files on the command line.
|
||
<A NAME="lbAE"> </A>
|
||
<H2>OPTIONS</H2>
|
||
|
||
|
||
|
||
<DL COMPACT>
|
||
<DT id="1"><B>-a</B>, <B>--alt</B><DD>
|
||
|
||
|
||
Use an alternate output format that, among other things, uses a different
|
||
heading style and marks <TT>"=item"</TT> entries with a colon in the left margin.
|
||
<DT id="2"><B>--code</B><DD>
|
||
|
||
|
||
Include any non-POD text from the input file in the output as well. Useful
|
||
for viewing code documented with <FONT SIZE="-1">POD</FONT> blocks with the <FONT SIZE="-1">POD</FONT> rendered and the
|
||
code left intact.
|
||
<DT id="3"><B>-c</B>, <B>--color</B><DD>
|
||
|
||
|
||
Format the output with <FONT SIZE="-1">ANSI</FONT> color escape sequences. Using this option
|
||
requires that Term::ANSIColor be installed on your system.
|
||
<DT id="4"><B>--errors</B>=<I>style</I><DD>
|
||
|
||
|
||
Set the error handling style. <TT>"die"</TT> says to throw an exception on any
|
||
<FONT SIZE="-1">POD</FONT> formatting error. <TT>"stderr"</TT> says to report errors on standard error,
|
||
but not to throw an exception. <TT>"pod"</TT> says to include a <FONT SIZE="-1">POD ERRORS</FONT>
|
||
section in the resulting documentation summarizing the errors. <TT>"none"</TT>
|
||
ignores <FONT SIZE="-1">POD</FONT> errors entirely, as much as possible.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
The default is <TT>"die"</TT>.
|
||
<DT id="5"><B>-i</B> <I>indent</I>, <B>--indent=</B><I>indent</I><DD>
|
||
|
||
|
||
Set the number of spaces to indent regular text, and the default indentation
|
||
for <TT>"=over"</TT> blocks. Defaults to 4 spaces if this option isn't given.
|
||
<DT id="6"><B>-h</B>, <B>--help</B><DD>
|
||
|
||
|
||
Print out usage information and exit.
|
||
<DT id="7"><B>-l</B>, <B>--loose</B><DD>
|
||
|
||
|
||
Print a blank line after a <TT>"=head1"</TT> heading. Normally, no blank line is
|
||
printed after <TT>"=head1"</TT>, although one is still printed after <TT>"=head2"</TT>,
|
||
because this is the expected formatting for manual pages; if you're
|
||
formatting arbitrary text documents, using this option is recommended.
|
||
<DT id="8"><B>-m</B> <I>width</I>, <B>--left-margin</B>=<I>width</I>, <B>--margin</B>=<I>width</I><DD>
|
||
|
||
|
||
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 <B>-i</B> option.
|
||
<DT id="9"><B>--nourls</B><DD>
|
||
|
||
|
||
Normally, L<> formatting codes with a <FONT SIZE="-1">URL</FONT> but anchor text are formatted
|
||
to show both the anchor text and the <FONT SIZE="-1">URL.</FONT> In other words:
|
||
|
||
|
||
<P>
|
||
|
||
|
||
|
||
|
||
<PRE>
|
||
L<foo|<A HREF="http://example.com/">http://example.com/</A>>
|
||
|
||
</PRE>
|
||
|
||
|
||
|
||
|
||
<P>
|
||
|
||
|
||
is formatted as:
|
||
|
||
|
||
<P>
|
||
|
||
|
||
|
||
|
||
<PRE>
|
||
foo <<A HREF="http://example.com/">http://example.com/</A>>
|
||
|
||
</PRE>
|
||
|
||
|
||
|
||
|
||
<P>
|
||
|
||
|
||
This flag, if given, suppresses the <FONT SIZE="-1">URL</FONT> when anchor text is given, so this
|
||
example would be formatted as just <TT>"foo"</TT>. This can produce less
|
||
cluttered output in cases where the URLs are not particularly important.
|
||
<DT id="10"><B>-o</B>, <B>--overstrike</B><DD>
|
||
|
||
|
||
Format the output with overstrike printing. Bold text is rendered as
|
||
character, backspace, character. Italics and file names are rendered as
|
||
underscore, backspace, character. Many pagers, such as <B>less</B>, know how
|
||
to convert this to bold or underlined text.
|
||
<DT id="11"><B>-q</B> <I>quotes</I>, <B>--quotes</B>=<I>quotes</I><DD>
|
||
|
||
|
||
Sets the quote marks used to surround C<> text to <I>quotes</I>. If
|
||
<I>quotes</I> is a single character, it is used as both the left and right
|
||
quote. Otherwise, it is split in half, and the first half of the string
|
||
is used as the left quote and the second is used as the right quote.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
<I>quotes</I> may also be set to the special value <TT>"none"</TT>, in which case no
|
||
quote marks are added around C<> text.
|
||
<DT id="12"><B>-s</B>, <B>--sentence</B><DD>
|
||
|
||
|
||
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.
|
||
<DT id="13"><B>--stderr</B><DD>
|
||
|
||
|
||
By default, <B>pod2text</B> dies if any errors are detected in the <FONT SIZE="-1">POD</FONT> input.
|
||
If <B>--stderr</B> is given and no <B>--errors</B> flag is present, errors are
|
||
sent to standard error, but <B>pod2text</B> does not abort. This is
|
||
equivalent to <TT>"--errors=stderr"</TT> and is supported for backward
|
||
compatibility.
|
||
<DT id="14"><B>-t</B>, <B>--termcap</B><DD>
|
||
|
||
|
||
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 <B>pod2text</B>
|
||
will contain terminal control sequences for your current terminal type.
|
||
<DT id="15"><B>-u</B>, <B>--utf8</B><DD>
|
||
|
||
|
||
By default, <B>pod2text</B> tries to use the same output encoding as its input
|
||
encoding (to be backward-compatible with older versions). This option
|
||
says to instead force the output encoding to <FONT SIZE="-1">UTF-8.</FONT>
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Be aware that, when using this option, the input encoding of your <FONT SIZE="-1">POD</FONT>
|
||
source should be properly declared unless it's US-ASCII. Pod::Simple
|
||
will attempt to guess the encoding and may be successful if it's
|
||
Latin-1 or <FONT SIZE="-1">UTF-8,</FONT> but it will warn, which by default results in a
|
||
<B>pod2text</B> failure. Use the <TT>"=encoding"</TT> command to declare the
|
||
encoding. See <B><A HREF="/cgi-bin/man/man2html?1+perlpod">perlpod</A></B>(1) for more information.
|
||
<DT id="16"><B>-w</B>, <B>--width=</B><I>width</I>, <B>-</B><I>width</I><DD>
|
||
|
||
|
||
The column at which to wrap text on the right-hand side. Defaults to 76,
|
||
unless <B>-t</B> is given, in which case it's two columns less than the width of
|
||
your terminal device.
|
||
</DL>
|
||
<A NAME="lbAF"> </A>
|
||
<H2>EXIT STATUS</H2>
|
||
|
||
|
||
|
||
As long as all documents processed result in some output, even if that
|
||
output includes errata (a <TT>"POD ERRORS"</TT> section generated with
|
||
<TT>"--errors=pod"</TT>), <B>pod2text</B> will exit with status 0. If any of the
|
||
documents being processed do not result in an output document, <B>pod2text</B>
|
||
will exit with status 1. If there are syntax errors in a <FONT SIZE="-1">POD</FONT> document
|
||
being processed and the error handling style is set to the default of
|
||
<TT>"die"</TT>, <B>pod2text</B> will abort immediately with exit status 255.
|
||
<A NAME="lbAG"> </A>
|
||
<H2>DIAGNOSTICS</H2>
|
||
|
||
|
||
|
||
If <B>pod2text</B> fails with errors, see Pod::Text and Pod::Simple for
|
||
information about what those errors might mean. Internally, it can also
|
||
produce the following diagnostics:
|
||
<DL COMPACT>
|
||
<DT id="17">-c (--color) requires Term::ANSIColor be installed<DD>
|
||
|
||
|
||
(F) <B>-c</B> or <B>--color</B> were given, but Term::ANSIColor could not be
|
||
loaded.
|
||
<DT id="18">Unknown option: %s<DD>
|
||
|
||
|
||
|
||
|
||
(F) An unknown command line option was given.
|
||
</DL>
|
||
<P>
|
||
|
||
In addition, other Getopt::Long error messages may result from invalid
|
||
command-line options.
|
||
<A NAME="lbAH"> </A>
|
||
<H2>ENVIRONMENT</H2>
|
||
|
||
|
||
|
||
<DL COMPACT>
|
||
<DT id="19"><FONT SIZE="-1">COLUMNS</FONT><DD>
|
||
|
||
|
||
If <B>-t</B> is given, <B>pod2text</B> will take the current width of your screen
|
||
from this environment variable, if available. It overrides terminal width
|
||
information in <FONT SIZE="-1">TERMCAP.</FONT>
|
||
<DT id="20"><FONT SIZE="-1">TERMCAP</FONT><DD>
|
||
|
||
|
||
If <B>-t</B> is given, <B>pod2text</B> will use the contents of this environment
|
||
variable if available to determine the correct formatting sequences for your
|
||
current terminal device.
|
||
</DL>
|
||
<A NAME="lbAI"> </A>
|
||
<H2>AUTHOR</H2>
|
||
|
||
|
||
|
||
Russ Allbery <<A HREF="mailto:rra@cpan.org">rra@cpan.org</A>>.
|
||
<A NAME="lbAJ"> </A>
|
||
<H2>COPYRIGHT AND LICENSE</H2>
|
||
|
||
|
||
|
||
Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2018 Russ Allbery
|
||
<<A HREF="mailto:rra@cpan.org">rra@cpan.org</A>>
|
||
<P>
|
||
|
||
This program is free software; you may redistribute it and/or modify it
|
||
under the same terms as Perl itself.
|
||
<A NAME="lbAK"> </A>
|
||
<H2>SEE ALSO</H2>
|
||
|
||
|
||
|
||
Pod::Text, Pod::Text::Color, Pod::Text::Overstrike,
|
||
Pod::Text::Termcap, Pod::Simple, <B><A HREF="/cgi-bin/man/man2html?1+perlpod">perlpod</A></B>(1)
|
||
<P>
|
||
|
||
The current version of this script is always available from its web site at
|
||
<<A HREF="https://www.eyrie.org/~eagle/software/podlators/">https://www.eyrie.org/~eagle/software/podlators/</A>>. It is also part of the
|
||
Perl core distribution as of 5.6.0.
|
||
<P>
|
||
|
||
<HR>
|
||
<A NAME="index"> </A><H2>Index</H2>
|
||
<DL>
|
||
<DT id="21"><A HREF="#lbAB">NAME</A><DD>
|
||
<DT id="22"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
||
<DT id="23"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
||
<DT id="24"><A HREF="#lbAE">OPTIONS</A><DD>
|
||
<DT id="25"><A HREF="#lbAF">EXIT STATUS</A><DD>
|
||
<DT id="26"><A HREF="#lbAG">DIAGNOSTICS</A><DD>
|
||
<DT id="27"><A HREF="#lbAH">ENVIRONMENT</A><DD>
|
||
<DT id="28"><A HREF="#lbAI">AUTHOR</A><DD>
|
||
<DT id="29"><A HREF="#lbAJ">COPYRIGHT AND LICENSE</A><DD>
|
||
<DT id="30"><A HREF="#lbAK">SEE ALSO</A><DD>
|
||
</DL>
|
||
<HR>
|
||
This document was created by
|
||
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
||
using the manual pages.<BR>
|
||
Time: 00:05:24 GMT, March 31, 2021
|
||
</BODY>
|
||
</HTML>
|