Debian Codegraph @

upstream/mageia-cauldron/man3pm/Pod::Man.3pm

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