1 files changed, 194 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/lib.3pm b/upstream/mageia-cauldron/man3pm/lib.3pm
new file mode 100644
index 00000000..63b8c46a
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/lib.3pm
@@ -0,0 +1,194 @@
+.\" -*- 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 "lib 3pm"
+.TH lib 3pm 2023-12-15 "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
+lib \- manipulate @INC at compile time
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use lib LIST;
+\&
+\&    no lib LIST;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is a small simple module which simplifies the manipulation of \f(CW@INC\fR
+at compile time.
+.PP
+It is typically used to add extra directories to perl's search path so
+that later \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR statements will find modules which are
+not located on perl's default search path.
+.ie n .SS "Adding directories to @INC"
+.el .SS "Adding directories to \f(CW@INC\fP"
+.IX Subsection "Adding directories to @INC"
+The parameters to \f(CW\*(C`use lib\*(C'\fR are added to the start of the perl search
+path. Saying
+.PP
+.Vb 1
+\&    use lib LIST;
+.Ve
+.PP
+is \fIalmost\fR the same as saying
+.PP
+.Vb 1
+\&    BEGIN { unshift(@INC, LIST) }
+.Ve
+.PP
+For each directory in LIST (called \f(CW$dir\fR here) the lib module also
+checks to see if a directory called \f(CW$dir\fR/$archname/auto exists.
+If so the \f(CW$dir\fR/$archname directory is assumed to be a corresponding
+architecture specific directory and is added to \f(CW@INC\fR in front of \f(CW$dir\fR.
+lib.pm also checks if directories called \f(CW$dir\fR/$version and \f(CW$dir\fR/$version/$archname
+exist and adds these directories to \f(CW@INC\fR.
+.PP
+The current value of \f(CW$archname\fR can be found with this command:
+.PP
+.Vb 1
+\&    perl \-V:archname
+.Ve
+.PP
+The corresponding command to get the current value of \f(CW$version\fR is:
+.PP
+.Vb 1
+\&    perl \-V:version
+.Ve
+.PP
+To avoid memory leaks, all trailing duplicate entries in \f(CW@INC\fR are
+removed.
+.ie n .SS "Deleting directories from @INC"
+.el .SS "Deleting directories from \f(CW@INC\fP"
+.IX Subsection "Deleting directories from @INC"
+You should normally only add directories to \f(CW@INC\fR.  If you need to
+delete directories from \f(CW@INC\fR take care to only delete those which you
+added yourself or which you are certain are not needed by other modules
+in your script.  Other modules may have added directories which they
+need for correct operation.
+.PP
+The \f(CW\*(C`no lib\*(C'\fR statement deletes all instances of each named directory
+from \f(CW@INC\fR.
+.PP
+For each directory in LIST (called \f(CW$dir\fR here) the lib module also
+checks to see if a directory called \f(CW$dir\fR/$archname/auto exists.
+If so the \f(CW$dir\fR/$archname directory is assumed to be a corresponding
+architecture specific directory and is also deleted from \f(CW@INC\fR. lib.pm also
+checks if directories called \f(CW$dir\fR/$version and \f(CW$dir\fR/$version/$archname
+exist and deletes these directories from \f(CW@INC\fR.
+.ie n .SS "Restoring original @INC"
+.el .SS "Restoring original \f(CW@INC\fP"
+.IX Subsection "Restoring original @INC"
+When the lib module is first loaded it records the current value of \f(CW@INC\fR
+in an array \f(CW@lib::ORIG_INC\fR. To restore \f(CW@INC\fR to that value you
+can say
+.PP
+.Vb 1
+\&    @INC = @lib::ORIG_INC;
+.Ve
+.SH CAVEATS
+.IX Header "CAVEATS"
+In order to keep lib.pm small and simple, it only works with Unix
+filepaths.  This doesn't mean it only works on Unix, but non-Unix
+users must first translate their file paths to Unix conventions.
+.PP
+.Vb 3
+\&    # VMS users wanting to put [.stuff.moo] into 
+\&    # their @INC would write
+\&    use lib \*(Aqstuff/moo\*(Aq;
+.Ve
+.SH NOTES
+.IX Header "NOTES"
+In the future, this module will likely use File::Spec for determining
+paths, as it does now for Mac OS (where Unix-style or Mac-style paths
+work, and Unix-style paths are converted properly to Mac-style paths
+before being added to \f(CW@INC\fR).
+.PP
+If you try to add a file to \f(CW@INC\fR as follows:
+.PP
+.Vb 1
+\&  use lib \*(Aqthis_is_a_file.txt\*(Aq;
+.Ve
+.PP
+\&\f(CW\*(C`lib\*(C'\fR will warn about this. The sole exceptions are files with the
+\&\f(CW\*(C`.par\*(C'\fR extension which are intended to be used as libraries.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+FindBin \- optional module which deals with paths relative to the source file.
+.PP
+PAR \- optional module which can treat \f(CW\*(C`.par\*(C'\fR files as Perl libraries.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Tim Bunce, 2nd June 1995.
+.PP
+\&\f(CW\*(C`lib\*(C'\fR is maintained by the perl5\-porters. Please direct
+any questions to the canonical mailing list. Anything that
+is applicable to the CPAN release can be sent to its maintainer,
+though.
+.PP
+Maintainer: The Perl5\-Porters <perl5\-porters@perl.org>
+.PP
+Maintainer of the CPAN release: Steffen Mueller <smueller@cpan.org>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+This package has been part of the perl core since perl 5.001.
+It has been released separately to CPAN so older installations
+can benefit from bug fixes.
+.PP
+This package has the same copyright and license as the perl core.