1POD2MAN(1) User Contributed Perl Documentation POD2MAN(1)
2
6 pod2man - Convert POD data to formatted *roff input
7
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 pod2man --help
19
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 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 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 --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
47 Each option is annotated with the version of podlators in which that
48 option was added with its current meaning.
49 -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 -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 -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 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 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 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 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 --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 The default is "die".
109 --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 --fixedbold=font
116 [1.0] Bold version of the fixed-width font. Defaults to "CB".
117 Only matters for troff output.
118 --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 --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 --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 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 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 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 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 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 Any unknown guesswork name is silently ignored (for potential
172 future compatibility), so be careful about spelling.
173 -h, --help
175 [1.00] Print out usage information.
176 -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 --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 This adds:
190 .mso <language>.tmac
192 .hla <language>
193 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 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 Unfortunately, the commands added with this option are specific to
205 groff and will not work with other troff and nroff implementations.
206 --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 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 -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 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 This option is probably not useful when converting multiple POD
234 files at once.
235 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 --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 L<foo|http://example.com/>
247 is formatted as:
249 foo <http://example.com/>
251 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 -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 -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 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 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 -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 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 -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 By default, section 1 will be used unless the file ends in ".pm",
301 in which case section 3 will be selected.
302 --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 -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 -v, --verbose
316 [1.11] Print out the name of each output file as it is being
317 generated.
318
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
329 If pod2man fails with errors, see Pod::Man and Pod::Simple for
330 information about what those errors might mean.
331
333 pod2man program > program.1
334 pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
335 pod2man --section=7 note.pod > note.7
336 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 troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
342 To get index entries on "STDERR", turn on the F register, as in:
344 troff -man -rF1 perl.1
346 The indexing merely outputs messages via ".tm" for each major page,
348 section, subsection, item, and any "X<>" directives.
349
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 This program is free software; you may redistribute it and/or modify it
359 under the same terms as Perl itself.
360
362 Pod::Man, Pod::Simple, man(1), nroff(1), perlpod(1), podchecker(1),
363 perlpodstyle(1), troff(1), man(7)
364 The man page documenting the an macro set may be man(5) instead of
366 man(7) on your system.
367 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.
371perl v5.38.0 2023-07-21 POD2MAN(1)