| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "POD2MAN 1" |
| 58 |
.TH POD2MAN 1 2026-04-10 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
pod2man \- Convert POD data to formatted *roff input |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
pod2man [\fB\-\-center\fR=\fIstring\fR] [\fB\-\-date\fR=\fIstring\fR] |
| 68 |
[\fB\-\-encoding\fR=\fIencoding\fR] [\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-fixed\fR=\fIfont\fR] |
| 69 |
[\fB\-\-fixedbold\fR=\fIfont\fR] [\fB\-\-fixeditalic\fR=\fIfont\fR] |
| 70 |
[\fB\-\-fixedbolditalic\fR=\fIfont\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]] |
| 71 |
[\fB\-\-name\fR=\fIname\fR] [\fB\-\-nourls\fR] [\fB\-\-official\fR] |
| 72 |
[\fB\-\-release\fR=\fIversion\fR] [\fB\-\-section\fR=\fImanext\fR] |
| 73 |
[\fB\-\-quotes\fR=\fIquotes\fR] [\fB\-\-lquote\fR=\fIquote\fR] [\fB\-\-rquote\fR=\fIquote\fR] |
| 74 |
[\fB\-\-stderr\fR] [\fB\-\-utf8\fR] [\fB\-\-verbose\fR] [\fIinput\fR [\fIoutput\fR] ...] |
| 75 |
.PP |
| 76 |
pod2man \fB\-\-help\fR |
| 77 |
.SH DESCRIPTION |
| 78 |
.IX Header "DESCRIPTION" |
| 79 |
\&\fBpod2man\fR is a wrapper script around the Pod::Man module, using it to |
| 80 |
generate *roff input from POD source. The resulting *roff code is suitable |
| 81 |
for display on a terminal using \fBnroff\fR\|(1), normally via \fBman\fR\|(1), or |
| 82 |
printing using \fBtroff\fR\|(1). |
| 83 |
.PP |
| 84 |
By default (on non-EBCDIC systems), \fBpod2man\fR outputs UTF\-8 manual pages. |
| 85 |
Its output should work with the \fBman\fR program on systems that use \fBgroff\fR |
| 86 |
(most Linux distributions) or \fBmandoc\fR (most BSD variants), but may result in |
| 87 |
mangled output on older UNIX systems. To choose a different, possibly more |
| 88 |
backward-compatible output mangling on such systems, use \f(CW\*(C`\-\-encoding=roff\*(C'\fR |
| 89 |
(the default in earlier Pod::Man versions). See the \fB\-\-encoding\fR option and |
| 90 |
"ENCODING" in Pod::Man for more details. |
| 91 |
.PP |
| 92 |
\&\fIinput\fR is the file to read for POD source (the POD can be embedded in code). |
| 93 |
If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR. \fIoutput\fR, if given, is the |
| 94 |
file to which to write the formatted output. If \fIoutput\fR isn't given, the |
| 95 |
formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR. Several POD files can be processed |
| 96 |
in the same \fBpod2man\fR invocation (saving module load and compile times) by |
| 97 |
providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line. |
| 98 |
.PP |
| 99 |
\&\fB\-\-section\fR, \fB\-\-release\fR, \fB\-\-center\fR, \fB\-\-date\fR, and \fB\-\-official\fR can be |
| 100 |
used to set the headers and footers to use. If not given, Pod::Man will |
| 101 |
assume various defaults. See below for details. |
| 102 |
.SH OPTIONS |
| 103 |
.IX Header "OPTIONS" |
| 104 |
Each option is annotated with the version of podlators in which that option |
| 105 |
was added with its current meaning. |
| 106 |
.IP "\fB\-c\fR \fIstring\fR, \fB\-\-center\fR=\fIstring\fR" 4 |
| 107 |
.IX Item "-c string, --center=string" |
| 108 |
[1.00] Sets the centered page header for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR. The |
| 109 |
default is \f(CW\*(C`User Contributed Perl Documentation\*(C'\fR, but also see \fB\-\-official\fR |
| 110 |
below. |
| 111 |
.IP "\fB\-d\fR \fIstring\fR, \fB\-\-date\fR=\fIstring\fR" 4 |
| 112 |
.IX Item "-d string, --date=string" |
| 113 |
[4.00] Set the left-hand footer string for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR. By |
| 114 |
default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH, the modification date |
| 115 |
of the input file, or the current date (if input comes from \f(CW\*(C`STDIN\*(C'\fR) will be |
| 116 |
used, and the date will be in UTC. See "CLASS METHODS" in Pod::Man for more |
| 117 |
details. |
| 118 |
.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR" 4 |
| 119 |
.IX Item "-e encoding, --encoding=encoding" |
| 120 |
[5.00] Specifies the encoding of the output. \fIencoding\fR must be an encoding |
| 121 |
recognized by the Encode module (see Encode::Supported). The default on |
| 122 |
non-EBCDIC systems is UTF\-8. |
| 123 |
.Sp |
| 124 |
If the output contains characters that cannot be represented in this encoding, |
| 125 |
that is an error that will be reported as configured by the \fB\-\-errors\fR |
| 126 |
option. If error handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character |
| 127 |
will be replaced with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR). |
| 128 |
.Sp |
| 129 |
If the \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`groff\*(C'\fR (the default on |
| 130 |
EBCDIC systems), or if the Encode module is not available and the encoding is |
| 131 |
set to anything other than \f(CW\*(C`roff\*(C'\fR (see below), Pod::Man will translate all |
| 132 |
non-ASCII characters to \f(CW\*(C`\e[uNNNN]\*(C'\fR Unicode escapes. These are not |
| 133 |
traditionally part of the *roff language, but are supported by \fBgroff\fR and |
| 134 |
\&\fBmandoc\fR and thus by the majority of manual page processors in use today. |
| 135 |
.Sp |
| 136 |
If \fIencoding\fR is set to the special value \f(CW\*(C`roff\*(C'\fR, \fBpod2man\fR will do its |
| 137 |
historic transformation of (some) ISO 8859\-1 characters into *roff escapes |
| 138 |
that may be adequate in troff and may be readable (if ugly) in nroff. This |
| 139 |
was the default behavior of versions of \fBpod2man\fR before 5.00. With this |
| 140 |
encoding, all other non-ASCII characters will be replaced with \f(CW\*(C`X\*(C'\fR. It may |
| 141 |
be required for very old troff and nroff implementations that do not support |
| 142 |
UTF\-8, but its representation of any non-ASCII character is very poor and |
| 143 |
often specific to European languages. Its use is discouraged. |
| 144 |
.Sp |
| 145 |
WARNING: The input encoding of the POD source is independent from the output |
| 146 |
encoding, and setting this option does not affect the interpretation of the |
| 147 |
POD input. Unless your POD source is US-ASCII, its encoding should be |
| 148 |
declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source. If this is not done, |
| 149 |
Pod::Simple will will attempt to guess the encoding and may be successful if |
| 150 |
it's Latin\-1 or UTF\-8, but it will produce warnings. See \fBperlpod\fR\|(1) for |
| 151 |
more information. |
| 152 |
.IP \fB\-\-errors\fR=\fIstyle\fR 4 |
| 153 |
.IX Item "--errors=style" |
| 154 |
[2.5.0] Set the error handling style. \f(CW\*(C`die\*(C'\fR says to throw an exception on |
| 155 |
any POD formatting error. \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error, |
| 156 |
but not to throw an exception. \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in |
| 157 |
the resulting documentation summarizing the errors. \f(CW\*(C`none\*(C'\fR ignores POD |
| 158 |
errors entirely, as much as possible. |
| 159 |
.Sp |
| 160 |
The default is \f(CW\*(C`die\*(C'\fR. |
| 161 |
.IP \fB\-\-fixed\fR=\fIfont\fR 4 |
| 162 |
.IX Item "--fixed=font" |
| 163 |
[1.0] The fixed-width font to use for verbatim text and code. Defaults to |
| 164 |
\&\f(CW\*(C`CW\*(C'\fR. Some systems may want \f(CW\*(C`CR\*(C'\fR instead. Only matters for \fBtroff\fR |
| 165 |
output. |
| 166 |
.IP \fB\-\-fixedbold\fR=\fIfont\fR 4 |
| 167 |
.IX Item "--fixedbold=font" |
| 168 |
[1.0] Bold version of the fixed-width font. Defaults to \f(CW\*(C`CB\*(C'\fR. Only matters |
| 169 |
for \fBtroff\fR output. |
| 170 |
.IP \fB\-\-fixeditalic\fR=\fIfont\fR 4 |
| 171 |
.IX Item "--fixeditalic=font" |
| 172 |
[1.0] Italic version of the fixed-width font (something of a misnomer, since |
| 173 |
most fixed-width fonts only have an oblique version, not an italic version). |
| 174 |
Defaults to \f(CW\*(C`CI\*(C'\fR. Only matters for \fBtroff\fR output. |
| 175 |
.IP \fB\-\-fixedbolditalic\fR=\fIfont\fR 4 |
| 176 |
.IX Item "--fixedbolditalic=font" |
| 177 |
[1.0] Bold italic (in theory, probably oblique in practice) version of the |
| 178 |
fixed-width font. Pod::Man doesn't assume you have this, and defaults to |
| 179 |
\&\f(CW\*(C`CB\*(C'\fR. Some systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR. |
| 180 |
Only matters for \fBtroff\fR output. |
| 181 |
.IP \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4 |
| 182 |
.IX Item "--guesswork=rule[,rule...]" |
| 183 |
[5.00] By default, \fBpod2man\fR applies some default formatting rules based on |
| 184 |
guesswork and regular expressions that are intended to make writing Perl |
| 185 |
documentation easier and require less explicit markup. These rules may not |
| 186 |
always be appropriate, particularly for documentation that isn't about Perl. |
| 187 |
This option allows turning all or some of it off. |
| 188 |
.Sp |
| 189 |
The special rule \f(CW\*(C`all\*(C'\fR enables all guesswork. This is also the default for |
| 190 |
backward compatibility reasons. The special rule \f(CW\*(C`none\*(C'\fR disables all |
| 191 |
guesswork. Otherwise, the value of this option should be a comma-separated |
| 192 |
list of one or more of the following keywords: |
| 193 |
.RS 4 |
| 194 |
.IP functions 4 |
| 195 |
.IX Item "functions" |
| 196 |
Convert function references like \f(CWfoo()\fR to bold even if they have no markup. |
| 197 |
The function name accepts valid Perl characters for function names (including |
| 198 |
\&\f(CW\*(C`:\*(C'\fR), and the trailing parentheses must be present and empty. |
| 199 |
.IP manref 4 |
| 200 |
.IX Item "manref" |
| 201 |
Make the first part (before the parentheses) of man page references like |
| 202 |
\&\f(CWfoo(1)\fR bold even if they have no markup. The section must be a single |
| 203 |
number optionally followed by lowercase letters. |
| 204 |
.IP quoting 4 |
| 205 |
.IX Item "quoting" |
| 206 |
If no guesswork is enabled, any text enclosed in C<> is surrounded by |
| 207 |
double quotes in nroff (terminal) output unless the contents are already |
| 208 |
quoted. When this guesswork is enabled, quote marks will also be suppressed |
| 209 |
for Perl variables, function names, function calls, numbers, and hex |
| 210 |
constants. |
| 211 |
.IP variables 4 |
| 212 |
.IX Item "variables" |
| 213 |
Convert Perl variable names to a fixed-width font even if they have no markup. |
| 214 |
This transformation will only be apparent in troff output, or some other |
| 215 |
output format (unlike nroff terminal output) that supports fixed-width fonts. |
| 216 |
.RE |
| 217 |
.RS 4 |
| 218 |
.Sp |
| 219 |
Any unknown guesswork name is silently ignored (for potential future |
| 220 |
compatibility), so be careful about spelling. |
| 221 |
.RE |
| 222 |
.IP "\fB\-h\fR, \fB\-\-help\fR" 4 |
| 223 |
.IX Item "-h, --help" |
| 224 |
[1.00] Print out usage information. |
| 225 |
.IP "\fB\-l\fR, \fB\-\-lax\fR" 4 |
| 226 |
.IX Item "-l, --lax" |
| 227 |
[1.00] No longer used. \fBpod2man\fR used to check its input for validity as a |
| 228 |
manual page, but this should now be done by \fBpodchecker\fR\|(1) instead. |
| 229 |
Accepted for backward compatibility; this option no longer does anything. |
| 230 |
.IP \fB\-\-language\fR=\fIlanguage\fR 4 |
| 231 |
.IX Item "--language=language" |
| 232 |
[5.00] Add commands telling \fBgroff\fR that the input file is in the given |
| 233 |
language. The value of this setting must be a language abbreviation for which |
| 234 |
\&\fBgroff\fR provides supplemental configuration, such as \f(CW\*(C`ja\*(C'\fR (for Japanese) or |
| 235 |
\&\f(CW\*(C`zh\*(C'\fR (for Chinese). |
| 236 |
.Sp |
| 237 |
This adds: |
| 238 |
.Sp |
| 239 |
.Vb 2 |
| 240 |
\& .mso <language>.tmac |
| 241 |
\& .hla <language> |
| 242 |
.Ve |
| 243 |
.Sp |
| 244 |
to the start of the file, which configure correct line breaking for the |
| 245 |
specified language. Without these commands, groff may not know how to add |
| 246 |
proper line breaks for Chinese and Japanese text if the man page is installed |
| 247 |
into the normal man page directory, such as \fI/usr/share/man\fR. |
| 248 |
.Sp |
| 249 |
On many systems, this will be done automatically if the man page is installed |
| 250 |
into a language-specific man page directory, such as \fI/usr/share/man/zh_CN\fR. |
| 251 |
In that case, this option is not required. |
| 252 |
.Sp |
| 253 |
Unfortunately, the commands added with this option are specific to \fBgroff\fR |
| 254 |
and will not work with other \fBtroff\fR and \fBnroff\fR implementations. |
| 255 |
.IP \fB\-\-lquote\fR=\fIquote\fR 4 |
| 256 |
.IX Item "--lquote=quote" |
| 257 |
.PD 0 |
| 258 |
.IP \fB\-\-rquote\fR=\fIquote\fR 4 |
| 259 |
.IX Item "--rquote=quote" |
| 260 |
.PD |
| 261 |
[4.08] Sets the quote marks used to surround C<> text. \fB\-\-lquote\fR sets |
| 262 |
the left quote mark and \fB\-\-rquote\fR sets the right quote mark. Either may |
| 263 |
also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote mark is added |
| 264 |
on that side of C<> text (but the font is still changed for troff output). |
| 265 |
.Sp |
| 266 |
Also see the \fB\-\-quotes\fR option, which can be used to set both quotes at once. |
| 267 |
If both \fB\-\-quotes\fR and one of the other options is set, \fB\-\-lquote\fR or |
| 268 |
\&\fB\-\-rquote\fR overrides \fB\-\-quotes\fR. |
| 269 |
.IP "\fB\-n\fR \fIname\fR, \fB\-\-name\fR=\fIname\fR" 4 |
| 270 |
.IX Item "-n name, --name=name" |
| 271 |
[4.08] Set the name of the manual page for the \f(CW\*(C`.TH\*(C'\fR macro to \fIname\fR. |
| 272 |
Without this option, the manual name is set to the uppercased base name of the |
| 273 |
file being converted unless the manual section is 3, in which case the path is |
| 274 |
parsed to see if it is a Perl module path. If it is, a path like |
| 275 |
\&\f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR is converted into a name like \f(CW\*(C`Pod::Man\*(C'\fR. This option, |
| 276 |
if given, overrides any automatic determination of the name. |
| 277 |
.Sp |
| 278 |
Although one does not have to follow this convention, be aware that the |
| 279 |
convention for UNIX manual pages is for the title to be in all-uppercase, even |
| 280 |
if the command isn't. (Perl modules traditionally use mixed case for the |
| 281 |
manual page title, however.) |
| 282 |
.Sp |
| 283 |
This option is probably not useful when converting multiple POD files at once. |
| 284 |
.Sp |
| 285 |
When converting POD source from standard input, the name will be set to |
| 286 |
\&\f(CW\*(C`STDIN\*(C'\fR if this option is not provided. Providing this option is strongly |
| 287 |
recommended to set a meaningful manual page name. |
| 288 |
.IP \fB\-\-nourls\fR 4 |
| 289 |
.IX Item "--nourls" |
| 290 |
[2.5.0] Normally, L<> formatting codes with a URL but anchor text are |
| 291 |
formatted to show both the anchor text and the URL. In other words: |
| 292 |
.Sp |
| 293 |
.Vb 1 |
| 294 |
\& L<foo|http://example.com/> |
| 295 |
.Ve |
| 296 |
.Sp |
| 297 |
is formatted as: |
| 298 |
.Sp |
| 299 |
.Vb 1 |
| 300 |
\& foo <http://example.com/> |
| 301 |
.Ve |
| 302 |
.Sp |
| 303 |
This flag, if given, suppresses the URL when anchor text is given, so this |
| 304 |
example would be formatted as just \f(CW\*(C`foo\*(C'\fR. This can produce less |
| 305 |
cluttered output in cases where the URLs are not particularly important. |
| 306 |
.IP "\fB\-o\fR, \fB\-\-official\fR" 4 |
| 307 |
.IX Item "-o, --official" |
| 308 |
[1.00] Set the default header to indicate that this page is part of the |
| 309 |
standard Perl release, if \fB\-\-center\fR is not also given. |
| 310 |
.IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4 |
| 311 |
.IX Item "-q quotes, --quotes=quotes" |
| 312 |
[4.00] Sets the quote marks used to surround C<> text to \fIquotes\fR. If |
| 313 |
\&\fIquotes\fR is a single character, it is used as both the left and right quote. |
| 314 |
Otherwise, it is split in half, and the first half of the string is used as |
| 315 |
the left quote and the second is used as the right quote. |
| 316 |
.Sp |
| 317 |
\&\fIquotes\fR may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote |
| 318 |
marks are added around C<> text (but the font is still changed for troff |
| 319 |
output). |
| 320 |
.Sp |
| 321 |
Also see the \fB\-\-lquote\fR and \fB\-\-rquote\fR options, which can be used to set the |
| 322 |
left and right quotes independently. If both \fB\-\-quotes\fR and one of the other |
| 323 |
options is set, \fB\-\-lquote\fR or \fB\-\-rquote\fR overrides \fB\-\-quotes\fR. |
| 324 |
.IP "\fB\-r\fR \fIversion\fR, \fB\-\-release\fR=\fIversion\fR" 4 |
| 325 |
.IX Item "-r version, --release=version" |
| 326 |
[1.00] Set the centered footer for the \f(CW\*(C`.TH\*(C'\fR macro to \fIversion\fR. By |
| 327 |
default, this is set to the version of Perl you run \fBpod2man\fR under. Setting |
| 328 |
this to the empty string will cause some *roff implementations to use the |
| 329 |
system default value. |
| 330 |
.Sp |
| 331 |
Note that some system \f(CW\*(C`an\*(C'\fR macro sets assume that the centered footer will be |
| 332 |
a modification date and will prepend something like \f(CW\*(C`Last modified: \*(C'\fR. If |
| 333 |
this is the case for your target system, you may want to set \fB\-\-release\fR to |
| 334 |
the last modified date and \fB\-\-date\fR to the version number. |
| 335 |
.IP "\fB\-s\fR \fIstring\fR, \fB\-\-section\fR=\fIstring\fR" 4 |
| 336 |
.IX Item "-s string, --section=string" |
| 337 |
[1.00] Set the section for the \f(CW\*(C`.TH\*(C'\fR macro. The standard section numbering |
| 338 |
convention is to use 1 for user commands, 2 for system calls, 3 for functions, |
| 339 |
4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous |
| 340 |
information, and 8 for administrator commands. There is a lot of variation |
| 341 |
here, however; some systems (like Solaris) use 4 for file formats, 5 for |
| 342 |
miscellaneous information, and 7 for devices. Still others use 1m instead of |
| 343 |
8, or some mix of both. About the only section numbers that are reliably |
| 344 |
consistent are 1, 2, and 3. |
| 345 |
.Sp |
| 346 |
By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR, in which |
| 347 |
case section 3 will be selected. |
| 348 |
.IP \fB\-\-stderr\fR 4 |
| 349 |
.IX Item "--stderr" |
| 350 |
[2.1.3] By default, \fBpod2man\fR dies if any errors are detected in the POD |
| 351 |
input. If \fB\-\-stderr\fR is given and no \fB\-\-errors\fR flag is present, errors are |
| 352 |
sent to standard error, but \fBpod2man\fR does not abort. This is equivalent to |
| 353 |
\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility. |
| 354 |
.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4 |
| 355 |
.IX Item "-u, --utf8" |
| 356 |
[2.1.0] This option used to tell \fBpod2man\fR to produce UTF\-8 output. Since |
| 357 |
this is now the default as of version 5.00, it is ignored and does nothing. |
| 358 |
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 |
| 359 |
.IX Item "-v, --verbose" |
| 360 |
[1.11] Print out the name of each output file as it is being generated. |
| 361 |
.SH "EXIT STATUS" |
| 362 |
.IX Header "EXIT STATUS" |
| 363 |
As long as all documents processed result in some output, even if that output |
| 364 |
includes errata (a \f(CW\*(C`POD ERRORS\*(C'\fR section generated with \f(CW\*(C`\-\-errors=pod\*(C'\fR), |
| 365 |
\&\fBpod2man\fR will exit with status 0. If any of the documents being processed |
| 366 |
do not result in an output document, \fBpod2man\fR will exit with status 1. If |
| 367 |
there are syntax errors in a POD document being processed and the error |
| 368 |
handling style is set to the default of \f(CW\*(C`die\*(C'\fR, \fBpod2man\fR will abort |
| 369 |
immediately with exit status 255. |
| 370 |
.SH DIAGNOSTICS |
| 371 |
.IX Header "DIAGNOSTICS" |
| 372 |
If \fBpod2man\fR fails with errors, see Pod::Man and Pod::Simple for |
| 373 |
information about what those errors might mean. |
| 374 |
.SH EXAMPLES |
| 375 |
.IX Header "EXAMPLES" |
| 376 |
.Vb 3 |
| 377 |
\& pod2man program > program.1 |
| 378 |
\& pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3 |
| 379 |
\& pod2man \-\-section=7 note.pod > note.7 |
| 380 |
.Ve |
| 381 |
.PP |
| 382 |
If you would like to print out a lot of man page continuously, you probably |
| 383 |
want to set the C and D registers to set contiguous page numbering and |
| 384 |
even/odd paging, at least on some versions of \fBman\fR\|(7). |
| 385 |
.PP |
| 386 |
.Vb 1 |
| 387 |
\& troff \-man \-rC1 \-rD1 perl.1 perldata.1 perlsyn.1 ... |
| 388 |
.Ve |
| 389 |
.PP |
| 390 |
To get index entries on \f(CW\*(C`STDERR\*(C'\fR, turn on the F register, as in: |
| 391 |
.PP |
| 392 |
.Vb 1 |
| 393 |
\& troff \-man \-rF1 perl.1 |
| 394 |
.Ve |
| 395 |
.PP |
| 396 |
The indexing merely outputs messages via \f(CW\*(C`.tm\*(C'\fR for each major page, section, |
| 397 |
subsection, item, and any \f(CW\*(C`X<>\*(C'\fR directives. |
| 398 |
.SH AUTHOR |
| 399 |
.IX Header "AUTHOR" |
| 400 |
Russ Allbery <[email protected]>, based on the original \fBpod2man\fR by Larry Wall |
| 401 |
and Tom Christiansen. |
| 402 |
.SH "COPYRIGHT AND LICENSE" |
| 403 |
.IX Header "COPYRIGHT AND LICENSE" |
| 404 |
Copyright 1999\-2001, 2004, 2006, 2008, 2010, 2012\-2019, 2022 Russ Allbery |
| 405 |
<[email protected]> |
| 406 |
.PP |
| 407 |
This program is free software; you may redistribute it and/or modify it |
| 408 |
under the same terms as Perl itself. |
| 409 |
.SH "SEE ALSO" |
| 410 |
.IX Header "SEE ALSO" |
| 411 |
Pod::Man, Pod::Simple, \fBman\fR\|(1), \fBnroff\fR\|(1), \fBperlpod\fR\|(1), |
| 412 |
\&\fBpodchecker\fR\|(1), \fBperlpodstyle\fR\|(1), \fBtroff\fR\|(1), \fBman\fR\|(7) |
| 413 |
.PP |
| 414 |
The man page documenting the an macro set may be \fBman\fR\|(5) instead of |
| 415 |
\&\fBman\fR\|(7) on your system. |
| 416 |
.PP |
| 417 |
The current version of this script is always available from its web site at |
| 418 |
<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the |
| 419 |
Perl core distribution as of 5.6.0. |