Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 266 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl b/upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl
new file mode 100644
index 00000000..a1ab0bc6
--- /dev/null
+++ b/upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl
@@ -0,0 +1,266 @@
+.\" -*- 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 "ExtUtils::MakeMaker::Tutorial 3perl"
+.TH ExtUtils::MakeMaker::Tutorial 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
+ExtUtils::MakeMaker::Tutorial \- Writing a module with MakeMaker
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use ExtUtils::MakeMaker;
+\&
+\&    WriteMakefile(
+\&        NAME            => \*(AqYour::Module\*(Aq,
+\&        VERSION_FROM    => \*(Aqlib/Your/Module.pm\*(Aq
+\&    );
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This is a short tutorial on writing a simple module with MakeMaker.
+It's really not that hard.
+.SS "The Mantra"
+.IX Subsection "The Mantra"
+MakeMaker modules are installed using this simple mantra
+.PP
+.Vb 4
+\&        perl Makefile.PL
+\&        make
+\&        make test
+\&        make install
+.Ve
+.PP
+There are lots more commands and options, but the above will do it.
+.SS "The Layout"
+.IX Subsection "The Layout"
+The basic files in a module look something like this.
+.PP
+.Vb 3
+\&        Makefile.PL
+\&        MANIFEST
+\&        lib/Your/Module.pm
+.Ve
+.PP
+That's all that's strictly necessary.  There's additional files you might
+want:
+.PP
+.Vb 8
+\&        lib/Your/Other/Module.pm
+\&        t/some_test.t
+\&        t/some_other_test.t
+\&        Changes
+\&        README
+\&        INSTALL
+\&        MANIFEST.SKIP
+\&        bin/some_program
+.Ve
+.IP Makefile.PL 4
+.IX Item "Makefile.PL"
+When you run Makefile.PL, it makes a Makefile.  That's the whole point of
+MakeMaker.  The Makefile.PL is a simple program which loads
+ExtUtils::MakeMaker and runs the \fBWriteMakefile()\fR function to generate a
+Makefile.
+.Sp
+Here's an example of what you need for a simple module:
+.Sp
+.Vb 1
+\&    use ExtUtils::MakeMaker;
+\&
+\&    WriteMakefile(
+\&        NAME            => \*(AqYour::Module\*(Aq,
+\&        VERSION_FROM    => \*(Aqlib/Your/Module.pm\*(Aq
+\&    );
+.Ve
+.Sp
+NAME is the top-level namespace of your module.  VERSION_FROM is the file
+which contains the \f(CW$VERSION\fR variable for the entire distribution.  Typically
+this is the same as your top-level module.
+.IP MANIFEST 4
+.IX Item "MANIFEST"
+A simple listing of all the files in your distribution.
+.Sp
+.Vb 3
+\&        Makefile.PL
+\&        MANIFEST
+\&        lib/Your/Module.pm
+.Ve
+.Sp
+File paths in a MANIFEST always use Unix conventions (ie. /) even if you're
+not on Unix.
+.Sp
+You can write this by hand or generate it with 'make manifest'.
+.Sp
+See ExtUtils::Manifest for more details.
+.IP lib/ 4
+.IX Item "lib/"
+This is the directory where the .pm and .pod files you wish to have
+installed go.  They are laid out according to namespace.  So Foo::Bar
+is \fIlib/Foo/Bar.pm\fR.
+.IP t/ 4
+.IX Item "t/"
+Tests for your modules go here.  Each test filename ends with a .t.
+So \fIt/foo.t\fR  'make test' will run these tests.
+.Sp
+Typically, the \fIt/\fR test directory is flat, with all test files located
+directly within it. However, you can nest tests within subdirectories, for
+example:
+.Sp
+.Vb 1
+\&    t/foo/subdir_test.t
+.Ve
+.Sp
+To do this, you need to inform \f(CWWriteMakefile()\fR in your \fIMakefile.PL\fR file
+in the following fashion:
+.Sp
+.Vb 1
+\&    test => {TESTS => \*(Aqt/*.t t/*/*.t\*(Aq}
+.Ve
+.Sp
+That will run all tests in \fIt/\fR, as well as all tests in all subdirectories
+that reside under \fIt/\fR. You can nest as deeply as makes sense for your project. 
+Simply add another entry in the test location string. For example, to test:
+.Sp
+.Vb 1
+\&    t/foo/bar/subdir_test.t
+.Ve
+.Sp
+You would use the following \f(CW\*(C`test\*(C'\fR directive:
+.Sp
+.Vb 1
+\&    test => {TESTS => \*(Aqt/*.t t/*/*/*.t\*(Aq}
+.Ve
+.Sp
+Note that in the above example, tests in the first subdirectory will not be
+run. To run all tests in the intermediary subdirectory preceding the one
+the test files are in, you need to explicitly note it:
+.Sp
+.Vb 1
+\&    test => {TESTS => \*(Aqt/*.t t/*/*.t t/*/*/*.t\*(Aq}
+.Ve
+.Sp
+You don't need to specify wildcards if you only want to test within specific
+subdirectories. The following example will only run tests in \fIt/foo\fR:
+.Sp
+.Vb 1
+\&    test => {TESTS => \*(Aqt/foo/*.t\*(Aq}
+.Ve
+.Sp
+Tests are run from the top level of your distribution.  So inside a test
+you would refer to ./lib to enter the lib directory, for example.
+.IP Changes 4
+.IX Item "Changes"
+A log of changes you've made to this module.  The layout is free-form.
+Here's an example:
+.Sp
+.Vb 3
+\&    1.01 Fri Apr 11 00:21:25 PDT 2003
+\&        \- thing() does some stuff now
+\&        \- fixed the wiggy bug in withit()
+\&
+\&    1.00 Mon Apr  7 00:57:15 PDT 2003
+\&        \- "Rain of Frogs" now supported
+.Ve
+.IP README 4
+.IX Item "README"
+A short description of your module, what it does, why someone would use it
+and its limitations.  CPAN automatically pulls your README file out of
+the archive and makes it available to CPAN users, it is the first thing
+they will read to decide if your module is right for them.
+.IP INSTALL 4
+.IX Item "INSTALL"
+Instructions on how to install your module along with any dependencies.
+Suggested information to include here:
+.Sp
+.Vb 3
+\&    any extra modules required for use
+\&    the minimum version of Perl required
+\&    if only works on certain operating systems
+.Ve
+.IP MANIFEST.SKIP 4
+.IX Item "MANIFEST.SKIP"
+A file full of regular expressions to exclude when using 'make
+manifest' to generate the MANIFEST.  These regular expressions
+are checked against each file path found in the distribution (so
+you're matching against "t/foo.t" not "foo.t").
+.Sp
+Here's a sample:
+.Sp
+.Vb 3
+\&    ~$          # ignore emacs and vim backup files
+\&    .bak$       # ignore manual backups
+\&    \e#          # ignore CVS old revision files and emacs temp files
+.Ve
+.Sp
+Since # can be used for comments, # must be escaped.
+.Sp
+MakeMaker comes with a default MANIFEST.SKIP to avoid things like
+version control directories and backup files.  Specifying your own
+will override this default.
+.IP bin/ 4
+.IX Item "bin/"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perlmodstyle gives stylistic help writing a module.
+.PP
+perlnewmod gives more information about how to write a module.
+.PP
+There are modules to help you through the process of writing a module:
+ExtUtils::ModuleMaker, Module::Starter, Minilla::Tutorial,
+Dist::Milla::Tutorial, Dist::Zilla::Starter