Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 514 insertions, 0 deletions

diff --git a/upstream/archlinux/man1/perlform.1perl b/upstream/archlinux/man1/perlform.1perl
new file mode 100644
index 00000000..4f2bcaad
--- /dev/null
+++ b/upstream/archlinux/man1/perlform.1perl
@@ -0,0 +1,514 @@
+.\" -*- 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 "PERLFORM 1perl"
+.TH PERLFORM 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
+perlform \- Perl formats
+.IX Xref "format report chart"
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Perl has a mechanism to help you generate simple reports and charts.  To
+facilitate this, Perl helps you code up your output page close to how it
+will look when it's printed.  It can keep track of things like how many
+lines are on a page, what page you're on, when to print page headers,
+etc.  Keywords are borrowed from FORTRAN: \fBformat()\fR to declare and \fBwrite()\fR
+to execute; see their entries in perlfunc.  Fortunately, the layout is
+much more legible, more like BASIC's PRINT USING statement.  Think of it
+as a poor man's \fBnroff\fR\|(1).
+.IX Xref "nroff"
+.PP
+Formats, like packages and subroutines, are declared rather than
+executed, so they may occur at any point in your program.  (Usually it's
+best to keep them all together though.) They have their own namespace
+apart from all the other "types" in Perl.  This means that if you have a
+function named "Foo", it is not the same thing as having a format named
+"Foo".  However, the default name for the format associated with a given
+filehandle is the same as the name of the filehandle.  Thus, the default
+format for STDOUT is named "STDOUT", and the default format for filehandle
+TEMP is named "TEMP".  They just look the same.  They aren't.
+.PP
+Output record formats are declared as follows:
+.PP
+.Vb 3
+\&    format NAME =
+\&    FORMLIST
+\&    .
+.Ve
+.PP
+If the name is omitted, format "STDOUT" is defined. A single "." in 
+column 1 is used to terminate a format.  FORMLIST consists of a sequence 
+of lines, each of which may be one of three types:
+.IP 1. 4
+A comment, indicated by putting a '#' in the first column.
+.IP 2. 4
+A "picture" line giving the format for one output line.
+.IP 3. 4
+An argument line supplying values to plug into the previous picture line.
+.PP
+Picture lines contain output field definitions, intermingled with
+literal text. These lines do not undergo any kind of variable interpolation.
+Field definitions are made up from a set of characters, for starting and
+extending a field to its desired width. This is the complete set of
+characters for field definitions:
+.IX Xref "format, picture line @ ^ < | > # 0 . ... @* ^* ~ ~~"
+.PP
+.Vb 10
+\&   @    start of regular field
+\&   ^    start of special field
+\&   <    pad character for left justification
+\&   |    pad character for centering
+\&   >    pad character for right justification
+\&   #    pad character for a right\-justified numeric field
+\&   0    instead of first #: pad number with leading zeroes
+\&   .    decimal point within a numeric field
+\&   ...  terminate a text field, show "..." as truncation evidence
+\&   @*   variable width field for a multi\-line value
+\&   ^*   variable width field for next line of a multi\-line value
+\&   ~    suppress line with all fields empty
+\&   ~~   repeat line until all fields are exhausted
+.Ve
+.PP
+Each field in a picture line starts with either "@" (at) or "^" (caret),
+indicating what we'll call, respectively, a "regular" or "special" field.
+The choice of pad characters determines whether a field is textual or
+numeric. The tilde operators are not part of a field.  Let's look at
+the various possibilities in detail.
+.SS "Text Fields"
+.IX Xref "format, text field"
+.IX Subsection "Text Fields"
+The length of the field is supplied by padding out the field with multiple 
+"<", ">", or "|" characters to specify a non-numeric field with,
+respectively, left justification, right justification, or centering. 
+For a regular field, the value (up to the first newline) is taken and
+printed according to the selected justification, truncating excess characters.
+If you terminate a text field with "...", three dots will be shown if
+the value is truncated. A special text field may be used to do rudimentary 
+multi-line text block filling; see "Using Fill Mode" for details.
+.PP
+.Vb 7
+\&   Example:
+\&      format STDOUT =
+\&      @<<<<<<   @||||||   @>>>>>>
+\&      "left",   "middle", "right"
+\&      .
+\&   Output:
+\&      left      middle    right
+.Ve
+.SS "Numeric Fields"
+.IX Xref "# format, numeric field"
+.IX Subsection "Numeric Fields"
+Using "#" as a padding character specifies a numeric field, with
+right justification. An optional "." defines the position of the
+decimal point. With a "0" (zero) instead of the first "#", the
+formatted number will be padded with leading zeroes if necessary.
+A special numeric field is blanked out if the value is undefined.
+If the resulting value would exceed the width specified the field is
+filled with "#" as overflow evidence.
+.PP
+.Vb 7
+\&   Example:
+\&      format STDOUT =
+\&      @###   @.###   @##.###  @###   @###   ^####
+\&       42,   3.1415,  undef,    0, 10000,   undef
+\&      .
+\&   Output:
+\&        42   3.142     0.000     0   ####
+.Ve
+.SS "The Field @* for Variable-Width Multi-Line Text"
+.IX Xref "@*"
+.IX Subsection "The Field @* for Variable-Width Multi-Line Text"
+The field "@*" can be used for printing multi-line, nontruncated
+values; it should (but need not) appear by itself on a line. A final
+line feed is chomped off, but all other characters are emitted verbatim.
+.SS "The Field ^* for Variable-Width One-line-at-a-time Text"
+.IX Xref "^*"
+.IX Subsection "The Field ^* for Variable-Width One-line-at-a-time Text"
+Like "@*", this is a variable-width field. The value supplied must be a 
+scalar variable. Perl puts the first line (up to the first "\en") of the 
+text into the field, and then chops off the front of the string so that 
+the next time the variable is referenced, more of the text can be printed. 
+The variable will \fInot\fR be restored.
+.PP
+.Vb 12
+\&   Example:
+\&      $text = "line 1\enline 2\enline 3";
+\&      format STDOUT =
+\&      Text: ^*
+\&            $text
+\&      ~~    ^*
+\&            $text
+\&      .
+\&   Output:
+\&      Text: line 1
+\&            line 2
+\&            line 3
+.Ve
+.SS "Specifying Values"
+.IX Xref "format, specifying values"
+.IX Subsection "Specifying Values"
+The values are specified on the following format line in the same order as
+the picture fields.  The expressions providing the values must be
+separated by commas.  They are all evaluated in a list context
+before the line is processed, so a single list expression could produce
+multiple list elements.  The expressions may be spread out to more than
+one line if enclosed in braces.  If so, the opening brace must be the first
+token on the first line.  If an expression evaluates to a number with a
+decimal part, and if the corresponding picture specifies that the decimal
+part should appear in the output (that is, any picture except multiple "#"
+characters \fBwithout\fR an embedded "."), the character used for the decimal
+point is determined by the current LC_NUMERIC locale if \f(CW\*(C`use locale\*(C'\fR is in
+effect.  This means that, if, for example, the run-time environment happens
+to specify a German locale, "," will be used instead of the default ".".  See
+perllocale and "WARNINGS" for more information.
+.SS "Using Fill Mode"
+.IX Xref "format, fill mode"
+.IX Subsection "Using Fill Mode"
+On text fields the caret enables a kind of fill mode.  Instead of an
+arbitrary expression, the value supplied must be a scalar variable
+that contains a text string.  Perl puts the next portion of the text into
+the field, and then chops off the front of the string so that the next time
+the variable is referenced, more of the text can be printed.  (Yes, this
+means that the variable itself is altered during execution of the \fBwrite()\fR
+call, and is not restored.)  The next portion of text is determined by
+a crude line-breaking algorithm. You may use the carriage return character
+(\f(CW\*(C`\er\*(C'\fR) to force a line break. You can change which characters are legal 
+to break on by changing the variable \f(CW$:\fR (that's 
+\&\f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR if you're using the English module) to a 
+list of the desired characters.
+.PP
+Normally you would use a sequence of fields in a vertical stack associated 
+with the same scalar variable to print out a block of text. You might wish 
+to end the final field with the text "...", which will appear in the output 
+if the text was too long to appear in its entirety.
+.SS "Suppressing Lines Where All Fields Are Void"
+.IX Xref "format, suppressing lines"
+.IX Subsection "Suppressing Lines Where All Fields Are Void"
+Using caret fields can produce lines where all fields are blank. You can
+suppress such lines by putting a "~" (tilde) character anywhere in the
+line.  The tilde will be translated to a space upon output.
+.SS "Repeating Format Lines"
+.IX Xref "format, repeating lines"
+.IX Subsection "Repeating Format Lines"
+If you put two contiguous tilde characters "~~" anywhere into a line,
+the line will be repeated until all the fields on the line are exhausted,
+i.e. undefined. For special (caret) text fields this will occur sooner or
+later, but if you use a text field of the at variety, the  expression you
+supply had better not give the same value every time forever! (\f(CWshift(@f)\fR
+is a simple example that would work.)  Don't use a regular (at) numeric 
+field in such lines, because it will never go blank.
+.SS "Top of Form Processing"
+.IX Xref "format, top of form top header"
+.IX Subsection "Top of Form Processing"
+Top-of-form processing is by default handled by a format with the
+same name as the current filehandle with "_TOP" concatenated to it.
+It's triggered at the top of each page.  See "write" in perlfunc.
+.PP
+Examples:
+.PP
+.Vb 10
+\& # a report on the /etc/passwd file
+\& format STDOUT_TOP =
+\&                         Passwd File
+\& Name                Login    Office   Uid   Gid Home
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& .
+\& format STDOUT =
+\& @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
+\& $name,              $login,  $office,$uid,$gid, $home
+\& .
+\&
+\&
+\& # a report from a bug report form
+\& format STDOUT_TOP =
+\&                         Bug Reports
+\& @<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>
+\& $system,                      $%,         $date
+\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& .
+\& format STDOUT =
+\& Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&          $subject
+\& Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&        $index,                       $description
+\& Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&           $priority,        $date,   $description
+\& From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&       $from,                         $description
+\& Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&              $programmer,            $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\&                                      $description
+\& ~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...
+\&                                      $description
+\& .
+.Ve
+.PP
+It is possible to intermix \fBprint()\fRs with \fBwrite()\fRs on the same output
+channel, but you'll have to handle \f(CW\*(C`$\-\*(C'\fR (\f(CW$FORMAT_LINES_LEFT\fR)
+yourself.
+.SS "Format Variables"
+.IX Xref "format variables format, variables"
+.IX Subsection "Format Variables"
+The current format name is stored in the variable \f(CW$~\fR (\f(CW$FORMAT_NAME\fR),
+and the current top of form format name is in \f(CW$^\fR (\f(CW$FORMAT_TOP_NAME\fR).
+The current output page number is stored in \f(CW$%\fR (\f(CW$FORMAT_PAGE_NUMBER\fR),
+and the number of lines on the page is in \f(CW$=\fR (\f(CW$FORMAT_LINES_PER_PAGE\fR).
+Whether to autoflush output on this handle is stored in \f(CW$|\fR
+(\f(CW$OUTPUT_AUTOFLUSH\fR).  The string output before each top of page (except
+the first) is stored in \f(CW$^L\fR (\f(CW$FORMAT_FORMFEED\fR).  These variables are
+set on a per-filehandle basis, so you'll need to \fBselect()\fR into a different
+one to affect them:
+.PP
+.Vb 4
+\&    select((select(OUTF),
+\&            $~ = "My_Other_Format",
+\&            $^ = "My_Top_Format"
+\&           )[0]);
+.Ve
+.PP
+Pretty ugly, eh?  It's a common idiom though, so don't be too surprised
+when you see it.  You can at least use a temporary variable to hold
+the previous filehandle: (this is a much better approach in general,
+because not only does legibility improve, you now have an intermediary
+stage in the expression to single-step the debugger through):
+.PP
+.Vb 4
+\&    $ofh = select(OUTF);
+\&    $~ = "My_Other_Format";
+\&    $^ = "My_Top_Format";
+\&    select($ofh);
+.Ve
+.PP
+If you use the English module, you can even read the variable names:
+.PP
+.Vb 5
+\&    use English;
+\&    $ofh = select(OUTF);
+\&    $FORMAT_NAME     = "My_Other_Format";
+\&    $FORMAT_TOP_NAME = "My_Top_Format";
+\&    select($ofh);
+.Ve
+.PP
+But you still have those funny \fBselect()\fRs.  So just use the FileHandle
+module.  Now, you can access these special variables using lowercase
+method names instead:
+.PP
+.Vb 3
+\&    use FileHandle;
+\&    format_name     OUTF "My_Other_Format";
+\&    format_top_name OUTF "My_Top_Format";
+.Ve
+.PP
+Much better!
+.SH NOTES
+.IX Header "NOTES"
+Because the values line may contain arbitrary expressions (for at fields,
+not caret fields), you can farm out more sophisticated processing
+to other functions, like \fBsprintf()\fR or one of your own.  For example:
+.PP
+.Vb 4
+\&    format Ident =
+\&        @<<<<<<<<<<<<<<<
+\&        &commify($n)
+\&    .
+.Ve
+.PP
+To get a real at or caret into the field, do this:
+.PP
+.Vb 4
+\&    format Ident =
+\&    I have an @ here.
+\&            "@"
+\&    .
+.Ve
+.PP
+To center a whole line of text, do something like this:
+.PP
+.Vb 4
+\&    format Ident =
+\&    @|||||||||||||||||||||||||||||||||||||||||||||||
+\&            "Some text line"
+\&    .
+.Ve
+.PP
+There is no builtin way to say "float this to the right hand side
+of the page, however wide it is."  You have to specify where it goes.
+The truly desperate can generate their own format on the fly, based
+on the current number of columns, and then \fBeval()\fR it:
+.PP
+.Vb 9
+\&    $format  = "format STDOUT = \en"
+\&             . \*(Aq^\*(Aq . \*(Aq<\*(Aq x $cols . "\en"
+\&             . \*(Aq$entry\*(Aq . "\en"
+\&             . "\et^" . "<" x ($cols\-8) . "~~\en"
+\&             . \*(Aq$entry\*(Aq . "\en"
+\&             . ".\en";
+\&    print $format if $Debugging;
+\&    eval $format;
+\&    die $@ if $@;
+.Ve
+.PP
+Which would generate a format looking something like this:
+.PP
+.Vb 6
+\& format STDOUT =
+\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+\& $entry
+\&         ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
+\& $entry
+\& .
+.Ve
+.PP
+Here's a little program that's somewhat like \fBfmt\fR\|(1):
+.PP
+.Vb 3
+\& format =
+\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
+\& $_
+\&
+\& .
+\&
+\& $/ = \*(Aq\*(Aq;
+\& while (<>) {
+\&     s/\es*\en\es*/ /g;
+\&     write;
+\& }
+.Ve
+.SS Footers
+.IX Xref "format, footer footer"
+.IX Subsection "Footers"
+While \f(CW$FORMAT_TOP_NAME\fR contains the name of the current header format,
+there is no corresponding mechanism to automatically do the same thing
+for a footer.  Not knowing how big a format is going to be until you
+evaluate it is one of the major problems.  It's on the TODO list.
+.PP
+Here's one strategy:  If you have a fixed-size footer, you can get footers
+by checking \f(CW$FORMAT_LINES_LEFT\fR before each \fBwrite()\fR and print the footer
+yourself if necessary.
+.PP
+Here's another strategy: Open a pipe to yourself, using \f(CW\*(C`open(MYSELF, "|\-")\*(C'\fR
+(see "open" in perlfunc) and always \fBwrite()\fR to MYSELF instead of STDOUT.
+Have your child process massage its STDIN to rearrange headers and footers
+however you like.  Not very convenient, but doable.
+.SS "Accessing Formatting Internals"
+.IX Xref "format, internals"
+.IX Subsection "Accessing Formatting Internals"
+For low-level access to the formatting mechanism, you may use \fBformline()\fR
+and access \f(CW$^A\fR (the \f(CW$ACCUMULATOR\fR variable) directly.
+.PP
+For example:
+.PP
+.Vb 3
+\&    $str = formline <<\*(AqEND\*(Aq, 1,2,3;
+\&    @<<<  @|||  @>>>
+\&    END
+\&
+\&    print "Wow, I just stored \*(Aq$^A\*(Aq in the accumulator!\en";
+.Ve
+.PP
+Or to make an \fBswrite()\fR subroutine, which is to \fBwrite()\fR what \fBsprintf()\fR
+is to \fBprintf()\fR, do this:
+.PP
+.Vb 8
+\&    use Carp;
+\&    sub swrite {
+\&        croak "usage: swrite PICTURE ARGS" unless @_;
+\&        my $format = shift;
+\&        $^A = "";
+\&        formline($format,@_);
+\&        return $^A;
+\&    }
+\&
+\&    $string = swrite(<<\*(AqEND\*(Aq, 1, 2, 3);
+\& Check me out
+\& @<<<  @|||  @>>>
+\& END
+\&    print $string;
+.Ve
+.SH WARNINGS
+.IX Header "WARNINGS"
+The lone dot that ends a format can also prematurely end a mail
+message passing through a misconfigured Internet mailer (and based on
+experience, such misconfiguration is the rule, not the exception).  So
+when sending format code through mail, you should indent it so that
+the format-ending dot is not on the left margin; this will prevent
+SMTP cutoff.
+.PP
+Lexical variables (declared with "my") are not visible within a
+format unless the format is declared within the scope of the lexical
+variable.
+.PP
+If a program's environment specifies an LC_NUMERIC locale and \f(CW\*(C`use
+locale\*(C'\fR is in effect when the format is declared, the locale is used
+to specify the decimal point character in formatted output.  Formatted
+output cannot be controlled by \f(CW\*(C`use locale\*(C'\fR at the time when \fBwrite()\fR
+is called. See perllocale for further discussion of locale handling.
+.PP
+Within strings that are to be displayed in a fixed-length text field,
+each control character is substituted by a space. (But remember the
+special meaning of \f(CW\*(C`\er\*(C'\fR when using fill mode.) This is done to avoid
+misalignment when control characters "disappear" on some output media.