Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 2542 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/CPAN.3pm b/upstream/mageia-cauldron/man3pm/CPAN.3pm
new file mode 100644
index 00000000..89007d66
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/CPAN.3pm
@@ -0,0 +1,2542 @@
+.\" -*- 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 "CPAN 3pm"
+.TH CPAN 3pm 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
+CPAN \- query, download and build perl modules from CPAN sites
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+Interactive mode:
+.PP
+.Vb 1
+\&  perl \-MCPAN \-e shell
+.Ve
+.PP
+\&\-\-or\-\-
+.PP
+.Vb 1
+\&  cpan
+.Ve
+.PP
+Basic commands:
+.PP
+.Vb 1
+\&  # Modules:
+\&
+\&  cpan> install Acme::Meta                       # in the shell
+\&
+\&  CPAN::Shell\->install("Acme::Meta");            # in perl
+\&
+\&  # Distributions:
+\&
+\&  cpan> install NWCLARK/Acme\-Meta\-0.02.tar.gz    # in the shell
+\&
+\&  CPAN::Shell\->
+\&    install("NWCLARK/Acme\-Meta\-0.02.tar.gz");    # in perl
+\&
+\&  # module objects:
+\&
+\&  $mo = CPAN::Shell\->expandany($mod);
+\&  $mo = CPAN::Shell\->expand("Module",$mod);      # same thing
+\&
+\&  # distribution objects:
+\&
+\&  $do = CPAN::Shell\->expand("Module",$mod)\->distribution;
+\&  $do = CPAN::Shell\->expandany($distro);         # same thing
+\&  $do = CPAN::Shell\->expand("Distribution",
+\&                            $distro);            # same thing
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The CPAN module automates or at least simplifies the make and install
+of perl modules and extensions. It includes some primitive searching
+capabilities and knows how to use LWP, HTTP::Tiny, Net::FTP and certain
+external download clients to fetch distributions from the net.
+.PP
+These are fetched from one or more mirrored CPAN (Comprehensive
+Perl Archive Network) sites and unpacked in a dedicated directory.
+.PP
+The CPAN module also supports named and versioned
+\&\fIbundles\fR of modules. Bundles simplify handling of sets of
+related modules. See Bundles below.
+.PP
+The package contains a session manager and a cache manager. The
+session manager keeps track of what has been fetched, built, and
+installed in the current session. The cache manager keeps track of the
+disk space occupied by the make processes and deletes excess space
+using a simple FIFO mechanism.
+.PP
+All methods provided are accessible in a programmer style and in an
+interactive shell style.
+.ie n .SS "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
+.el .SS "CPAN::shell([$prompt, \f(CW$command\fP]) Starting Interactive Mode"
+.IX Subsection "CPAN::shell([$prompt, $command]) Starting Interactive Mode"
+Enter interactive mode by running
+.PP
+.Vb 1
+\&    perl \-MCPAN \-e shell
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    cpan
+.Ve
+.PP
+which puts you into a readline interface. If \f(CW\*(C`Term::ReadKey\*(C'\fR and
+either of \f(CW\*(C`Term::ReadLine::Perl\*(C'\fR or \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR are installed,
+history and command completion are supported.
+.PP
+Once at the command line, type \f(CW\*(C`h\*(C'\fR for one-page help
+screen; the rest should be self-explanatory.
+.PP
+The function call \f(CW\*(C`shell\*(C'\fR takes two optional arguments: one the
+prompt, the second the default initial command line (the latter
+only works if a real ReadLine interface module is installed).
+.PP
+The most common uses of the interactive modes are
+.IP "Searching for authors, bundles, distribution files and modules" 2
+.IX Item "Searching for authors, bundles, distribution files and modules"
+There are corresponding one-letter commands \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`d\*(C'\fR, and \f(CW\*(C`m\*(C'\fR
+for each of the four categories and another, \f(CW\*(C`i\*(C'\fR for any of the
+mentioned four. Each of the four entities is implemented as a class
+with slightly differing methods for displaying an object.
+.Sp
+Arguments to these commands are either strings exactly matching
+the identification string of an object, or regular expressions
+matched case-insensitively against various attributes of the
+objects. The parser only recognizes a regular expression when you
+enclose it with slashes.
+.Sp
+The principle is that the number of objects found influences how an
+item is displayed. If the search finds one item, the result is
+displayed with the rather verbose method \f(CW\*(C`as_string\*(C'\fR, but if
+more than one is found, each object is displayed with the terse method
+\&\f(CW\*(C`as_glimpse\*(C'\fR.
+.Sp
+Examples:
+.Sp
+.Vb 10
+\&  cpan> m Acme::MetaSyntactic
+\&  Module id = Acme::MetaSyntactic
+\&      CPAN_USERID  BOOK (Philippe Bruhat (BooK) <[...]>)
+\&      CPAN_VERSION 0.99
+\&      CPAN_FILE    B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
+\&      UPLOAD_DATE  2006\-11\-06
+\&      MANPAGE      Acme::MetaSyntactic \- Themed metasyntactic variables names
+\&      INST_FILE    /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm
+\&      INST_VERSION 0.99
+\&  cpan> a BOOK
+\&  Author id = BOOK
+\&      EMAIL        [...]
+\&      FULLNAME     Philippe Bruhat (BooK)
+\&  cpan> d BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
+\&  Distribution id = B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz
+\&      CPAN_USERID  BOOK (Philippe Bruhat (BooK) <[...]>)
+\&      CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...]
+\&      UPLOAD_DATE  2006\-11\-06
+\&  cpan> m /lorem/
+\&  Module  = Acme::MetaSyntactic::loremipsum (BOOK/Acme\-MetaSyntactic\-0.99.tar.gz)
+\&  Module    Text::Lorem            (ADEOLA/Text\-Lorem\-0.3.tar.gz)
+\&  Module    Text::Lorem::More      (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
+\&  Module    Text::Lorem::More::Source (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz)
+\&  cpan> i /berlin/
+\&  Distribution    BEATNIK/Filter\-NumberLines\-0.02.tar.gz
+\&  Module  = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime\-TimeZone\-0.7904.tar.gz)
+\&  Module    Filter::NumberLines    (BEATNIK/Filter\-NumberLines\-0.02.tar.gz)
+\&  Author          [...]
+.Ve
+.Sp
+The examples illustrate several aspects: the first three queries
+target modules, authors, or distros directly and yield exactly one
+result. The last two use regular expressions and yield several
+results. The last one targets all of bundles, modules, authors, and
+distros simultaneously. When more than one result is available, they
+are printed in one-line format.
+.ie n .IP """get"", ""make"", ""test"", ""install"", ""clean"" modules or distributions" 2
+.el .IP "\f(CWget\fR, \f(CWmake\fR, \f(CWtest\fR, \f(CWinstall\fR, \f(CWclean\fR modules or distributions" 2
+.IX Item "get, make, test, install, clean modules or distributions"
+These commands take any number of arguments and investigate what is
+necessary to perform the action. Argument processing is as follows:
+.Sp
+.Vb 5
+\&  known module name in format Foo/Bar.pm   module
+\&  other embedded slash                     distribution
+\&    \- with trailing slash dot              directory
+\&  enclosing slashes                        regexp
+\&  known module name in format Foo::Bar     module
+.Ve
+.Sp
+If the argument is a distribution file name (recognized by embedded
+slashes), it is processed. If it is a module, CPAN determines the
+distribution file in which this module is included and processes that,
+following any dependencies named in the module's META.yml or
+Makefile.PL (this behavior is controlled by the configuration
+parameter \f(CW\*(C`prerequisites_policy\*(C'\fR). If an argument is enclosed in
+slashes it is treated as a regular expression: it is expanded and if
+the result is a single object (distribution, bundle or module), this
+object is processed.
+.Sp
+Example:
+.Sp
+.Vb 3
+\&    install Dummy::Perl                   # installs the module
+\&    install AUXXX/Dummy\-Perl\-3.14.tar.gz  # installs that distribution
+\&    install /Dummy\-Perl\-3.14/             # same if the regexp is unambiguous
+.Ve
+.Sp
+\&\f(CW\*(C`get\*(C'\fR downloads a distribution file and untars or unzips it, \f(CW\*(C`make\*(C'\fR
+builds it, \f(CW\*(C`test\*(C'\fR runs the test suite, and \f(CW\*(C`install\*(C'\fR installs it.
+.Sp
+Any \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`test\*(C'\fR is run unconditionally. An
+.Sp
+.Vb 1
+\&  install <distribution_file>
+.Ve
+.Sp
+is also run unconditionally. But for
+.Sp
+.Vb 1
+\&  install <module>
+.Ve
+.Sp
+CPAN checks whether an install is needed and prints
+\&\fImodule up to date\fR if the distribution file containing
+the module doesn't need updating.
+.Sp
+CPAN also keeps track of what it has done within the current session
+and doesn't try to build a package a second time regardless of whether it
+succeeded or not. It does not repeat a test run if the test
+has been run successfully before. Same for install runs.
+.Sp
+The \f(CW\*(C`force\*(C'\fR pragma may precede another command (currently: \f(CW\*(C`get\*(C'\fR,
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, or \f(CW\*(C`install\*(C'\fR) to execute the command from scratch
+and attempt to continue past certain errors. See the section below on
+the \f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
+.Sp
+The \f(CW\*(C`notest\*(C'\fR pragma skips the test part in the build
+process.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&    cpan> notest install Tk
+.Ve
+.Sp
+A \f(CW\*(C`clean\*(C'\fR command results in a
+.Sp
+.Vb 1
+\&  make clean
+.Ve
+.Sp
+being executed within the distribution file's working directory.
+.ie n .IP """readme"", ""perldoc"", ""look"" module or distribution" 2
+.el .IP "\f(CWreadme\fR, \f(CWperldoc\fR, \f(CWlook\fR module or distribution" 2
+.IX Item "readme, perldoc, look module or distribution"
+\&\f(CW\*(C`readme\*(C'\fR displays the README file of the associated distribution.
+\&\f(CW\*(C`Look\*(C'\fR gets and untars (if not yet done) the distribution file,
+changes to the appropriate directory and opens a subshell process in
+that directory. \f(CW\*(C`perldoc\*(C'\fR displays the module's pod documentation
+in html or plain text format.
+.ie n .IP """ls"" author" 2
+.el .IP "\f(CWls\fR author" 2
+.IX Item "ls author"
+.PD 0
+.ie n .IP """ls"" globbing_expression" 2
+.el .IP "\f(CWls\fR globbing_expression" 2
+.IX Item "ls globbing_expression"
+.PD
+The first form lists all distribution files in and below an author's
+CPAN directory as stored in the CHECKSUMS files distributed on
+CPAN. The listing recurses into subdirectories.
+.Sp
+The second form limits or expands the output with shell
+globbing as in the following examples:
+.Sp
+.Vb 3
+\&      ls JV/make*
+\&      ls GSAR/*make*
+\&      ls */*make*
+.Ve
+.Sp
+The last example is very slow and outputs extra progress indicators
+that break the alignment of the result.
+.Sp
+Note that globbing only lists directories explicitly asked for, for
+example FOO/* will not list FOO/bar/Acme\-Sthg\-n.nn.tar.gz. This may be
+regarded as a bug that may be changed in some future version.
+.ie n .IP """failed""" 2
+.el .IP \f(CWfailed\fR 2
+.IX Item "failed"
+The \f(CW\*(C`failed\*(C'\fR command reports all distributions that failed on one of
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR or \f(CW\*(C`install\*(C'\fR for some reason in the currently
+running shell session.
+.IP "Persistence between sessions" 2
+.IX Item "Persistence between sessions"
+If the \f(CW\*(C`YAML\*(C'\fR or the \f(CW\*(C`YAML::Syck\*(C'\fR module is installed a record of
+the internal state of all modules is written to disk after each step.
+The files contain a signature of the currently running perl version
+for later perusal.
+.Sp
+If the configurations variable \f(CW\*(C`build_dir_reuse\*(C'\fR is set to a true
+value, then CPAN.pm reads the collected YAML files. If the stored
+signature matches the currently running perl, the stored state is
+loaded into memory such that persistence between sessions
+is effectively established.
+.ie n .IP "The ""force"" and the ""fforce"" pragma" 2
+.el .IP "The \f(CWforce\fR and the \f(CWfforce\fR pragma" 2
+.IX Item "The force and the fforce pragma"
+To speed things up in complex installation scenarios, CPAN.pm keeps
+track of what it has already done and refuses to do some things a
+second time. A \f(CW\*(C`get\*(C'\fR, a \f(CW\*(C`make\*(C'\fR, and an \f(CW\*(C`install\*(C'\fR are not repeated.
+A \f(CW\*(C`test\*(C'\fR is repeated only if the previous test was unsuccessful. The
+diagnostic message when CPAN.pm refuses to do something a second time
+is one of \fIHas already been \fR\f(CW\*(C`unwrapped|made|tested successfully\*(C'\fR or
+something similar. Another situation where CPAN refuses to act is an
+\&\f(CW\*(C`install\*(C'\fR if the corresponding \f(CW\*(C`test\*(C'\fR was not successful.
+.Sp
+In all these cases, the user can override this stubborn behaviour by
+prepending the command with the word force, for example:
+.Sp
+.Vb 4
+\&  cpan> force get Foo
+\&  cpan> force make AUTHOR/Bar\-3.14.tar.gz
+\&  cpan> force test Baz
+\&  cpan> force install Acme::Meta
+.Ve
+.Sp
+Each \fIforced\fR command is executed with the corresponding part of its
+memory erased.
+.Sp
+The \f(CW\*(C`fforce\*(C'\fR pragma is a variant that emulates a \f(CW\*(C`force get\*(C'\fR which
+erases the entire memory followed by the action specified, effectively
+restarting the whole get/make/test/install procedure from scratch.
+.IP Lockfile 2
+.IX Item "Lockfile"
+Interactive sessions maintain a lockfile, by default \f(CW\*(C`~/.cpan/.lock\*(C'\fR.
+Batch jobs can run without a lockfile and not disturb each other.
+.Sp
+The shell offers to run in \fIdowngraded mode\fR when another process is
+holding the lockfile. This is an experimental feature that is not yet
+tested very well. This second shell then does not write the history
+file, does not use the metadata file, and has a different prompt.
+.IP Signals 2
+.IX Item "Signals"
+CPAN.pm installs signal handlers for SIGINT and SIGTERM. While you are
+in the cpan-shell, it is intended that you can press \f(CW\*(C`^C\*(C'\fR anytime and
+return to the cpan-shell prompt. A SIGTERM will cause the cpan-shell
+to clean up and leave the shell loop. You can emulate the effect of a
+SIGTERM by sending two consecutive SIGINTs, which usually means by
+pressing \f(CW\*(C`^C\*(C'\fR twice.
+.Sp
+CPAN.pm ignores SIGPIPE. If the user sets \f(CW\*(C`inactivity_timeout\*(C'\fR, a
+SIGALRM is used during the run of the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
+Build.PL\*(C'\fR subprocess. A SIGALRM is also used during module version
+parsing, and is controlled by \f(CW\*(C`version_timeout\*(C'\fR.
+.SS CPAN::Shell
+.IX Subsection "CPAN::Shell"
+The commands available in the shell interface are methods in
+the package CPAN::Shell. If you enter the shell command, your
+input is split by the \fBText::ParseWords::shellwords()\fR routine, which
+acts like most shells do. The first word is interpreted as the
+method to be invoked, and the rest of the words are treated as the method's arguments.
+Continuation lines are supported by ending a line with a
+literal backslash.
+.SS autobundle
+.IX Subsection "autobundle"
+\&\f(CW\*(C`autobundle\*(C'\fR writes a bundle file into the
+\&\f(CW\*(C`$CPAN::Config\->{cpan_home}/Bundle\*(C'\fR directory. The file contains
+a list of all modules that are both available from CPAN and currently
+installed within \f(CW@INC\fR. Duplicates of each distribution are suppressed.
+The name of the bundle file is based on the current date and a
+counter, e.g. \fIBundle/Snapshot_2012_05_21_00.pm\fR. This is installed
+again by running \f(CW\*(C`cpan Bundle::Snapshot_2012_05_21_00\*(C'\fR, or installing
+\&\f(CW\*(C`Bundle::Snapshot_2012_05_21_00\*(C'\fR from the CPAN shell.
+.PP
+Return value: path to the written file.
+.SS hosts
+.IX Subsection "hosts"
+Note: this feature is still in alpha state and may change in future
+versions of CPAN.pm
+.PP
+This commands provides a statistical overview over recent download
+activities. The data for this is collected in the YAML file
+\&\f(CW\*(C`FTPstats.yml\*(C'\fR in your \f(CW\*(C`cpan_home\*(C'\fR directory. If no YAML module is
+configured or YAML not installed, no stats are provided.
+.IP install_tested 4
+.IX Item "install_tested"
+Install all distributions that have been tested successfully but have
+not yet been installed. See also \f(CW\*(C`is_tested\*(C'\fR.
+.IP is_tested 4
+.IX Item "is_tested"
+List all build directories of distributions that have been tested
+successfully but have not yet been installed. See also
+\&\f(CW\*(C`install_tested\*(C'\fR.
+.SS mkmyconfig
+.IX Subsection "mkmyconfig"
+\&\fBmkmyconfig()\fR writes your own CPAN::MyConfig file into your \f(CW\*(C`~/.cpan/\*(C'\fR
+directory so that you can save your own preferences instead of the
+system-wide ones.
+.SS "r [Module|/Regexp/]..."
+.IX Subsection "r [Module|/Regexp/]..."
+scans current perl installation for modules that have a newer version
+available on CPAN and provides a list of them. If called without
+argument, all potential upgrades are listed; if called with arguments
+the list is filtered to the modules and regexps given as arguments.
+.PP
+The listing looks something like this:
+.PP
+.Vb 10
+\&  Package namespace         installed    latest  in CPAN file
+\&  CPAN                        1.94_64    1.9600  ANDK/CPAN\-1.9600.tar.gz
+\&  CPAN::Reporter               1.1801    1.1902  DAGOLDEN/CPAN\-Reporter\-1.1902.tar.gz
+\&  YAML                           0.70      0.73  INGY/YAML\-0.73.tar.gz
+\&  YAML::Syck                     1.14      1.17  AVAR/YAML\-Syck\-1.17.tar.gz
+\&  YAML::Tiny                     1.44      1.50  ADAMK/YAML\-Tiny\-1.50.tar.gz
+\&  CGI                            3.43      3.55  MARKSTOS/CGI.pm\-3.55.tar.gz
+\&  Module::Build::YAML            1.40      1.41  DAGOLDEN/Module\-Build\-0.3800.tar.gz
+\&  TAP::Parser::Result::YAML      3.22      3.23  ANDYA/Test\-Harness\-3.23.tar.gz
+\&  YAML::XS                       0.34      0.35  INGY/YAML\-LibYAML\-0.35.tar.gz
+.Ve
+.PP
+It suppresses duplicates in the column \f(CW\*(C`in CPAN file\*(C'\fR such that
+distributions with many upgradeable modules are listed only once.
+.PP
+Note that the list is not sorted.
+.SS "recent ***EXPERIMENTAL COMMAND***"
+.IX Subsection "recent ***EXPERIMENTAL COMMAND***"
+The \f(CW\*(C`recent\*(C'\fR command downloads a list of recent uploads to CPAN and
+displays them \fIslowly\fR. While the command is running, a \f(CW$SIG\fR{INT}
+exits the loop after displaying the current item.
+.PP
+\&\fBNote\fR: This command requires XML::LibXML installed.
+.PP
+\&\fBNote\fR: This whole command currently is just a hack and will
+probably change in future versions of CPAN.pm, but the general
+approach will likely remain.
+.PP
+\&\fBNote\fR: See also smoke
+.SS recompile
+.IX Subsection "recompile"
+\&\fBrecompile()\fR is a special command that takes no argument and
+runs the make/test/install cycle with brute force over all installed
+dynamically loadable extensions (a.k.a. XS modules) with 'force' in
+effect. The primary purpose of this command is to finish a network
+installation. Imagine you have a common source tree for two different
+architectures. You decide to do a completely independent fresh
+installation. You start on one architecture with the help of a Bundle
+file produced earlier. CPAN installs the whole Bundle for you, but
+when you try to repeat the job on the second architecture, CPAN
+responds with a \f(CW"Foo up to date"\fR message for all modules. So you
+invoke CPAN's recompile on the second architecture and you're done.
+.PP
+Another popular use for \f(CW\*(C`recompile\*(C'\fR is to act as a rescue in case your
+perl breaks binary compatibility. If one of the modules that CPAN uses
+is in turn depending on binary compatibility (so you cannot run CPAN
+commands), then you should try the CPAN::Nox module for recovery.
+.SS "report Bundle|Distribution|Module"
+.IX Subsection "report Bundle|Distribution|Module"
+The \f(CW\*(C`report\*(C'\fR command temporarily turns on the \f(CW\*(C`test_report\*(C'\fR config
+variable, then runs the \f(CW\*(C`force test\*(C'\fR command with the given
+arguments. The \f(CW\*(C`force\*(C'\fR pragma reruns the tests and repeats
+every step that might have failed before.
+.SS "smoke ***EXPERIMENTAL COMMAND***"
+.IX Subsection "smoke ***EXPERIMENTAL COMMAND***"
+\&\fB*** WARNING: this command downloads and executes software from CPAN to
+your computer of completely unknown status. You should never do
+this with your normal account and better have a dedicated well
+separated and secured machine to do this. ***\fR
+.PP
+The \f(CW\*(C`smoke\*(C'\fR command takes the list of recent uploads to CPAN as
+provided by the \f(CW\*(C`recent\*(C'\fR command and tests them all. While the
+command is running \f(CW$SIG\fR{INT} is defined to mean that the current item
+shall be skipped.
+.PP
+\&\fBNote\fR: This whole command currently is just a hack and will
+probably change in future versions of CPAN.pm, but the general
+approach will likely remain.
+.PP
+\&\fBNote\fR: See also recent
+.SS "upgrade [Module|/Regexp/]..."
+.IX Subsection "upgrade [Module|/Regexp/]..."
+The \f(CW\*(C`upgrade\*(C'\fR command first runs an \f(CW\*(C`r\*(C'\fR command with the given
+arguments and then installs the newest versions of all modules that
+were listed by that.
+.ie n .SS "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution"
+.el .SS "The four \f(CWCPAN::*\fP Classes: Author, Bundle, Module, Distribution"
+.IX Subsection "The four CPAN::* Classes: Author, Bundle, Module, Distribution"
+Although it may be considered internal, the class hierarchy does matter
+for both users and programmer. CPAN.pm deals with the four
+classes mentioned above, and those classes all share a set of methods. Classical
+single polymorphism is in effect. A metaclass object registers all
+objects of all kinds and indexes them with a string. The strings
+referencing objects have a separated namespace (well, not completely
+separated):
+.PP
+.Vb 1
+\&         Namespace                         Class
+\&
+\&   words containing a "/" (slash)      Distribution
+\&    words starting with Bundle::          Bundle
+\&          everything else            Module or Author
+.Ve
+.PP
+Modules know their associated Distribution objects. They always refer
+to the most recent official release. Developers may mark their releases
+as unstable development versions (by inserting an underscore into the
+module version number which will also be reflected in the distribution
+name when you run 'make dist'), so the really hottest and newest
+distribution is not always the default.  If a module Foo circulates
+on CPAN in both version 1.23 and 1.23_90, CPAN.pm offers a convenient
+way to install version 1.23 by saying
+.PP
+.Vb 1
+\&    install Foo
+.Ve
+.PP
+This would install the complete distribution file (say
+BAR/Foo\-1.23.tar.gz) with all accompanying material. But if you would
+like to install version 1.23_90, you need to know where the
+distribution file resides on CPAN relative to the authors/id/
+directory. If the author is BAR, this might be BAR/Foo\-1.23_90.tar.gz;
+so you would have to say
+.PP
+.Vb 1
+\&    install BAR/Foo\-1.23_90.tar.gz
+.Ve
+.PP
+The first example will be driven by an object of the class
+CPAN::Module, the second by an object of class CPAN::Distribution.
+.SS "Integrating local directories"
+.IX Subsection "Integrating local directories"
+Note: this feature is still in alpha state and may change in future
+versions of CPAN.pm
+.PP
+Distribution objects are normally distributions from the CPAN, but
+there is a slightly degenerate case for Distribution objects, too, of
+projects held on the local disk. These distribution objects have the
+same name as the local directory and end with a dot. A dot by itself
+is also allowed for the current directory at the time CPAN.pm was
+used. All actions such as \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, and \f(CW\*(C`install\*(C'\fR are applied
+directly to that directory. This gives the command \f(CW\*(C`cpan .\*(C'\fR an
+interesting touch: while the normal mantra of installing a CPAN module
+without CPAN.pm is one of
+.PP
+.Vb 5
+\&    perl Makefile.PL                 perl Build.PL
+\&           ( go and get prerequisites )
+\&    make                             ./Build
+\&    make test                        ./Build test
+\&    make install                     ./Build install
+.Ve
+.PP
+the command \f(CW\*(C`cpan .\*(C'\fR does all of this at once. It figures out which
+of the two mantras is appropriate, fetches and installs all
+prerequisites, takes care of them recursively, and finally finishes the
+installation of the module in the current directory, be it a CPAN
+module or not.
+.PP
+The typical usage case is for private modules or working copies of
+projects from remote repositories on the local disk.
+.SS Redirection
+.IX Subsection "Redirection"
+The usual shell redirection symbols \f(CW\*(C` | \*(C'\fR and \f(CW\*(C`>\*(C'\fR are recognized
+by the cpan shell \fBonly when surrounded by whitespace\fR. So piping to
+pager or redirecting output into a file works somewhat as in a normal
+shell, with the stipulation that you must type extra spaces.
+.SS "Plugin support ***EXPERIMENTAL***"
+.IX Subsection "Plugin support ***EXPERIMENTAL***"
+Plugins are objects that implement any of currently eight methods:
+.PP
+.Vb 8
+\&  pre_get
+\&  post_get
+\&  pre_make
+\&  post_make
+\&  pre_test
+\&  post_test
+\&  pre_install
+\&  post_install
+.Ve
+.PP
+The \f(CW\*(C`plugin_list\*(C'\fR configuration parameter holds a list of strings of
+the form
+.PP
+.Vb 1
+\&  Modulename=arg0,arg1,arg2,arg3,...
+.Ve
+.PP
+eg:
+.PP
+.Vb 1
+\&  CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1
+.Ve
+.PP
+At run time, each listed plugin is instantiated as a singleton object
+by running the equivalent of this pseudo code:
+.PP
+.Vb 3
+\&  my $plugin = <string representation from config>;
+\&  <generate Modulename and arguments from $plugin>;
+\&  my $p = $instance{$plugin} ||= Modulename\->new($arg0,$arg1,...);
+.Ve
+.PP
+The generated singletons are kept around from instantiation until the
+end of the shell session. <plugin_list> can be reconfigured at any
+time at run time. While the cpan shell is running, it checks all
+activated plugins at each of the 8 reference points listed above and
+runs the respective method if it is implemented for that object. The
+method is called with the active CPAN::Distribution object passed in
+as an argument.
+.SH CONFIGURATION
+.IX Header "CONFIGURATION"
+When the CPAN module is used for the first time, a configuration
+dialogue tries to determine a couple of site specific options. The
+result of the dialog is stored in a hash reference \f(CW $CPAN::Config \fR
+in a file CPAN/Config.pm.
+.PP
+Default values defined in the CPAN/Config.pm file can be
+overridden in a user specific file: CPAN/MyConfig.pm. Such a file is
+best placed in \f(CW\*(C`$HOME/.cpan/CPAN/MyConfig.pm\*(C'\fR, because \f(CW\*(C`$HOME/.cpan\*(C'\fR is
+added to the search path of the CPAN module before the \fBuse()\fR or
+\&\fBrequire()\fR statements. The mkmyconfig command writes this file for you.
+.PP
+The \f(CW\*(C`o conf\*(C'\fR command has various bells and whistles:
+.IP "completion support" 4
+.IX Item "completion support"
+If you have a ReadLine module installed, you can hit TAB at any point
+of the commandline and \f(CW\*(C`o conf\*(C'\fR will offer you completion for the
+built-in subcommands and/or config variable names.
+.IP "displaying some help: o conf help" 4
+.IX Item "displaying some help: o conf help"
+Displays a short help
+.IP "displaying current values: o conf [KEY]" 4
+.IX Item "displaying current values: o conf [KEY]"
+Displays the current value(s) for this config variable. Without KEY,
+displays all subcommands and config variables.
+.Sp
+Example:
+.Sp
+.Vb 1
+\&  o conf shell
+.Ve
+.Sp
+If KEY starts and ends with a slash, the string in between is
+treated as a regular expression and only keys matching this regexp
+are displayed
+.Sp
+Example:
+.Sp
+.Vb 1
+\&  o conf /color/
+.Ve
+.IP "changing of scalar values: o conf KEY VALUE" 4
+.IX Item "changing of scalar values: o conf KEY VALUE"
+Sets the config variable KEY to VALUE. The empty string can be
+specified as usual in shells, with \f(CW\*(Aq\*(Aq\fR or \f(CW""\fR
+.Sp
+Example:
+.Sp
+.Vb 1
+\&  o conf wget /usr/bin/wget
+.Ve
+.IP "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST" 4
+.IX Item "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST"
+If a config variable name ends with \f(CW\*(C`list\*(C'\fR, it is a list. \f(CW\*(C`o conf
+KEY shift\*(C'\fR removes the first element of the list, \f(CW\*(C`o conf KEY pop\*(C'\fR
+removes the last element of the list. \f(CW\*(C`o conf KEYS unshift LIST\*(C'\fR
+prepends a list of values to the list, \f(CW\*(C`o conf KEYS push LIST\*(C'\fR
+appends a list of valued to the list.
+.Sp
+Likewise, \f(CW\*(C`o conf KEY splice LIST\*(C'\fR passes the LIST to the corresponding
+splice command.
+.Sp
+Finally, any other list of arguments is taken as a new list value for
+the KEY variable discarding the previous value.
+.Sp
+Examples:
+.Sp
+.Vb 3
+\&  o conf urllist unshift http://cpan.dev.local/CPAN
+\&  o conf urllist splice 3 1
+\&  o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org
+.Ve
+.IP "reverting to saved: o conf defaults" 4
+.IX Item "reverting to saved: o conf defaults"
+Reverts all config variables to the state in the saved config file.
+.IP "saving the config: o conf commit" 4
+.IX Item "saving the config: o conf commit"
+Saves all config variables to the current config file (CPAN/Config.pm
+or CPAN/MyConfig.pm that was loaded at start).
+.PP
+The configuration dialog can be started any time later again by
+issuing the command \f(CW\*(C` o conf init \*(C'\fR in the CPAN shell. A subset of
+the configuration dialog can be run by issuing \f(CW\*(C`o conf init WORD\*(C'\fR
+where WORD is any valid config variable or a regular expression.
+.SS "Config Variables"
+.IX Subsection "Config Variables"
+The following keys in the hash reference \f(CW$CPAN::Config\fR are
+currently defined:
+.PP
+.Vb 10
+\&  allow_installing_module_downgrades
+\&                     allow or disallow installing module downgrades
+\&  allow_installing_outdated_dists
+\&                     allow or disallow installing modules that are
+\&                     indexed in the cpan index pointing to a distro
+\&                     with a higher distro\-version number
+\&  applypatch         path to external prg
+\&  auto_commit        commit all changes to config variables to disk
+\&  build_cache        size of cache for directories to build modules
+\&  build_dir          locally accessible directory to build modules
+\&  build_dir_reuse    boolean if distros in build_dir are persistent
+\&  build_requires_install_policy
+\&                     to install or not to install when a module is
+\&                     only needed for building. yes|no|ask/yes|ask/no
+\&  bzip2              path to external prg
+\&  cache_metadata     use serializer to cache metadata
+\&  check_sigs         if signatures should be verified
+\&  cleanup_after_install
+\&                     remove build directory immediately after a
+\&                     successful install and remember that for the
+\&                     duration of the session
+\&  colorize_debug     Term::ANSIColor attributes for debugging output
+\&  colorize_output    boolean if Term::ANSIColor should colorize output
+\&  colorize_print     Term::ANSIColor attributes for normal output
+\&  colorize_warn      Term::ANSIColor attributes for warnings
+\&  commandnumber_in_prompt
+\&                     boolean if you want to see current command number
+\&  commands_quote     preferred character to use for quoting external
+\&                     commands when running them. Defaults to double
+\&                     quote on Windows, single tick everywhere else;
+\&                     can be set to space to disable quoting
+\&  connect_to_internet_ok
+\&                     whether to ask if opening a connection is ok before
+\&                     urllist is specified
+\&  cpan_home          local directory reserved for this package
+\&  curl               path to external prg
+\&  dontload_hash      DEPRECATED
+\&  dontload_list      arrayref: modules in the list will not be
+\&                     loaded by the CPAN::has_inst() routine
+\&  ftp                path to external prg
+\&  ftp_passive        if set, the environment variable FTP_PASSIVE is set
+\&                     for downloads
+\&  ftp_proxy          proxy host for ftp requests
+\&  ftpstats_period    max number of days to keep download statistics
+\&  ftpstats_size      max number of items to keep in the download statistics
+\&  getcwd             see below
+\&  gpg                path to external prg
+\&  gzip               location of external program gzip
+\&  halt_on_failure    stop processing after the first failure of queued
+\&                     items or dependencies
+\&  histfile           file to maintain history between sessions
+\&  histsize           maximum number of lines to keep in histfile
+\&  http_proxy         proxy host for http requests
+\&  inactivity_timeout breaks interactive Makefile.PLs or Build.PLs
+\&                     after this many seconds inactivity. Set to 0 to
+\&                     disable timeouts.
+\&  index_expire       refetch index files after this many days
+\&  inhibit_startup_message
+\&                     if true, suppress the startup message
+\&  keep_source_where  directory in which to keep the source (if we do)
+\&  load_module_verbosity
+\&                     report loading of optional modules used by CPAN.pm
+\&  lynx               path to external prg
+\&  make               location of external make program
+\&  make_arg           arguments that should always be passed to \*(Aqmake\*(Aq
+\&  make_install_make_command
+\&                     the make command for running \*(Aqmake install\*(Aq, for
+\&                     example \*(Aqsudo make\*(Aq
+\&  make_install_arg   same as make_arg for \*(Aqmake install\*(Aq
+\&  makepl_arg         arguments passed to \*(Aqperl Makefile.PL\*(Aq
+\&  mbuild_arg         arguments passed to \*(Aq./Build\*(Aq
+\&  mbuild_install_arg arguments passed to \*(Aq./Build install\*(Aq
+\&  mbuild_install_build_command
+\&                     command to use instead of \*(Aq./Build\*(Aq when we are
+\&                     in the install stage, for example \*(Aqsudo ./Build\*(Aq
+\&  mbuildpl_arg       arguments passed to \*(Aqperl Build.PL\*(Aq
+\&  ncftp              path to external prg
+\&  ncftpget           path to external prg
+\&  no_proxy           don\*(Aqt proxy to these hosts/domains (comma separated list)
+\&  pager              location of external program more (or any pager)
+\&  password           your password if you CPAN server wants one
+\&  patch              path to external prg
+\&  patches_dir        local directory containing patch files
+\&  perl5lib_verbosity verbosity level for PERL5LIB additions
+\&  plugin_list        list of active hooks (see Plugin support above
+\&                     and the CPAN::Plugin module)
+\&  prefer_external_tar
+\&                     per default all untar operations are done with
+\&                     Archive::Tar; by setting this variable to true
+\&                     the external tar command is used if available
+\&  prefer_installer   legal values are MB and EUMM: if a module comes
+\&                     with both a Makefile.PL and a Build.PL, use the
+\&                     former (EUMM) or the latter (MB); if the module
+\&                     comes with only one of the two, that one will be
+\&                     used no matter the setting
+\&  prerequisites_policy
+\&                     what to do if you are missing module prerequisites
+\&                     (\*(Aqfollow\*(Aq automatically, \*(Aqask\*(Aq me, or \*(Aqignore\*(Aq)
+\&                     For \*(Aqfollow\*(Aq, also sets PERL_AUTOINSTALL and
+\&                     PERL_EXTUTILS_AUTOINSTALL for "\-\-defaultdeps" if
+\&                     not already set
+\&  prefs_dir          local directory to store per\-distro build options
+\&  proxy_user         username for accessing an authenticating proxy
+\&  proxy_pass         password for accessing an authenticating proxy
+\&  pushy_https        use https to cpan.org when possible, otherwise use http
+\&                     to cpan.org and issue a warning
+\&  randomize_urllist  add some randomness to the sequence of the urllist
+\&  recommends_policy  whether recommended prerequisites should be included
+\&  scan_cache         controls scanning of cache (\*(Aqatstart\*(Aq, \*(Aqatexit\*(Aq or \*(Aqnever\*(Aq)
+\&  shell              your favorite shell
+\&  show_unparsable_versions
+\&                     boolean if r command tells which modules are versionless
+\&  show_upload_date   boolean if commands should try to determine upload date
+\&  show_zero_versions boolean if r command tells for which modules $version==0
+\&  suggests_policy    whether suggested prerequisites should be included
+\&  tar                location of external program tar
+\&  tar_verbosity      verbosity level for the tar command
+\&  term_is_latin      deprecated: if true Unicode is translated to ISO\-8859\-1
+\&                     (and nonsense for characters outside latin range)
+\&  term_ornaments     boolean to turn ReadLine ornamenting on/off
+\&  test_report        email test reports (if CPAN::Reporter is installed)
+\&  trust_test_report_history
+\&                     skip testing when previously tested ok (according to
+\&                     CPAN::Reporter history)
+\&  unzip              location of external program unzip
+\&  urllist            arrayref to nearby CPAN sites (or equivalent locations)
+\&  urllist_ping_external
+\&                     use external ping command when autoselecting mirrors
+\&  urllist_ping_verbose
+\&                     increase verbosity when autoselecting mirrors
+\&  use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install
+\&  use_sqlite         use CPAN::SQLite for metadata storage (fast and lean)
+\&  username           your username if you CPAN server wants one
+\&  version_timeout    stops version parsing after this many seconds.
+\&                     Default is 15 secs. Set to 0 to disable.
+\&  wait_list          arrayref to a wait server to try (See CPAN::WAIT)
+\&  wget               path to external prg
+\&  yaml_load_code     enable YAML code deserialisation via CPAN::DeferredCode
+\&  yaml_module        which module to use to read/write YAML files
+.Ve
+.PP
+You can set and query each of these options interactively in the cpan
+shell with the \f(CW\*(C`o conf\*(C'\fR or the \f(CW\*(C`o conf init\*(C'\fR command as specified below.
+.ie n .IP """o conf <scalar option>""" 2
+.el .IP "\f(CWo conf <scalar option>\fR" 2
+.IX Item "o conf <scalar option>"
+prints the current value of the \fIscalar option\fR
+.ie n .IP """o conf <scalar option> <value>""" 2
+.el .IP "\f(CWo conf <scalar option> <value>\fR" 2
+.IX Item "o conf <scalar option> <value>"
+Sets the value of the \fIscalar option\fR to \fIvalue\fR
+.ie n .IP """o conf <list option>""" 2
+.el .IP "\f(CWo conf <list option>\fR" 2
+.IX Item "o conf <list option>"
+prints the current value of the \fIlist option\fR in MakeMaker's
+neatvalue format.
+.ie n .IP """o conf <list option> [shift|pop]""" 2
+.el .IP "\f(CWo conf <list option> [shift|pop]\fR" 2
+.IX Item "o conf <list option> [shift|pop]"
+shifts or pops the array in the \fIlist option\fR variable
+.ie n .IP """o conf <list option> [unshift|push|splice] <list>""" 2
+.el .IP "\f(CWo conf <list option> [unshift|push|splice] <list>\fR" 2
+.IX Item "o conf <list option> [unshift|push|splice] <list>"
+works like the corresponding perl commands.
+.IP "interactive editing: o conf init [MATCH|LIST]" 2
+.IX Item "interactive editing: o conf init [MATCH|LIST]"
+Runs an interactive configuration dialog for matching variables.
+Without argument runs the dialog over all supported config variables.
+To specify a MATCH the argument must be enclosed by slashes.
+.Sp
+Examples:
+.Sp
+.Vb 2
+\&  o conf init ftp_passive ftp_proxy
+\&  o conf init /color/
+.Ve
+.Sp
+Note: this method of setting config variables often provides more
+explanation about the functioning of a variable than the manpage.
+.SS "CPAN::anycwd($path): Note on config variable getcwd"
+.IX Subsection "CPAN::anycwd($path): Note on config variable getcwd"
+CPAN.pm changes the current working directory often and needs to
+determine its own current working directory. By default it uses
+Cwd::cwd, but if for some reason this doesn't work on your system,
+configure alternatives according to the following table:
+.IP cwd 4
+.IX Item "cwd"
+Calls Cwd::cwd
+.IP getcwd 4
+.IX Item "getcwd"
+Calls Cwd::getcwd
+.IP fastcwd 4
+.IX Item "fastcwd"
+Calls Cwd::fastcwd
+.IP getdcwd 4
+.IX Item "getdcwd"
+Calls Cwd::getdcwd
+.IP backtickcwd 4
+.IX Item "backtickcwd"
+Calls the external command cwd.
+.SS "Note on the format of the urllist parameter"
+.IX Subsection "Note on the format of the urllist parameter"
+urllist parameters are URLs according to RFC 1738. We do a little
+guessing if your URL is not compliant, but if you have problems with
+\&\f(CW\*(C`file\*(C'\fR URLs, please try the correct format. Either:
+.PP
+.Vb 1
+\&    file://localhost/whatever/ftp/pub/CPAN/
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&    file:///home/ftp/pub/CPAN/
+.Ve
+.SS "The urllist parameter has CD-ROM support"
+.IX Subsection "The urllist parameter has CD-ROM support"
+The \f(CW\*(C`urllist\*(C'\fR parameter of the configuration table contains a list of
+URLs used for downloading. If the list contains any
+\&\f(CW\*(C`file\*(C'\fR URLs, CPAN always tries there first. This
+feature is disabled for index files. So the recommendation for the
+owner of a CD-ROM with CPAN contents is: include your local, possibly
+outdated CD-ROM as a \f(CW\*(C`file\*(C'\fR URL at the end of urllist, e.g.
+.PP
+.Vb 1
+\&  o conf urllist push file://localhost/CDROM/CPAN
+.Ve
+.PP
+CPAN.pm will then fetch the index files from one of the CPAN sites
+that come at the beginning of urllist. It will later check for each
+module to see whether there is a local copy of the most recent version.
+.PP
+Another peculiarity of urllist is that the site that we could
+successfully fetch the last file from automatically gets a preference
+token and is tried as the first site for the next request. So if you
+add a new site at runtime it may happen that the previously preferred
+site will be tried another time. This means that if you want to disallow
+a site for the next transfer, it must be explicitly removed from
+urllist.
+.SS "Maintaining the urllist parameter"
+.IX Subsection "Maintaining the urllist parameter"
+If you have YAML.pm (or some other YAML module configured in
+\&\f(CW\*(C`yaml_module\*(C'\fR) installed, CPAN.pm collects a few statistical data
+about recent downloads. You can view the statistics with the \f(CW\*(C`hosts\*(C'\fR
+command or inspect them directly by looking into the \f(CW\*(C`FTPstats.yml\*(C'\fR
+file in your \f(CW\*(C`cpan_home\*(C'\fR directory.
+.PP
+To get some interesting statistics, it is recommended that
+\&\f(CW\*(C`randomize_urllist\*(C'\fR be set; this introduces some amount of
+randomness into the URL selection.
+.ie n .SS "The ""requires"" and ""build_requires"" dependency declarations"
+.el .SS "The \f(CWrequires\fP and \f(CWbuild_requires\fP dependency declarations"
+.IX Subsection "The requires and build_requires dependency declarations"
+Since CPAN.pm version 1.88_51 modules declared as \f(CW\*(C`build_requires\*(C'\fR by
+a distribution are treated differently depending on the config
+variable \f(CW\*(C`build_requires_install_policy\*(C'\fR. By setting
+\&\f(CW\*(C`build_requires_install_policy\*(C'\fR to \f(CW\*(C`no\*(C'\fR, such a module is not
+installed. It is only built and tested, and then kept in the list of
+tested but uninstalled modules. As such, it is available during the
+build of the dependent module by integrating the path to the
+\&\f(CW\*(C`blib/arch\*(C'\fR and \f(CW\*(C`blib/lib\*(C'\fR directories in the environment variable
+PERL5LIB. If \f(CW\*(C`build_requires_install_policy\*(C'\fR is set to \f(CW\*(C`yes\*(C'\fR, then
+both modules declared as \f(CW\*(C`requires\*(C'\fR and those declared as
+\&\f(CW\*(C`build_requires\*(C'\fR are treated alike. By setting to \f(CW\*(C`ask/yes\*(C'\fR or
+\&\f(CW\*(C`ask/no\*(C'\fR, CPAN.pm asks the user and sets the default accordingly.
+.SS "Configuration of the allow_installing_* parameters"
+.IX Subsection "Configuration of the allow_installing_* parameters"
+The \f(CW\*(C`allow_installing_*\*(C'\fR parameters are evaluated during
+the \f(CW\*(C`make\*(C'\fR phase. If set to \f(CW\*(C`yes\*(C'\fR, they allow the testing and the installation of
+the current distro and otherwise have no effect. If set to \f(CW\*(C`no\*(C'\fR, they
+may abort the build (preventing testing and installing), depending on the contents of the
+\&\f(CW\*(C`blib/\*(C'\fR directory. The \f(CW\*(C`blib/\*(C'\fR directory is the directory that holds
+all the files that would usually be installed in the \f(CW\*(C`install\*(C'\fR phase.
+.PP
+\&\f(CW\*(C`allow_installing_outdated_dists\*(C'\fR compares the \f(CW\*(C`blib/\*(C'\fR directory with the CPAN index.
+If it finds something there that belongs, according to the index, to a different
+dist, it aborts the current build.
+.PP
+\&\f(CW\*(C`allow_installing_module_downgrades\*(C'\fR compares the \f(CW\*(C`blib/\*(C'\fR directory
+with already installed modules, actually their version numbers, as
+determined by ExtUtils::MakeMaker or equivalent. If a to-be-installed
+module would downgrade an already installed module, the current build
+is aborted.
+.PP
+An interesting twist occurs when a distroprefs document demands the
+installation of an outdated dist via goto while
+\&\f(CW\*(C`allow_installing_outdated_dists\*(C'\fR forbids it. Without additional
+provisions, this would let the \f(CW\*(C`allow_installing_outdated_dists\*(C'\fR
+win and the distroprefs lose. So the proper arrangement in such a case
+is to write a second distroprefs document for the distro that \f(CW\*(C`goto\*(C'\fR
+points to and overrule the \f(CW\*(C`cpanconfig\*(C'\fR there. E.g.:
+.PP
+.Vb 9
+\&  \-\-\-
+\&  match:
+\&    distribution: "^MAUKE/Keyword\-Simple\-0.04.tar.gz"
+\&  goto: "MAUKE/Keyword\-Simple\-0.03.tar.gz"
+\&  \-\-\-
+\&  match:
+\&    distribution: "^MAUKE/Keyword\-Simple\-0.03.tar.gz"
+\&  cpanconfig:
+\&    allow_installing_outdated_dists: yes
+.Ve
+.SS "Configuration for individual distributions (\fIDistroprefs\fP)"
+.IX Subsection "Configuration for individual distributions (Distroprefs)"
+(\fBNote:\fR This feature has been introduced in CPAN.pm 1.8854)
+.PP
+Distributions on CPAN usually behave according to what we call the
+CPAN mantra. Or since the advent of Module::Build we should talk about
+two mantras:
+.PP
+.Vb 4
+\&    perl Makefile.PL     perl Build.PL
+\&    make                 ./Build
+\&    make test            ./Build test
+\&    make install         ./Build install
+.Ve
+.PP
+But some modules cannot be built with this mantra. They try to get
+some extra data from the user via the environment, extra arguments, or
+interactively\-\-thus disturbing the installation of large bundles like
+Phalanx100 or modules with many dependencies like Plagger.
+.PP
+The distroprefs system of \f(CW\*(C`CPAN.pm\*(C'\fR addresses this problem by
+allowing the user to specify extra informations and recipes in YAML
+files to either
+.IP \(bu 4
+pass additional arguments to one of the four commands,
+.IP \(bu 4
+set environment variables
+.IP \(bu 4
+instantiate an Expect object that reads from the console, waits for
+some regular expressions and enters some answers
+.IP \(bu 4
+temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables
+.IP \(bu 4
+specify dependencies the original maintainer forgot
+.IP \(bu 4
+disable the installation of an object altogether
+.PP
+See the YAML and Data::Dumper files that come with the \f(CW\*(C`CPAN.pm\*(C'\fR
+distribution in the \f(CW\*(C`distroprefs/\*(C'\fR directory for examples.
+.SS Filenames
+.IX Subsection "Filenames"
+The YAML files themselves must have the \f(CW\*(C`.yml\*(C'\fR extension; all other
+files are ignored (for two exceptions see \fIFallback Data::Dumper and
+Storable\fR below). The containing directory can be specified in
+\&\f(CW\*(C`CPAN.pm\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR config variable. Try \f(CW\*(C`o conf init
+prefs_dir\*(C'\fR in the CPAN shell to set and activate the distroprefs
+system.
+.PP
+Every YAML file may contain arbitrary documents according to the YAML
+specification, and every document is treated as an entity that
+can specify the treatment of a single distribution.
+.PP
+Filenames can be picked arbitrarily; \f(CW\*(C`CPAN.pm\*(C'\fR always reads
+all files (in alphabetical order) and takes the key \f(CW\*(C`match\*(C'\fR (see
+below in \fILanguage Specs\fR) as a hashref containing match criteria
+that determine if the current distribution matches the YAML document
+or not.
+.SS "Fallback Data::Dumper and Storable"
+.IX Subsection "Fallback Data::Dumper and Storable"
+If neither your configured \f(CW\*(C`yaml_module\*(C'\fR nor YAML.pm is installed,
+CPAN.pm falls back to using Data::Dumper and Storable and looks for
+files with the extensions \f(CW\*(C`.dd\*(C'\fR or \f(CW\*(C`.st\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR
+directory. These files are expected to contain one or more hashrefs.
+For Data::Dumper generated files, this is expected to be done with by
+defining \f(CW$VAR1\fR, \f(CW$VAR2\fR, etc. The YAML shell would produce these
+with the command
+.PP
+.Vb 1
+\&    ysh < somefile.yml > somefile.dd
+.Ve
+.PP
+For Storable files the rule is that they must be constructed such that
+\&\f(CWStorable::retrieve(file)\fR returns an array reference and the array
+elements represent one distropref object each. The conversion from
+YAML would look like so:
+.PP
+.Vb 3
+\&    perl \-MYAML=LoadFile \-MStorable=nstore \-e \*(Aq
+\&        @y=LoadFile(shift);
+\&        nstore(\e@y, shift)\*(Aq somefile.yml somefile.st
+.Ve
+.PP
+In bootstrapping situations it is usually sufficient to translate only
+a few YAML files to Data::Dumper for crucial modules like
+\&\f(CW\*(C`YAML::Syck\*(C'\fR, \f(CW\*(C`YAML.pm\*(C'\fR and \f(CW\*(C`Expect.pm\*(C'\fR. If you prefer Storable
+over Data::Dumper, remember to pull out a Storable version that writes
+an older format than all the other Storable versions that will need to
+read them.
+.SS Blueprint
+.IX Subsection "Blueprint"
+The following example contains all supported keywords and structures
+with the exception of \f(CW\*(C`eexpect\*(C'\fR which can be used instead of
+\&\f(CW\*(C`expect\*(C'\fR.
+.PP
+.Vb 10
+\&  \-\-\-
+\&  comment: "Demo"
+\&  match:
+\&    module: "Dancing::Queen"
+\&    distribution: "^CHACHACHA/Dancing\-"
+\&    not_distribution: "\e.zip$"
+\&    perl: "/usr/local/cariba\-perl/bin/perl"
+\&    perlconfig:
+\&      archname: "freebsd"
+\&      not_cc: "gcc"
+\&    env:
+\&      DANCING_FLOOR: "Shubiduh"
+\&  disabled: 1
+\&  cpanconfig:
+\&    make: gmake
+\&  pl:
+\&    args:
+\&      \- "\-\-somearg=specialcase"
+\&
+\&    env: {}
+\&
+\&    expect:
+\&      \- "Which is your favorite fruit"
+\&      \- "apple\en"
+\&
+\&  make:
+\&    args:
+\&      \- all
+\&      \- extra\-all
+\&
+\&    env: {}
+\&
+\&    expect: []
+\&
+\&    commandline: "echo SKIPPING make"
+\&
+\&  test:
+\&    args: []
+\&
+\&    env: {}
+\&
+\&    expect: []
+\&
+\&  install:
+\&    args: []
+\&
+\&    env:
+\&      WANT_TO_INSTALL: YES
+\&
+\&    expect:
+\&      \- "Do you really want to install"
+\&      \- "y\en"
+\&
+\&  patches:
+\&    \- "ABCDE/Fedcba\-3.14\-ABCDE\-01.patch"
+\&
+\&  depends:
+\&    configure_requires:
+\&      LWP: 5.8
+\&    build_requires:
+\&      Test::Exception: 0.25
+\&    requires:
+\&      Spiffy: 0.30
+.Ve
+.SS "Language Specs"
+.IX Subsection "Language Specs"
+Every YAML document represents a single hash reference. The valid keys
+in this hash are as follows:
+.IP "comment [scalar]" 4
+.IX Item "comment [scalar]"
+A comment
+.IP "cpanconfig [hash]" 4
+.IX Item "cpanconfig [hash]"
+Temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables.
+.Sp
+Supported are: \f(CW\*(C`build_requires_install_policy\*(C'\fR, \f(CW\*(C`check_sigs\*(C'\fR,
+\&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make_install_make_command\*(C'\fR, \f(CW\*(C`prefer_installer\*(C'\fR,
+\&\f(CW\*(C`test_report\*(C'\fR. Please report as a bug when you need another one
+supported.
+.IP "depends [hash] *** EXPERIMENTAL FEATURE ***" 4
+.IX Item "depends [hash] *** EXPERIMENTAL FEATURE ***"
+All three types, namely \f(CW\*(C`configure_requires\*(C'\fR, \f(CW\*(C`build_requires\*(C'\fR, and
+\&\f(CW\*(C`requires\*(C'\fR are supported in the way specified in the META.yml
+specification. The current implementation \fImerges\fR the specified
+dependencies with those declared by the package maintainer. In a
+future implementation this may be changed to override the original
+declaration.
+.IP "disabled [boolean]" 4
+.IX Item "disabled [boolean]"
+Specifies that this distribution shall not be processed at all.
+.IP "features [array] *** EXPERIMENTAL FEATURE ***" 4
+.IX Item "features [array] *** EXPERIMENTAL FEATURE ***"
+Experimental implementation to deal with optional_features from
+META.yml. Still needs coordination with installer software and
+currently works only for META.yml declaring \f(CW\*(C`dynamic_config=0\*(C'\fR. Use
+with caution.
+.IP "goto [string]" 4
+.IX Item "goto [string]"
+The canonical name of a delegate distribution to install
+instead. Useful when a new version, although it tests OK itself,
+breaks something else or a developer release or a fork is already
+uploaded that is better than the last released version.
+.IP "install [hash]" 4
+.IX Item "install [hash]"
+Processing instructions for the \f(CW\*(C`make install\*(C'\fR or \f(CW\*(C`./Build install\*(C'\fR
+phase of the CPAN mantra. See below under \fIProcessing Instructions\fR.
+.IP "make [hash]" 4
+.IX Item "make [hash]"
+Processing instructions for the \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`./Build\*(C'\fR phase of the
+CPAN mantra. See below under \fIProcessing Instructions\fR.
+.IP "match [hash]" 4
+.IX Item "match [hash]"
+A hashref with one or more of the keys \f(CW\*(C`distribution\*(C'\fR, \f(CW\*(C`module\*(C'\fR,
+\&\f(CW\*(C`perl\*(C'\fR, \f(CW\*(C`perlconfig\*(C'\fR, and \f(CW\*(C`env\*(C'\fR that specify whether a document is
+targeted at a specific CPAN distribution or installation.
+Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
+.Sp
+The corresponding values are interpreted as regular expressions. The
+\&\f(CW\*(C`distribution\*(C'\fR related one will be matched against the canonical
+distribution name, e.g. "AUTHOR/Foo\-Bar\-3.14.tar.gz".
+.Sp
+The \f(CW\*(C`module\*(C'\fR related one will be matched against \fIall\fR modules
+contained in the distribution until one module matches.
+.Sp
+The \f(CW\*(C`perl\*(C'\fR related one will be matched against \f(CW$^X\fR (but with the
+absolute path).
+.Sp
+The value associated with \f(CW\*(C`perlconfig\*(C'\fR is itself a hashref that is
+matched against corresponding values in the \f(CW%Config::Config\fR hash
+living in the \f(CW\*(C`Config.pm\*(C'\fR module.
+Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
+.Sp
+The value associated with \f(CW\*(C`env\*(C'\fR is itself a hashref that is
+matched against corresponding values in the \f(CW%ENV\fR hash.
+Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match.
+.Sp
+If more than one restriction of \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`distribution\*(C'\fR, etc. is
+specified, the results of the separately computed match values must
+all match. If so, the hashref represented by the
+YAML document is returned as the preference structure for the current
+distribution.
+.IP "patches [array]" 4
+.IX Item "patches [array]"
+An array of patches on CPAN or on the local disk to be applied in
+order via an external patch program. If the value for the \f(CW\*(C`\-p\*(C'\fR
+parameter is \f(CW0\fR or \f(CW1\fR is determined by reading the patch
+beforehand. The path to each patch is either an absolute path on the
+local filesystem or relative to a patch directory specified in the
+\&\f(CW\*(C`patches_dir\*(C'\fR configuration variable or in the format of a canonical
+distro name. For examples please consult the distroprefs/ directory in
+the CPAN.pm distribution (these examples are not installed by
+default).
+.Sp
+Note: if the \f(CW\*(C`applypatch\*(C'\fR program is installed and \f(CW\*(C`CPAN::Config\*(C'\fR
+knows about it \fBand\fR a patch is written by the \f(CW\*(C`makepatch\*(C'\fR program,
+then \f(CW\*(C`CPAN.pm\*(C'\fR lets \f(CW\*(C`applypatch\*(C'\fR apply the patch. Both \f(CW\*(C`makepatch\*(C'\fR
+and \f(CW\*(C`applypatch\*(C'\fR are available from CPAN in the \f(CW\*(C`JV/makepatch\-*\*(C'\fR
+distribution.
+.IP "pl [hash]" 4
+.IX Item "pl [hash]"
+Processing instructions for the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl
+Build.PL\*(C'\fR phase of the CPAN mantra. See below under \fIProcessing
+Instructions\fR.
+.IP "test [hash]" 4
+.IX Item "test [hash]"
+Processing instructions for the \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`./Build test\*(C'\fR phase
+of the CPAN mantra. See below under \fIProcessing Instructions\fR.
+.SS "Processing Instructions"
+.IX Subsection "Processing Instructions"
+.IP "args [array]" 4
+.IX Item "args [array]"
+Arguments to be added to the command line
+.IP commandline 4
+.IX Item "commandline"
+A full commandline to run via \f(CWsystem()\fR.
+During execution, the environment variable PERL is set
+to $^X (but with an absolute path). If \f(CW\*(C`commandline\*(C'\fR is specified,
+\&\f(CW\*(C`args\*(C'\fR is not used.
+.IP "eexpect [hash]" 4
+.IX Item "eexpect [hash]"
+Extended \f(CW\*(C`expect\*(C'\fR. This is a hash reference with four allowed keys,
+\&\f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, \f(CW\*(C`reuse\*(C'\fR, and \f(CW\*(C`talk\*(C'\fR.
+.Sp
+You must install the \f(CW\*(C`Expect\*(C'\fR module to use \f(CW\*(C`eexpect\*(C'\fR. CPAN.pm
+does not install it for you.
+.Sp
+\&\f(CW\*(C`mode\*(C'\fR may have the values \f(CW\*(C`deterministic\*(C'\fR for the case where all
+questions come in the order written down and \f(CW\*(C`anyorder\*(C'\fR for the case
+where the questions may come in any order. The default mode is
+\&\f(CW\*(C`deterministic\*(C'\fR.
+.Sp
+\&\f(CW\*(C`timeout\*(C'\fR denotes a timeout in seconds. Floating-point timeouts are
+OK. With \f(CW\*(C`mode=deterministic\*(C'\fR, the timeout denotes the
+timeout per question; with \f(CW\*(C`mode=anyorder\*(C'\fR it denotes the
+timeout per byte received from the stream or questions.
+.Sp
+\&\f(CW\*(C`talk\*(C'\fR is a reference to an array that contains alternating questions
+and answers. Questions are regular expressions and answers are literal
+strings. The Expect module watches the stream from the
+execution of the external program (\f(CW\*(C`perl Makefile.PL\*(C'\fR, \f(CW\*(C`perl
+Build.PL\*(C'\fR, \f(CW\*(C`make\*(C'\fR, etc.).
+.Sp
+For \f(CW\*(C`mode=deterministic\*(C'\fR, the CPAN.pm injects the
+corresponding answer as soon as the stream matches the regular expression.
+.Sp
+For \f(CW\*(C`mode=anyorder\*(C'\fR CPAN.pm answers a question as soon
+as the timeout is reached for the next byte in the input stream. In
+this mode you can use the \f(CW\*(C`reuse\*(C'\fR parameter to decide what will
+happen with a question-answer pair after it has been used. In the
+default case (reuse=0) it is removed from the array, avoiding being
+used again accidentally. If you want to answer the
+question \f(CW\*(C`Do you really want to do that\*(C'\fR several times, then it must
+be included in the array at least as often as you want this answer to
+be given. Setting the parameter \f(CW\*(C`reuse\*(C'\fR to 1 makes this repetition
+unnecessary.
+.IP "env [hash]" 4
+.IX Item "env [hash]"
+Environment variables to be set during the command
+.IP "expect [array]" 4
+.IX Item "expect [array]"
+You must install the \f(CW\*(C`Expect\*(C'\fR module to use \f(CW\*(C`expect\*(C'\fR. CPAN.pm
+does not install it for you.
+.Sp
+\&\f(CW\*(C`expect: <array>\*(C'\fR is a short notation for this \f(CW\*(C`eexpect\*(C'\fR:
+.Sp
+.Vb 4
+\&        eexpect:
+\&                mode: deterministic
+\&                timeout: 15
+\&                talk: <array>
+.Ve
+.ie n .SS "Schema verification with ""Kwalify"""
+.el .SS "Schema verification with \f(CWKwalify\fP"
+.IX Subsection "Schema verification with Kwalify"
+If you have the \f(CW\*(C`Kwalify\*(C'\fR module installed (which is part of the
+Bundle::CPANxxl), then all your distroprefs files are checked for
+syntactic correctness.
+.SS "Example Distroprefs Files"
+.IX Subsection "Example Distroprefs Files"
+\&\f(CW\*(C`CPAN.pm\*(C'\fR comes with a collection of example YAML files. Note that these
+are really just examples and should not be used without care because
+they cannot fit everybody's purpose. After all, the authors of the
+packages that ask questions had a need to ask, so you should watch
+their questions and adjust the examples to your environment and your
+needs. You have been warned:\-)
+.SH "PROGRAMMER'S INTERFACE"
+.IX Header "PROGRAMMER'S INTERFACE"
+If you do not enter the shell, shell commands are
+available both as methods (\f(CW\*(C`CPAN::Shell\->install(...)\*(C'\fR) and as
+functions in the calling package (\f(CWinstall(...)\fR).  Before calling low-level
+commands, it makes sense to initialize components of CPAN you need, e.g.:
+.PP
+.Vb 3
+\&  CPAN::HandleConfig\->load;
+\&  CPAN::Shell::setup_output;
+\&  CPAN::Index\->reload;
+.Ve
+.PP
+High-level commands do such initializations automatically.
+.PP
+There's currently only one class that has a stable interface \-
+CPAN::Shell. All commands that are available in the CPAN shell are
+methods of the class CPAN::Shell. The arguments on the commandline are
+passed as arguments to the method.
+.PP
+So if you take for example the shell command
+.PP
+.Vb 1
+\&  notest install A B C
+.Ve
+.PP
+the actually executed command is
+.PP
+.Vb 1
+\&  CPAN::Shell\->notest("install","A","B","C");
+.Ve
+.PP
+Each of the commands that produce listings of modules (\f(CW\*(C`r\*(C'\fR,
+\&\f(CW\*(C`autobundle\*(C'\fR, \f(CW\*(C`u\*(C'\fR) also return a list of the IDs of all modules
+within the list.
+.IP expand($type,@things) 2
+.IX Item "expand($type,@things)"
+The IDs of all objects available within a program are strings that can
+be expanded to the corresponding real objects with the
+\&\f(CW\*(C`CPAN::Shell\->expand("Module",@things)\*(C'\fR method. Expand returns a
+list of CPAN::Module objects according to the \f(CW@things\fR arguments
+given. In scalar context, it returns only the first element of the
+list.
+.IP expandany(@things) 2
+.IX Item "expandany(@things)"
+Like expand, but returns objects of the appropriate type, i.e.
+CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and
+CPAN::Distribution objects for distributions. Note: it does not expand
+to CPAN::Author objects.
+.IP "Programming Examples" 2
+.IX Item "Programming Examples"
+This enables the programmer to do operations that combine
+functionalities that are available in the shell.
+.Sp
+.Vb 2
+\&    # install everything that is outdated on my disk:
+\&    perl \-MCPAN \-e \*(AqCPAN::Shell\->install(CPAN::Shell\->r)\*(Aq
+\&
+\&    # install my favorite programs if necessary:
+\&    for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) {
+\&        CPAN::Shell\->install($mod);
+\&    }
+\&
+\&    # list all modules on my disk that have no VERSION number
+\&    for $mod (CPAN::Shell\->expand("Module","/./")) {
+\&        next unless $mod\->inst_file;
+\&        # MakeMaker convention for undefined $VERSION:
+\&        next unless $mod\->inst_version eq "undef";
+\&        print "No VERSION in ", $mod\->id, "\en";
+\&    }
+\&
+\&    # find out which distribution on CPAN contains a module:
+\&    print CPAN::Shell\->expand("Module","Apache::Constants")\->cpan_file
+.Ve
+.Sp
+Or if you want to schedule a \fIcron\fR job to watch CPAN, you could list
+all modules that need updating. First a quick and dirty way:
+.Sp
+.Vb 1
+\&    perl \-e \*(Aquse CPAN; CPAN::Shell\->r;\*(Aq
+.Ve
+.Sp
+If you don't want any output should all modules be
+up to date, parse the output of above command for the regular
+expression \f(CW\*(C`/modules are up to date/\*(C'\fR and decide to mail the output
+only if it doesn't match.
+.Sp
+If you prefer to do it more in a programmerish style in one single
+process, something like this may better suit you:
+.Sp
+.Vb 7
+\&  # list all modules on my disk that have newer versions on CPAN
+\&  for $mod (CPAN::Shell\->expand("Module","/./")) {
+\&    next unless $mod\->inst_file;
+\&    next if $mod\->uptodate;
+\&    printf "Module %s is installed as %s, could be updated to %s from CPAN\en",
+\&        $mod\->id, $mod\->inst_version, $mod\->cpan_version;
+\&  }
+.Ve
+.Sp
+If that gives too much output every day, you may want to
+watch only for three modules. You can write
+.Sp
+.Vb 1
+\&  for $mod (CPAN::Shell\->expand("Module","/Apache|LWP|CGI/")) {
+.Ve
+.Sp
+as the first line instead. Or you can combine some of the above
+tricks:
+.Sp
+.Vb 5
+\&  # watch only for a new mod_perl module
+\&  $mod = CPAN::Shell\->expand("Module","mod_perl");
+\&  exit if $mod\->uptodate;
+\&  # new mod_perl arrived, let me know all update recommendations
+\&  CPAN::Shell\->r;
+.Ve
+.SS "Methods in the other Classes"
+.IX Subsection "Methods in the other Classes"
+.IP \fBCPAN::Author::as_glimpse()\fR 4
+.IX Item "CPAN::Author::as_glimpse()"
+Returns a one-line description of the author
+.IP \fBCPAN::Author::as_string()\fR 4
+.IX Item "CPAN::Author::as_string()"
+Returns a multi-line description of the author
+.IP \fBCPAN::Author::email()\fR 4
+.IX Item "CPAN::Author::email()"
+Returns the author's email address
+.IP \fBCPAN::Author::fullname()\fR 4
+.IX Item "CPAN::Author::fullname()"
+Returns the author's name
+.IP \fBCPAN::Author::name()\fR 4
+.IX Item "CPAN::Author::name()"
+An alias for fullname
+.IP \fBCPAN::Bundle::as_glimpse()\fR 4
+.IX Item "CPAN::Bundle::as_glimpse()"
+Returns a one-line description of the bundle
+.IP \fBCPAN::Bundle::as_string()\fR 4
+.IX Item "CPAN::Bundle::as_string()"
+Returns a multi-line description of the bundle
+.IP \fBCPAN::Bundle::clean()\fR 4
+.IX Item "CPAN::Bundle::clean()"
+Recursively runs the \f(CW\*(C`clean\*(C'\fR method on all items contained in the bundle.
+.IP \fBCPAN::Bundle::contains()\fR 4
+.IX Item "CPAN::Bundle::contains()"
+Returns a list of objects' IDs contained in a bundle. The associated
+objects may be bundles, modules or distributions.
+.IP CPAN::Bundle::force($method,@args) 4
+.IX Item "CPAN::Bundle::force($method,@args)"
+Forces CPAN to perform a task that it normally would have refused to
+do. Force takes as arguments a method name to be called and any number
+of additional arguments that should be passed to the called method.
+The internals of the object get the needed changes so that CPAN.pm
+does not refuse to take the action. The \f(CW\*(C`force\*(C'\fR is passed recursively
+to all contained objects. See also the section above on the \f(CW\*(C`force\*(C'\fR
+and the \f(CW\*(C`fforce\*(C'\fR pragma.
+.IP \fBCPAN::Bundle::get()\fR 4
+.IX Item "CPAN::Bundle::get()"
+Recursively runs the \f(CW\*(C`get\*(C'\fR method on all items contained in the bundle
+.IP \fBCPAN::Bundle::inst_file()\fR 4
+.IX Item "CPAN::Bundle::inst_file()"
+Returns the highest installed version of the bundle in either \f(CW@INC\fR or
+\&\f(CW\*(C`$CPAN::Config\->{cpan_home}\*(C'\fR. Note that this is different from
+CPAN::Module::inst_file.
+.IP \fBCPAN::Bundle::inst_version()\fR 4
+.IX Item "CPAN::Bundle::inst_version()"
+Like CPAN::Bundle::inst_file, but returns the \f(CW$VERSION\fR
+.IP \fBCPAN::Bundle::uptodate()\fR 4
+.IX Item "CPAN::Bundle::uptodate()"
+Returns 1 if the bundle itself and all its members are up-to-date.
+.IP \fBCPAN::Bundle::install()\fR 4
+.IX Item "CPAN::Bundle::install()"
+Recursively runs the \f(CW\*(C`install\*(C'\fR method on all items contained in the bundle
+.IP \fBCPAN::Bundle::make()\fR 4
+.IX Item "CPAN::Bundle::make()"
+Recursively runs the \f(CW\*(C`make\*(C'\fR method on all items contained in the bundle
+.IP \fBCPAN::Bundle::readme()\fR 4
+.IX Item "CPAN::Bundle::readme()"
+Recursively runs the \f(CW\*(C`readme\*(C'\fR method on all items contained in the bundle
+.IP \fBCPAN::Bundle::test()\fR 4
+.IX Item "CPAN::Bundle::test()"
+Recursively runs the \f(CW\*(C`test\*(C'\fR method on all items contained in the bundle
+.IP \fBCPAN::Distribution::as_glimpse()\fR 4
+.IX Item "CPAN::Distribution::as_glimpse()"
+Returns a one-line description of the distribution
+.IP \fBCPAN::Distribution::as_string()\fR 4
+.IX Item "CPAN::Distribution::as_string()"
+Returns a multi-line description of the distribution
+.IP CPAN::Distribution::author 4
+.IX Item "CPAN::Distribution::author"
+Returns the CPAN::Author object of the maintainer who uploaded this
+distribution
+.IP \fBCPAN::Distribution::pretty_id()\fR 4
+.IX Item "CPAN::Distribution::pretty_id()"
+Returns a string of the form "AUTHORID/TARBALL", where AUTHORID is the
+author's PAUSE ID and TARBALL is the distribution filename.
+.IP \fBCPAN::Distribution::base_id()\fR 4
+.IX Item "CPAN::Distribution::base_id()"
+Returns the distribution filename without any archive suffix.  E.g
+"Foo\-Bar\-0.01"
+.IP \fBCPAN::Distribution::clean()\fR 4
+.IX Item "CPAN::Distribution::clean()"
+Changes to the directory where the distribution has been unpacked and
+runs \f(CW\*(C`make clean\*(C'\fR there.
+.IP \fBCPAN::Distribution::containsmods()\fR 4
+.IX Item "CPAN::Distribution::containsmods()"
+Returns a list of IDs of modules contained in a distribution file.
+Works only for distributions listed in the 02packages.details.txt.gz
+file. This typically means that just most recent version of a
+distribution is covered.
+.IP \fBCPAN::Distribution::cvs_import()\fR 4
+.IX Item "CPAN::Distribution::cvs_import()"
+Changes to the directory where the distribution has been unpacked and
+runs something like
+.Sp
+.Vb 1
+\&    cvs \-d $cvs_root import \-m $cvs_log $cvs_dir $userid v$version
+.Ve
+.Sp
+there.
+.IP \fBCPAN::Distribution::dir()\fR 4
+.IX Item "CPAN::Distribution::dir()"
+Returns the directory into which this distribution has been unpacked.
+.IP CPAN::Distribution::force($method,@args) 4
+.IX Item "CPAN::Distribution::force($method,@args)"
+Forces CPAN to perform a task that it normally would have refused to
+do. Force takes as arguments a method name to be called and any number
+of additional arguments that should be passed to the called method.
+The internals of the object get the needed changes so that CPAN.pm
+does not refuse to take the action. See also the section above on the
+\&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
+.IP \fBCPAN::Distribution::get()\fR 4
+.IX Item "CPAN::Distribution::get()"
+Downloads the distribution from CPAN and unpacks it. Does nothing if
+the distribution has already been downloaded and unpacked within the
+current session.
+.IP \fBCPAN::Distribution::install()\fR 4
+.IX Item "CPAN::Distribution::install()"
+Changes to the directory where the distribution has been unpacked and
+runs the external command \f(CW\*(C`make install\*(C'\fR there. If \f(CW\*(C`make\*(C'\fR has not
+yet been run, it will be run first. A \f(CW\*(C`make test\*(C'\fR is issued in
+any case and if this fails, the install is cancelled. The
+cancellation can be avoided by letting \f(CW\*(C`force\*(C'\fR run the \f(CW\*(C`install\*(C'\fR for
+you.
+.Sp
+This install method only has the power to install the distribution if
+there are no dependencies in the way. To install an object along with all
+its dependencies, use CPAN::Shell\->install.
+.Sp
+Note that \fBinstall()\fR gives no meaningful return value. See \fBuptodate()\fR.
+.IP \fBCPAN::Distribution::isa_perl()\fR 4
+.IX Item "CPAN::Distribution::isa_perl()"
+Returns 1 if this distribution file seems to be a perl distribution.
+Normally this is derived from the file name only, but the index from
+CPAN can contain a hint to achieve a return value of true for other
+filenames too.
+.IP \fBCPAN::Distribution::look()\fR 4
+.IX Item "CPAN::Distribution::look()"
+Changes to the directory where the distribution has been unpacked and
+opens a subshell there. Exiting the subshell returns.
+.IP \fBCPAN::Distribution::make()\fR 4
+.IX Item "CPAN::Distribution::make()"
+First runs the \f(CW\*(C`get\*(C'\fR method to make sure the distribution is
+downloaded and unpacked. Changes to the directory where the
+distribution has been unpacked and runs the external commands \f(CW\*(C`perl
+Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR and \f(CW\*(C`make\*(C'\fR there.
+.IP \fBCPAN::Distribution::perldoc()\fR 4
+.IX Item "CPAN::Distribution::perldoc()"
+Downloads the pod documentation of the file associated with a
+distribution (in HTML format) and runs it through the external
+command \fIlynx\fR specified in \f(CW\*(C`$CPAN::Config\->{lynx}\*(C'\fR. If \fIlynx\fR
+isn't available, it converts it to plain text with the external
+command \fIhtml2text\fR and runs it through the pager specified
+in \f(CW\*(C`$CPAN::Config\->{pager}\*(C'\fR.
+.IP \fBCPAN::Distribution::prefs()\fR 4
+.IX Item "CPAN::Distribution::prefs()"
+Returns the hash reference from the first matching YAML file that the
+user has deposited in the \f(CW\*(C`prefs_dir/\*(C'\fR directory. The first
+succeeding match wins. The files in the \f(CW\*(C`prefs_dir/\*(C'\fR are processed
+alphabetically, and the canonical distro name (e.g.
+AUTHOR/Foo\-Bar\-3.14.tar.gz) is matched against the regular expressions
+stored in the \f(CW$root\fR\->{match}{distribution} attribute value.
+Additionally all module names contained in a distribution are matched
+against the regular expressions in the \f(CW$root\fR\->{match}{module} attribute
+value. The two match values are ANDed together. Each of the two
+attributes are optional.
+.IP \fBCPAN::Distribution::prereq_pm()\fR 4
+.IX Item "CPAN::Distribution::prereq_pm()"
+Returns the hash reference that has been announced by a distribution
+as the \f(CW\*(C`requires\*(C'\fR and \f(CW\*(C`build_requires\*(C'\fR elements. These can be
+declared either by the \f(CW\*(C`META.yml\*(C'\fR (if authoritative) or can be
+deposited after the run of \f(CW\*(C`Build.PL\*(C'\fR in the file \f(CW\*(C`./_build/prereqs\*(C'\fR
+or after the run of \f(CW\*(C`Makfile.PL\*(C'\fR written as the \f(CW\*(C`PREREQ_PM\*(C'\fR hash in
+a comment in the produced \f(CW\*(C`Makefile\*(C'\fR. \fINote\fR: this method only works
+after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns
+undef otherwise.
+.IP \fBCPAN::Distribution::readme()\fR 4
+.IX Item "CPAN::Distribution::readme()"
+Downloads the README file associated with a distribution and runs it
+through the pager specified in \f(CW\*(C`$CPAN::Config\->{pager}\*(C'\fR.
+.IP \fBCPAN::Distribution::reports()\fR 4
+.IX Item "CPAN::Distribution::reports()"
+Downloads report data for this distribution from www.cpantesters.org
+and displays a subset of them.
+.IP \fBCPAN::Distribution::read_yaml()\fR 4
+.IX Item "CPAN::Distribution::read_yaml()"
+Returns the content of the META.yml of this distro as a hashref. Note:
+works only after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution.
+Returns undef otherwise. Also returns undef if the content of META.yml
+is not authoritative. (The rules about what exactly makes the content
+authoritative are still in flux.)
+.IP \fBCPAN::Distribution::test()\fR 4
+.IX Item "CPAN::Distribution::test()"
+Changes to the directory where the distribution has been unpacked and
+runs \f(CW\*(C`make test\*(C'\fR there.
+.IP \fBCPAN::Distribution::uptodate()\fR 4
+.IX Item "CPAN::Distribution::uptodate()"
+Returns 1 if all the modules contained in the distribution are
+up-to-date. Relies on containsmods.
+.IP \fBCPAN::Index::force_reload()\fR 4
+.IX Item "CPAN::Index::force_reload()"
+Forces a reload of all indices.
+.IP \fBCPAN::Index::reload()\fR 4
+.IX Item "CPAN::Index::reload()"
+Reloads all indices if they have not been read for more than
+\&\f(CW\*(C`$CPAN::Config\->{index_expire}\*(C'\fR days.
+.IP \fBCPAN::InfoObj::dump()\fR 4
+.IX Item "CPAN::InfoObj::dump()"
+CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution
+inherit this method. It prints the data structure associated with an
+object. Useful for debugging. Note: the data structure is considered
+internal and thus subject to change without notice.
+.IP \fBCPAN::Module::as_glimpse()\fR 4
+.IX Item "CPAN::Module::as_glimpse()"
+Returns a one-line description of the module in four columns: The
+first column contains the word \f(CW\*(C`Module\*(C'\fR, the second column consists
+of one character: an equals sign if this module is already installed
+and up-to-date, a less-than sign if this module is installed but can be
+upgraded, and a space if the module is not installed. The third column
+is the name of the module and the fourth column gives maintainer or
+distribution information.
+.IP \fBCPAN::Module::as_string()\fR 4
+.IX Item "CPAN::Module::as_string()"
+Returns a multi-line description of the module
+.IP \fBCPAN::Module::clean()\fR 4
+.IX Item "CPAN::Module::clean()"
+Runs a clean on the distribution associated with this module.
+.IP \fBCPAN::Module::cpan_file()\fR 4
+.IX Item "CPAN::Module::cpan_file()"
+Returns the filename on CPAN that is associated with the module.
+.IP \fBCPAN::Module::cpan_version()\fR 4
+.IX Item "CPAN::Module::cpan_version()"
+Returns the latest version of this module available on CPAN.
+.IP \fBCPAN::Module::cvs_import()\fR 4
+.IX Item "CPAN::Module::cvs_import()"
+Runs a cvs_import on the distribution associated with this module.
+.IP \fBCPAN::Module::description()\fR 4
+.IX Item "CPAN::Module::description()"
+Returns a 44 character description of this module. Only available for
+modules listed in The Module List (CPAN/modules/00modlist.long.html
+or 00modlist.long.txt.gz)
+.IP \fBCPAN::Module::distribution()\fR 4
+.IX Item "CPAN::Module::distribution()"
+Returns the CPAN::Distribution object that contains the current
+version of this module.
+.IP \fBCPAN::Module::dslip_status()\fR 4
+.IX Item "CPAN::Module::dslip_status()"
+Returns a hash reference. The keys of the hash are the letters \f(CW\*(C`D\*(C'\fR,
+\&\f(CW\*(C`S\*(C'\fR, \f(CW\*(C`L\*(C'\fR, \f(CW\*(C`I\*(C'\fR, and <P>, for development status, support level,
+language, interface and public licence respectively. The data for the
+DSLIP status are collected by pause.perl.org when authors register
+their namespaces. The values of the 5 hash elements are one-character
+words whose meaning is described in the table below. There are also 5
+hash elements \f(CW\*(C`DV\*(C'\fR, \f(CW\*(C`SV\*(C'\fR, \f(CW\*(C`LV\*(C'\fR, \f(CW\*(C`IV\*(C'\fR, and <PV> that carry a more
+verbose value of the 5 status variables.
+.Sp
+Where the 'DSLIP' characters have the following meanings:
+.Sp
+.Vb 7
+\&  D \- Development Stage  (Note: *NO IMPLIED TIMESCALES*):
+\&    i   \- Idea, listed to gain consensus or as a placeholder
+\&    c   \- under construction but pre\-alpha (not yet released)
+\&    a/b \- Alpha/Beta testing
+\&    R   \- Released
+\&    M   \- Mature (no rigorous definition)
+\&    S   \- Standard, supplied with Perl 5
+\&
+\&  S \- Support Level:
+\&    m   \- Mailing\-list
+\&    d   \- Developer
+\&    u   \- Usenet newsgroup comp.lang.perl.modules
+\&    n   \- None known, try comp.lang.perl.modules
+\&    a   \- abandoned; volunteers welcome to take over maintenance
+\&
+\&  L \- Language Used:
+\&    p   \- Perl\-only, no compiler needed, should be platform independent
+\&    c   \- C and perl, a C compiler will be needed
+\&    h   \- Hybrid, written in perl with optional C code, no compiler needed
+\&    +   \- C++ and perl, a C++ compiler will be needed
+\&    o   \- perl and another language other than C or C++
+\&
+\&  I \- Interface Style
+\&    f   \- plain Functions, no references used
+\&    h   \- hybrid, object and function interfaces available
+\&    n   \- no interface at all (huh?)
+\&    r   \- some use of unblessed References or ties
+\&    O   \- Object oriented using blessed references and/or inheritance
+\&
+\&  P \- Public License
+\&    p   \- Standard\-Perl: user may choose between GPL and Artistic
+\&    g   \- GPL: GNU General Public License
+\&    l   \- LGPL: "GNU Lesser General Public License" (previously known as
+\&          "GNU Library General Public License")
+\&    b   \- BSD: The BSD License
+\&    a   \- Artistic license alone
+\&    2   \- Artistic license 2.0 or later
+\&    o   \- open source: approved by www.opensource.org
+\&    d   \- allows distribution without restrictions
+\&    r   \- restricted distribution
+\&    n   \- no license at all
+.Ve
+.IP CPAN::Module::force($method,@args) 4
+.IX Item "CPAN::Module::force($method,@args)"
+Forces CPAN to perform a task it would normally refuse to
+do. Force takes as arguments a method name to be invoked and any number
+of additional arguments to pass that method.
+The internals of the object get the needed changes so that CPAN.pm
+does not refuse to take the action. See also the section above on the
+\&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma.
+.IP \fBCPAN::Module::get()\fR 4
+.IX Item "CPAN::Module::get()"
+Runs a get on the distribution associated with this module.
+.IP \fBCPAN::Module::inst_file()\fR 4
+.IX Item "CPAN::Module::inst_file()"
+Returns the filename of the module found in \f(CW@INC\fR. The first file found
+is reported, just as perl itself stops searching \f(CW@INC\fR once it finds a
+module.
+.IP \fBCPAN::Module::available_file()\fR 4
+.IX Item "CPAN::Module::available_file()"
+Returns the filename of the module found in PERL5LIB or \f(CW@INC\fR. The
+first file found is reported. The advantage of this method over
+\&\f(CW\*(C`inst_file\*(C'\fR is that modules that have been tested but not yet
+installed are included because PERL5LIB keeps track of tested modules.
+.IP \fBCPAN::Module::inst_version()\fR 4
+.IX Item "CPAN::Module::inst_version()"
+Returns the version number of the installed module in readable format.
+.IP \fBCPAN::Module::available_version()\fR 4
+.IX Item "CPAN::Module::available_version()"
+Returns the version number of the available module in readable format.
+.IP \fBCPAN::Module::install()\fR 4
+.IX Item "CPAN::Module::install()"
+Runs an \f(CW\*(C`install\*(C'\fR on the distribution associated with this module.
+.IP \fBCPAN::Module::look()\fR 4
+.IX Item "CPAN::Module::look()"
+Changes to the directory where the distribution associated with this
+module has been unpacked and opens a subshell there. Exiting the
+subshell returns.
+.IP \fBCPAN::Module::make()\fR 4
+.IX Item "CPAN::Module::make()"
+Runs a \f(CW\*(C`make\*(C'\fR on the distribution associated with this module.
+.IP \fBCPAN::Module::manpage_headline()\fR 4
+.IX Item "CPAN::Module::manpage_headline()"
+If module is installed, peeks into the module's manpage, reads the
+headline, and returns it. Moreover, if the module has been downloaded
+within this session, does the equivalent on the downloaded module even
+if it hasn't been installed yet.
+.IP \fBCPAN::Module::perldoc()\fR 4
+.IX Item "CPAN::Module::perldoc()"
+Runs a \f(CW\*(C`perldoc\*(C'\fR on this module.
+.IP \fBCPAN::Module::readme()\fR 4
+.IX Item "CPAN::Module::readme()"
+Runs a \f(CW\*(C`readme\*(C'\fR on the distribution associated with this module.
+.IP \fBCPAN::Module::reports()\fR 4
+.IX Item "CPAN::Module::reports()"
+Calls the \fBreports()\fR method on the associated distribution object.
+.IP \fBCPAN::Module::test()\fR 4
+.IX Item "CPAN::Module::test()"
+Runs a \f(CW\*(C`test\*(C'\fR on the distribution associated with this module.
+.IP \fBCPAN::Module::uptodate()\fR 4
+.IX Item "CPAN::Module::uptodate()"
+Returns 1 if the module is installed and up-to-date.
+.IP \fBCPAN::Module::userid()\fR 4
+.IX Item "CPAN::Module::userid()"
+Returns the author's ID of the module.
+.SS "Cache Manager"
+.IX Subsection "Cache Manager"
+Currently the cache manager only keeps track of the build directory
+($CPAN::Config\->{build_dir}). It is a simple FIFO mechanism that
+deletes complete directories below \f(CW\*(C`build_dir\*(C'\fR as soon as the size of
+all directories there gets bigger than \f(CW$CPAN::Config\fR\->{build_cache}
+(in MB). The contents of this cache may be used for later
+re-installations that you intend to do manually, but will never be
+trusted by CPAN itself. This is due to the fact that the user might
+use these directories for building modules on different architectures.
+.PP
+There is another directory ($CPAN::Config\->{keep_source_where}) where
+the original distribution files are kept. This directory is not
+covered by the cache manager and must be controlled by the user. If
+you choose to have the same directory as build_dir and as
+keep_source_where directory, then your sources will be deleted with
+the same fifo mechanism.
+.SS Bundles
+.IX Subsection "Bundles"
+A bundle is just a perl module in the namespace Bundle:: that does not
+define any functions or methods. It usually only contains documentation.
+.PP
+It starts like a perl module with a package declaration and a \f(CW$VERSION\fR
+variable. After that the pod section looks like any other pod with the
+only difference being that \fIone special pod section\fR exists starting with
+(verbatim):
+.PP
+.Vb 1
+\&    =head1 CONTENTS
+.Ve
+.PP
+In this pod section each line obeys the format
+.PP
+.Vb 1
+\&        Module_Name [Version_String] [\- optional text]
+.Ve
+.PP
+The only required part is the first field, the name of a module
+(e.g. Foo::Bar, i.e. \fInot\fR the name of the distribution file). The rest
+of the line is optional. The comment part is delimited by a dash just
+as in the man page header.
+.PP
+The distribution of a bundle should follow the same convention as
+other distributions.
+.PP
+Bundles are treated specially in the CPAN package. If you say 'install
+Bundle::Tkkit' (assuming such a bundle exists), CPAN will install all
+the modules in the CONTENTS section of the pod. You can install your
+own Bundles locally by placing a conformant Bundle file somewhere into
+your \f(CW@INC\fR path. The \fBautobundle()\fR command which is available in the
+shell interface does that for you by including all currently installed
+modules in a snapshot bundle file.
+.SH PREREQUISITES
+.IX Header "PREREQUISITES"
+The CPAN program is trying to depend on as little as possible so the
+user can use it in hostile environment. It works better the more goodies
+the environment provides. For example if you try in the CPAN shell
+.PP
+.Vb 1
+\&  install Bundle::CPAN
+.Ve
+.PP
+or
+.PP
+.Vb 1
+\&  install Bundle::CPANxxl
+.Ve
+.PP
+you will find the shell more convenient than the bare shell before.
+.PP
+If you have a local mirror of CPAN and can access all files with
+"file:" URLs, then you only need a perl later than perl5.003 to run
+this module. Otherwise Net::FTP is strongly recommended. LWP may be
+required for non-UNIX systems, or if your nearest CPAN site is
+associated with a URL that is not \f(CW\*(C`ftp:\*(C'\fR.
+.PP
+If you have neither Net::FTP nor LWP, there is a fallback mechanism
+implemented for an external ftp command or for an external lynx
+command.
+.SH UTILITIES
+.IX Header "UTILITIES"
+.SS "Finding packages and VERSION"
+.IX Subsection "Finding packages and VERSION"
+This module presumes that all packages on CPAN
+.IP \(bu 2
+declare their \f(CW$VERSION\fR variable in an easy to parse manner. This
+prerequisite can hardly be relaxed because it consumes far too much
+memory to load all packages into the running program just to determine
+the \f(CW$VERSION\fR variable. Currently all programs that are dealing with
+version use something like this
+.Sp
+.Vb 2
+\&    perl \-MExtUtils::MakeMaker \-le \e
+\&        \*(Aqprint MM\->parse_version(shift)\*(Aq filename
+.Ve
+.Sp
+If you are author of a package and wonder if your \f(CW$VERSION\fR can be
+parsed, please try the above method.
+.IP \(bu 2
+come as compressed or gzipped tarfiles or as zip files and contain a
+\&\f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR (well, we try to handle a bit more, but
+with little enthusiasm).
+.SS Debugging
+.IX Subsection "Debugging"
+Debugging this module is more than a bit complex due to interference from
+the software producing the indices on CPAN, the mirroring process on CPAN,
+packaging, configuration, synchronicity, and even (gasp!) due to bugs
+within the CPAN.pm module itself.
+.PP
+For debugging the code of CPAN.pm itself in interactive mode, some
+debugging aid can be turned on for most packages within
+CPAN.pm with one of
+.IP "o debug package..." 2
+.IX Item "o debug package..."
+sets debug mode for packages.
+.IP "o debug \-package..." 2
+.IX Item "o debug -package..."
+unsets debug mode for packages.
+.IP "o debug all" 2
+.IX Item "o debug all"
+turns debugging on for all packages.
+.IP "o debug number" 2
+.IX Item "o debug number"
+.PP
+which sets the debugging packages directly. Note that \f(CW\*(C`o debug 0\*(C'\fR
+turns debugging off.
+.PP
+What seems a successful strategy is the combination of \f(CW\*(C`reload
+cpan\*(C'\fR and the debugging switches. Add a new debug statement while
+running in the shell and then issue a \f(CW\*(C`reload cpan\*(C'\fR and see the new
+debugging messages immediately without losing the current context.
+.PP
+\&\f(CW\*(C`o debug\*(C'\fR without an argument lists the valid package names and the
+current set of packages in debugging mode. \f(CW\*(C`o debug\*(C'\fR has built-in
+completion support.
+.PP
+For debugging of CPAN data there is the \f(CW\*(C`dump\*(C'\fR command which takes
+the same arguments as make/test/install and outputs each object's
+Data::Dumper dump. If an argument looks like a perl variable and
+contains one of \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, it is \fBeval()\fRed and fed to
+Data::Dumper directly.
+.SS "Floppy, Zip, Offline Mode"
+.IX Subsection "Floppy, Zip, Offline Mode"
+CPAN.pm works nicely without network access, too. If you maintain machines
+that are not networked at all, you should consider working with \f(CW\*(C`file:\*(C'\fR
+URLs. You'll have to collect your modules somewhere first. So
+you might use CPAN.pm to put together all you need on a networked
+machine. Then copy the \f(CW$CPAN::Config\fR\->{keep_source_where} (but not
+\&\f(CW$CPAN::Config\fR\->{build_dir}) directory on a floppy. This floppy is kind
+of a personal CPAN. CPAN.pm on the non-networked machines works nicely
+with this floppy. See also below the paragraph about CD-ROM support.
+.SS "Basic Utilities for Programmers"
+.IX Subsection "Basic Utilities for Programmers"
+.IP has_inst($module) 2
+.IX Item "has_inst($module)"
+Returns true if the module is installed. Used to load all modules into
+the running CPAN.pm that are considered optional. The config variable
+\&\f(CW\*(C`dontload_list\*(C'\fR intercepts the \f(CWhas_inst()\fR call such
+that an optional module is not loaded despite being available. For
+example, the following command will prevent \f(CW\*(C`YAML.pm\*(C'\fR from being
+loaded:
+.Sp
+.Vb 1
+\&    cpan> o conf dontload_list push YAML
+.Ve
+.Sp
+See the source for details.
+.IP use_inst($module) 2
+.IX Item "use_inst($module)"
+Similary to \fBhas_inst()\fR tries to load optional library but also dies if
+library is not available
+.IP has_usable($module) 2
+.IX Item "has_usable($module)"
+Returns true if the module is installed and in a usable state. Only
+useful for a handful of modules that are used internally. See the
+source for details.
+.IP instance($module) 2
+.IX Item "instance($module)"
+The constructor for all the singletons used to represent modules,
+distributions, authors, and bundles. If the object already exists, this
+method returns the object; otherwise, it calls the constructor.
+.IP \fBfrontend()\fR 2
+.IX Item "frontend()"
+.PD 0
+.IP frontend($new_frontend) 2
+.IX Item "frontend($new_frontend)"
+.PD
+Getter/setter for frontend object. Method just allows to subclass CPAN.pm.
+.SH SECURITY
+.IX Header "SECURITY"
+There's no strong security layer in CPAN.pm. CPAN.pm helps you to
+install foreign, unmasked, unsigned code on your machine. We compare
+to a checksum that comes from the net just as the distribution file
+itself. But we try to make it easy to add security on demand:
+.SS "Cryptographically signed modules"
+.IX Subsection "Cryptographically signed modules"
+Since release 1.77, CPAN.pm has been able to verify cryptographically
+signed module distributions using Module::Signature.  The CPAN modules
+can be signed by their authors, thus giving more security.  The simple
+unsigned MD5 checksums that were used before by CPAN protect mainly
+against accidental file corruption.
+.PP
+You will need to have Module::Signature installed, which in turn
+requires that you have at least one of Crypt::OpenPGP module or the
+command-line \fIgpg\fR tool installed.
+.PP
+You will also need to be able to connect over the Internet to the public
+key servers, like pgp.mit.edu, and their port 11731 (the HKP protocol).
+.PP
+The configuration parameter check_sigs is there to turn signature
+checking on or off.
+.SH EXPORT
+.IX Header "EXPORT"
+Most functions in package CPAN are exported by default. The reason
+for this is that the primary use is intended for the cpan shell or for
+one-liners.
+.SH ENVIRONMENT
+.IX Header "ENVIRONMENT"
+When the CPAN shell enters a subshell via the look command, it sets
+the environment CPAN_SHELL_LEVEL to 1, or increments that variable if it is
+already set.
+.PP
+When CPAN runs, it sets the environment variable PERL5_CPAN_IS_RUNNING
+to the ID of the running process. It also sets
+PERL5_CPANPLUS_IS_RUNNING to prevent runaway processes which could
+happen with older versions of Module::Install.
+.PP
+When running \f(CW\*(C`perl Makefile.PL\*(C'\fR, the environment variable
+\&\f(CW\*(C`PERL5_CPAN_IS_EXECUTING\*(C'\fR is set to the full path of the
+\&\f(CW\*(C`Makefile.PL\*(C'\fR that is being executed. This prevents runaway processes
+with newer versions of Module::Install.
+.PP
+When the config variable ftp_passive is set, all downloads will be run
+with the environment variable FTP_PASSIVE set to this value. This is
+in general a good idea as it influences both Net::FTP and LWP based
+connections. The same effect can be achieved by starting the cpan
+shell with this environment variable set. For Net::FTP alone, one can
+also always set passive mode by running libnetcfg.
+.SH "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
+.IX Header "POPULATE AN INSTALLATION WITH LOTS OF MODULES"
+Populating a freshly installed perl with one's favorite modules is pretty
+easy if you maintain a private bundle definition file. To get a useful
+blueprint of a bundle definition file, the command autobundle can be used
+on the CPAN shell command line. This command writes a bundle definition
+file for all modules installed for the current perl
+interpreter. It's recommended to run this command once only, and from then
+on maintain the file manually under a private name, say
+Bundle/my_bundle.pm. With a clever bundle file you can then simply say
+.PP
+.Vb 1
+\&    cpan> install Bundle::my_bundle
+.Ve
+.PP
+then answer a few questions and go out for coffee (possibly
+even in a different city).
+.PP
+Maintaining a bundle definition file means keeping track of two
+things: dependencies and interactivity. CPAN.pm sometimes fails on
+calculating dependencies because not all modules define all MakeMaker
+attributes correctly, so a bundle definition file should specify
+prerequisites as early as possible. On the other hand, it's
+annoying that so many distributions need some interactive configuring. So
+what you can try to accomplish in your private bundle file is to have the
+packages that need to be configured early in the file and the gentle
+ones later, so you can go out for coffee after a few minutes and leave CPAN.pm
+to churn away unattended.
+.SH "WORKING WITH CPAN.pm BEHIND FIREWALLS"
+.IX Header "WORKING WITH CPAN.pm BEHIND FIREWALLS"
+Thanks to Graham Barr for contributing the following paragraphs about
+the interaction between perl, and various firewall configurations. For
+further information on firewalls, it is recommended to consult the
+documentation that comes with the \fIncftp\fR program. If you are unable to
+go through the firewall with a simple Perl setup, it is likely
+that you can configure \fIncftp\fR so that it works through your firewall.
+.SS "Three basic types of firewalls"
+.IX Subsection "Three basic types of firewalls"
+Firewalls can be categorized into three basic types.
+.IP "http firewall" 4
+.IX Item "http firewall"
+This is when the firewall machine runs a web server, and to access the
+outside world, you must do so via that web server. If you set environment
+variables like http_proxy or ftp_proxy to values beginning with http://,
+or in your web browser you've proxy information set, then you know
+you are running behind an http firewall.
+.Sp
+To access servers outside these types of firewalls with perl (even for
+ftp), you need LWP or HTTP::Tiny.
+.IP "ftp firewall" 4
+.IX Item "ftp firewall"
+This where the firewall machine runs an ftp server. This kind of
+firewall will only let you access ftp servers outside the firewall.
+This is usually done by connecting to the firewall with ftp, then
+entering a username like "user@outside.host.com".
+.Sp
+To access servers outside these type of firewalls with perl, you
+need Net::FTP.
+.IP "One-way visibility" 4
+.IX Item "One-way visibility"
+One-way visibility means these firewalls try to make themselves
+invisible to users inside the firewall. An FTP data connection is
+normally created by sending your IP address to the remote server and then
+listening for the return connection. But the remote server will not be able to
+connect to you because of the firewall. For these types of firewall,
+FTP connections need to be done in a passive mode.
+.Sp
+There are two that I can think off.
+.RS 4
+.IP SOCKS 4
+.IX Item "SOCKS"
+If you are using a SOCKS firewall, you will need to compile perl and link
+it with the SOCKS library.  This is what is normally called a 'socksified'
+perl. With this executable you will be able to connect to servers outside
+the firewall as if it were not there.
+.IP "IP Masquerade" 4
+.IX Item "IP Masquerade"
+This is when the firewall implemented in the kernel (via NAT, or networking
+address translation), it allows you to hide a complete network behind one
+IP address. With this firewall no special compiling is needed as you can
+access hosts directly.
+.Sp
+For accessing ftp servers behind such firewalls you usually need to
+set the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR or the config variable
+ftp_passive to a true value.
+.RE
+.RS 4
+.RE
+.SS "Configuring lynx or ncftp for going through a firewall"
+.IX Subsection "Configuring lynx or ncftp for going through a firewall"
+If you can go through your firewall with e.g. lynx, presumably with a
+command such as
+.PP
+.Vb 1
+\&    /usr/local/bin/lynx \-pscott:tiger
+.Ve
+.PP
+then you would configure CPAN.pm with the command
+.PP
+.Vb 1
+\&    o conf lynx "/usr/local/bin/lynx \-pscott:tiger"
+.Ve
+.PP
+That's all. Similarly for ncftp or ftp, you would configure something
+like
+.PP
+.Vb 1
+\&    o conf ncftp "/usr/bin/ncftp \-f /home/scott/ncftplogin.cfg"
+.Ve
+.PP
+Your mileage may vary...
+.SH FAQ
+.IX Header "FAQ"
+.IP 1) 4
+.IX Item "1)"
+I installed a new version of module X but CPAN keeps saying,
+I have the old version installed
+.Sp
+Probably you \fBdo\fR have the old version installed. This can
+happen if a module installs itself into a different directory in the
+\&\f(CW@INC\fR path than it was previously installed. This is not really a
+CPAN.pm problem, you would have the same problem when installing the
+module manually. The easiest way to prevent this behaviour is to add
+the argument \f(CW\*(C`UNINST=1\*(C'\fR to the \f(CW\*(C`make install\*(C'\fR call, and that is why
+many people add this argument permanently by configuring
+.Sp
+.Vb 1
+\&  o conf make_install_arg UNINST=1
+.Ve
+.IP 2) 4
+.IX Item "2)"
+So why is UNINST=1 not the default?
+.Sp
+Because there are people who have their precise expectations about who
+may install where in the \f(CW@INC\fR path and who uses which \f(CW@INC\fR array. In
+fine tuned environments \f(CW\*(C`UNINST=1\*(C'\fR can cause damage.
+.IP 3) 4
+.IX Item "3)"
+I want to clean up my mess, and install a new perl along with
+all modules I have. How do I go about it?
+.Sp
+Run the autobundle command for your old perl and optionally rename the
+resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl
+with the Configure option prefix, e.g.
+.Sp
+.Vb 1
+\&    ./Configure \-Dprefix=/usr/local/perl\-5.6.78.9
+.Ve
+.Sp
+Install the bundle file you produced in the first step with something like
+.Sp
+.Vb 1
+\&    cpan> install Bundle::mybundle
+.Ve
+.Sp
+and you're done.
+.IP 4) 4
+.IX Item "4)"
+When I install bundles or multiple modules with one command
+there is too much output to keep track of.
+.Sp
+You may want to configure something like
+.Sp
+.Vb 2
+\&  o conf make_arg "| tee \-ai /root/.cpan/logs/make.out"
+\&  o conf make_install_arg "| tee \-ai /root/.cpan/logs/make_install.out"
+.Ve
+.Sp
+so that STDOUT is captured in a file for later inspection.
+.IP 5) 4
+.IX Item "5)"
+I am not root, how can I install a module in a personal directory?
+.Sp
+As of CPAN 1.9463, if you do not have permission to write the default perl
+library directories, CPAN's configuration process will ask you whether
+you want to bootstrap <local::lib>, which makes keeping a personal
+perl library directory easy.
+.Sp
+Another thing you should bear in mind is that the UNINST parameter can
+be dangerous when you are installing into a private area because you
+might accidentally remove modules that other people depend on that are
+not using the private area.
+.IP 6) 4
+.IX Item "6)"
+How to get a package, unwrap it, and make a change before building it?
+.Sp
+Have a look at the \f(CW\*(C`look\*(C'\fR (!) command.
+.IP 7) 4
+.IX Item "7)"
+I installed a Bundle and had a couple of fails. When I
+retried, everything resolved nicely. Can this be fixed to work
+on first try?
+.Sp
+The reason for this is that CPAN does not know the dependencies of all
+modules when it starts out. To decide about the additional items to
+install, it just uses data found in the META.yml file or the generated
+Makefile. An undetected missing piece breaks the process. But it may
+well be that your Bundle installs some prerequisite later than some
+depending item and thus your second try is able to resolve everything.
+Please note, CPAN.pm does not know the dependency tree in advance and
+cannot sort the queue of things to install in a topologically correct
+order. It resolves perfectly well \fBif\fR all modules declare the
+prerequisites correctly with the PREREQ_PM attribute to MakeMaker or
+the \f(CW\*(C`requires\*(C'\fR stanza of Module::Build. For bundles which fail and
+you need to install often, it is recommended to sort the Bundle
+definition file manually.
+.IP 8) 4
+.IX Item "8)"
+In our intranet, we have many modules for internal use. How
+can I integrate these modules with CPAN.pm but without uploading
+the modules to CPAN?
+.Sp
+Have a look at the CPAN::Site module.
+.IP 9) 4
+.IX Item "9)"
+When I run CPAN's shell, I get an error message about things in my
+\&\f(CW\*(C`/etc/inputrc\*(C'\fR (or \f(CW\*(C`~/.inputrc\*(C'\fR) file.
+.Sp
+These are readline issues and can only be fixed by studying readline
+configuration on your architecture and adjusting the referenced file
+accordingly. Please make a backup of the \f(CW\*(C`/etc/inputrc\*(C'\fR or \f(CW\*(C`~/.inputrc\*(C'\fR
+and edit them. Quite often harmless changes like uppercasing or
+lowercasing some arguments solves the problem.
+.IP 10) 4
+.IX Item "10)"
+Some authors have strange characters in their names.
+.Sp
+Internally CPAN.pm uses the UTF\-8 charset. If your terminal is
+expecting ISO\-8859\-1 charset, a converter can be activated by setting
+term_is_latin to a true value in your config file. One way of doing so
+would be
+.Sp
+.Vb 1
+\&    cpan> o conf term_is_latin 1
+.Ve
+.Sp
+If other charset support is needed, please file a bug report against
+CPAN.pm at rt.cpan.org and describe your needs. Maybe we can extend
+the support or maybe UTF\-8 terminals become widely available.
+.Sp
+Note: this config variable is deprecated and will be removed in a
+future version of CPAN.pm. It will be replaced with the conventions
+around the family of \f(CW$LANG\fR and \f(CW$LC_\fR* environment variables.
+.IP 11) 4
+.IX Item "11)"
+When an install fails for some reason and then I correct the error
+condition and retry, CPAN.pm refuses to install the module, saying
+\&\f(CW\*(C`Already tried without success\*(C'\fR.
+.Sp
+Use the force pragma like so
+.Sp
+.Vb 1
+\&  force install Foo::Bar
+.Ve
+.Sp
+Or you can use
+.Sp
+.Vb 1
+\&  look Foo::Bar
+.Ve
+.Sp
+and then \f(CW\*(C`make install\*(C'\fR directly in the subshell.
+.IP 12) 4
+.IX Item "12)"
+How do I install a "DEVELOPER RELEASE" of a module?
+.Sp
+By default, CPAN will install the latest non-developer release of a
+module. If you want to install a dev release, you have to specify the
+partial path starting with the author id to the tarball you wish to
+install, like so:
+.Sp
+.Vb 1
+\&    cpan> install KWILLIAMS/Module\-Build\-0.27_07.tar.gz
+.Ve
+.Sp
+Note that you can use the \f(CW\*(C`ls\*(C'\fR command to get this path listed.
+.IP 13) 4
+.IX Item "13)"
+How do I install a module and all its dependencies from the commandline,
+without being prompted for anything, despite my CPAN configuration
+(or lack thereof)?
+.Sp
+CPAN uses ExtUtils::MakeMaker's \fBprompt()\fR function to ask its questions, so
+if you set the PERL_MM_USE_DEFAULT environment variable, you shouldn't be
+asked any questions at all (assuming the modules you are installing are
+nice about obeying that variable as well):
+.Sp
+.Vb 1
+\&    % PERL_MM_USE_DEFAULT=1 perl \-MCPAN \-e \*(Aqinstall My::Module\*(Aq
+.Ve
+.IP 14) 4
+.IX Item "14)"
+How do I create a Module::Build based Build.PL derived from an
+ExtUtils::MakeMaker focused Makefile.PL?
+.Sp
+http://search.cpan.org/dist/Module\-Build\-Convert/
+.IP 15) 4
+.IX Item "15)"
+I'm frequently irritated with the CPAN shell's inability to help me
+select a good mirror.
+.Sp
+CPAN can now help you select a "good" mirror, based on which ones have the
+lowest 'ping' round-trip times.  From the shell, use the command 'o conf init
+urllist' and allow CPAN to automatically select mirrors for you.
+.Sp
+Beyond that help, the urllist config parameter is yours. You can add and remove
+sites at will. You should find out which sites have the best up-to-dateness,
+bandwidth, reliability, etc. and are topologically close to you. Some people
+prefer fast downloads, others up-to-dateness, others reliability.  You decide
+which to try in which order.
+.Sp
+Henk P. Penning maintains a site that collects data about CPAN sites:
+.Sp
+.Vb 1
+\&  http://mirrors.cpan.org/
+.Ve
+.Sp
+Also, feel free to play with experimental features. Run
+.Sp
+.Vb 1
+\&  o conf init randomize_urllist ftpstats_period ftpstats_size
+.Ve
+.Sp
+and choose your favorite parameters. After a few downloads running the
+\&\f(CW\*(C`hosts\*(C'\fR command will probably assist you in choosing the best mirror
+sites.
+.IP 16) 4
+.IX Item "16)"
+Why do I get asked the same questions every time I start the shell?
+.Sp
+You can make your configuration changes permanent by calling the
+command \f(CW\*(C`o conf commit\*(C'\fR. Alternatively set the \f(CW\*(C`auto_commit\*(C'\fR
+variable to true by running \f(CW\*(C`o conf init auto_commit\*(C'\fR and answering
+the following question with yes.
+.IP 17) 4
+.IX Item "17)"
+Older versions of CPAN.pm had the original root directory of all
+tarballs in the build directory. Now there are always random
+characters appended to these directory names. Why was this done?
+.Sp
+The random characters are provided by File::Temp and ensure that each
+module's individual build directory is unique. This makes running
+CPAN.pm in concurrent processes simultaneously safe.
+.IP 18) 4
+.IX Item "18)"
+Speaking of the build directory. Do I have to clean it up myself?
+.Sp
+You have the choice to set the config variable \f(CW\*(C`scan_cache\*(C'\fR to
+\&\f(CW\*(C`never\*(C'\fR. Then you must clean it up yourself. The other possible
+values, \f(CW\*(C`atstart\*(C'\fR and \f(CW\*(C`atexit\*(C'\fR clean up the build directory when you
+start (or more precisely, after the first extraction into the build
+directory) or exit the CPAN shell, respectively. If you never start up
+the CPAN shell, you probably also have to clean up the build directory
+yourself.
+.IP 19) 4
+.IX Item "19)"
+How can I switch to sudo instead of local::lib?
+.Sp
+The following 5 environment veriables need to be reset to the previous
+values: PATH, PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MB_OPT, PERL_MM_OPT;
+and these two CPAN.pm config variables must be reconfigured:
+make_install_make_command and mbuild_install_build_command. The five
+env variables have probably been overwritten in your \f(CW$HOME\fR/.bashrc or
+some equivalent. You either find them there and delete their traces
+and logout/login or you override them temporarily, depending on your
+exact desire. The two cpanpm config variables can be set with:
+.Sp
+.Vb 1
+\&  o conf init /install_.*_command/
+.Ve
+.Sp
+probably followed by
+.Sp
+.Vb 1
+\&  o conf commit
+.Ve
+.SH COMPATIBILITY
+.IX Header "COMPATIBILITY"
+.SS "OLD PERL VERSIONS"
+.IX Subsection "OLD PERL VERSIONS"
+CPAN.pm is regularly tested to run under 5.005 and assorted
+newer versions. It is getting more and more difficult to get the
+minimal prerequisites working on older perls. It is close to
+impossible to get the whole Bundle::CPAN working there. If you're in
+the position to have only these old versions, be advised that CPAN is
+designed to work fine without the Bundle::CPAN installed.
+.PP
+To get things going, note that GBARR/Scalar\-List\-Utils\-1.18.tar.gz is
+compatible with ancient perls and that File::Temp is listed as a
+prerequisite but CPAN has reasonable workarounds if it is missing.
+.SS CPANPLUS
+.IX Subsection "CPANPLUS"
+This module and its competitor, the CPANPLUS module, are both much
+cooler than the other. CPAN.pm is older. CPANPLUS was designed to be
+more modular, but it was never intended to be compatible with CPAN.pm.
+.SS CPANMINUS
+.IX Subsection "CPANMINUS"
+In the year 2010 App::cpanminus was launched as a new approach to a
+cpan shell with a considerably smaller footprint. Very cool stuff.
+.SH "SECURITY ADVICE"
+.IX Header "SECURITY ADVICE"
+This software enables you to upgrade software on your computer and so
+is inherently dangerous because the newly installed software may
+contain bugs and may alter the way your computer works or even make it
+unusable. Please consider backing up your data before every upgrade.
+.SH BUGS
+.IX Header "BUGS"
+Please report bugs via <http://rt.cpan.org/>
+.PP
+Before submitting a bug, please make sure that the traditional method
+of building a Perl module package from a shell by following the
+installation instructions of that package still works in your
+environment.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Andreas Koenig \f(CW\*(C`<andk@cpan.org>\*(C'\fR
+.SH LICENSE
+.IX Header "LICENSE"
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See <http://www.perl.com/perl/misc/Artistic.html>
+.SH TRANSLATIONS
+.IX Header "TRANSLATIONS"
+Kawai,Takanori provides a Japanese translation of a very old version
+of this manpage at
+<http://homepage3.nifty.com/hippo2000/perltips/CPAN.htm>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Many people enter the CPAN shell by running the cpan utility
+program which is installed in the same directory as perl itself. So if
+you have this directory in your PATH variable (or some equivalent in
+your operating system) then typing \f(CW\*(C`cpan\*(C'\fR in a console window will
+work for you as well. Above that the utility provides several
+commandline shortcuts.
+.PP
+melezhik (Alexey) sent me a link where he published a chef recipe to
+work with CPAN.pm: http://community.opscode.com/cookbooks/cpan.