| 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 "Pod::Man 3perl" |
| 58 |
.TH Pod::Man 3perl 2025-11-16 "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 |
Pod::Man \- Convert POD data to formatted *roff input |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 2 |
| 68 |
\& use Pod::Man; |
| 69 |
\& my $parser = Pod::Man\->new (release => $VERSION, section => 8); |
| 70 |
\& |
| 71 |
\& # Read POD from STDIN and write to STDOUT. |
| 72 |
\& $parser\->parse_file (\e*STDIN); |
| 73 |
\& |
| 74 |
\& # Read POD from file.pod and write to file.1. |
| 75 |
\& $parser\->parse_from_file (\*(Aqfile.pod\*(Aq, \*(Aqfile.1\*(Aq); |
| 76 |
.Ve |
| 77 |
.SH DESCRIPTION |
| 78 |
.IX Header "DESCRIPTION" |
| 79 |
Pod::Man is a module to convert documentation in the POD format (the |
| 80 |
preferred language for documenting Perl) into *roff input using the man |
| 81 |
macro set. The resulting *roff code is suitable for display on a terminal |
| 82 |
using \fBnroff\fR\|(1), normally via \fBman\fR\|(1), or printing using \fBtroff\fR\|(1). |
| 83 |
It is conventionally invoked using the driver script \fBpod2man\fR, but it can |
| 84 |
also be used directly. |
| 85 |
.PP |
| 86 |
By default (on non-EBCDIC systems), Pod::Man outputs UTF\-8. Its output should |
| 87 |
work with the \fBman\fR program on systems that use \fBgroff\fR (most Linux |
| 88 |
distributions) or \fBmandoc\fR (most BSD variants), but may result in mangled |
| 89 |
output on older UNIX systems. To choose a different, possibly more |
| 90 |
backward-compatible output mangling on such systems, set the \f(CW\*(C`encoding\*(C'\fR |
| 91 |
option to \f(CW\*(C`roff\*(C'\fR (the default in earlier Pod::Man versions). See the |
| 92 |
\&\f(CW\*(C`encoding\*(C'\fR option and "ENCODING" for more details. |
| 93 |
.PP |
| 94 |
See "COMPATIBILTY" for the versions of Pod::Man with significant |
| 95 |
backward-incompatible changes (other than constructor options, whose versions |
| 96 |
are documented below), and the versions of Perl that included them. |
| 97 |
.SH "CLASS METHODS" |
| 98 |
.IX Header "CLASS METHODS" |
| 99 |
.IP new(ARGS) 4 |
| 100 |
.IX Item "new(ARGS)" |
| 101 |
Create a new Pod::Man object. ARGS should be a list of key/value pairs, where |
| 102 |
the keys are chosen from the following. Each option is annotated with the |
| 103 |
version of Pod::Man in which that option was added with its current meaning. |
| 104 |
.RS 4 |
| 105 |
.IP center 4 |
| 106 |
.IX Item "center" |
| 107 |
[1.00] Sets the centered page header for the \f(CW\*(C`.TH\*(C'\fR macro. The default, if |
| 108 |
this option is not specified, is \f(CW\*(C`User Contributed Perl Documentation\*(C'\fR. |
| 109 |
.IP date 4 |
| 110 |
.IX Item "date" |
| 111 |
[4.00] Sets the left-hand footer for the \f(CW\*(C`.TH\*(C'\fR macro. If this option is not |
| 112 |
set, the contents of the environment variable POD_MAN_DATE, if set, will be |
| 113 |
used. Failing that, the value of SOURCE_DATE_EPOCH, the modification date of |
| 114 |
the input file, or the current time if \fBstat()\fR can't find that file (which will |
| 115 |
be the case if the input is from \f(CW\*(C`STDIN\*(C'\fR) will be used. If taken from any |
| 116 |
source other than POD_MAN_DATE (which is used verbatim), the date will be |
| 117 |
formatted as \f(CW\*(C`YYYY\-MM\-DD\*(C'\fR and will be based on UTC (so that the output will |
| 118 |
be reproducible regardless of local time zone). |
| 119 |
.IP encoding 4 |
| 120 |
.IX Item "encoding" |
| 121 |
[5.00] Specifies the encoding of the output. The value must be an encoding |
| 122 |
recognized by the Encode module (see Encode::Supported), or the special |
| 123 |
values \f(CW\*(C`roff\*(C'\fR or \f(CW\*(C`groff\*(C'\fR. The default on non-EBCDIC systems is UTF\-8. |
| 124 |
.Sp |
| 125 |
If the output contains characters that cannot be represented in this encoding, |
| 126 |
that is an error that will be reported as configured by the \f(CW\*(C`errors\*(C'\fR option. |
| 127 |
If error handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character will be |
| 128 |
replaced with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR). |
| 129 |
.Sp |
| 130 |
If the \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`groff\*(C'\fR (the default on |
| 131 |
EBCDIC systems), or if the Encode module is not available and the encoding is |
| 132 |
set to anything other than \f(CW\*(C`roff\*(C'\fR, Pod::Man will translate all non-ASCII |
| 133 |
characters to \f(CW\*(C`\e[uNNNN]\*(C'\fR Unicode escapes. These are not traditionally part |
| 134 |
of the *roff language, but are supported by \fBgroff\fR and \fBmandoc\fR and thus by |
| 135 |
the majority of manual page processors in use today. |
| 136 |
.Sp |
| 137 |
If the \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`roff\*(C'\fR, Pod::Man will |
| 138 |
do its historic transformation of (some) ISO 8859\-1 characters into *roff |
| 139 |
escapes that may be adequate in troff and may be readable (if ugly) in nroff. |
| 140 |
This was the default behavior of versions of Pod::Man before 5.00. With this |
| 141 |
encoding, all other non-ASCII characters will be replaced with \f(CW\*(C`X\*(C'\fR. It may |
| 142 |
be required for very old troff and nroff implementations that do not support |
| 143 |
UTF\-8, but its representation of any non-ASCII character is very poor and |
| 144 |
often specific to European languages. |
| 145 |
.Sp |
| 146 |
If the output file handle has a PerlIO encoding layer set, setting \f(CW\*(C`encoding\*(C'\fR |
| 147 |
to anything other than \f(CW\*(C`groff\*(C'\fR or \f(CW\*(C`roff\*(C'\fR will be ignored and no encoding |
| 148 |
will be done by Pod::Man. It will instead rely on the encoding layer to make |
| 149 |
whatever output encoding transformations are desired. |
| 150 |
.Sp |
| 151 |
WARNING: The input encoding of the POD source is independent from the output |
| 152 |
encoding, and setting this option does not affect the interpretation of the |
| 153 |
POD input. Unless your POD source is US-ASCII, its encoding should be |
| 154 |
declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source. If this is not done, |
| 155 |
Pod::Simple will will attempt to guess the encoding and may be successful if |
| 156 |
it's Latin\-1 or UTF\-8, but it will produce warnings. See \fBperlpod\fR\|(1) for |
| 157 |
more information. |
| 158 |
.IP errors 4 |
| 159 |
.IX Item "errors" |
| 160 |
[2.27] How to report errors. \f(CW\*(C`die\*(C'\fR says to throw an exception on any POD |
| 161 |
formatting error. \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error, but not |
| 162 |
to throw an exception. \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in the |
| 163 |
resulting documentation summarizing the errors. \f(CW\*(C`none\*(C'\fR ignores POD errors |
| 164 |
entirely, as much as possible. |
| 165 |
.Sp |
| 166 |
The default is \f(CW\*(C`pod\*(C'\fR. |
| 167 |
.IP fixed 4 |
| 168 |
.IX Item "fixed" |
| 169 |
[1.00] The fixed-width font to use for verbatim text and code. Defaults to |
| 170 |
\&\f(CW\*(C`CW\*(C'\fR. Some systems prefer \f(CW\*(C`CR\*(C'\fR instead. Only matters for \fBtroff\fR output. |
| 171 |
.IP fixedbold 4 |
| 172 |
.IX Item "fixedbold" |
| 173 |
[1.00] Bold version of the fixed-width font. Defaults to \f(CW\*(C`CB\*(C'\fR. Only matters |
| 174 |
for \fBtroff\fR output. |
| 175 |
.IP fixeditalic 4 |
| 176 |
.IX Item "fixeditalic" |
| 177 |
[1.00] Italic version of the fixed-width font (something of a misnomer, since |
| 178 |
most fixed-width fonts only have an oblique version, not an italic version). |
| 179 |
Defaults to \f(CW\*(C`CI\*(C'\fR. Only matters for \fBtroff\fR output. |
| 180 |
.IP fixedbolditalic 4 |
| 181 |
.IX Item "fixedbolditalic" |
| 182 |
[1.00] Bold italic (in theory, probably oblique in practice) version of the |
| 183 |
fixed-width font. Pod::Man doesn't assume you have this, and defaults to |
| 184 |
\&\f(CW\*(C`CB\*(C'\fR. Some systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR. |
| 185 |
Only matters for \fBtroff\fR output. |
| 186 |
.IP guesswork 4 |
| 187 |
.IX Item "guesswork" |
| 188 |
[5.00] By default, Pod::Man applies some default formatting rules based on |
| 189 |
guesswork and regular expressions that are intended to make writing Perl |
| 190 |
documentation easier and require less explicit markup. These rules may not |
| 191 |
always be appropriate, particularly for documentation that isn't about Perl. |
| 192 |
This option allows turning all or some of it off. |
| 193 |
.Sp |
| 194 |
The special value \f(CW\*(C`all\*(C'\fR enables all guesswork. This is also the default for |
| 195 |
backward compatibility reasons. The special value \f(CW\*(C`none\*(C'\fR disables all |
| 196 |
guesswork. Otherwise, the value of this option should be a comma-separated |
| 197 |
list of one or more of the following keywords: |
| 198 |
.RS 4 |
| 199 |
.IP functions 4 |
| 200 |
.IX Item "functions" |
| 201 |
Convert function references like \f(CWfoo()\fR to bold even if they have no markup. |
| 202 |
The function name accepts valid Perl characters for function names (including |
| 203 |
\&\f(CW\*(C`:\*(C'\fR), and the trailing parentheses must be present and empty. |
| 204 |
.IP manref 4 |
| 205 |
.IX Item "manref" |
| 206 |
Make the first part (before the parentheses) of manual page references like |
| 207 |
\&\f(CWfoo(1)\fR bold even if they have no markup. The section must be a single |
| 208 |
number optionally followed by lowercase letters. |
| 209 |
.IP quoting 4 |
| 210 |
.IX Item "quoting" |
| 211 |
If no guesswork is enabled, any text enclosed in C<> is surrounded by |
| 212 |
double quotes in nroff (terminal) output unless the contents are already |
| 213 |
quoted. When this guesswork is enabled, quote marks will also be suppressed |
| 214 |
for Perl variables, function names, function calls, numbers, and hex |
| 215 |
constants. |
| 216 |
.IP variables 4 |
| 217 |
.IX Item "variables" |
| 218 |
Convert Perl variable names to a fixed-width font even if they have no markup. |
| 219 |
This transformation will only be apparent in troff output, or some other |
| 220 |
output format (unlike nroff terminal output) that supports fixed-width fonts. |
| 221 |
.RE |
| 222 |
.RS 4 |
| 223 |
.Sp |
| 224 |
Any unknown guesswork name is silently ignored (for potential future |
| 225 |
compatibility), so be careful about spelling. |
| 226 |
.RE |
| 227 |
.IP language 4 |
| 228 |
.IX Item "language" |
| 229 |
[5.00] Add commands telling \fBgroff\fR that the input file is in the given |
| 230 |
language. The value of this setting must be a language abbreviation for which |
| 231 |
\&\fBgroff\fR provides supplemental configuration, such as \f(CW\*(C`ja\*(C'\fR (for Japanese) or |
| 232 |
\&\f(CW\*(C`zh\*(C'\fR (for Chinese). |
| 233 |
.Sp |
| 234 |
Specifically, this adds: |
| 235 |
.Sp |
| 236 |
.Vb 2 |
| 237 |
\& .mso <language>.tmac |
| 238 |
\& .hla <language> |
| 239 |
.Ve |
| 240 |
.Sp |
| 241 |
to the start of the file, which configure correct line breaking for the |
| 242 |
specified language. Without these commands, groff may not know how to add |
| 243 |
proper line breaks for Chinese and Japanese text if the manual page is |
| 244 |
installed into the normal manual page directory, such as \fI/usr/share/man\fR. |
| 245 |
.Sp |
| 246 |
On many systems, this will be done automatically if the manual page is |
| 247 |
installed into a language-specific manual page directory, such as |
| 248 |
\&\fI/usr/share/man/zh_CN\fR. In that case, this option is not required. |
| 249 |
.Sp |
| 250 |
Unfortunately, the commands added with this option are specific to \fBgroff\fR |
| 251 |
and will not work with other \fBtroff\fR and \fBnroff\fR implementations. |
| 252 |
.IP lquote 4 |
| 253 |
.IX Item "lquote" |
| 254 |
.PD 0 |
| 255 |
.IP rquote 4 |
| 256 |
.IX Item "rquote" |
| 257 |
.PD |
| 258 |
[4.08] Sets the quote marks used to surround C<> text. \f(CW\*(C`lquote\*(C'\fR sets the |
| 259 |
left quote mark and \f(CW\*(C`rquote\*(C'\fR sets the right quote mark. Either may also be |
| 260 |
set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote mark is added on that |
| 261 |
side of C<> text (but the font is still changed for troff output). |
| 262 |
.Sp |
| 263 |
Also see the \f(CW\*(C`quotes\*(C'\fR option, which can be used to set both quotes at once. |
| 264 |
If both \f(CW\*(C`quotes\*(C'\fR and one of the other options is set, \f(CW\*(C`lquote\*(C'\fR or \f(CW\*(C`rquote\*(C'\fR |
| 265 |
overrides \f(CW\*(C`quotes\*(C'\fR. |
| 266 |
.IP name 4 |
| 267 |
.IX Item "name" |
| 268 |
[4.08] Set the name of the manual page for the \f(CW\*(C`.TH\*(C'\fR macro. Without this |
| 269 |
option, the manual name is set to the uppercased base name of the file being |
| 270 |
converted unless the manual section is 3, in which case the path is parsed to |
| 271 |
see if it is a Perl module path. If it is, a path like \f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR |
| 272 |
is converted into a name like \f(CW\*(C`Pod::Man\*(C'\fR. This option, if given, overrides |
| 273 |
any automatic determination of the name. |
| 274 |
.Sp |
| 275 |
If generating a manual page from standard input, the name will be set to |
| 276 |
\&\f(CW\*(C`STDIN\*(C'\fR if this option is not provided. In this case, providing this option |
| 277 |
is strongly recommended to set a meaningful manual page name. |
| 278 |
.IP nourls 4 |
| 279 |
.IX Item "nourls" |
| 280 |
[2.27] Normally, L<> formatting codes with a URL but anchor text are |
| 281 |
formatted to show both the anchor text and the URL. In other words: |
| 282 |
.Sp |
| 283 |
.Vb 1 |
| 284 |
\& L<foo|http://example.com/> |
| 285 |
.Ve |
| 286 |
.Sp |
| 287 |
is formatted as: |
| 288 |
.Sp |
| 289 |
.Vb 1 |
| 290 |
\& foo <http://example.com/> |
| 291 |
.Ve |
| 292 |
.Sp |
| 293 |
This option, if set to a true value, suppresses the URL when anchor text |
| 294 |
is given, so this example would be formatted as just \f(CW\*(C`foo\*(C'\fR. This can |
| 295 |
produce less cluttered output in cases where the URLs are not particularly |
| 296 |
important. |
| 297 |
.IP quotes 4 |
| 298 |
.IX Item "quotes" |
| 299 |
[4.00] Sets the quote marks used to surround C<> text. If the value is a |
| 300 |
single character, it is used as both the left and right quote. Otherwise, it |
| 301 |
is split in half, and the first half of the string is used as the left quote |
| 302 |
and the second is used as the right quote. |
| 303 |
.Sp |
| 304 |
This may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote |
| 305 |
marks are added around C<> text (but the font is still changed for troff |
| 306 |
output). |
| 307 |
.Sp |
| 308 |
Also see the \f(CW\*(C`lquote\*(C'\fR and \f(CW\*(C`rquote\*(C'\fR options, which can be used to set the |
| 309 |
left and right quotes independently. If both \f(CW\*(C`quotes\*(C'\fR and one of the other |
| 310 |
options is set, \f(CW\*(C`lquote\*(C'\fR or \f(CW\*(C`rquote\*(C'\fR overrides \f(CW\*(C`quotes\*(C'\fR. |
| 311 |
.IP release 4 |
| 312 |
.IX Item "release" |
| 313 |
[1.00] Set the centered footer for the \f(CW\*(C`.TH\*(C'\fR macro. By default, this is set |
| 314 |
to the version of Perl you run Pod::Man under. Setting this to the empty |
| 315 |
string will cause some *roff implementations to use the system default value. |
| 316 |
.Sp |
| 317 |
Note that some system \f(CW\*(C`an\*(C'\fR macro sets assume that the centered footer will be |
| 318 |
a modification date and will prepend something like \f(CW\*(C`Last modified: \*(C'\fR. If |
| 319 |
this is the case for your target system, you may want to set \f(CW\*(C`release\*(C'\fR to the |
| 320 |
last modified date and \f(CW\*(C`date\*(C'\fR to the version number. |
| 321 |
.IP section 4 |
| 322 |
.IX Item "section" |
| 323 |
[1.00] Set the section for the \f(CW\*(C`.TH\*(C'\fR macro. The standard section numbering |
| 324 |
convention is to use 1 for user commands, 2 for system calls, 3 for functions, |
| 325 |
4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous |
| 326 |
information, and 8 for administrator commands. There is a lot of variation |
| 327 |
here, however; some systems (like Solaris) use 4 for file formats, 5 for |
| 328 |
miscellaneous information, and 7 for devices. Still others use 1m instead of |
| 329 |
8, or some mix of both. About the only section numbers that are reliably |
| 330 |
consistent are 1, 2, and 3. |
| 331 |
.Sp |
| 332 |
By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR in which |
| 333 |
case section 3 will be selected. |
| 334 |
.IP stderr 4 |
| 335 |
.IX Item "stderr" |
| 336 |
[2.19] If set to a true value, send error messages about invalid POD to |
| 337 |
standard error instead of appending a POD ERRORS section to the generated |
| 338 |
*roff output. This is equivalent to setting \f(CW\*(C`errors\*(C'\fR to \f(CW\*(C`stderr\*(C'\fR if |
| 339 |
\&\f(CW\*(C`errors\*(C'\fR is not already set. |
| 340 |
.Sp |
| 341 |
This option is for backward compatibility with Pod::Man versions that did not |
| 342 |
support \f(CW\*(C`errors\*(C'\fR. Normally, the \f(CW\*(C`errors\*(C'\fR option should be used instead. |
| 343 |
.IP utf8 4 |
| 344 |
.IX Item "utf8" |
| 345 |
[2.21] This option used to set the output encoding to UTF\-8. Since this is |
| 346 |
now the default, it is ignored and does nothing. |
| 347 |
.RE |
| 348 |
.RS 4 |
| 349 |
.RE |
| 350 |
.SH "INSTANCE METHODS" |
| 351 |
.IX Header "INSTANCE METHODS" |
| 352 |
As a derived class from Pod::Simple, Pod::Man supports the same methods and |
| 353 |
interfaces. See Pod::Simple for all the details. This section summarizes |
| 354 |
the most-frequently-used methods and the ones added by Pod::Man. |
| 355 |
.IP output_fh(FH) 4 |
| 356 |
.IX Item "output_fh(FH)" |
| 357 |
Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR |
| 358 |
to the file handle FH instead of \f(CW\*(C`STDOUT\*(C'\fR. |
| 359 |
.IP output_string(REF) 4 |
| 360 |
.IX Item "output_string(REF)" |
| 361 |
Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR |
| 362 |
to the scalar variable pointed to by REF, rather than \f(CW\*(C`STDOUT\*(C'\fR. For example: |
| 363 |
.Sp |
| 364 |
.Vb 4 |
| 365 |
\& my $man = Pod::Man\->new(); |
| 366 |
\& my $output; |
| 367 |
\& $man\->output_string(\e$output); |
| 368 |
\& $man\->parse_file(\*(Aq/some/input/file\*(Aq); |
| 369 |
.Ve |
| 370 |
.Sp |
| 371 |
Be aware that the output in that variable will already be encoded in UTF\-8. |
| 372 |
.IP parse_file(PATH) 4 |
| 373 |
.IX Item "parse_file(PATH)" |
| 374 |
Read the POD source from PATH and format it. By default, the output is sent |
| 375 |
to \f(CW\*(C`STDOUT\*(C'\fR, but this can be changed with the \fBoutput_fh()\fR or \fBoutput_string()\fR |
| 376 |
methods. |
| 377 |
.IP "parse_from_file(INPUT, OUTPUT)" 4 |
| 378 |
.IX Item "parse_from_file(INPUT, OUTPUT)" |
| 379 |
.PD 0 |
| 380 |
.IP "parse_from_filehandle(FH, OUTPUT)" 4 |
| 381 |
.IX Item "parse_from_filehandle(FH, OUTPUT)" |
| 382 |
.PD |
| 383 |
Read the POD source from INPUT, format it, and output the results to OUTPUT. |
| 384 |
.Sp |
| 385 |
\&\fBparse_from_filehandle()\fR is provided for backward compatibility with older |
| 386 |
versions of Pod::Man. \fBparse_from_file()\fR should be used instead. |
| 387 |
.IP "parse_lines(LINES[, ...[, undef]])" 4 |
| 388 |
.IX Item "parse_lines(LINES[, ...[, undef]])" |
| 389 |
Parse the provided lines as POD source, writing the output to either \f(CW\*(C`STDOUT\*(C'\fR |
| 390 |
or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR methods. This |
| 391 |
method can be called repeatedly to provide more input lines. An explicit |
| 392 |
\&\f(CW\*(C`undef\*(C'\fR should be passed to indicate the end of input. |
| 393 |
.Sp |
| 394 |
This method expects raw bytes, not decoded characters. |
| 395 |
.IP parse_string_document(INPUT) 4 |
| 396 |
.IX Item "parse_string_document(INPUT)" |
| 397 |
Parse the provided scalar variable as POD source, writing the output to either |
| 398 |
\&\f(CW\*(C`STDOUT\*(C'\fR or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR |
| 399 |
methods. |
| 400 |
.Sp |
| 401 |
This method expects raw bytes, not decoded characters. |
| 402 |
.SH ENCODING |
| 403 |
.IX Header "ENCODING" |
| 404 |
As of Pod::Man 5.00, the default output encoding for Pod::Man is UTF\-8. This |
| 405 |
should work correctly on any modern system that uses either \fBgroff\fR (most |
| 406 |
Linux distributions) or \fBmandoc\fR (Alpine Linux and most BSD variants, |
| 407 |
including macOS). |
| 408 |
.PP |
| 409 |
The user will probably have to use a UTF\-8 locale to see correct output. This |
| 410 |
may be done by default; if not, set the LANG or LC_CTYPE environment variables |
| 411 |
to an appropriate local. The locale \f(CW\*(C`C.UTF\-8\*(C'\fR is available on most systems |
| 412 |
if one wants correct output without changing the other things locales affect, |
| 413 |
such as collation. |
| 414 |
.PP |
| 415 |
The backward-compatible output format used in Pod::Man versions before 5.00 is |
| 416 |
available by setting the \f(CW\*(C`encoding\*(C'\fR option to \f(CW\*(C`roff\*(C'\fR. This may produce |
| 417 |
marginally nicer results on older UNIX versions that do not use \fBgroff\fR or |
| 418 |
\&\fBmandoc\fR, but none of the available options will correctly render Unicode |
| 419 |
characters on those systems. |
| 420 |
.PP |
| 421 |
Below are some additional details about how this choice was made and some |
| 422 |
discussion of alternatives. |
| 423 |
.SS History |
| 424 |
.IX Subsection "History" |
| 425 |
The default output encoding for Pod::Man has been a long-standing problem. |
| 426 |
\&\fBtroff\fR and \fBnroff\fR predate Unicode by a significant margin, and their |
| 427 |
implementations for many UNIX systems reflect that legacy. It's common for |
| 428 |
Unicode to not be supported in any form. |
| 429 |
.PP |
| 430 |
Because of this, versions of Pod::Man prior to 5.00 maintained the highly |
| 431 |
conservative output of the original pod2man, which output pure ASCII with |
| 432 |
complex macros to simulate common western European accented characters when |
| 433 |
processed with troff. The nroff output was awkward and sometimes incorrect, |
| 434 |
and characters not used in western European scripts were replaced with \f(CW\*(C`X\*(C'\fR. |
| 435 |
This choice maximized backwards compatibility with \fBman\fR and |
| 436 |
\&\fBnroff\fR/\fBtroff\fR implementations at the cost of incorrect rendering of many |
| 437 |
POD documents, particularly those containing people's names. |
| 438 |
.PP |
| 439 |
The modern implementations, \fBgroff\fR (used in most Linux distributions) and |
| 440 |
\&\fBmandoc\fR (used by most BSD variants), do now support Unicode. Other UNIX |
| 441 |
systems often do not, but they're now a tiny minority of the systems people |
| 442 |
use on a daily basis. It's increasingly common (for very good reasons) to use |
| 443 |
Unicode characters for POD documents rather than using ASCII conversions of |
| 444 |
people's names or avoiding non-English text, making the limitations in the old |
| 445 |
output format more apparent. |
| 446 |
.PP |
| 447 |
Four options have been proposed to fix this: |
| 448 |
.IP \(bu 2 |
| 449 |
Optionally support UTF\-8 output but don't change the default. This is the |
| 450 |
approach taken since Pod::Man 2.1.0, which added the \f(CW\*(C`utf8\*(C'\fR option. Some |
| 451 |
Pod::Man users use this option for better output on platforms known to support |
| 452 |
Unicode, but since the defaults have not changed, people continued to |
| 453 |
encounter (and file bug reports about) the poor default rendering. |
| 454 |
.IP \(bu 2 |
| 455 |
Convert characters to troff \f(CW\*(C`\e(xx\*(C'\fR escapes. This requires maintaining a |
| 456 |
large translation table and addresses only a tiny part of the problem, since |
| 457 |
many Unicode characters have no standard troff name. \fBgroff\fR has the largest |
| 458 |
list, but if one is willing to assume \fBgroff\fR is the formatter, the next |
| 459 |
option is better. |
| 460 |
.IP \(bu 2 |
| 461 |
Convert characters to groff \f(CW\*(C`\e[uNNNN]\*(C'\fR escapes. This is implemented as the |
| 462 |
\&\f(CW\*(C`groff\*(C'\fR encoding for those who want to use it, and is supported by both |
| 463 |
\&\fBgroff\fR and \fBmandoc\fR. However, it is no better than UTF\-8 output for |
| 464 |
portability to other implementations. See "Testing results" for more |
| 465 |
details. |
| 466 |
.IP \(bu 2 |
| 467 |
Change the default output format to UTF\-8 and ask those who want maximum |
| 468 |
backward compatibility to explicitly select the old encoding. This fixes the |
| 469 |
issue for most users at the cost of backwards compatibility. While the |
| 470 |
rendering of non-ASCII characters is different on older systems that don't |
| 471 |
support UTF\-8, it's not always worse than the old output. |
| 472 |
.PP |
| 473 |
Pod::Man 5.00 and later makes the last choice. This arguably produces worse |
| 474 |
output when manual pages are formatted with \fBtroff\fR into PostScript or PDF, |
| 475 |
but doing this is rare and normally manual, so the encoding can be changed in |
| 476 |
those cases. The older output encoding is available by setting \f(CW\*(C`encoding\*(C'\fR to |
| 477 |
\&\f(CW\*(C`roff\*(C'\fR. |
| 478 |
.SS "Testing results" |
| 479 |
.IX Subsection "Testing results" |
| 480 |
Here is the results of testing \f(CW\*(C`encoding\*(C'\fR values of \f(CW\*(C`utf\-8\*(C'\fR and \f(CW\*(C`groff\*(C'\fR on |
| 481 |
various operating systems. The testing methodology was to create \fIman/man1\fR |
| 482 |
in the current directory, copy \fIencoding.utf8\fR or \fIencoding.groff\fR from the |
| 483 |
podlators 5.00 distribution to \fIman/man1/encoding.1\fR, and then run: |
| 484 |
.PP |
| 485 |
.Vb 1 |
| 486 |
\& LANG=C.UTF\-8 MANPATH=$(pwd)/man man 1 encoding |
| 487 |
.Ve |
| 488 |
.PP |
| 489 |
If the locale is not explicitly set to one that includes UTF\-8, the Unicode |
| 490 |
characters were usually converted to ASCII (by, for example, dropping an |
| 491 |
accent) or deleted or replaced with \f(CW\*(C`<?>\*(C'\fR if there was no conversion. |
| 492 |
.PP |
| 493 |
Tested on 2022\-09\-25. Many thanks to the GCC Compile Farm project for access |
| 494 |
to testing hosts. |
| 495 |
.PP |
| 496 |
.Vb 12 |
| 497 |
\& OS UTF\-8 groff |
| 498 |
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\- |
| 499 |
\& AIX 7.1 no [1] no [2] |
| 500 |
\& Alpine 3.15.0 yes yes |
| 501 |
\& CentOS 7.9 yes yes |
| 502 |
\& Debian 7 yes yes |
| 503 |
\& FreeBSD 13.0 yes yes |
| 504 |
\& NetBSD 9.2 yes yes |
| 505 |
\& OpenBSD 7.1 yes yes |
| 506 |
\& openSUSE Leap 15.4 yes yes |
| 507 |
\& Solaris 10 yes no [2] |
| 508 |
\& Solaris 11 no [3] no [3] |
| 509 |
.Ve |
| 510 |
.PP |
| 511 |
I did not have access to a macOS system for testing, but since it uses |
| 512 |
\&\fBmandoc\fR, it's behavior is probably the same as the BSD hosts. |
| 513 |
.PP |
| 514 |
Notes: |
| 515 |
.IP [1] 4 |
| 516 |
.IX Item "[1]" |
| 517 |
Unicode characters were converted to one or two random ASCII characters |
| 518 |
unrelated to the original character. |
| 519 |
.IP [2] 4 |
| 520 |
.IX Item "[2]" |
| 521 |
Unicode characters were shown as the body of the groff escape rather than the |
| 522 |
indicated character (in other words, text like \f(CW\*(C`[u00EF]\*(C'\fR). |
| 523 |
.IP [3] 4 |
| 524 |
.IX Item "[3]" |
| 525 |
Unicode characters were deleted entirely, as if they weren't there. Using |
| 526 |
\&\f(CW\*(C`nroff \-man\*(C'\fR instead of \fBman\fR to format the page showed the same results as |
| 527 |
Solaris 10. Using \f(CW\*(C`groff \-k \-man \-Tutf8\*(C'\fR to format the page produced the |
| 528 |
correct output. |
| 529 |
.PP |
| 530 |
PostScript and PDF output using groff on a Debian 12 system do not support |
| 531 |
combining accent marks or SMP characters due to a lack of support in the |
| 532 |
default output font. |
| 533 |
.PP |
| 534 |
Testing on additional platforms is welcome. Please let the author know if you |
| 535 |
have additional results. |
| 536 |
.SH DIAGNOSTICS |
| 537 |
.IX Header "DIAGNOSTICS" |
| 538 |
.IP "roff font should be 1 or 2 chars, not ""%s""" 4 |
| 539 |
.IX Item "roff font should be 1 or 2 chars, not ""%s""" |
| 540 |
(F) You specified a *roff font (using \f(CW\*(C`fixed\*(C'\fR, \f(CW\*(C`fixedbold\*(C'\fR, etc.) that |
| 541 |
wasn't either one or two characters. Pod::Man doesn't support *roff fonts |
| 542 |
longer than two characters, although some *roff extensions do (the |
| 543 |
canonical versions of \fBnroff\fR and \fBtroff\fR don't either). |
| 544 |
.IP "Invalid errors setting ""%s""" 4 |
| 545 |
.IX Item "Invalid errors setting ""%s""" |
| 546 |
(F) The \f(CW\*(C`errors\*(C'\fR parameter to the constructor was set to an unknown value. |
| 547 |
.IP "Invalid quote specification ""%s""" 4 |
| 548 |
.IX Item "Invalid quote specification ""%s""" |
| 549 |
(F) The quote specification given (the \f(CW\*(C`quotes\*(C'\fR option to the |
| 550 |
constructor) was invalid. A quote specification must be either one |
| 551 |
character long or an even number (greater than one) characters long. |
| 552 |
.IP "POD document had syntax errors" 4 |
| 553 |
.IX Item "POD document had syntax errors" |
| 554 |
(F) The POD document being formatted had syntax errors and the \f(CW\*(C`errors\*(C'\fR |
| 555 |
option was set to \f(CW\*(C`die\*(C'\fR. |
| 556 |
.SH ENVIRONMENT |
| 557 |
.IX Header "ENVIRONMENT" |
| 558 |
.IP PERL_CORE 4 |
| 559 |
.IX Item "PERL_CORE" |
| 560 |
If set and Encode is not available, silently fall back to an encoding of |
| 561 |
\&\f(CW\*(C`groff\*(C'\fR without complaining to standard error. This environment variable is |
| 562 |
set during Perl core builds, which build Encode after podlators. Encode is |
| 563 |
expected to not (yet) be available in that case. |
| 564 |
.IP POD_MAN_DATE 4 |
| 565 |
.IX Item "POD_MAN_DATE" |
| 566 |
If set, this will be used as the value of the left-hand footer unless the |
| 567 |
\&\f(CW\*(C`date\*(C'\fR option is explicitly set, overriding the timestamp of the input |
| 568 |
file or the current time. This is primarily useful to ensure reproducible |
| 569 |
builds of the same output file given the same source and Pod::Man version, |
| 570 |
even when file timestamps may not be consistent. |
| 571 |
.IP SOURCE_DATE_EPOCH 4 |
| 572 |
.IX Item "SOURCE_DATE_EPOCH" |
| 573 |
If set, and POD_MAN_DATE and the \f(CW\*(C`date\*(C'\fR options are not set, this will be |
| 574 |
used as the modification time of the source file, overriding the timestamp of |
| 575 |
the input file or the current time. It should be set to the desired time in |
| 576 |
seconds since UNIX epoch. This is primarily useful to ensure reproducible |
| 577 |
builds of the same output file given the same source and Pod::Man version, |
| 578 |
even when file timestamps may not be consistent. See |
| 579 |
<https://reproducible\-builds.org/specs/source\-date\-epoch/> for the full |
| 580 |
specification. |
| 581 |
.Sp |
| 582 |
(Arguably, according to the specification, this variable should be used only |
| 583 |
if the timestamp of the input file is not available and Pod::Man uses the |
| 584 |
current time. However, for reproducible builds in Debian, results were more |
| 585 |
reliable if this variable overrode the timestamp of the input file.) |
| 586 |
.SH COMPATIBILITY |
| 587 |
.IX Header "COMPATIBILITY" |
| 588 |
Pod::Man 1.02 (based on Pod::Parser) was the first version included with |
| 589 |
Perl, in Perl 5.6.0. |
| 590 |
.PP |
| 591 |
The current API based on Pod::Simple was added in Pod::Man 2.00. Pod::Man |
| 592 |
2.04 was included in Perl 5.9.3, the first version of Perl to incorporate |
| 593 |
those changes. This is the first version that correctly supports all modern |
| 594 |
POD syntax. The \fBparse_from_filehandle()\fR method was re-added for backward |
| 595 |
compatibility in Pod::Man 2.09, included in Perl 5.9.4. |
| 596 |
.PP |
| 597 |
Support for anchor text in L<> links of type URL was added in Pod::Man |
| 598 |
2.23, included in Perl 5.11.5. |
| 599 |
.PP |
| 600 |
\&\fBparse_lines()\fR, \fBparse_string_document()\fR, and \fBparse_file()\fR set a default output |
| 601 |
file handle of \f(CW\*(C`STDOUT\*(C'\fR if one was not already set as of Pod::Man 2.28, |
| 602 |
included in Perl 5.19.5. |
| 603 |
.PP |
| 604 |
Support for SOURCE_DATE_EPOCH and POD_MAN_DATE was added in Pod::Man 4.00, |
| 605 |
included in Perl 5.23.7, and generated dates were changed to use UTC instead |
| 606 |
of the local time zone. This is also the first release that aligned the |
| 607 |
module version and the version of the podlators distribution. All modules |
| 608 |
included in podlators, and the podlators distribution itself, share the same |
| 609 |
version number from this point forward. |
| 610 |
.PP |
| 611 |
Pod::Man 4.10, included in Perl 5.27.8, changed the formatting for manual page |
| 612 |
references and function names to bold instead of italic, following the current |
| 613 |
Linux manual page standard. |
| 614 |
.PP |
| 615 |
Pod::Man 5.00 changed the default output encoding to UTF\-8, overridable with |
| 616 |
the new \f(CW\*(C`encoding\*(C'\fR option. It also fixed problems with bold or italic |
| 617 |
extending too far when used with C<> escapes, and began converting Unicode |
| 618 |
zero-width spaces (U+200B) to the \f(CW\*(C`\e:\*(C'\fR *roff escape. It also dropped |
| 619 |
attempts to add subtle formatting corrections in the output that would only be |
| 620 |
visible when typeset with \fBtroff\fR, which had previously been a significant |
| 621 |
source of bugs. |
| 622 |
.SH BUGS |
| 623 |
.IX Header "BUGS" |
| 624 |
There are numerous bugs and language-specific assumptions in the nroff |
| 625 |
fallbacks for accented characters in the \f(CW\*(C`roff\*(C'\fR encoding. Since the point of |
| 626 |
this encoding is backward compatibility with the output from earlier versions |
| 627 |
of Pod::Man, and it is deprecated except when necessary to support old |
| 628 |
systems, those bugs are unlikely to ever be fixed. |
| 629 |
.PP |
| 630 |
Pod::Man doesn't handle font names longer than two characters. Neither do |
| 631 |
most \fBtroff\fR implementations, but groff does as an extension. It would be |
| 632 |
nice to support as an option for those who want to use it. |
| 633 |
.SH CAVEATS |
| 634 |
.IX Header "CAVEATS" |
| 635 |
.SS "Sentence spacing" |
| 636 |
.IX Subsection "Sentence spacing" |
| 637 |
Pod::Man copies the input spacing verbatim to the output *roff document. This |
| 638 |
means your output will be affected by how \fBnroff\fR generally handles sentence |
| 639 |
spacing. |
| 640 |
.PP |
| 641 |
\&\fBnroff\fR dates from an era in which it was standard to use two spaces after |
| 642 |
sentences, and will always add two spaces after a line-ending period (or |
| 643 |
similar punctuation) when reflowing text. For example, the following input: |
| 644 |
.PP |
| 645 |
.Vb 1 |
| 646 |
\& =pod |
| 647 |
\& |
| 648 |
\& One sentence. |
| 649 |
\& Another sentence. |
| 650 |
.Ve |
| 651 |
.PP |
| 652 |
will result in two spaces after the period when the text is reflowed. If you |
| 653 |
use two spaces after sentences anyway, this will be consistent, although you |
| 654 |
will have to be careful to not end a line with an abbreviation such as \f(CW\*(C`e.g.\*(C'\fR |
| 655 |
or \f(CW\*(C`Ms.\*(C'\fR. Output will also be consistent if you use the *roff style guide |
| 656 |
(and XKCD 1285 <https://xkcd.com/1285/>) recommendation of putting a line |
| 657 |
break after each sentence, although that will consistently produce two spaces |
| 658 |
after each sentence, which may not be what you want. |
| 659 |
.PP |
| 660 |
If you prefer one space after sentences (which is the more modern style), you |
| 661 |
will unfortunately need to ensure that no line in the middle of a paragraph |
| 662 |
ends in a period or similar sentence-ending paragraph. Otherwise, \fBnroff\fR |
| 663 |
will add a two spaces after that sentence when reflowing, and your output |
| 664 |
document will have inconsistent spacing. |
| 665 |
.SS Hyphens |
| 666 |
.IX Subsection "Hyphens" |
| 667 |
The handling of hyphens versus dashes is somewhat fragile, and one may get a |
| 668 |
the wrong one under some circumstances. This will normally only matter for |
| 669 |
line breaking and possibly for troff output. |
| 670 |
.SH AUTHOR |
| 671 |
.IX Header "AUTHOR" |
| 672 |
Written by Russ Allbery <[email protected]>, based on the original \fBpod2man\fR by |
| 673 |
Tom Christiansen <[email protected]>. |
| 674 |
.PP |
| 675 |
The modifications to work with Pod::Simple instead of Pod::Parser were |
| 676 |
contributed by Sean Burke <[email protected]>, but I've since hacked them beyond |
| 677 |
recognition and all bugs are mine. |
| 678 |
.SH "COPYRIGHT AND LICENSE" |
| 679 |
.IX Header "COPYRIGHT AND LICENSE" |
| 680 |
Copyright 1999\-2010, 2012\-2020, 2022 Russ Allbery <[email protected]> |
| 681 |
.PP |
| 682 |
Substantial contributions by Sean Burke <[email protected]>. |
| 683 |
.PP |
| 684 |
This program is free software; you may redistribute it and/or modify it |
| 685 |
under the same terms as Perl itself. |
| 686 |
.SH "SEE ALSO" |
| 687 |
.IX Header "SEE ALSO" |
| 688 |
Encode::Supported, Pod::Simple, \fBperlpod\fR\|(1), \fBpod2man\fR\|(1), |
| 689 |
\&\fBnroff\fR\|(1), \fBtroff\fR\|(1), \fBman\fR\|(1), \fBman\fR\|(7) |
| 690 |
.PP |
| 691 |
Ossanna, Joseph F., and Brian W. Kernighan. "Troff User's Manual," |
| 692 |
Computing Science Technical Report No. 54, AT&T Bell Laboratories. This is |
| 693 |
the best documentation of standard \fBnroff\fR and \fBtroff\fR. At the time of |
| 694 |
this writing, it's available at <http://www.troff.org/54.pdf>. |
| 695 |
.PP |
| 696 |
The manual page documenting the man macro set may be \fBman\fR\|(5) instead of |
| 697 |
\&\fBman\fR\|(7) on your system. |
| 698 |
.PP |
| 699 |
See \fBperlpodstyle\fR\|(1) for documentation on writing manual pages in POD if |
| 700 |
you've not done it before and aren't familiar with the conventions. |
| 701 |
.PP |
| 702 |
The current version of this module is always available from its web site at |
| 703 |
<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the |
| 704 |
Perl core distribution as of 5.6.0. |