1POD2MAN(1)            User Contributed Perl Documentation           POD2MAN(1)
2
3
4

NAME

6       pod2man - Convert POD data to formatted *roff input
7

SYNOPSIS

9       pod2man [--center=string] [--date=string]
10           [--encoding=encoding] [--errors=style] [--fixed=font]
11           [--fixedbold=font] [--fixeditalic=font]
12           [--fixedbolditalic=font] [--guesswork=rule[,rule...]]
13           [--name=name] [--nourls] [--official]
14           [--release=version] [--section=manext]
15           [--quotes=quotes] [--lquote=quote] [--rquote=quote]
16           [--stderr] [--utf8] [--verbose] [input [output] ...]
17
18       pod2man --help
19

DESCRIPTION

21       pod2man is a wrapper script around the Pod::Man module, using it to
22       generate *roff input from POD source.  The resulting *roff code is
23       suitable for display on a terminal using nroff(1), normally via man(1),
24       or printing using troff(1).
25
26       By default (on non-EBCDIC systems), pod2man outputs UTF-8 manual pages.
27       Its output should work with the man program on systems that use groff
28       (most Linux distributions) or mandoc (most BSD variants), but may
29       result in mangled output on older UNIX systems.  To choose a different,
30       possibly more backward-compatible output mangling on such systems, use
31       "--encoding=roff" (the default in earlier Pod::Man versions).  See the
32       --encoding option and "ENCODING" in Pod::Man for more details.
33
34       input is the file to read for POD source (the POD can be embedded in
35       code).  If input isn't given, it defaults to "STDIN".  output, if
36       given, is the file to which to write the formatted output.  If output
37       isn't given, the formatted output is written to "STDOUT".  Several POD
38       files can be processed in the same pod2man invocation (saving module
39       load and compile times) by providing multiple pairs of input and output
40       files on the command line.
41
42       --section, --release, --center, --date, and --official can be used to
43       set the headers and footers to use.  If not given, Pod::Man will assume
44       various defaults.  See below for details.
45

OPTIONS

47       Each option is annotated with the version of podlators in which that
48       option was added with its current meaning.
49
50       -c string, --center=string
51           [1.00] Sets the centered page header for the ".TH" macro to string.
52           The default is "User Contributed Perl Documentation", but also see
53           --official below.
54
55       -d string, --date=string
56           [4.00] Set the left-hand footer string for the ".TH" macro to
57           string.  By default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH,
58           the modification date of the input file, or the current date (if
59           input comes from "STDIN") will be used, and the date will be in
60           UTC.  See "CLASS METHODS" in Pod::Man for more details.
61
62       -e encoding, --encoding=encoding
63           [5.00] Specifies the encoding of the output.  encoding must be an
64           encoding recognized by the Encode module (see Encode::Supported).
65           The default on non-EBCDIC systems is UTF-8.
66
67           If the output contains characters that cannot be represented in
68           this encoding, that is an error that will be reported as configured
69           by the --errors option.  If error handling is other than "die", the
70           unrepresentable character will be replaced with the Encode
71           substitution character (normally "?").
72
73           If the "encoding" option is set to the special value "groff" (the
74           default on EBCDIC systems), or if the Encode module is not
75           available and the encoding is set to anything other than "roff"
76           (see below), Pod::Man will translate all non-ASCII characters to
77           "\[uNNNN]" Unicode escapes.  These are not traditionally part of
78           the *roff language, but are supported by groff and mandoc and thus
79           by the majority of manual page processors in use today.
80
81           If encoding is set to the special value "roff", pod2man will do its
82           historic transformation of (some) ISO 8859-1 characters into *roff
83           escapes that may be adequate in troff and may be readable (if ugly)
84           in nroff.  This was the default behavior of versions of pod2man
85           before 5.00.  With this encoding, all other non-ASCII characters
86           will be replaced with "X".  It may be required for very old troff
87           and nroff implementations that do not support UTF-8, but its
88           representation of any non-ASCII character is very poor and often
89           specific to European languages.  Its use is discouraged.
90
91           WARNING: The input encoding of the POD source is independent from
92           the output encoding, and setting this option does not affect the
93           interpretation of the POD input.  Unless your POD source is US-
94           ASCII, its encoding should be declared with the "=encoding" command
95           in the source.  If this is not done, Pod::Simple will will attempt
96           to guess the encoding and may be successful if it's Latin-1 or
97           UTF-8, but it will produce warnings.  See perlpod(1) for more
98           information.
99
100       --errors=style
101           [2.5.0] Set the error handling style.  "die" says to throw an
102           exception on any POD formatting error.  "stderr" says to report
103           errors on standard error, but not to throw an exception.  "pod"
104           says to include a POD ERRORS section in the resulting documentation
105           summarizing the errors.  "none" ignores POD errors entirely, as
106           much as possible.
107
108           The default is "die".
109
110       --fixed=font
111           [1.0] The fixed-width font to use for verbatim text and code.
112           Defaults to "CW".  Some systems may want "CR" instead.  Only
113           matters for troff output.
114
115       --fixedbold=font
116           [1.0] Bold version of the fixed-width font.  Defaults to "CB".
117           Only matters for troff output.
118
119       --fixeditalic=font
120           [1.0] Italic version of the fixed-width font (something of a
121           misnomer, since most fixed-width fonts only have an oblique
122           version, not an italic version).  Defaults to "CI".  Only matters
123           for troff output.
124
125       --fixedbolditalic=font
126           [1.0] Bold italic (in theory, probably oblique in practice) version
127           of the fixed-width font.  Pod::Man doesn't assume you have this,
128           and defaults to "CB".  Some systems (such as Solaris) have this
129           font available as "CX".  Only matters for troff output.
130
131       --guesswork=rule[,rule...]
132           [5.00] By default, pod2man applies some default formatting rules
133           based on guesswork and regular expressions that are intended to
134           make writing Perl documentation easier and require less explicit
135           markup.  These rules may not always be appropriate, particularly
136           for documentation that isn't about Perl.  This option allows
137           turning all or some of it off.
138
139           The special rule "all" enables all guesswork.  This is also the
140           default for backward compatibility reasons.  The special rule
141           "none" disables all guesswork.  Otherwise, the value of this option
142           should be a comma-separated list of one or more of the following
143           keywords:
144
145           functions
146               Convert function references like foo() to bold even if they
147               have no markup.  The function name accepts valid Perl
148               characters for function names (including ":"), and the trailing
149               parentheses must be present and empty.
150
151           manref
152               Make the first part (before the parentheses) of man page
153               references like foo(1) bold even if they have no markup.  The
154               section must be a single number optionally followed by
155               lowercase letters.
156
157           quoting
158               If no guesswork is enabled, any text enclosed in C<> is
159               surrounded by double quotes in nroff (terminal) output unless
160               the contents are already quoted.  When this guesswork is
161               enabled, quote marks will also be suppressed for Perl
162               variables, function names, function calls, numbers, and hex
163               constants.
164
165           variables
166               Convert Perl variable names to a fixed-width font even if they
167               have no markup.  This transformation will only be apparent in
168               troff output, or some other output format (unlike nroff
169               terminal output) that supports fixed-width fonts.
170
171           Any unknown guesswork name is silently ignored (for potential
172           future compatibility), so be careful about spelling.
173
174       -h, --help
175           [1.00] Print out usage information.
176
177       -l, --lax
178           [1.00] No longer used.  pod2man used to check its input for
179           validity as a manual page, but this should now be done by
180           podchecker(1) instead.  Accepted for backward compatibility; this
181           option no longer does anything.
182
183       --language=language
184           [5.00] Add commands telling groff that the input file is in the
185           given language.  The value of this setting must be a language
186           abbreviation for which groff provides supplemental configuration,
187           such as "ja" (for Japanese) or "zh" (for Chinese).
188
189           This adds:
190
191               .mso <language>.tmac
192               .hla <language>
193
194           to the start of the file, which configure correct line breaking for
195           the specified language.  Without these commands, groff may not know
196           how to add proper line breaks for Chinese and Japanese text if the
197           man page is installed into the normal man page directory, such as
198           /usr/share/man.
199
200           On many systems, this will be done automatically if the man page is
201           installed into a language-specific man page directory, such as
202           /usr/share/man/zh_CN.  In that case, this option is not required.
203
204           Unfortunately, the commands added with this option are specific to
205           groff and will not work with other troff and nroff implementations.
206
207       --lquote=quote
208       --rquote=quote
209           [4.08] Sets the quote marks used to surround C<> text.  --lquote
210           sets the left quote mark and --rquote sets the right quote mark.
211           Either may also be set to the special value "none", in which case
212           no quote mark is added on that side of C<> text (but the font is
213           still changed for troff output).
214
215           Also see the --quotes option, which can be used to set both quotes
216           at once.  If both --quotes and one of the other options is set,
217           --lquote or --rquote overrides --quotes.
218
219       -n name, --name=name
220           [4.08] Set the name of the manual page for the ".TH" macro to name.
221           Without this option, the manual name is set to the uppercased base
222           name of the file being converted unless the manual section is 3, in
223           which case the path is parsed to see if it is a Perl module path.
224           If it is, a path like ".../lib/Pod/Man.pm" is converted into a name
225           like "Pod::Man".  This option, if given, overrides any automatic
226           determination of the name.
227
228           Although one does not have to follow this convention, be aware that
229           the convention for UNIX manual pages is for the title to be in all-
230           uppercase, even if the command isn't.  (Perl modules traditionally
231           use mixed case for the manual page title, however.)
232
233           This option is probably not useful when converting multiple POD
234           files at once.
235
236           When converting POD source from standard input, the name will be
237           set to "STDIN" if this option is not provided.  Providing this
238           option is strongly recommended to set a meaningful manual page
239           name.
240
241       --nourls
242           [2.5.0] Normally, L<> formatting codes with a URL but anchor text
243           are formatted to show both the anchor text and the URL.  In other
244           words:
245
246               L<foo|http://example.com/>
247
248           is formatted as:
249
250               foo <http://example.com/>
251
252           This flag, if given, suppresses the URL when anchor text is given,
253           so this example would be formatted as just "foo".  This can produce
254           less cluttered output in cases where the URLs are not particularly
255           important.
256
257       -o, --official
258           [1.00] Set the default header to indicate that this page is part of
259           the standard Perl release, if --center is not also given.
260
261       -q quotes, --quotes=quotes
262           [4.00] Sets the quote marks used to surround C<> text to quotes.
263           If quotes is a single character, it is used as both the left and
264           right quote.  Otherwise, it is split in half, and the first half of
265           the string is used as the left quote and the second is used as the
266           right quote.
267
268           quotes may also be set to the special value "none", in which case
269           no quote marks are added around C<> text (but the font is still
270           changed for troff output).
271
272           Also see the --lquote and --rquote options, which can be used to
273           set the left and right quotes independently.  If both --quotes and
274           one of the other options is set, --lquote or --rquote overrides
275           --quotes.
276
277       -r version, --release=version
278           [1.00] Set the centered footer for the ".TH" macro to version.  By
279           default, this is set to the version of Perl you run pod2man under.
280           Setting this to the empty string will cause some *roff
281           implementations to use the system default value.
282
283           Note that some system "an" macro sets assume that the centered
284           footer will be a modification date and will prepend something like
285           "Last modified: ".  If this is the case for your target system, you
286           may want to set --release to the last modified date and --date to
287           the version number.
288
289       -s string, --section=string
290           [1.00] Set the section for the ".TH" macro.  The standard section
291           numbering convention is to use 1 for user commands, 2 for system
292           calls, 3 for functions, 4 for devices, 5 for file formats, 6 for
293           games, 7 for miscellaneous information, and 8 for administrator
294           commands.  There is a lot of variation here, however; some systems
295           (like Solaris) use 4 for file formats, 5 for miscellaneous
296           information, and 7 for devices.  Still others use 1m instead of 8,
297           or some mix of both.  About the only section numbers that are
298           reliably consistent are 1, 2, and 3.
299
300           By default, section 1 will be used unless the file ends in ".pm",
301           in which case section 3 will be selected.
302
303       --stderr
304           [2.1.3] By default, pod2man dies if any errors are detected in the
305           POD input.  If --stderr is given and no --errors flag is present,
306           errors are sent to standard error, but pod2man does not abort.
307           This is equivalent to "--errors=stderr" and is supported for
308           backward compatibility.
309
310       -u, --utf8
311           [2.1.0] This option used to tell pod2man to produce UTF-8 output.
312           Since this is now the default as of version 5.00, it is ignored and
313           does nothing.
314
315       -v, --verbose
316           [1.11] Print out the name of each output file as it is being
317           generated.
318

EXIT STATUS

320       As long as all documents processed result in some output, even if that
321       output includes errata (a "POD ERRORS" section generated with
322       "--errors=pod"), pod2man will exit with status 0.  If any of the
323       documents being processed do not result in an output document, pod2man
324       will exit with status 1.  If there are syntax errors in a POD document
325       being processed and the error handling style is set to the default of
326       "die", pod2man will abort immediately with exit status 255.
327

DIAGNOSTICS

329       If pod2man fails with errors, see Pod::Man and Pod::Simple for
330       information about what those errors might mean.
331

EXAMPLES

333           pod2man program > program.1
334           pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
335           pod2man --section=7 note.pod > note.7
336
337       If you would like to print out a lot of man page continuously, you
338       probably want to set the C and D registers to set contiguous page
339       numbering and even/odd paging, at least on some versions of man(7).
340
341           troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
342
343       To get index entries on "STDERR", turn on the F register, as in:
344
345           troff -man -rF1 perl.1
346
347       The indexing merely outputs messages via ".tm" for each major page,
348       section, subsection, item, and any "X<>" directives.
349

AUTHOR

351       Russ Allbery <rra@cpan.org>, based on the original pod2man by Larry
352       Wall and Tom Christiansen.
353
355       Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ
356       Allbery <rra@cpan.org>
357
358       This program is free software; you may redistribute it and/or modify it
359       under the same terms as Perl itself.
360

SEE ALSO

362       Pod::Man, Pod::Simple, man(1), nroff(1), perlpod(1), podchecker(1),
363       perlpodstyle(1), troff(1), man(7)
364
365       The man page documenting the an macro set may be man(5) instead of
366       man(7) on your system.
367
368       The current version of this script is always available from its web
369       site at <https://www.eyrie.org/~eagle/software/podlators/>.  It is also
370       part of the Perl core distribution as of 5.6.0.
371
372
373
374perl v5.36.0                      2023-01-20                        POD2MAN(1)
Impressum