Daftar Isi

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• DIAGNOSTICS
• EXAMPLES
• BUGS
• SEE ALSO
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

pod2man - Convert POD data to formatted *roff input

SYNOPSIS

pod2man [--center=string] [--date=string] [--fixed=font] [--fixedbold=font] [--fixeditalic=font] [--fixedbolditalic=font] [--name=name] [--official] [--quotes=quotes] [--release[=version]] [--section=manext] [--stderr] [--utf8] [--verbose] [input [output] ...]

pod2man --help

DESCRIPTION

pod2man is a front-end for Pod::Man, using it to generate *roff inputfrom POD source. The resulting *roff code is suitable for display on aterminal using nroff(1), normally via man(1), or printing using troff(1).

input is the file to read for POD source (the POD can be embedded incode). If input isn't given, it defaults to STDIN. output, ifgiven, is the file to which to write the formatted output. If outputisn't given, the formatted output is written to STDOUT. Several PODfiles can be processed in the same pod2man invocation (saving moduleload and compile times) by providing multiple pairs of input andoutput files on the command line.

--section, --release, --center, --date, and --official canbe used to set the headers and footers to use; if not given, Pod::Man willassume various defaults. See below or Pod::Man for details.

pod2man assumes that your *roff formatters have a fixed-width fontnamed CW. If yours is called something else (like CR), use--fixed to specify it. This generally only matters for troff outputfor printing. Similarly, you can set the fonts used for bold, italic, andbold italic fixed-width output.

Besides the obvious pod conversions, Pod::Man, and therefore pod2man alsotakes care of formatting func(), func(n), and simple variable referenceslike $foo or @bar so you don't have to use code escapes for them; complexexpressions like $fred{'stuff'} will still need to be escaped, though.It also translates dashes that aren't used as hyphens into en dashes, makeslong dashes--like this--into proper em dashes, fixes "paired quotes," andtakes care of several other troff-specific tweaks. See Pod::Man forcomplete information.

OPTIONS

• -c string, --center=string

  Sets the centered page header to string. The default is "UserContributed Perl Documentation", but also see --official below.

• -d string, --date=string

  Set the left-hand footer string to this value. By default, the modificationdate of the input file will be used, or the current date if input comes fromSTDIN.

• --fixed=font

  The fixed-width font to use for verbatim text and code. Defaults toCW. Some systems may want CR instead. Only matters for troff(1)output.

• --fixedbold=font

  Bold version of the fixed-width font. Defaults to CB. Only mattersfor troff(1) output.

• --fixeditalic=font

  Italic version of the fixed-width font (actually, something of a misnomer,since most fixed-width fonts only have an oblique version, not an italicversion). Defaults to CI. Only matters for troff(1) output.

• --fixedbolditalic=font

  Bold italic (probably actually oblique) version of the fixed-width font.Pod::Man doesn't assume you have this, and defaults to CB. Somesystems (such as Solaris) have this font available as CX. Only mattersfor troff(1) output.

• -h, --help

  Print out usage information.

• -l, --lax

  No longer used. pod2man used to check its input for validity as amanual page, but this should now be done by podchecker(1) instead.Accepted for backward compatibility; this option no longer does anything.

• -n name, --name=name

  Set the name of the manual page to name. Without this option, the manualname is set to the uppercased base name of the file being converted unlessthe manual section is 3, in which case the path is parsed to see if it is aPerl module path. If it is, a path like .../lib/Pod/Man.pm is convertedinto a name like Pod::Man. This option, if given, overrides anyautomatic determination of the name.

  Note that this option is probably not useful when converting multiple PODfiles at once. The convention for Unix man pages for commands is for theman page title to be in all-uppercase even if the command isn't.

• -o, --official

  Set the default header to indicate that this page is part of the standardPerl release, if --center is not also given.

• -q quotes, --quotes=quotes

  Sets the quote marks used to surround C<> text to quotes. Ifquotes is a single character, it is used as both the left and rightquote; if quotes is two characters, the first character is used as theleft quote and the second as the right quoted; and if quotes is fourcharacters, the first two are used as the left quote and the second two asthe right quote.

  quotes may also be set to the special value none, in which case noquote marks are added around C<> text (but the font is still changed fortroff output).

• -r, --release

  Set the centered footer. By default, this is the version of Perl you runpod2man under. Note that some system an macro sets assume that thecentered footer will be a modification date and will prepend something like"Last modified: "; if this is the case, you may want to set --release tothe last modified date and --date to the version number.

• -s, --section

  Set the section for the .TH macro. The standard section numberingconvention is to use 1 for user commands, 2 for system calls, 3 forfunctions, 4 for devices, 5 for file formats, 6 for games, 7 formiscellaneous information, and 8 for administrator commands. There is a lotof variation here, however; some systems (like Solaris) use 4 for fileformats, 5 for miscellaneous information, and 7 for devices. Still othersuse 1m instead of 8, or some mix of both. About the only section numbersthat are reliably consistent are 1, 2, and 3.

  By default, section 1 will be used unless the file ends in .pm, inwhich case section 3 will be selected.

• --stderr

  By default, pod2man puts any errors detected in the POD input in a PODERRORS section in the output manual page. If --stderr is given, errorsare sent to standard error instead and the POD ERRORS section issuppressed.

• -u, --utf8

  By default, pod2man produces the most conservative possible *roffoutput to try to ensure that it will work with as many different *roffimplementations as possible. Many *roff implementations cannot handlenon-ASCII characters, so this means all non-ASCII characters are convertedeither to a *roff escape sequence that tries to create a properly accentedcharacter (at least for troff output) or to X.

  This option says to instead output literal UTF-8 characters. If your*roff implementation can handle it, this is the best output format to useand avoids corruption of documents containing non-ASCII characters.However, be warned that *roff source with literal UTF-8 characters is notsupported by many implementations and may even result in segfaults andother bad behavior.

  Be aware that, when using this option, the input encoding of your PODsource must be properly declared unless it is US-ASCII or Latin-1. PODinput without an =encoding command will be assumed to be in Latin-1,and if it's actually in UTF-8, the output will be double-encoded. Seeperlpod(1) for more information on the =encoding command.

• -v, --verbose

  Print out the name of each output file as it is being generated.

DIAGNOSTICS

If pod2man fails with errors, see Pod::Man and Pod::Simple forinformation about what those errors might mean.

EXAMPLES

 pod2man program > program.1
 
 pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
 
 pod2man --section=7 note.pod > note.7
 

If you would like to print out a lot of man page continuously, you probablywant to set the C and D registers to set contiguous page numbering andeven/odd paging, at least on some versions of man(7).

 troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
 

To get index entries on STDERR, turn on the F register, as in:

 troff -man -rF1 perl.1
 

The indexing merely outputs messages via .tm for each major page,section, subsection, item, and any X<> directives. SeePod::Man for more details.

BUGS

Lots of this documentation is duplicated from Pod::Man.

SEE ALSO

Pod::Man, Pod::Simple, man(1), nroff(1), perlpod(1),podchecker(1), perlpodstyle(1), troff(1), man(7)

The man page documenting the an macro set may be man(5) instead ofman(7) on your system.

The current version of this script is always available from its web site athttp://www.eyrie.org/~eagle/software/podlators/. It is also part of thePerl core distribution as of 5.6.0.

AUTHOR

Russ Allbery <[email protected]>, based very heavily on the originalpod2man by Larry Wall and Tom Christiansen.

COPYRIGHT AND LICENSE

Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010 Russ Allbery<[email protected]>.

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