pod2man - translate embedded Perl pod directives into man pages
pod2man [ --section=manext ] [ --release=relpatch ] [ --center=string ] [ --date=string ] [ --fixed=font ] [ --official ] [ --lax ] inputfile
pod2man converts its input file containing embedded pod directives (see
the perlpod manpage) into nroff source suitable for viewing with
nroff(1) or
troff(1) using the
man(7) macro set.
Besides the obvious pod conversions, pod2man also takes care of
func(),
func(n), and simple variable references like $foo or @bar so you don't have to use code escapes for them; complex expressions like
$fred{'stuff'} will still need to be escaped, though. Other nagging little roffish things that it catches include translating the minus in something like foo-bar, making a long dash--like this--into a real em dash, fixing up ``paired quotes'', putting a little space after the parens in something like
func(), making
C++ and
PI look right, making double underbars have a little tiny space between them, making
ALLCAPS a teeny bit smaller in
troff(1), and escaping backslashes so you don't have to.
--official flag is given, in which case the default is ``Perl Programmers Reference
Guide''.
--center is not given.
.TH macro. The standard conventions on sections are 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. This works best if you put your Perl man pages in a separate
tree, like
/usr/local/perl/man/. By default, section 1 will be used unless the file ends in .pm in which case section 3 will be selected.
For those not sure of the proper layout of a man page, here's an example of
the skeleton of a proper man page. Head of the major headers should be
setout as a =head1 directive, and are historically written in the rather startling
ALL
UPPER
CASE format, although this is not mandatory. Minor headers may be included using
=head2, and are typically in mixed case.
foo, bar - programs to do something
=head2 directives, like
=head2 A Sample Subection
=head2 Yet Another Sample Subection
man(1),
man(7),
makewhatis(8), or
catman(8).
pod2man program > program.1
pod2man some_module.pm > /usr/perl/man/man3/some_module.3
pod2man --section=7 note.pod > note.7
The following diagnostics are generated by pod2man. Items marked ``(W)'' are non-fatal, whereas the ``(F)'' errors will cause pod2man to immediately exit with a non-zero status.
--fixed option was not a one- or two-digit roff font.
E<> directive. Besides amp, lt, gt, and quot, recognized entities are Aacute, aacute, Acirc, acirc, AElig, aelig, Agrave, agrave, Aring, aring, Atilde, atilde, Auml, auml, Ccedil, ccedil, Eacute, eacute, Ecirc, ecirc, Egrave, egrave,
ETH, eth, Euml, euml, Iacute, iacute, Icirc, icirc, Igrave, igrave, Iuml, iuml, Ntilde, ntilde, Oacute, oacute, Ocirc, ocirc, Ograve, ograve, Oslash, oslash, Otilde, otilde, Ouml, ouml, szlig,
THORN, thorn, Uacute, uacute, Ucirc, ucirc, Ugrave, ugrave, Uuml, uuml, Yacute, yacute, and yuml.
=back without a corresponding =over.
=head1, =head2, =item, =over, =back, or =cut.
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
man(7). Settting the
F register will get you some additional experimental indexing:
troff -man -rC1 -rD1 -rF1 perl.1 perldata.1 perlsyn.1 ...
The indexing merely outputs messages via .tm for each major page, section, subsection, item, and any X<>
directives.
None at this time.
The =over and =back directives don't really work right. They take absolute positions instead of offsets, don't nest well, and making people count is suboptimal in any event.
Original prototype by Larry Wall, but so massively hacked over by Tom Christiansen such that Larry probably doesn't recognize it anymore.
If rather than formatting bugs, you encounter substantive content errors in these documents, such as mistakes in the explanations or code, please use the perlbug utility included with the Perl distribution.