Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 254 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/ExtUtils::MakeMaker::Locale.3perl b/upstream/archlinux/man3/ExtUtils::MakeMaker::Locale.3perl
new file mode 100644
index 00000000..5e435629
--- /dev/null
+++ b/upstream/archlinux/man3/ExtUtils::MakeMaker::Locale.3perl
@@ -0,0 +1,254 @@
+.\" -*- 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 "ExtUtils::MakeMaker::Locale 3perl"
+.TH ExtUtils::MakeMaker::Locale 3perl 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
+ExtUtils::MakeMaker::Locale \- bundled Encode::Locale
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&  use Encode::Locale;
+\&  use Encode;
+\&
+\&  $string = decode(locale => $bytes);
+\&  $bytes = encode(locale => $string);
+\&
+\&  if (\-t) {
+\&      binmode(STDIN, ":encoding(console_in)");
+\&      binmode(STDOUT, ":encoding(console_out)");
+\&      binmode(STDERR, ":encoding(console_out)");
+\&  }
+\&
+\&  # Processing file names passed in as arguments
+\&  my $uni_filename = decode(locale => $ARGV[0]);
+\&  open(my $fh, "<", encode(locale_fs => $uni_filename))
+\&     || die "Can\*(Aqt open \*(Aq$uni_filename\*(Aq: $!";
+\&  binmode($fh, ":encoding(locale)");
+\&  ...
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+In many applications it's wise to let Perl use Unicode for the strings it
+processes.  Most of the interfaces Perl has to the outside world are still byte
+based.  Programs therefore need to decode byte strings that enter the program
+from the outside and encode them again on the way out.
+.PP
+The POSIX locale system is used to specify both the language conventions
+requested by the user and the preferred character set to consume and
+output.  The \f(CW\*(C`Encode::Locale\*(C'\fR module looks up the charset and encoding (called
+a CODESET in the locale jargon) and arranges for the Encode module to know
+this encoding under the name "locale".  It means bytes obtained from the
+environment can be converted to Unicode strings by calling \f(CW\*(C`Encode::encode(locale => $bytes)\*(C'\fR and converted back again with \f(CW\*(C`Encode::decode(locale => $string)\*(C'\fR.
+.PP
+Where file systems interfaces pass file names in and out of the program we also
+need care.  The trend is for operating systems to use a fixed file encoding
+that don't actually depend on the locale; and this module determines the most
+appropriate encoding for file names. The Encode module will know this
+encoding under the name "locale_fs".  For traditional Unix systems this will
+be an alias to the same encoding as "locale".
+.PP
+For programs running in a terminal window (called a "Console" on some systems)
+the "locale" encoding is usually a good choice for what to expect as input and
+output.  Some systems allows us to query the encoding set for the terminal and
+\&\f(CW\*(C`Encode::Locale\*(C'\fR will do that if available and make these encodings known
+under the \f(CW\*(C`Encode\*(C'\fR aliases "console_in" and "console_out".  For systems where
+we can't determine the terminal encoding these will be aliased as the same
+encoding as "locale".  The advice is to use "console_in" for input known to
+come from the terminal and "console_out" for output to the terminal.
+.PP
+In addition to arranging for various Encode aliases the following functions and
+variables are provided:
+.IP "decode_argv( )" 4
+.IX Item "decode_argv( )"
+.PD 0
+.IP "decode_argv( Encode::FB_CROAK )" 4
+.IX Item "decode_argv( Encode::FB_CROAK )"
+.PD
+This will decode the command line arguments to perl (the \f(CW@ARGV\fR array) in-place.
+.Sp
+The function will by default replace characters that can't be decoded by
+"\ex{FFFD}", the Unicode replacement character.
+.Sp
+Any argument provided is passed as CHECK to underlying \fBEncode::decode()\fR call.
+Pass the value \f(CW\*(C`Encode::FB_CROAK\*(C'\fR to have the decoding croak if not all the
+command line arguments can be decoded.  See "Handling Malformed Data" in Encode
+for details on other options for CHECK.
+.ie n .IP "env( $uni_key )" 4
+.el .IP "env( \f(CW$uni_key\fR )" 4
+.IX Item "env( $uni_key )"
+.PD 0
+.ie n .IP "env( $uni_key => $uni_value )" 4
+.el .IP "env( \f(CW$uni_key\fR => \f(CW$uni_value\fR )" 4
+.IX Item "env( $uni_key => $uni_value )"
+.PD
+Interface to get/set environment variables.  Returns the current value as a
+Unicode string. The \f(CW$uni_key\fR and \f(CW$uni_value\fR arguments are expected to be
+Unicode strings as well.  Passing \f(CW\*(C`undef\*(C'\fR as \f(CW$uni_value\fR deletes the
+environment variable named \f(CW$uni_key\fR.
+.Sp
+The returned value will have the characters that can't be decoded replaced by
+"\ex{FFFD}", the Unicode replacement character.
+.Sp
+There is no interface to request alternative CHECK behavior as for
+\&\fBdecode_argv()\fR.  If you need that you need to call encode/decode yourself.
+For example:
+.Sp
+.Vb 2
+\&    my $key = Encode::encode(locale => $uni_key, Encode::FB_CROAK);
+\&    my $uni_value = Encode::decode(locale => $ENV{$key}, Encode::FB_CROAK);
+.Ve
+.IP "reinit( )" 4
+.IX Item "reinit( )"
+.PD 0
+.ie n .IP "reinit( $encoding )" 4
+.el .IP "reinit( \f(CW$encoding\fR )" 4
+.IX Item "reinit( $encoding )"
+.PD
+Reinitialize the encodings from the locale.  You want to call this function if
+you changed anything in the environment that might influence the locale.
+.Sp
+This function will croak if the determined encoding isn't recognized by
+the Encode module.
+.Sp
+With argument force \f(CW$ENCODING_\fR... variables to set to the given value.
+.ie n .IP $ENCODING_LOCALE 4
+.el .IP \f(CW$ENCODING_LOCALE\fR 4
+.IX Item "$ENCODING_LOCALE"
+The encoding name determined to be suitable for the current locale.
+Encode know this encoding as "locale".
+.ie n .IP $ENCODING_LOCALE_FS 4
+.el .IP \f(CW$ENCODING_LOCALE_FS\fR 4
+.IX Item "$ENCODING_LOCALE_FS"
+The encoding name determined to be suitable for file system interfaces
+involving file names.
+Encode know this encoding as "locale_fs".
+.ie n .IP $ENCODING_CONSOLE_IN 4
+.el .IP \f(CW$ENCODING_CONSOLE_IN\fR 4
+.IX Item "$ENCODING_CONSOLE_IN"
+.PD 0
+.ie n .IP $ENCODING_CONSOLE_OUT 4
+.el .IP \f(CW$ENCODING_CONSOLE_OUT\fR 4
+.IX Item "$ENCODING_CONSOLE_OUT"
+.PD
+The encodings to be used for reading and writing output to the a console.
+Encode know these encodings as "console_in" and "console_out".
+.SH NOTES
+.IX Header "NOTES"
+This table summarizes the mapping of the encodings set up
+by the \f(CW\*(C`Encode::Locale\*(C'\fR module:
+.PP
+.Vb 7
+\&  Encode      |         |              |
+\&  Alias       | Windows | Mac OS X     | POSIX
+\&  \-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
+\&  locale      | ANSI    | nl_langinfo  | nl_langinfo
+\&  locale_fs   | ANSI    | UTF\-8        | nl_langinfo
+\&  console_in  | OEM     | nl_langinfo  | nl_langinfo
+\&  console_out | OEM     | nl_langinfo  | nl_langinfo
+.Ve
+.SS Windows
+.IX Subsection "Windows"
+Windows has basically 2 sets of APIs.  A wide API (based on passing UTF\-16
+strings) and a byte based API based a character set called ANSI.  The
+regular Perl interfaces to the OS currently only uses the ANSI APIs.
+Unfortunately ANSI is not a single character set.
+.PP
+The encoding that corresponds to ANSI varies between different editions of
+Windows.  For many western editions of Windows ANSI corresponds to CP\-1252
+which is a character set similar to ISO\-8859\-1.  Conceptually the ANSI
+character set is a similar concept to the POSIX locale CODESET so this module
+figures out what the ANSI code page is and make this available as
+\&\f(CW$ENCODING_LOCALE\fR and the "locale" Encoding alias.
+.PP
+Windows systems also operate with another byte based character set.
+It's called the OEM code page.  This is the encoding that the Console
+takes as input and output.  It's common for the OEM code page to
+differ from the ANSI code page.
+.SS "Mac OS X"
+.IX Subsection "Mac OS X"
+On Mac OS X the file system encoding is always UTF\-8 while the locale
+can otherwise be set up as normal for POSIX systems.
+.PP
+File names on Mac OS X will at the OS-level be converted to
+NFD-form.  A file created by passing a NFC-filename will come
+in NFD-form from \fBreaddir()\fR.  See Unicode::Normalize for details
+of NFD/NFC.
+.PP
+Actually, Apple does not follow the Unicode NFD standard since not all
+character ranges are decomposed.  The claim is that this avoids problems with
+round trip conversions from old Mac text encodings.  See Encode::UTF8Mac for
+details.
+.SS "POSIX (Linux and other Unixes)"
+.IX Subsection "POSIX (Linux and other Unixes)"
+File systems might vary in what encoding is to be used for
+filenames.  Since this module has no way to actually figure out
+what the is correct it goes with the best guess which is to
+assume filenames are encoding according to the current locale.
+Users are advised to always specify UTF\-8 as the locale charset.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+I18N::Langinfo, Encode, Term::Encoding
+.SH AUTHOR
+.IX Header "AUTHOR"
+Copyright 2010 Gisle Aas <gisle@aas.no>.
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.