Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 254 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1/perlutil.1 b/upstream/mageia-cauldron/man1/perlutil.1
new file mode 100644
index 00000000..ce505cf1
--- /dev/null
+++ b/upstream/mageia-cauldron/man1/perlutil.1
@@ -0,0 +1,254 @@
+.\" -*- 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 "PERLUTIL 1"
+.TH PERLUTIL 1 2023-11-28 "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
+perlutil \- utilities packaged with the Perl distribution
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+Along with the Perl interpreter itself, the Perl distribution installs a
+range of utilities on your system. There are also several utilities
+which are used by the Perl distribution itself as part of the install
+process. This document exists to list all of these utilities, explain
+what they are for and provide pointers to each module's documentation,
+if appropriate.
+.SH "LIST OF UTILITIES"
+.IX Header "LIST OF UTILITIES"
+.SS Documentation
+.IX Subsection "Documentation"
+.IP perldoc 3
+.IX Item "perldoc"
+The main interface to Perl's documentation is \fIperldoc\fR, although
+if you're reading this, it's more than likely that you've already found
+it. \fIperldoc\fR will extract and format the documentation from any file
+in the current directory, any Perl module installed on the system, or
+any of the standard documentation pages, such as this one. Use 
+\&\f(CW\*(C`perldoc <name>\*(C'\fR to get information on any of the utilities
+described in this document.
+.IP pod2man 3
+.IX Item "pod2man"
+.PD 0
+.IP pod2text 3
+.IX Item "pod2text"
+.PD
+If it's run from a terminal, \fIperldoc\fR will usually call \fIpod2man\fR to
+translate POD (Plain Old Documentation \- see perlpod for an
+explanation) into a manpage, and then run \fIman\fR to display it; if
+\&\fIman\fR isn't available, \fIpod2text\fR will be used instead and the output
+piped through your favourite pager.
+.IP pod2html 3
+.IX Item "pod2html"
+As well as these two, there is another converter: \fIpod2html\fR will
+produce HTML pages from POD.
+.IP pod2usage 3
+.IX Item "pod2usage"
+If you just want to know how to use the utilities described here,
+\&\fIpod2usage\fR will just extract the "USAGE" section; some of
+the utilities will automatically call \fIpod2usage\fR on themselves when
+you call them with \f(CW\*(C`\-help\*(C'\fR.
+.IP podchecker 3
+.IX Item "podchecker"
+If you're writing your own documentation in POD, the \fIpodchecker\fR
+utility will look for errors in your markup.
+.IP splain 3
+.IX Item "splain"
+\&\fIsplain\fR is an interface to perldiag \- paste in your error message
+to it, and it'll explain it for you.
+.IP \fIroffitall\fR 3
+.IX Item "roffitall"
+The \fIroffitall\fR utility is not installed on your system but lives in
+the \fIpod/\fR directory of your Perl source kit; it converts all the
+documentation from the distribution to \fI*roff\fR format, and produces a
+typeset PostScript or text file of the whole lot.
+.SS Converters
+.IX Subsection "Converters"
+.IP pl2pm 3
+.IX Item "pl2pm"
+To help you convert legacy programs to more modern Perl, the
+\&\fIpl2pm\fR utility will help you convert old-style Perl 4 libraries
+to new-style Perl5 modules.
+.SS Administration
+.IX Subsection "Administration"
+.IP libnetcfg 3
+.IX Item "libnetcfg"
+To display and change the libnet configuration run the libnetcfg command.
+.IP perlivp 3
+.IX Item "perlivp"
+The \fIperlivp\fR program is set up at Perl source code build time to test
+the Perl version it was built under.  It can be used after running \f(CW\*(C`make
+install\*(C'\fR (or your platform's equivalent procedure) to verify that perl
+and its libraries have been installed correctly.
+.SS Development
+.IX Subsection "Development"
+There are a set of utilities which help you in developing Perl programs, 
+and in particular, extending Perl with C.
+.IP perlbug 3
+.IX Item "perlbug"
+\&\fIperlbug\fR used to be the recommended way to report bugs in the perl
+interpreter itself or any of the standard library modules back to the
+developers; bug reports and patches should now be submitted to
+<https://github.com/Perl/perl5/issues>.
+.IP perlthanks 3
+.IX Item "perlthanks"
+This program provides an easy way to send a thank-you message back to the
+authors and maintainers of perl. It's just \fIperlbug\fR installed under
+another name.
+.IP h2ph 3
+.IX Item "h2ph"
+Back before Perl had the XS system for connecting with C libraries,
+programmers used to get library constants by reading through the C
+header files. You may still see \f(CW\*(C`require\ \*(Aqsyscall.ph\*(Aq\*(C'\fR or similar
+around \- the \fI.ph\fR file should be created by running \fIh2ph\fR on the
+corresponding \fI.h\fR file. See the h2ph documentation for more on how
+to convert a whole bunch of header files at once.
+.IP h2xs 3
+.IX Item "h2xs"
+\&\fIh2xs\fR converts C header files into XS modules, and will try and write
+as much glue between C libraries and Perl modules as it can. It's also
+very useful for creating skeletons of pure Perl modules.
+.IP enc2xs 3
+.IX Item "enc2xs"
+\&\fIenc2xs\fR builds a Perl extension for use by Encode from either
+Unicode Character Mapping files (.ucm) or Tcl Encoding Files (.enc).
+Besides being used internally during the build process of the Encode
+module, you can use \fIenc2xs\fR to add your own encoding to perl.
+No knowledge of XS is necessary.
+.IP xsubpp 3
+.IX Item "xsubpp"
+\&\fIxsubpp\fR is a compiler to convert Perl XS code into C code.
+It is typically run by the makefiles created by ExtUtils::MakeMaker.
+.Sp
+\&\fIxsubpp\fR will compile XS code into C code by embedding the constructs
+necessary to let C functions manipulate Perl values and creates the glue
+necessary to let Perl access those functions.
+.IP prove 3
+.IX Item "prove"
+\&\fIprove\fR is a command-line interface to the test-running functionality
+of Test::Harness.  It's an alternative to \f(CW\*(C`make test\*(C'\fR.
+.IP corelist 3
+.IX Item "corelist"
+A command-line front-end to Module::CoreList, to query what modules
+were shipped with given versions of perl.
+.SS "General tools"
+.IX Subsection "General tools"
+A few general-purpose tools are shipped with perl, mostly because they
+came along modules included in the perl distribution.
+.IP encguess 3
+.IX Item "encguess"
+\&\fIencguess\fR will attempt to guess the character encoding of files.
+.IP json_pp 3
+.IX Item "json_pp"
+\&\fIjson_pp\fR is a pure Perl JSON converter and formatter.
+.IP piconv 3
+.IX Item "piconv"
+\&\fIpiconv\fR is a Perl version of \fBiconv\fR\|(1), a character encoding converter
+widely available for various Unixen today.  This script was primarily a
+technology demonstrator for Perl v5.8.0, but you can use piconv in the
+place of iconv for virtually any case.
+.IP ptar 3
+.IX Item "ptar"
+\&\fIptar\fR is a tar-like program, written in pure Perl.
+.IP ptardiff 3
+.IX Item "ptardiff"
+\&\fIptardiff\fR is a small utility that produces a diff between an extracted
+archive and an unextracted one. (Note that this utility requires the
+Text::Diff module to function properly; this module isn't distributed
+with perl, but is available from the CPAN.)
+.IP ptargrep 3
+.IX Item "ptargrep"
+\&\fIptargrep\fR is a utility to apply pattern matching to the contents of files 
+in a tar archive.
+.IP shasum 3
+.IX Item "shasum"
+This utility, that comes with the Digest::SHA module, is used to print
+or verify SHA checksums.
+.IP streamzip 3
+.IX Item "streamzip"
+\&\fIstreamzip\fR compresses data streamed to STDIN into a streamed zip container.
+.IP zipdetails 3
+.IX Item "zipdetails"
+\&\fIzipdetails\fR displays information about the internal record structure of the zip file.
+It is not concerned with displaying any details of the compressed data stored in the zip file.
+.SS Installation
+.IX Subsection "Installation"
+These utilities help manage extra Perl modules that don't come with the perl
+distribution.
+.IP cpan 3
+.IX Item "cpan"
+\&\fIcpan\fR is a command-line interface to CPAN.pm.  It allows you to install
+modules or distributions from CPAN, or just get information about them, and
+a lot more.  It is similar to the command line mode of the CPAN module,
+.Sp
+.Vb 1
+\&    perl \-MCPAN \-e shell
+.Ve
+.IP instmodsh 3
+.IX Item "instmodsh"
+A little interface to ExtUtils::Installed to examine installed modules,
+validate your packlists and even create a tarball from an installed module.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+perldoc, pod2man, pod2text, pod2html, pod2usage,
+podchecker, splain, pl2pm,
+perlbug, h2ph, h2xs, enc2xs,
+xsubpp, cpan, encguess, instmodsh, json_pp,
+piconv, prove, corelist, ptar,
+ptardiff, shasum, streamzip, zipdetails