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

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pod::Man 3perl"
.TH Pod::Man 3perl 2024-05-30 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Pod::Man \- Convert POD data to formatted *roff input
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use Pod::Man;
\&    my $parser = Pod::Man\->new (release => $VERSION, section => 8);
\&
\&    # Read POD from STDIN and write to STDOUT.
\&    $parser\->parse_file (\e*STDIN);
\&
\&    # Read POD from file.pod and write to file.1.
\&    $parser\->parse_from_file (\*(Aqfile.pod\*(Aq, \*(Aqfile.1\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Pod::Man is a module to convert documentation in the POD format (the
preferred language for documenting Perl) into *roff input using the man
macro set.  The resulting *roff code is suitable for display on a terminal
using \fBnroff\fR\|(1), normally via \fBman\fR\|(1), or printing using \fBtroff\fR\|(1).
It is conventionally invoked using the driver script \fBpod2man\fR, but it can
also be used directly.
.PP
By default (on non-EBCDIC systems), Pod::Man outputs UTF\-8.  Its output should
work with the \fBman\fR program on systems that use \fBgroff\fR (most Linux
distributions) or \fBmandoc\fR (most BSD variants), but may result in mangled
output on older UNIX systems.  To choose a different, possibly more
backward-compatible output mangling on such systems, set the \f(CW\*(C`encoding\*(C'\fR
option to \f(CW\*(C`roff\*(C'\fR (the default in earlier Pod::Man versions).  See the
\&\f(CW\*(C`encoding\*(C'\fR option and "ENCODING" for more details.
.PP
See "COMPATIBILTY" for the versions of Pod::Man with significant
backward-incompatible changes (other than constructor options, whose versions
are documented below), and the versions of Perl that included them.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP new(ARGS) 4
.IX Item "new(ARGS)"
Create a new Pod::Man object.  ARGS should be a list of key/value pairs, where
the keys are chosen from the following.  Each option is annotated with the
version of Pod::Man in which that option was added with its current meaning.
.RS 4
.IP center 4
.IX Item "center"
[1.00] Sets the centered page header for the \f(CW\*(C`.TH\*(C'\fR macro.  The default, if
this option is not specified, is \f(CW\*(C`User Contributed Perl Documentation\*(C'\fR.
.IP date 4
.IX Item "date"
[4.00] Sets the left-hand footer for the \f(CW\*(C`.TH\*(C'\fR macro.  If this option is not
set, the contents of the environment variable POD_MAN_DATE, if set, will be
used.  Failing that, the value of SOURCE_DATE_EPOCH, the modification date of
the input file, or the current time if \fBstat()\fR can't find that file (which will
be the case if the input is from \f(CW\*(C`STDIN\*(C'\fR) will be used.  If taken from any
source other than POD_MAN_DATE (which is used verbatim), the date will be
formatted as \f(CW\*(C`YYYY\-MM\-DD\*(C'\fR and will be based on UTC (so that the output will
be reproducible regardless of local time zone).
.IP encoding 4
.IX Item "encoding"
[5.00] Specifies the encoding of the output.  The value must be an encoding
recognized by the Encode module (see Encode::Supported), or the special
values \f(CW\*(C`roff\*(C'\fR or \f(CW\*(C`groff\*(C'\fR.  The default on non-EBCDIC systems is UTF\-8.
.Sp
If the output contains characters that cannot be represented in this encoding,
that is an error that will be reported as configured by the \f(CW\*(C`errors\*(C'\fR option.
If error handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character will be
replaced with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR).
.Sp
If the \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`groff\*(C'\fR (the default on
EBCDIC systems), or if the Encode module is not available and the encoding is
set to anything other than \f(CW\*(C`roff\*(C'\fR, Pod::Man will translate all non-ASCII
characters to \f(CW\*(C`\e[uNNNN]\*(C'\fR Unicode escapes.  These are not traditionally part
of the *roff language, but are supported by \fBgroff\fR and \fBmandoc\fR and thus by
the majority of manual page processors in use today.
.Sp
If the \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`roff\*(C'\fR, Pod::Man will
do its historic transformation of (some) ISO 8859\-1 characters into *roff
escapes that may be adequate in troff and may be readable (if ugly) in nroff.
This was the default behavior of versions of Pod::Man before 5.00.  With this
encoding, all other non-ASCII characters will be replaced with \f(CW\*(C`X\*(C'\fR.  It may
be required for very old troff and nroff implementations that do not support
UTF\-8, but its representation of any non-ASCII character is very poor and
often specific to European languages.
.Sp
If the output file handle has a PerlIO encoding layer set, setting \f(CW\*(C`encoding\*(C'\fR
to anything other than \f(CW\*(C`groff\*(C'\fR or \f(CW\*(C`roff\*(C'\fR will be ignored and no encoding
will be done by Pod::Man.  It will instead rely on the encoding layer to make
whatever output encoding transformations are desired.
.Sp
WARNING: The input encoding of the POD source is independent from the output
encoding, and setting this option does not affect the interpretation of the
POD input.  Unless your POD source is US-ASCII, its encoding should be
declared with the \f(CW\*(C`=encoding\*(C'\fR command in the source.  If this is not done,
Pod::Simple will will attempt to guess the encoding and may be successful if
it's Latin\-1 or UTF\-8, but it will produce warnings.  See \fBperlpod\fR\|(1) for
more information.
.IP errors 4
.IX Item "errors"
[2.27] How to report errors.  \f(CW\*(C`die\*(C'\fR says to throw an exception on any POD
formatting error.  \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error, but not
to throw an exception.  \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in the
resulting documentation summarizing the errors.  \f(CW\*(C`none\*(C'\fR ignores POD errors
entirely, as much as possible.
.Sp
The default is \f(CW\*(C`pod\*(C'\fR.
.IP fixed 4
.IX Item "fixed"
[1.00] The fixed-width font to use for verbatim text and code.  Defaults to
\&\f(CW\*(C`CW\*(C'\fR.  Some systems prefer \f(CW\*(C`CR\*(C'\fR instead.  Only matters for \fBtroff\fR output.
.IP fixedbold 4
.IX Item "fixedbold"
[1.00] Bold version of the fixed-width font.  Defaults to \f(CW\*(C`CB\*(C'\fR.  Only matters
for \fBtroff\fR output.
.IP fixeditalic 4
.IX Item "fixeditalic"
[1.00] Italic version of the fixed-width font (something of a misnomer, since
most fixed-width fonts only have an oblique version, not an italic version).
Defaults to \f(CW\*(C`CI\*(C'\fR.  Only matters for \fBtroff\fR output.
.IP fixedbolditalic 4
.IX Item "fixedbolditalic"
[1.00] Bold italic (in theory, probably oblique in practice) version of the
fixed-width font.  Pod::Man doesn't assume you have this, and defaults to
\&\f(CW\*(C`CB\*(C'\fR.  Some systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR.
Only matters for \fBtroff\fR output.
.IP guesswork 4
.IX Item "guesswork"
[5.00] By default, Pod::Man applies some default formatting rules based on
guesswork and regular expressions that are intended to make writing Perl
documentation easier and require less explicit markup.  These rules may not
always be appropriate, particularly for documentation that isn't about Perl.
This option allows turning all or some of it off.
.Sp
The special value \f(CW\*(C`all\*(C'\fR enables all guesswork.  This is also the default for
backward compatibility reasons.  The special value \f(CW\*(C`none\*(C'\fR disables all
guesswork.  Otherwise, the value of this option should be a comma-separated
list of one or more of the following keywords:
.RS 4
.IP functions 4
.IX Item "functions"
Convert function references like \f(CWfoo()\fR to bold even if they have no markup.
The function name accepts valid Perl characters for function names (including
\&\f(CW\*(C`:\*(C'\fR), and the trailing parentheses must be present and empty.
.IP manref 4
.IX Item "manref"
Make the first part (before the parentheses) of manual page references like
\&\f(CWfoo(1)\fR bold even if they have no markup.  The section must be a single
number optionally followed by lowercase letters.
.IP quoting 4
.IX Item "quoting"
If no guesswork is enabled, any text enclosed in C<> is surrounded by
double quotes in nroff (terminal) output unless the contents are already
quoted.  When this guesswork is enabled, quote marks will also be suppressed
for Perl variables, function names, function calls, numbers, and hex
constants.
.IP variables 4
.IX Item "variables"
Convert Perl variable names to a fixed-width font even if they have no markup.
This transformation will only be apparent in troff output, or some other
output format (unlike nroff terminal output) that supports fixed-width fonts.
.RE
.RS 4
.Sp
Any unknown guesswork name is silently ignored (for potential future
compatibility), so be careful about spelling.
.RE
.IP language 4
.IX Item "language"
[5.00] Add commands telling \fBgroff\fR that the input file is in the given
language.  The value of this setting must be a language abbreviation for which
\&\fBgroff\fR provides supplemental configuration, such as \f(CW\*(C`ja\*(C'\fR (for Japanese) or
\&\f(CW\*(C`zh\*(C'\fR (for Chinese).
.Sp
Specifically, this adds:
.Sp
.Vb 2
\&    .mso <language>.tmac
\&    .hla <language>
.Ve
.Sp
to the start of the file, which configure correct line breaking for the
specified language.  Without these commands, groff may not know how to add
proper line breaks for Chinese and Japanese text if the manual page is
installed into the normal manual page directory, such as \fI/usr/share/man\fR.
.Sp
On many systems, this will be done automatically if the manual page is
installed into a language-specific manual page directory, such as
\&\fI/usr/share/man/zh_CN\fR.  In that case, this option is not required.
.Sp
Unfortunately, the commands added with this option are specific to \fBgroff\fR
and will not work with other \fBtroff\fR and \fBnroff\fR implementations.
.IP lquote 4
.IX Item "lquote"
.PD 0
.IP rquote 4
.IX Item "rquote"
.PD
[4.08] Sets the quote marks used to surround C<> text.  \f(CW\*(C`lquote\*(C'\fR sets the
left quote mark and \f(CW\*(C`rquote\*(C'\fR sets the right quote mark.  Either may also be
set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote mark is added on that
side of C<> text (but the font is still changed for troff output).
.Sp
Also see the \f(CW\*(C`quotes\*(C'\fR option, which can be used to set both quotes at once.
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
overrides \f(CW\*(C`quotes\*(C'\fR.
.IP name 4
.IX Item "name"
[4.08] Set the name of the manual page for the \f(CW\*(C`.TH\*(C'\fR macro.  Without this
option, the manual name is set to the uppercased base name of the file being
converted unless the manual section is 3, in which case the path is parsed to
see if it is a Perl module path.  If it is, a path like \f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR
is converted into a name like \f(CW\*(C`Pod::Man\*(C'\fR.  This option, if given, overrides
any automatic determination of the name.
.Sp
If generating a manual page from standard input, the name will be set to
\&\f(CW\*(C`STDIN\*(C'\fR if this option is not provided.  In this case, providing this option
is strongly recommended to set a meaningful manual page name.
.IP nourls 4
.IX Item "nourls"
[2.27] Normally, L<> formatting codes with a URL but anchor text are
formatted to show both the anchor text and the URL.  In other words:
.Sp
.Vb 1
\&    L<foo|http://example.com/>
.Ve
.Sp
is formatted as:
.Sp
.Vb 1
\&    foo <http://example.com/>
.Ve
.Sp
This option, if set to a true value, suppresses the URL when anchor text
is given, so this example would be formatted as just \f(CW\*(C`foo\*(C'\fR.  This can
produce less cluttered output in cases where the URLs are not particularly
important.
.IP quotes 4
.IX Item "quotes"
[4.00] Sets the quote marks used to surround C<> text.  If the value is a
single character, it is used as both the left and right quote.  Otherwise, it
is split in half, and the first half of the string is used as the left quote
and the second is used as the right quote.
.Sp
This may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
marks are added around C<> text (but the font is still changed for troff
output).
.Sp
Also see the \f(CW\*(C`lquote\*(C'\fR and \f(CW\*(C`rquote\*(C'\fR options, which can be used to set the
left and right quotes independently.  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 overrides \f(CW\*(C`quotes\*(C'\fR.
.IP release 4
.IX Item "release"
[1.00] Set the centered footer for the \f(CW\*(C`.TH\*(C'\fR macro.  By default, this is set
to the version of Perl you run Pod::Man under.  Setting this to the empty
string will cause some *roff implementations to use the system default value.
.Sp
Note that some system \f(CW\*(C`an\*(C'\fR macro sets assume that the centered footer will be
a modification date and will prepend something like \f(CW\*(C`Last modified: \*(C'\fR.  If
this is the case for your target system, you may want to set \f(CW\*(C`release\*(C'\fR to the
last modified date and \f(CW\*(C`date\*(C'\fR to the version number.
.IP section 4
.IX Item "section"
[1.00] Set the section for the \f(CW\*(C`.TH\*(C'\fR macro.  The standard section numbering
convention is to use 1 for user commands, 2 for system calls, 3 for functions,
4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous
information, and 8 for administrator commands.  There is a lot of variation
here, however; some systems (like Solaris) use 4 for file formats, 5 for
miscellaneous information, and 7 for devices.  Still others use 1m instead of
8, or some mix of both.  About the only section numbers that are reliably
consistent are 1, 2, and 3.
.Sp
By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR in which
case section 3 will be selected.
.IP stderr 4
.IX Item "stderr"
[2.19] If set to a true value, send error messages about invalid POD to
standard error instead of appending a POD ERRORS section to the generated
*roff output.  This is equivalent to setting \f(CW\*(C`errors\*(C'\fR to \f(CW\*(C`stderr\*(C'\fR if
\&\f(CW\*(C`errors\*(C'\fR is not already set.
.Sp
This option is for backward compatibility with Pod::Man versions that did not
support \f(CW\*(C`errors\*(C'\fR.  Normally, the \f(CW\*(C`errors\*(C'\fR option should be used instead.
.IP utf8 4
.IX Item "utf8"
[2.21] This option used to set the output encoding to UTF\-8.  Since this is
now the default, it is ignored and does nothing.
.RE
.RS 4
.RE
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
As a derived class from Pod::Simple, Pod::Man supports the same methods and
interfaces.  See Pod::Simple for all the details.  This section summarizes
the most-frequently-used methods and the ones added by Pod::Man.
.IP output_fh(FH) 4
.IX Item "output_fh(FH)"
Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR
to the file handle FH instead of \f(CW\*(C`STDOUT\*(C'\fR.
.IP output_string(REF) 4
.IX Item "output_string(REF)"
Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR
to the scalar variable pointed to by REF, rather than \f(CW\*(C`STDOUT\*(C'\fR.  For example:
.Sp
.Vb 4
\&    my $man = Pod::Man\->new();
\&    my $output;
\&    $man\->output_string(\e$output);
\&    $man\->parse_file(\*(Aq/some/input/file\*(Aq);
.Ve
.Sp
Be aware that the output in that variable will already be encoded in UTF\-8.
.IP parse_file(PATH) 4
.IX Item "parse_file(PATH)"
Read the POD source from PATH and format it.  By default, the output is sent
to \f(CW\*(C`STDOUT\*(C'\fR, but this can be changed with the \fBoutput_fh()\fR or \fBoutput_string()\fR
methods.
.IP "parse_from_file(INPUT, OUTPUT)" 4
.IX Item "parse_from_file(INPUT, OUTPUT)"
.PD 0
.IP "parse_from_filehandle(FH, OUTPUT)" 4
.IX Item "parse_from_filehandle(FH, OUTPUT)"
.PD
Read the POD source from INPUT, format it, and output the results to OUTPUT.
.Sp
\&\fBparse_from_filehandle()\fR is provided for backward compatibility with older
versions of Pod::Man.  \fBparse_from_file()\fR should be used instead.
.IP "parse_lines(LINES[, ...[, undef]])" 4
.IX Item "parse_lines(LINES[, ...[, undef]])"
Parse the provided lines as POD source, writing the output to either \f(CW\*(C`STDOUT\*(C'\fR
or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR methods.  This
method can be called repeatedly to provide more input lines.  An explicit
\&\f(CW\*(C`undef\*(C'\fR should be passed to indicate the end of input.
.Sp
This method expects raw bytes, not decoded characters.
.IP parse_string_document(INPUT) 4
.IX Item "parse_string_document(INPUT)"
Parse the provided scalar variable as POD source, writing the output to either
\&\f(CW\*(C`STDOUT\*(C'\fR or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR
methods.
.Sp
This method expects raw bytes, not decoded characters.
.SH ENCODING
.IX Header "ENCODING"
As of Pod::Man 5.00, the default output encoding for Pod::Man is UTF\-8.  This
should work correctly on any modern system that uses either \fBgroff\fR (most
Linux distributions) or \fBmandoc\fR (Alpine Linux and most BSD variants,
including macOS).
.PP
The user will probably have to use a UTF\-8 locale to see correct output.  This
may be done by default; if not, set the LANG or LC_CTYPE environment variables
to an appropriate local.  The locale \f(CW\*(C`C.UTF\-8\*(C'\fR is available on most systems
if one wants correct output without changing the other things locales affect,
such as collation.
.PP
The backward-compatible output format used in Pod::Man versions before 5.00 is
available by setting the \f(CW\*(C`encoding\*(C'\fR option to \f(CW\*(C`roff\*(C'\fR.  This may produce
marginally nicer results on older UNIX versions that do not use \fBgroff\fR or
\&\fBmandoc\fR, but none of the available options will correctly render Unicode
characters on those systems.
.PP
Below are some additional details about how this choice was made and some
discussion of alternatives.
.SS History
.IX Subsection "History"
The default output encoding for Pod::Man has been a long-standing problem.
\&\fBtroff\fR and \fBnroff\fR predate Unicode by a significant margin, and their
implementations for many UNIX systems reflect that legacy.  It's common for
Unicode to not be supported in any form.
.PP
Because of this, versions of Pod::Man prior to 5.00 maintained the highly
conservative output of the original pod2man, which output pure ASCII with
complex macros to simulate common western European accented characters when
processed with troff.  The nroff output was awkward and sometimes incorrect,
and characters not used in western European scripts were replaced with \f(CW\*(C`X\*(C'\fR.
This choice maximized backwards compatibility with \fBman\fR and
\&\fBnroff\fR/\fBtroff\fR implementations at the cost of incorrect rendering of many
POD documents, particularly those containing people's names.
.PP
The modern implementations, \fBgroff\fR (used in most Linux distributions) and
\&\fBmandoc\fR (used by most BSD variants), do now support Unicode.  Other UNIX
systems often do not, but they're now a tiny minority of the systems people
use on a daily basis.  It's increasingly common (for very good reasons) to use
Unicode characters for POD documents rather than using ASCII conversions of
people's names or avoiding non-English text, making the limitations in the old
output format more apparent.
.PP
Four options have been proposed to fix this:
.IP \(bu 2
Optionally support UTF\-8 output but don't change the default.  This is the
approach taken since Pod::Man 2.1.0, which added the \f(CW\*(C`utf8\*(C'\fR option.  Some
Pod::Man users use this option for better output on platforms known to support
Unicode, but since the defaults have not changed, people continued to
encounter (and file bug reports about) the poor default rendering.
.IP \(bu 2
Convert characters to troff \f(CW\*(C`\e(xx\*(C'\fR escapes.  This requires maintaining a
large translation table and addresses only a tiny part of the problem, since
many Unicode characters have no standard troff name.  \fBgroff\fR has the largest
list, but if one is willing to assume \fBgroff\fR is the formatter, the next
option is better.
.IP \(bu 2
Convert characters to groff \f(CW\*(C`\e[uNNNN]\*(C'\fR escapes.  This is implemented as the
\&\f(CW\*(C`groff\*(C'\fR encoding for those who want to use it, and is supported by both
\&\fBgroff\fR and \fBmandoc\fR.  However, it is no better than UTF\-8 output for
portability to other implementations.  See "Testing results" for more
details.
.IP \(bu 2
Change the default output format to UTF\-8 and ask those who want maximum
backward compatibility to explicitly select the old encoding.  This fixes the
issue for most users at the cost of backwards compatibility.  While the
rendering of non-ASCII characters is different on older systems that don't
support UTF\-8, it's not always worse than the old output.
.PP
Pod::Man 5.00 and later makes the last choice.  This arguably produces worse
output when manual pages are formatted with \fBtroff\fR into PostScript or PDF,
but doing this is rare and normally manual, so the encoding can be changed in
those cases.  The older output encoding is available by setting \f(CW\*(C`encoding\*(C'\fR to
\&\f(CW\*(C`roff\*(C'\fR.
.SS "Testing results"
.IX Subsection "Testing results"
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
various operating systems.  The testing methodology was to create \fIman/man1\fR
in the current directory, copy \fIencoding.utf8\fR or \fIencoding.groff\fR from the
podlators 5.00 distribution to \fIman/man1/encoding.1\fR, and then run:
.PP
.Vb 1
\&    LANG=C.UTF\-8 MANPATH=$(pwd)/man man 1 encoding
.Ve
.PP
If the locale is not explicitly set to one that includes UTF\-8, the Unicode
characters were usually converted to ASCII (by, for example, dropping an
accent) or deleted or replaced with \f(CW\*(C`<?>\*(C'\fR if there was no conversion.
.PP
Tested on 2022\-09\-25.  Many thanks to the GCC Compile Farm project for access
to testing hosts.
.PP
.Vb 12
\&    OS                   UTF\-8      groff
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-    \-\-\-\-\-\-\-
\&    AIX 7.1              no [1]     no [2]
\&    Alpine 3.15.0        yes        yes
\&    CentOS 7.9           yes        yes
\&    Debian 7             yes        yes
\&    FreeBSD 13.0         yes        yes
\&    NetBSD 9.2           yes        yes
\&    OpenBSD 7.1          yes        yes
\&    openSUSE Leap 15.4   yes        yes
\&    Solaris 10           yes        no [2]
\&    Solaris 11           no [3]     no [3]
.Ve
.PP
I did not have access to a macOS system for testing, but since it uses
\&\fBmandoc\fR, it's behavior is probably the same as the BSD hosts.
.PP
Notes:
.IP [1] 4
.IX Item "[1]"
Unicode characters were converted to one or two random ASCII characters
unrelated to the original character.
.IP [2] 4
.IX Item "[2]"
Unicode characters were shown as the body of the groff escape rather than the
indicated character (in other words, text like \f(CW\*(C`[u00EF]\*(C'\fR).
.IP [3] 4
.IX Item "[3]"
Unicode characters were deleted entirely, as if they weren't there.  Using
\&\f(CW\*(C`nroff \-man\*(C'\fR instead of \fBman\fR to format the page showed the same results as
Solaris 10.  Using \f(CW\*(C`groff \-k \-man \-Tutf8\*(C'\fR to format the page produced the
correct output.
.PP
PostScript and PDF output using groff on a Debian 12 system do not support
combining accent marks or SMP characters due to a lack of support in the
default output font.
.PP
Testing on additional platforms is welcome.  Please let the author know if you
have additional results.
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
.IP "roff font should be 1 or 2 chars, not ""%s""" 4
.IX Item "roff font should be 1 or 2 chars, not ""%s"""
(F) You specified a *roff font (using \f(CW\*(C`fixed\*(C'\fR, \f(CW\*(C`fixedbold\*(C'\fR, etc.) that
wasn't either one or two characters.  Pod::Man doesn't support *roff fonts
longer than two characters, although some *roff extensions do (the
canonical versions of \fBnroff\fR and \fBtroff\fR don't either).
.IP "Invalid errors setting ""%s""" 4
.IX Item "Invalid errors setting ""%s"""
(F) The \f(CW\*(C`errors\*(C'\fR parameter to the constructor was set to an unknown value.
.IP "Invalid quote specification ""%s""" 4
.IX Item "Invalid quote specification ""%s"""
(F) The quote specification given (the \f(CW\*(C`quotes\*(C'\fR option to the
constructor) was invalid.  A quote specification must be either one
character long or an even number (greater than one) characters long.
.IP "POD document had syntax errors" 4
.IX Item "POD document had syntax errors"
(F) The POD document being formatted had syntax errors and the \f(CW\*(C`errors\*(C'\fR
option was set to \f(CW\*(C`die\*(C'\fR.
.SH ENVIRONMENT
.IX Header "ENVIRONMENT"
.IP PERL_CORE 4
.IX Item "PERL_CORE"
If set and Encode is not available, silently fall back to an encoding of
\&\f(CW\*(C`groff\*(C'\fR without complaining to standard error.  This environment variable is
set during Perl core builds, which build Encode after podlators.  Encode is
expected to not (yet) be available in that case.
.IP POD_MAN_DATE 4
.IX Item "POD_MAN_DATE"
If set, this will be used as the value of the left-hand footer unless the
\&\f(CW\*(C`date\*(C'\fR option is explicitly set, overriding the timestamp of the input
file or the current time.  This is primarily useful to ensure reproducible
builds of the same output file given the same source and Pod::Man version,
even when file timestamps may not be consistent.
.IP SOURCE_DATE_EPOCH 4
.IX Item "SOURCE_DATE_EPOCH"
If set, and POD_MAN_DATE and the \f(CW\*(C`date\*(C'\fR options are not set, this will be
used as the modification time of the source file, overriding the timestamp of
the input file or the current time.  It should be set to the desired time in
seconds since UNIX epoch.  This is primarily useful to ensure reproducible
builds of the same output file given the same source and Pod::Man version,
even when file timestamps may not be consistent.  See
<https://reproducible\-builds.org/specs/source\-date\-epoch/> for the full
specification.
.Sp
(Arguably, according to the specification, this variable should be used only
if the timestamp of the input file is not available and Pod::Man uses the
current time.  However, for reproducible builds in Debian, results were more
reliable if this variable overrode the timestamp of the input file.)
.SH COMPATIBILITY
.IX Header "COMPATIBILITY"
Pod::Man 1.02 (based on Pod::Parser) was the first version included with
Perl, in Perl 5.6.0.
.PP
The current API based on Pod::Simple was added in Pod::Man 2.00.  Pod::Man
2.04 was included in Perl 5.9.3, the first version of Perl to incorporate
those changes.  This is the first version that correctly supports all modern
POD syntax.  The \fBparse_from_filehandle()\fR method was re-added for backward
compatibility in Pod::Man 2.09, included in Perl 5.9.4.
.PP
Support for anchor text in L<> links of type URL was added in Pod::Man
2.23, included in Perl 5.11.5.
.PP
\&\fBparse_lines()\fR, \fBparse_string_document()\fR, and \fBparse_file()\fR set a default output
file handle of \f(CW\*(C`STDOUT\*(C'\fR if one was not already set as of Pod::Man 2.28,
included in Perl 5.19.5.
.PP
Support for SOURCE_DATE_EPOCH and POD_MAN_DATE was added in Pod::Man 4.00,
included in Perl 5.23.7, and generated dates were changed to use UTC instead
of the local time zone.  This is also the first release that aligned the
module version and the version of the podlators distribution.  All modules
included in podlators, and the podlators distribution itself, share the same
version number from this point forward.
.PP
Pod::Man 4.10, included in Perl 5.27.8, changed the formatting for manual page
references and function names to bold instead of italic, following the current
Linux manual page standard.
.PP
Pod::Man 5.00 changed the default output encoding to UTF\-8, overridable with
the new \f(CW\*(C`encoding\*(C'\fR option.  It also fixed problems with bold or italic
extending too far when used with C<> escapes, and began converting Unicode
zero-width spaces (U+200B) to the \f(CW\*(C`\e:\*(C'\fR *roff escape.  It also dropped
attempts to add subtle formatting corrections in the output that would only be
visible when typeset with \fBtroff\fR, which had previously been a significant
source of bugs.
.SH BUGS
.IX Header "BUGS"
There are numerous bugs and language-specific assumptions in the nroff
fallbacks for accented characters in the \f(CW\*(C`roff\*(C'\fR encoding.  Since the point of
this encoding is backward compatibility with the output from earlier versions
of Pod::Man, and it is deprecated except when necessary to support old
systems, those bugs are unlikely to ever be fixed.
.PP
Pod::Man doesn't handle font names longer than two characters.  Neither do
most \fBtroff\fR implementations, but groff does as an extension.  It would be
nice to support as an option for those who want to use it.
.SH CAVEATS
.IX Header "CAVEATS"
.SS "Sentence spacing"
.IX Subsection "Sentence spacing"
Pod::Man copies the input spacing verbatim to the output *roff document.  This
means your output will be affected by how \fBnroff\fR generally handles sentence
spacing.
.PP
\&\fBnroff\fR dates from an era in which it was standard to use two spaces after
sentences, and will always add two spaces after a line-ending period (or
similar punctuation) when reflowing text.  For example, the following input:
.PP
.Vb 1
\&    =pod
\&
\&    One sentence.
\&    Another sentence.
.Ve
.PP
will result in two spaces after the period when the text is reflowed.  If you
use two spaces after sentences anyway, this will be consistent, although you
will have to be careful to not end a line with an abbreviation such as \f(CW\*(C`e.g.\*(C'\fR
or \f(CW\*(C`Ms.\*(C'\fR.  Output will also be consistent if you use the *roff style guide
(and XKCD 1285 <https://xkcd.com/1285/>) recommendation of putting a line
break after each sentence, although that will consistently produce two spaces
after each sentence, which may not be what you want.
.PP
If you prefer one space after sentences (which is the more modern style), you
will unfortunately need to ensure that no line in the middle of a paragraph
ends in a period or similar sentence-ending paragraph.  Otherwise, \fBnroff\fR
will add a two spaces after that sentence when reflowing, and your output
document will have inconsistent spacing.
.SS Hyphens
.IX Subsection "Hyphens"
The handling of hyphens versus dashes is somewhat fragile, and one may get a
the wrong one under some circumstances.  This will normally only matter for
line breaking and possibly for troff output.
.SH AUTHOR
.IX Header "AUTHOR"
Written by Russ Allbery <rra@cpan.org>, based on the original \fBpod2man\fR by
Tom Christiansen <tchrist@mox.perl.com>.
.PP
The modifications to work with Pod::Simple instead of Pod::Parser were
contributed by Sean Burke <sburke@cpan.org>, but I've since hacked them beyond
recognition and all bugs are mine.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 1999\-2010, 2012\-2020, 2022 Russ Allbery <rra@cpan.org>
.PP
Substantial contributions by Sean Burke <sburke@cpan.org>.
.PP
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Encode::Supported, Pod::Simple, \fBperlpod\fR\|(1), \fBpod2man\fR\|(1),
\&\fBnroff\fR\|(1), \fBtroff\fR\|(1), \fBman\fR\|(1), \fBman\fR\|(7)
.PP
Ossanna, Joseph F., and Brian W. Kernighan.  "Troff User's Manual,"
Computing Science Technical Report No. 54, AT&T Bell Laboratories.  This is
the best documentation of standard \fBnroff\fR and \fBtroff\fR.  At the time of
this writing, it's available at <http://www.troff.org/54.pdf>.
.PP
The manual page documenting the man macro set may be \fBman\fR\|(5) instead of
\&\fBman\fR\|(7) on your system.
.PP
See \fBperlpodstyle\fR\|(1) for documentation on writing manual pages in POD if
you've not done it before and aren't familiar with the conventions.
.PP
The current version of this module is always available from its web site at
<https://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
Perl core distribution as of 5.6.0.