473 lines
17 KiB
HTML
473 lines
17 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of POD2MAN</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>POD2MAN</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>
|
|
|
|
pod2man - Convert POD data to formatted *roff input
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
pod2man [<B>--center</B>=<I>string</I>] [<B>--date</B>=<I>string</I>] [<B>--errors</B>=<I>style</I>]
|
|
<BR> [<B>--fixed</B>=<I>font</I>] [<B>--fixedbold</B>=<I>font</I>] [<B>--fixeditalic</B>=<I>font</I>]
|
|
<BR> [<B>--fixedbolditalic</B>=<I>font</I>] [<B>--name</B>=<I>name</I>] [<B>--nourls</B>]
|
|
<BR> [<B>--official</B>] [<B>--release</B>=<I>version</I>] [<B>--section</B>=<I>manext</I>]
|
|
<BR> [<B>--quotes</B>=<I>quotes</I>] [<B>--lquote</B>=<I>quote</I>] [<B>--rquote</B>=<I>quote</I>]
|
|
<BR> [<B>--stderr</B>] [<B>--utf8</B>] [<B>--verbose</B>] [<I>input</I> [<I>output</I>] ...]
|
|
<P>
|
|
|
|
pod2man <B>--help</B>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
<B>pod2man</B> is a front-end for Pod::Man, using it to generate *roff input
|
|
from <FONT SIZE="-1">POD</FONT> source. The resulting *roff code is suitable for display on a
|
|
terminal using <B><A HREF="/cgi-bin/man/man2html?1+nroff">nroff</A></B>(1), normally via <B><A HREF="/cgi-bin/man/man2html?1+man">man</A></B>(1), or printing using <B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1).
|
|
<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>pod2man</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.
|
|
<P>
|
|
|
|
<B>--section</B>, <B>--release</B>, <B>--center</B>, <B>--date</B>, and <B>--official</B> can
|
|
be used to set the headers and footers to use; if not given, Pod::Man will
|
|
assume various defaults. See below or Pod::Man for details.
|
|
<P>
|
|
|
|
<B>pod2man</B> assumes that your *roff formatters have a fixed-width font
|
|
named <TT>"CW"</TT>. If yours is called something else (like <TT>"CR"</TT>), use
|
|
<B>--fixed</B> to specify it. This generally only matters for troff output
|
|
for printing. Similarly, you can set the fonts used for bold, italic, and
|
|
bold italic fixed-width output.
|
|
<P>
|
|
|
|
Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
|
|
takes care of formatting <B>func()</B>, <A HREF="/cgi-bin/man/man2html?n+func">func</A>(n), and simple variable references
|
|
like <TT>$foo</TT> or <TT>@bar</TT> so you don't have to use code escapes for them; complex
|
|
expressions like <TT>$fred{'stuff'}</TT> will still need to be escaped, though.
|
|
It also translates dashes that aren't used as hyphens into en dashes, makes
|
|
long dashes---like this---into proper em dashes, fixes ``paired quotes,'' and
|
|
takes care of several other troff-specific tweaks. See Pod::Man for
|
|
complete information.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-c</B> <I>string</I>, <B>--center</B>=<I>string</I><DD>
|
|
|
|
|
|
Sets the centered page header for the <TT>".TH"</TT> macro to <I>string</I>. The
|
|
default is ``User Contributed Perl Documentation'', but also see
|
|
<B>--official</B> below.
|
|
<DT id="2"><B>-d</B> <I>string</I>, <B>--date</B>=<I>string</I><DD>
|
|
|
|
|
|
Set the left-hand footer string for the <TT>".TH"</TT> macro to <I>string</I>. By
|
|
default, the modification date of the input file will be used, or the
|
|
current date if input comes from <TT>"STDIN"</TT>, and will be based on <FONT SIZE="-1">UTC</FONT> (so
|
|
that the output will be reproducible regardless of local time zone).
|
|
<DT id="3"><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="4"><B>--fixed</B>=<I>font</I><DD>
|
|
|
|
|
|
The fixed-width font to use for verbatim text and code. Defaults to
|
|
<TT>"CW"</TT>. Some systems may want <TT>"CR"</TT> instead. Only matters for <B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1)
|
|
output.
|
|
<DT id="5"><B>--fixedbold</B>=<I>font</I><DD>
|
|
|
|
|
|
Bold version of the fixed-width font. Defaults to <TT>"CB"</TT>. Only matters
|
|
for <B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1) output.
|
|
<DT id="6"><B>--fixeditalic</B>=<I>font</I><DD>
|
|
|
|
|
|
Italic version of the fixed-width font (actually, something of a misnomer,
|
|
since most fixed-width fonts only have an oblique version, not an italic
|
|
version). Defaults to <TT>"CI"</TT>. Only matters for <B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1) output.
|
|
<DT id="7"><B>--fixedbolditalic</B>=<I>font</I><DD>
|
|
|
|
|
|
Bold italic (probably actually oblique) version of the fixed-width font.
|
|
Pod::Man doesn't assume you have this, and defaults to <TT>"CB"</TT>. Some
|
|
systems (such as Solaris) have this font available as <TT>"CX"</TT>. Only matters
|
|
for <B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1) output.
|
|
<DT id="8"><B>-h</B>, <B>--help</B><DD>
|
|
|
|
|
|
Print out usage information.
|
|
<DT id="9"><B>-l</B>, <B>--lax</B><DD>
|
|
|
|
|
|
No longer used. <B>pod2man</B> used to check its input for validity as a
|
|
manual page, but this should now be done by <B><A HREF="/cgi-bin/man/man2html?1+podchecker">podchecker</A></B>(1) instead.
|
|
Accepted for backward compatibility; this option no longer does anything.
|
|
<DT id="10"><B>--lquote</B>=<I>quote</I><DD>
|
|
|
|
|
|
|
|
<DT id="11"><B>--rquote</B>=<I>quote</I><DD>
|
|
|
|
|
|
|
|
Sets the quote marks used to surround C<> text. <B>--lquote</B> sets the
|
|
left quote mark and <B>--rquote</B> sets the right quote mark. Either may also
|
|
be set to the special value <TT>"none"</TT>, in which case no quote mark is added
|
|
on that side of C<> text (but the font is still changed for troff
|
|
output).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Also see the <B>--quotes</B> option, which can be used to set both quotes at once.
|
|
If both <B>--quotes</B> and one of the other options is set, <B>--lquote</B> or
|
|
<B>--rquote</B> overrides <B>--quotes</B>.
|
|
<DT id="12"><B>-n</B> <I>name</I>, <B>--name</B>=<I>name</I><DD>
|
|
|
|
|
|
Set the name of the manual page for the <TT>".TH"</TT> macro to <I>name</I>. Without
|
|
this option, the manual name is set to the uppercased base name of the
|
|
file being converted unless the manual section is 3, in which case the
|
|
path is parsed to see if it is a Perl module path. If it is, a path like
|
|
<TT>".../lib/Pod/Man.pm"</TT> is converted into a name like <TT>"Pod::Man"</TT>. This
|
|
option, if given, overrides any automatic determination of the name.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Although one does not have to follow this convention, be aware that the
|
|
convention for <FONT SIZE="-1">UNIX</FONT> man pages for commands is for the man page title to be
|
|
in all-uppercase, even if the command isn't.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is probably not useful when converting multiple <FONT SIZE="-1">POD</FONT> files at
|
|
once.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When converting <FONT SIZE="-1">POD</FONT> source from standard input, the name will be set to
|
|
<TT>"STDIN"</TT> if this option is not provided. Providing this option is strongly
|
|
recommended to set a meaningful manual page name.
|
|
<DT id="13"><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="14"><B>-o</B>, <B>--official</B><DD>
|
|
|
|
|
|
Set the default header to indicate that this page is part of the standard
|
|
Perl release, if <B>--center</B> is not also given.
|
|
<DT id="15"><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 (but the font is still changed for
|
|
troff output).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Also see the <B>--lquote</B> and <B>--rquote</B> options, which can be used to set the
|
|
left and right quotes independently. If both <B>--quotes</B> and one of the other
|
|
options is set, <B>--lquote</B> or <B>--rquote</B> overrides <B>--quotes</B>.
|
|
<DT id="16"><B>-r</B> <I>version</I>, <B>--release</B>=<I>version</I><DD>
|
|
|
|
|
|
Set the centered footer for the <TT>".TH"</TT> macro to <I>version</I>. By default,
|
|
this is set to the version of Perl you run <B>pod2man</B> under. Setting this
|
|
to the empty string will cause some *roff implementations to use the
|
|
system default value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that some system <TT>"an"</TT> macro sets assume that the centered footer
|
|
will be a modification date and will prepend something like ``Last
|
|
modified: ''. If this is the case for your target system, you may want to
|
|
set <B>--release</B> to the last modified date and <B>--date</B> to the version
|
|
number.
|
|
<DT id="17"><B>-s</B> <I>string</I>, <B>--section</B>=<I>string</I><DD>
|
|
|
|
|
|
Set the section for the <TT>".TH"</TT> macro. The standard section numbering
|
|
convention is to use 1 for user commands, 2 for system calls, 3 for
|
|
functions, 4 for devices, 5 for file formats, 6 for games, 7 for
|
|
miscellaneous information, and 8 for administrator commands. There is a lot
|
|
of variation here, however; some systems (like Solaris) use 4 for file
|
|
formats, 5 for miscellaneous information, and 7 for devices. Still others
|
|
use 1m instead of 8, or some mix of both. About the only section numbers
|
|
that are reliably consistent are 1, 2, and 3.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
By default, section 1 will be used unless the file ends in <TT>".pm"</TT>, in
|
|
which case section 3 will be selected.
|
|
<DT id="18"><B>--stderr</B><DD>
|
|
|
|
|
|
By default, <B>pod2man</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>pod2man</B> does not abort. This is equivalent
|
|
to <TT>"--errors=stderr"</TT> and is supported for backward compatibility.
|
|
<DT id="19"><B>-u</B>, <B>--utf8</B><DD>
|
|
|
|
|
|
By default, <B>pod2man</B> produces the most conservative possible *roff
|
|
output to try to ensure that it will work with as many different *roff
|
|
implementations as possible. Many *roff implementations cannot handle
|
|
non-ASCII characters, so this means all non-ASCII characters are converted
|
|
either to a *roff escape sequence that tries to create a properly accented
|
|
character (at least for troff output) or to <TT>"X"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option says to instead output literal <FONT SIZE="-1">UTF-8</FONT> characters. If your
|
|
*roff implementation can handle it, this is the best output format to use
|
|
and avoids corruption of documents containing non-ASCII characters.
|
|
However, be warned that *roff source with literal <FONT SIZE="-1">UTF-8</FONT> characters is not
|
|
supported by many implementations and may even result in segfaults and
|
|
other bad behavior.
|
|
|
|
|
|
<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>pod2man</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="20"><B>-v</B>, <B>--verbose</B><DD>
|
|
|
|
|
|
Print out the name of each output file as it is being generated.
|
|
</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>pod2man</B> will exit with status 0. If any of the
|
|
documents being processed do not result in an output document, <B>pod2man</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>pod2man</B> will abort immediately with exit status 255.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>DIAGNOSTICS</H2>
|
|
|
|
|
|
|
|
If <B>pod2man</B> fails with errors, see Pod::Man and Pod::Simple for
|
|
information about what those errors might mean.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
pod2man program > program.1
|
|
pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
|
|
pod2man --section=7 note.pod > note.7
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
If you would like to print out a lot of man page continuously, you probably
|
|
want to set the C and D registers to set contiguous page numbering and
|
|
even/odd paging, at least on some versions of <B><A HREF="/cgi-bin/man/man2html?7+man">man</A></B>(7).
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
To get index entries on <TT>"STDERR"</TT>, turn on the F register, as in:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
troff -man -rF1 perl.1
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The indexing merely outputs messages via <TT>".tm"</TT> for each major page,
|
|
section, subsection, item, and any <TT>"X<>"</TT> directives. See
|
|
Pod::Man for more details.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
|
|
Lots of this documentation is duplicated from Pod::Man.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Russ Allbery <<A HREF="mailto:rra@cpan.org">rra@cpan.org</A>>, based <I>very</I> heavily on the original
|
|
<B>pod2man</B> by Larry Wall and Tom Christiansen.
|
|
<A NAME="lbAK"> </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="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
Pod::Man, Pod::Simple, <B><A HREF="/cgi-bin/man/man2html?1+man">man</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+nroff">nroff</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+perlpod">perlpod</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+podchecker">podchecker</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+perlpodstyle">perlpodstyle</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?7+man">man</A></B>(7)
|
|
<P>
|
|
|
|
The man page documenting the an macro set may be <B><A HREF="/cgi-bin/man/man2html?5+man">man</A></B>(5) instead of
|
|
<B><A HREF="/cgi-bin/man/man2html?7+man">man</A></B>(7) on your system.
|
|
<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">EXAMPLES</A><DD>
|
|
<DT id="28"><A HREF="#lbAI">BUGS</A><DD>
|
|
<DT id="29"><A HREF="#lbAJ">AUTHOR</A><DD>
|
|
<DT id="30"><A HREF="#lbAK">COPYRIGHT AND LICENSE</A><DD>
|
|
<DT id="31"><A HREF="#lbAL">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>
|