Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 175 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Encode::MIME::Header.3perl b/upstream/debian-unstable/man3/Encode::MIME::Header.3perl
new file mode 100644
index 00000000..43ca55da
--- /dev/null
+++ b/upstream/debian-unstable/man3/Encode::MIME::Header.3perl
@@ -0,0 +1,175 @@
+.\" -*- 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 "Encode::MIME::Header 3perl"
+.TH Encode::MIME::Header 3perl 2024-01-12 "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
+Encode::MIME::Header \-\- MIME encoding for an unstructured email header
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use Encode qw(encode decode);
+\&
+\&    my $mime_str = encode("MIME\-Header", "Sample:Text \eN{U+263A}");
+\&    # $mime_str is "=?UTF\-8?B?U2FtcGxlOlRleHQg4pi6?="
+\&
+\&    my $mime_q_str = encode("MIME\-Q", "Sample:Text \eN{U+263A}");
+\&    # $mime_q_str is "=?UTF\-8?Q?Sample=3AText_=E2=98=BA?="
+\&
+\&    my $str = decode("MIME\-Header",
+\&        "=?ISO\-8859\-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=\er\en " .
+\&        "=?ISO\-8859\-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?="
+\&    );
+\&    # $str is "If you can read this you understand the example."
+\&
+\&    use Encode qw(decode :fallbacks);
+\&    use Encode::MIME::Header;
+\&    local $Encode::MIME::Header::STRICT_DECODE = 1;
+\&    my $strict_string = decode("MIME\-Header", $mime_string, FB_CROAK);
+\&    # use strict decoding and croak on errors
+.Ve
+.SH ABSTRACT
+.IX Header "ABSTRACT"
+This module implements RFC 2047 <https://tools.ietf.org/html/rfc2047> MIME
+encoding for an unstructured field body of the email header.  It can also be
+used for RFC 822 <https://tools.ietf.org/html/rfc822> 'text' token.  However,
+it cannot be used directly for the whole header with the field name or for the
+structured header fields like From, To, Cc, Message-Id, etc...  There are 3
+encoding names supported by this module: \f(CW\*(C`MIME\-Header\*(C'\fR, \f(CW\*(C`MIME\-B\*(C'\fR and
+\&\f(CW\*(C`MIME\-Q\*(C'\fR.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Decode method takes an unstructured field body of the email header (or
+RFC 822 <https://tools.ietf.org/html/rfc822> 'text' token) as its input and
+decodes each MIME encoded-word from input string to a sequence of bytes
+according to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
+RFC 2231 <https://tools.ietf.org/html/rfc2231>.  Subsequently, each sequence
+of bytes with the corresponding MIME charset is decoded with
+the Encode module and finally, one output string is returned.  Text
+parts of the input string which do not contain MIME encoded-word stay
+unmodified in the output string.  Folded newlines between two consecutive MIME
+encoded-words are discarded, others are preserved in the output string.
+\&\f(CW\*(C`MIME\-B\*(C'\fR can decode Base64 variant, \f(CW\*(C`MIME\-Q\*(C'\fR can decode Quoted-Printable
+variant and \f(CW\*(C`MIME\-Header\*(C'\fR can decode both of them.  If Encode module
+does not support particular MIME charset or chosen variant then an action based
+on CHECK flags is performed (by default, the
+MIME encoded-word is not decoded).
+.PP
+Encode method takes a scalar string as its input and uses
+strict UTF\-8 encoder for encoding it to UTF\-8
+bytes.  Then a sequence of UTF\-8 bytes is encoded into MIME encoded-words
+(\f(CW\*(C`MIME\-Header\*(C'\fR and \f(CW\*(C`MIME\-B\*(C'\fR use a Base64 variant while \f(CW\*(C`MIME\-Q\*(C'\fR uses a
+Quoted-Printable variant) where each MIME encoded-word is limited to 75
+characters.  MIME encoded-words are separated by \f(CW\*(C`CRLF SPACE\*(C'\fR and joined to
+one output string.  Output string is suitable for unstructured field body of
+the email header.
+.PP
+Both encode and decode methods propagate
+CHECK flags when encoding and decoding the
+MIME charset.
+.SH BUGS
+.IX Header "BUGS"
+Versions prior to 2.22 (part of Encode 2.83) have a malfunctioning decoder
+and encoder.  The MIME encoder infamously inserted additional spaces or
+discarded white spaces between consecutive MIME encoded-words, which led to
+invalid MIME headers produced by this module.  The MIME decoder had a tendency
+to discard white spaces, incorrectly interpret data or attempt to decode Base64
+MIME encoded-words as Quoted-Printable.  These problems were fixed in version
+2.22.  It is highly recommended not to use any version prior 2.22!
+.PP
+Versions prior to 2.24 (part of Encode 2.87) ignored
+CHECK flags.  The MIME encoder used
+not strict utf8 encoder for input Unicode
+strings which could lead to invalid UTF\-8 sequences.  MIME decoder used also
+not strict utf8 decoder and additionally
+called the decode method with a \f(CW\*(C`Encode::FB_PERLQQ\*(C'\fR flag (thus user-specified
+CHECK flags were ignored).  Moreover, it
+automatically croaked when a MIME encoded-word contained unknown encoding.
+Since version 2.24, this module uses
+strict UTF\-8 encoder and decoder.  And
+CHECK flags are correctly propagated.
+.PP
+Since version 2.22 (part of Encode 2.83), the MIME encoder should be fully
+compliant to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
+RFC 2231 <https://tools.ietf.org/html/rfc2231>.  Due to the aforementioned
+bugs in previous versions of the MIME encoder, there is a \fIless strict\fR
+compatible mode for the MIME decoder which is used by default.  It should be
+able to decode MIME encoded-words encoded by pre 2.22 versions of this module.
+However, note that this is not correct according to
+RFC 2047 <https://tools.ietf.org/html/rfc2047>.
+.PP
+In default \fInot strict\fR mode the MIME decoder attempts to decode every substring
+which looks like a MIME encoded-word.  Therefore, the MIME encoded-words do not
+need to be separated by white space.  To enforce a correct \fIstrict\fR mode, set
+variable \f(CW$Encode::MIME::Header::STRICT_DECODE\fR to 1 e.g. by localizing:
+.PP
+.Vb 2
+\&  use Encode::MIME::Header;
+\&  local $Encode::MIME::Header::STRICT_DECODE = 1;
+.Ve
+.SH AUTHORS
+.IX Header "AUTHORS"
+Pali <pali@cpan.org>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Encode,
+RFC 822 <https://tools.ietf.org/html/rfc822>,
+RFC 2047 <https://tools.ietf.org/html/rfc2047>,
+RFC 2231 <https://tools.ietf.org/html/rfc2231>