Debian Codegraph @

upstream/debian-unstable/man3/Pod::Man.3perl

raw
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.