Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 419 insertions, 0 deletions

diff --git a/upstream/archlinux/man1/pod2man.1perl b/upstream/archlinux/man1/pod2man.1perl
new file mode 100644
index 00000000..44295289
--- /dev/null
+++ b/upstream/archlinux/man1/pod2man.1perl
@@ -0,0 +1,419 @@
+.\" -*- 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 "POD2MAN 1perl"
+.TH POD2MAN 1perl 2024-02-11 "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
+pod2man \- Convert POD data to formatted *roff input
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+pod2man [\fB\-\-center\fR=\fIstring\fR] [\fB\-\-date\fR=\fIstring\fR]
+    [\fB\-\-encoding\fR=\fIencoding\fR] [\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-fixed\fR=\fIfont\fR]
+    [\fB\-\-fixedbold\fR=\fIfont\fR] [\fB\-\-fixeditalic\fR=\fIfont\fR]
+    [\fB\-\-fixedbolditalic\fR=\fIfont\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]]
+    [\fB\-\-name\fR=\fIname\fR] [\fB\-\-nourls\fR] [\fB\-\-official\fR]
+    [\fB\-\-release\fR=\fIversion\fR] [\fB\-\-section\fR=\fImanext\fR]
+    [\fB\-\-quotes\fR=\fIquotes\fR] [\fB\-\-lquote\fR=\fIquote\fR] [\fB\-\-rquote\fR=\fIquote\fR]
+    [\fB\-\-stderr\fR] [\fB\-\-utf8\fR] [\fB\-\-verbose\fR] [\fIinput\fR [\fIoutput\fR] ...]
+.PP
+pod2man \fB\-\-help\fR
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+\&\fBpod2man\fR is a wrapper script around the Pod::Man module, using it to
+generate *roff input from POD source.  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).
+.PP
+By default (on non-EBCDIC systems), \fBpod2man\fR outputs UTF\-8 manual pages.
+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, use \f(CW\*(C`\-\-encoding=roff\*(C'\fR
+(the default in earlier Pod::Man versions).  See the \fB\-\-encoding\fR option and
+"ENCODING" in Pod::Man for more details.
+.PP
+\&\fIinput\fR is the file to read for POD source (the POD can be embedded in code).
+If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR.  \fIoutput\fR, if given, is the
+file to which to write the formatted output.  If \fIoutput\fR isn't given, the
+formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR.  Several POD files can be processed
+in the same \fBpod2man\fR invocation (saving module load and compile times) by
+providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line.
+.PP
+\&\fB\-\-section\fR, \fB\-\-release\fR, \fB\-\-center\fR, \fB\-\-date\fR, and \fB\-\-official\fR can be
+used to set the headers and footers to use.  If not given, Pod::Man will
+assume various defaults.  See below for details.
+.SH OPTIONS
+.IX Header "OPTIONS"
+Each option is annotated with the version of podlators in which that option
+was added with its current meaning.
+.IP "\fB\-c\fR \fIstring\fR, \fB\-\-center\fR=\fIstring\fR" 4
+.IX Item "-c string, --center=string"
+[1.00] Sets the centered page header for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR.  The
+default is \f(CW\*(C`User Contributed Perl Documentation\*(C'\fR, but also see \fB\-\-official\fR
+below.
+.IP "\fB\-d\fR \fIstring\fR, \fB\-\-date\fR=\fIstring\fR" 4
+.IX Item "-d string, --date=string"
+[4.00] Set the left-hand footer string for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR.  By
+default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH, the modification date
+of the input file, or the current date (if input comes from \f(CW\*(C`STDIN\*(C'\fR) will be
+used, and the date will be in UTC.  See "CLASS METHODS" in Pod::Man for more
+details.
+.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR" 4
+.IX Item "-e encoding, --encoding=encoding"
+[5.00] Specifies the encoding of the output.  \fIencoding\fR must be an encoding
+recognized by the Encode module (see Encode::Supported).  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 \fB\-\-errors\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 (see below), 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 \fIencoding\fR is set to the special value \f(CW\*(C`roff\*(C'\fR, \fBpod2man\fR 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 \fBpod2man\fR 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.  Its use is discouraged.
+.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 \fB\-\-errors\fR=\fIstyle\fR 4
+.IX Item "--errors=style"
+[2.5.0] Set the error handling style.  \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`die\*(C'\fR.
+.IP \fB\-\-fixed\fR=\fIfont\fR 4
+.IX Item "--fixed=font"
+[1.0] The fixed-width font to use for verbatim text and code.  Defaults to
+\&\f(CW\*(C`CW\*(C'\fR.  Some systems may want \f(CW\*(C`CR\*(C'\fR instead.  Only matters for \fBtroff\fR
+output.
+.IP \fB\-\-fixedbold\fR=\fIfont\fR 4
+.IX Item "--fixedbold=font"
+[1.0] Bold version of the fixed-width font.  Defaults to \f(CW\*(C`CB\*(C'\fR.  Only matters
+for \fBtroff\fR output.
+.IP \fB\-\-fixeditalic\fR=\fIfont\fR 4
+.IX Item "--fixeditalic=font"
+[1.0] 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 \fB\-\-fixedbolditalic\fR=\fIfont\fR 4
+.IX Item "--fixedbolditalic=font"
+[1.0] 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 \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4
+.IX Item "--guesswork=rule[,rule...]"
+[5.00] By default, \fBpod2man\fR 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 rule \f(CW\*(C`all\*(C'\fR enables all guesswork.  This is also the default for
+backward compatibility reasons.  The special rule \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 man 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 "\fB\-h\fR, \fB\-\-help\fR" 4
+.IX Item "-h, --help"
+[1.00] Print out usage information.
+.IP "\fB\-l\fR, \fB\-\-lax\fR" 4
+.IX Item "-l, --lax"
+[1.00] No longer used.  \fBpod2man\fR used to check its input for validity as a
+manual page, but this should now be done by \fBpodchecker\fR\|(1) instead.
+Accepted for backward compatibility; this option no longer does anything.
+.IP \fB\-\-language\fR=\fIlanguage\fR 4
+.IX Item "--language=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
+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 man page is installed
+into the normal man page directory, such as \fI/usr/share/man\fR.
+.Sp
+On many systems, this will be done automatically if the man page is installed
+into a language-specific man 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 \fB\-\-lquote\fR=\fIquote\fR 4
+.IX Item "--lquote=quote"
+.PD 0
+.IP \fB\-\-rquote\fR=\fIquote\fR 4
+.IX Item "--rquote=quote"
+.PD
+[4.08] Sets the quote marks used to surround C<> text.  \fB\-\-lquote\fR sets
+the left quote mark and \fB\-\-rquote\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 \fB\-\-quotes\fR option, which can be used to set both quotes at once.
+If both \fB\-\-quotes\fR and one of the other options is set, \fB\-\-lquote\fR or
+\&\fB\-\-rquote\fR overrides \fB\-\-quotes\fR.
+.IP "\fB\-n\fR \fIname\fR, \fB\-\-name\fR=\fIname\fR" 4
+.IX Item "-n name, --name=name"
+[4.08] Set the name of the manual page for the \f(CW\*(C`.TH\*(C'\fR macro to \fIname\fR.
+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
+Although one does not have to follow this convention, be aware that the
+convention for UNIX manual pages is for the title to be in all-uppercase, even
+if the command isn't.  (Perl modules traditionally use mixed case for the
+manual page title, however.)
+.Sp
+This option is probably not useful when converting multiple POD files at once.
+.Sp
+When converting POD source from standard input, the name will be set to
+\&\f(CW\*(C`STDIN\*(C'\fR if this option is not provided.  Providing this option is strongly
+recommended to set a meaningful manual page name.
+.IP \fB\-\-nourls\fR 4
+.IX Item "--nourls"
+[2.5.0] 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 flag, if given, 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 "\fB\-o\fR, \fB\-\-official\fR" 4
+.IX Item "-o, --official"
+[1.00] Set the default header to indicate that this page is part of the
+standard Perl release, if \fB\-\-center\fR is not also given.
+.IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4
+.IX Item "-q quotes, --quotes=quotes"
+[4.00] Sets the quote marks used to surround C<> text to \fIquotes\fR.  If
+\&\fIquotes\fR 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
+\&\fIquotes\fR 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 \fB\-\-lquote\fR and \fB\-\-rquote\fR options, which can be used to set the
+left and right quotes independently.  If both \fB\-\-quotes\fR and one of the other
+options is set, \fB\-\-lquote\fR or \fB\-\-rquote\fR overrides \fB\-\-quotes\fR.
+.IP "\fB\-r\fR \fIversion\fR, \fB\-\-release\fR=\fIversion\fR" 4
+.IX Item "-r version, --release=version"
+[1.00] Set the centered footer for the \f(CW\*(C`.TH\*(C'\fR macro to \fIversion\fR.  By
+default, this is set to the version of Perl you run \fBpod2man\fR 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 \fB\-\-release\fR to
+the last modified date and \fB\-\-date\fR to the version number.
+.IP "\fB\-s\fR \fIstring\fR, \fB\-\-section\fR=\fIstring\fR" 4
+.IX Item "-s string, --section=string"
+[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 \fB\-\-stderr\fR 4
+.IX Item "--stderr"
+[2.1.3] By default, \fBpod2man\fR dies if any errors are detected in the POD
+input.  If \fB\-\-stderr\fR is given and no \fB\-\-errors\fR flag is present, errors are
+sent to standard error, but \fBpod2man\fR does not abort.  This is equivalent to
+\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility.
+.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4
+.IX Item "-u, --utf8"
+[2.1.0] This option used to tell \fBpod2man\fR to produce UTF\-8 output.  Since
+this is now the default as of version 5.00, it is ignored and does nothing.
+.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
+.IX Item "-v, --verbose"
+[1.11] Print out the name of each output file as it is being generated.
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+As long as all documents processed result in some output, even if that output
+includes errata (a \f(CW\*(C`POD ERRORS\*(C'\fR section generated with \f(CW\*(C`\-\-errors=pod\*(C'\fR),
+\&\fBpod2man\fR will exit with status 0.  If any of the documents being processed
+do not result in an output document, \fBpod2man\fR will exit with status 1.  If
+there are syntax errors in a POD document being processed and the error
+handling style is set to the default of \f(CW\*(C`die\*(C'\fR, \fBpod2man\fR will abort
+immediately with exit status 255.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+If \fBpod2man\fR fails with errors, see Pod::Man and Pod::Simple for
+information about what those errors might mean.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.Vb 3
+\&    pod2man program > program.1
+\&    pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
+\&    pod2man \-\-section=7 note.pod > note.7
+.Ve
+.PP
+If you would like to print out a lot of man page continuously, you probably
+want to set the C and D registers to set contiguous page numbering and
+even/odd paging, at least on some versions of \fBman\fR\|(7).
+.PP
+.Vb 1
+\&    troff \-man \-rC1 \-rD1 perl.1 perldata.1 perlsyn.1 ...
+.Ve
+.PP
+To get index entries on \f(CW\*(C`STDERR\*(C'\fR, turn on the F register, as in:
+.PP
+.Vb 1
+\&    troff \-man \-rF1 perl.1
+.Ve
+.PP
+The indexing merely outputs messages via \f(CW\*(C`.tm\*(C'\fR for each major page, section,
+subsection, item, and any \f(CW\*(C`X<>\*(C'\fR directives.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Russ Allbery <rra@cpan.org>, based on the original \fBpod2man\fR by Larry Wall
+and Tom Christiansen.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 1999\-2001, 2004, 2006, 2008, 2010, 2012\-2019, 2022 Russ Allbery
+<rra@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"
+Pod::Man, Pod::Simple, \fBman\fR\|(1), \fBnroff\fR\|(1), \fBperlpod\fR\|(1),
+\&\fBpodchecker\fR\|(1), \fBperlpodstyle\fR\|(1), \fBtroff\fR\|(1), \fBman\fR\|(7)
+.PP
+The man page documenting the an macro set may be \fBman\fR\|(5) instead of
+\&\fBman\fR\|(7) on your system.
+.PP
+The current version of this script 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.