Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 428 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Pod::Text.3perl b/upstream/debian-unstable/man3/Pod::Text.3perl
new file mode 100644
index 00000000..9606b101
--- /dev/null
+++ b/upstream/debian-unstable/man3/Pod::Text.3perl
@@ -0,0 +1,428 @@
+.\" -*- 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::Text 3perl"
+.TH Pod::Text 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
+Pod::Text \- Convert POD data to formatted text
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 2
+\&    use Pod::Text;
+\&    my $parser = Pod::Text\->new (sentence => 1, width => 78);
+\&
+\&    # Read POD from STDIN and write to STDOUT.
+\&    $parser\->parse_from_filehandle;
+\&
+\&    # Read POD from file.pod and write to file.txt.
+\&    $parser\->parse_from_file (\*(Aqfile.pod\*(Aq, \*(Aqfile.txt\*(Aq);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Pod::Text is a module that can convert documentation in the POD format (the
+preferred language for documenting Perl) into formatted text.  It uses no
+special formatting controls or codes, and its output is therefore suitable for
+nearly any device.
+.SS Encoding
+.IX Subsection "Encoding"
+Pod::Text uses the following logic to choose an output encoding, in order:
+.IP 1. 4
+If a PerlIO encoding layer is set on the output file handle, do not do any
+output encoding and will instead rely on the PerlIO encoding layer.
+.IP 2. 4
+If the \f(CW\*(C`encoding\*(C'\fR or \f(CW\*(C`utf8\*(C'\fR options are set, use the output encoding
+specified by those options.
+.IP 3. 4
+If the input encoding of the POD source file was explicitly specified (using
+\&\f(CW\*(C`=encoding\*(C'\fR) or automatically detected by Pod::Simple, use that as the output
+encoding as well.
+.IP 4. 4
+Otherwise, if running on a non-EBCDIC system, use UTF\-8 as the output
+encoding.  Since this is a superset of ASCII, this will result in ASCII output
+unless the POD input contains non-ASCII characters without declaring or
+autodetecting an encoding (usually via E<> escapes).
+.IP 5. 4
+Otherwise, for EBCDIC systems, output without doing any encoding and hope
+this works.
+.PP
+One caveat: Pod::Text has to commit to an output encoding the first time it
+outputs a non-ASCII character, and then has to stick with it for consistency.
+However, \f(CW\*(C`=encoding\*(C'\fR commands don't have to be at the beginning of a POD
+document.  If someone uses a non-ASCII character early in a document with an
+escape, such as E<0xEF>, and then puts \f(CW\*(C`=encoding iso\-8859\-1\*(C'\fR later,
+ideally Pod::Text would follow rule 3 and output the entire document as ISO
+8859\-1.  Instead, it will commit to UTF\-8 following rule 4 as soon as it sees
+that escape, and then stick with that encoding for the rest of the document.
+.PP
+Unfortunately, there's no universally good choice for an output encoding.
+Each choice will be incorrect in some circumstances.  This approach was chosen
+primarily for backwards compatibility.  Callers should consider forcing the
+output encoding via \f(CW\*(C`encoding\*(C'\fR if they have any knowledge about what encoding
+the user may expect.
+.PP
+In particular, consider importing the Encode::Locale module, if available,
+and setting \f(CW\*(C`encoding\*(C'\fR to \f(CW\*(C`locale\*(C'\fR to use an output encoding appropriate to
+the user's locale.  But be aware that if the user is not using locales or is
+using a locale of \f(CW\*(C`C\*(C'\fR, Encode::Locale will set the output encoding to
+US-ASCII.  This will cause all non-ASCII characters will be replaced with \f(CW\*(C`?\*(C'\fR
+and produce a flurry of warnings about unsupported characters, which may or
+may not be what you want.
+.SH "CLASS METHODS"
+.IX Header "CLASS METHODS"
+.IP new(ARGS) 4
+.IX Item "new(ARGS)"
+Create a new Pod::Text 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::Text in which that option was added with its current
+meaning.
+.RS 4
+.IP alt 4
+.IX Item "alt"
+[2.00] If set to a true value, selects an alternate output format that, among
+other things, uses a different heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a
+colon in the left margin.  Defaults to false.
+.IP code 4
+.IX Item "code"
+[2.13] If set to a true value, the non-POD parts of the input file will be
+included in the output.  Useful for viewing code documented with POD blocks
+with the POD rendered and the code left intact.
+.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).  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 output file handle has a PerlIO encoding layer set, this parameter 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, as near to the top of
+the file as possible.  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"
+[3.17] 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 guesswork 4
+.IX Item "guesswork"
+[5.01] By default, Pod::Text 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 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.
+.RE
+.RS 4
+.Sp
+Any unknown guesswork name is silently ignored (for potential future
+compatibility), so be careful about spelling.
+.RE
+.IP indent 4
+.IX Item "indent"
+[2.00] The number of spaces to indent regular text, and the default
+indentation for \f(CW\*(C`=over\*(C'\fR blocks.  Defaults to 4.
+.IP loose 4
+.IX Item "loose"
+[2.00] If set to a true value, a blank line is printed after a \f(CW\*(C`=head1\*(C'\fR
+heading.  If set to false (the default), no blank line is printed after
+\&\f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR.  This is the default
+because it's the expected formatting for manual pages; if you're formatting
+arbitrary text documents, setting this to true may result in more pleasing
+output.
+.IP margin 4
+.IX Item "margin"
+[2.21] The width of the left margin in spaces.  Defaults to 0.  This is the
+margin for all text, including headings, not the amount by which regular text
+is indented; for the latter, see the \fIindent\fR option.  To set the right
+margin, see the \fIwidth\fR option.
+.IP nourls 4
+.IX Item "nourls"
+[3.17] 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.
+.IP sentence 4
+.IX Item "sentence"
+[3.00] If set to a true value, Pod::Text will assume that each sentence ends
+in two spaces, and will try to preserve that spacing.  If set to false, all
+consecutive whitespace in non-verbatim paragraphs is compressed into a single
+space.  Defaults to false.
+.IP stderr 4
+.IX Item "stderr"
+[3.10] Send error messages about invalid POD to standard error instead of
+appending a POD ERRORS section to the generated 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.  It is
+supported for backward compatibility.
+.IP utf8 4
+.IX Item "utf8"
+[3.12] If this option is set to a true value, the output encoding is set to
+UTF\-8.  This is equivalent to setting \f(CW\*(C`encoding\*(C'\fR to \f(CW\*(C`UTF\-8\*(C'\fR if \f(CW\*(C`encoding\*(C'\fR
+is not already set.  It is supported for backward compatibility.
+.IP width 4
+.IX Item "width"
+[2.00] The column at which to wrap text on the right-hand side.  Defaults to
+76.
+.RE
+.RS 4
+.RE
+.SH "INSTANCE METHODS"
+.IX Header "INSTANCE METHODS"
+As a derived class from Pod::Simple, Pod::Text 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::Text.
+.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 (see
+"Encoding").
+.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 FUNCTIONS
+.IX Header "FUNCTIONS"
+Pod::Text exports one function for backward compatibility with older versions.
+This function is deprecated; instead, use the object-oriented interface
+described above.
+.IP "pod2text([[\-a,] [\-NNN,]] INPUT[, OUTPUT])" 4
+.IX Item "pod2text([[-a,] [-NNN,]] INPUT[, OUTPUT])"
+Convert the POD source from INPUT to text and write it to OUTPUT.  If OUTPUT
+is not given, defaults to \f(CW\*(C`STDOUT\*(C'\fR.  INPUT can be any expression supported as
+the second argument to two-argument \fBopen()\fR.
+.Sp
+If \f(CW\*(C`\-a\*(C'\fR is given as an initial argument, pass the \f(CW\*(C`alt\*(C'\fR option to the
+Pod::Text constructor.  This enables alternative formatting.
+.Sp
+If \f(CW\*(C`\-NNN\*(C'\fR is given as an initial argument, pass the \f(CW\*(C`width\*(C'\fR option to the
+Pod::Text constructor with the number \f(CW\*(C`NNN\*(C'\fR as its argument.  This sets the
+wrap line width to NNN.
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+.IP "Bizarre space in item" 4
+.IX Item "Bizarre space in item"
+.PD 0
+.IP "Item called without tag" 4
+.IX Item "Item called without tag"
+.PD
+(W) Something has gone wrong in internal \f(CW\*(C`=item\*(C'\fR processing.  These
+messages indicate a bug in Pod::Text; you should never see them.
+.ie n .IP "Can't open %s for reading: %s" 4
+.el .IP "Can't open \f(CW%s\fR for reading: \f(CW%s\fR" 4
+.IX Item "Can't open %s for reading: %s"
+(F) Pod::Text was invoked via the compatibility mode \fBpod2text()\fR interface
+and the input file it was given could not be opened.
+.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 COMPATIBILITY
+.IX Header "COMPATIBILITY"
+Pod::Text 2.03 (based on Pod::Parser) was the first version of this module
+included with Perl, in Perl 5.6.0.  Earlier versions of Perl had a different
+Pod::Text module, with a different API.
+.PP
+The current API based on Pod::Simple was added in Pod::Text 3.00.
+Pod::Text 3.01 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::Text 3.07, included in Perl 5.9.4.
+.PP
+Pod::Text 3.12, included in Perl 5.10.1, first implemented the current
+practice of attempting to match the default output encoding with the input
+encoding of the POD source, unless overridden by the \f(CW\*(C`utf8\*(C'\fR option or (added
+later) the \f(CW\*(C`encoding\*(C'\fR option.
+.PP
+Support for anchor text in L<> links of type URL was added in Pod::Text
+3.14, 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::Text 3.18,
+included in Perl 5.19.5.
+.PP
+Pod::Text 4.00, included in Perl 5.23.7, 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::Text 4.09, included in Perl 5.25.7, fixed a serious bug on EBCDIC
+systems, present in all versions back to 3.00, that would cause opening
+brackets to disappear.
+.PP
+Pod::Text 5.00 now defaults, on non-EBCDIC systems, to UTF\-8 encoding if it
+sees a non-ASCII character in the input and the input encoding is not
+specified.  It also commits to an encoding with the first non-ASCII character
+and does not change the output encoding if the input encoding changes.  The
+Encode module is now used for all output encoding rather than PerlIO
+layers, which fixes earlier problems with output to scalars.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Russ Allbery <rra@cpan.org>, based \fIvery\fR heavily on the original Pod::Text
+by Tom Christiansen <tchrist@mox.perl.com> and its conversion to Pod::Parser
+by Brad Appleton <bradapp@enteract.com>.  Sean Burke's initial conversion of
+Pod::Man to use Pod::Simple provided much-needed guidance on how to use
+Pod::Simple.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 1999\-2002, 2004, 2006, 2008\-2009, 2012\-2016, 2018\-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"
+Encode::Locale, Encode::Supproted, Pod::Simple,
+Pod::Text::Termcap, \fBperlpod\fR\|(1), \fBpod2text\fR\|(1)
+.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.