Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 184 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/B::Xref.3perl b/upstream/archlinux/man3/B::Xref.3perl
new file mode 100644
index 00000000..931928c7
--- /dev/null
+++ b/upstream/archlinux/man3/B::Xref.3perl
@@ -0,0 +1,184 @@
+.\" -*- 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 "B::Xref 3perl"
+.TH B::Xref 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
+B::Xref \- Generates cross reference reports for Perl programs
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+perl \-MO=Xref[,OPTIONS] foo.pl
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The B::Xref module is used to generate a cross reference listing of all
+definitions and uses of variables, subroutines and formats in a Perl program.
+It is implemented as a backend for the Perl compiler.
+.PP
+The report generated is in the following format:
+.PP
+.Vb 8
+\&    File filename1
+\&      Subroutine subname1
+\&        Package package1
+\&          object1        line numbers
+\&          object2        line numbers
+\&          ...
+\&        Package package2
+\&        ...
+.Ve
+.PP
+Each \fBFile\fR section reports on a single file. Each \fBSubroutine\fR section
+reports on a single subroutine apart from the special cases
+"(definitions)" and "(main)". These report, respectively, on subroutine
+definitions found by the initial symbol table walk and on the main part of
+the program or module external to all subroutines.
+.PP
+The report is then grouped by the \fBPackage\fR of each variable,
+subroutine or format with the special case "(lexicals)" meaning
+lexical variables. Each \fBobject\fR name (implicitly qualified by its
+containing \fBPackage\fR) includes its type character(s) at the beginning
+where possible. Lexical variables are easier to track and even
+included dereferencing information where possible.
+.PP
+The \f(CW\*(C`line numbers\*(C'\fR are a comma separated list of line numbers (some
+preceded by code letters) where that object is used in some way.
+Simple uses aren't preceded by a code letter. Introductions (such as
+where a lexical is first defined with \f(CW\*(C`my\*(C'\fR) are indicated with the
+letter "i". Subroutine and method calls are indicated by the character
+"&".  Subroutine definitions are indicated by "s" and format
+definitions by "f".
+.PP
+For instance, here's part of the report from the \fIpod2man\fR program that
+comes with Perl:
+.PP
+.Vb 12
+\&  Subroutine clear_noremap
+\&    Package (lexical)
+\&      $ready_to_print   i1069, 1079
+\&    Package main
+\&      $&                1086
+\&      $.                1086
+\&      $0                1086
+\&      $1                1087
+\&      $2                1085, 1085
+\&      $3                1085, 1085
+\&      $ARGV             1086
+\&      %HTML_Escapes     1085, 1085
+.Ve
+.PP
+This shows the variables used in the subroutine \f(CW\*(C`clear_noremap\*(C'\fR.  The
+variable \f(CW$ready_to_print\fR is a \fBmy()\fR (lexical) variable,
+\&\fBi\fRntroduced (first declared with \fBmy()\fR) on line 1069, and used on
+line 1079.  The variable \f(CW$&\fR from the main package is used on 1086,
+and so on.
+.PP
+A line number may be prefixed by a single letter:
+.IP i 4
+.IX Item "i"
+Lexical variable introduced (declared with \fBmy()\fR) for the first time.
+.IP & 4
+Subroutine or method call.
+.IP s 4
+.IX Item "s"
+Subroutine defined.
+.IP r 4
+.IX Item "r"
+Format defined.
+.PP
+The most useful option the cross referencer has is to save the report
+to a separate file.  For instance, to save the report on
+\&\fImyperlprogram\fR to the file \fIreport\fR:
+.PP
+.Vb 1
+\&  $ perl \-MO=Xref,\-oreport myperlprogram
+.Ve
+.SH OPTIONS
+.IX Header "OPTIONS"
+Option words are separated by commas (not whitespace) and follow the
+usual conventions of compiler backend options.
+.ie n .IP """\-oFILENAME""" 8
+.el .IP \f(CW\-oFILENAME\fR 8
+.IX Item "-oFILENAME"
+Directs output to \f(CW\*(C`FILENAME\*(C'\fR instead of standard output.
+.ie n .IP """\-r""" 8
+.el .IP \f(CW\-r\fR 8
+.IX Item "-r"
+Raw output. Instead of producing a human-readable report, outputs a line
+in machine-readable form for each definition/use of a variable/sub/format.
+.ie n .IP """\-d""" 8
+.el .IP \f(CW\-d\fR 8
+.IX Item "-d"
+Don't output the "(definitions)" sections.
+.ie n .IP """\-D[tO]""" 8
+.el .IP \f(CW\-D[tO]\fR 8
+.IX Item "-D[tO]"
+(Internal) debug options, probably only useful if \f(CW\*(C`\-r\*(C'\fR included.
+The \f(CW\*(C`t\*(C'\fR option prints the object on the top of the stack as it's
+being tracked. The \f(CW\*(C`O\*(C'\fR option prints each operator as it's being
+processed in the execution order of the program.
+.SH BUGS
+.IX Header "BUGS"
+Non-lexical variables are quite difficult to track through a program.
+Sometimes the type of a non-lexical variable's use is impossible to
+determine. Introductions of non-lexical non-scalars don't seem to be
+reported properly.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Malcolm Beattie, mbeattie@sable.ox.ac.uk.