tl20 perl 5.30.1 for Windows, from Siep

git-svn-id: svn://tug.org/texlive/trunk@54166 c570f23f-e606-0410-a88d-b1316a301751

23 files changed, 259 insertions, 91 deletions

diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm
index d33e4af2e40..513475f1a3c 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Basic.pm
@@ -2,7 +2,7 @@ package LWP::Authen::Basic;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require MIME::Base64;
 
@@ -11,6 +11,10 @@ sub auth_header {
     return "Basic " . MIME::Base64::encode("$user:$pass", "");
 }
 
+sub _reauth_requested {
+    return 0;
+}
+
 sub authenticate
 {
     my($class, $ua, $proxy, $auth_param, $response,
@@ -37,9 +41,15 @@ sub authenticate
     });
     $h->{auth_param} = $auth_param;
 
-    if (!$proxy && !$request->header($auth_header) && $ua->credentials($host_port, $realm)) {
-	# we can make sure this handler applies and retry
-        add_path($h, $url->path);
+    my $reauth_requested
+        = $class->_reauth_requested($auth_param, $ua, $request, $auth_header);
+    if (   !$proxy
+        && (!$request->header($auth_header) || $reauth_requested)
+        && $ua->credentials($host_port, $realm))
+    {
+        # we can make sure this handler applies and retry
+        add_path($h, $url->path)
+            unless $reauth_requested;  # Do not clobber up path list for retries
         return $ua->request($request->clone, $arg, $size, $response);
     }
 
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm
index 2e11ac638b9..5ed025182f6 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Digest.pm
@@ -3,10 +3,23 @@ package LWP::Authen::Digest;
 use strict;
 use base 'LWP::Authen::Basic';
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require Digest::MD5;
 
+sub _reauth_requested {
+    my ($class, $auth_param, $ua, $request, $auth_header) = @_;
+    my $ret = defined($$auth_param{stale}) && lc($$auth_param{stale}) eq 'true';
+    if ($ret) {
+        my $hdr = $request->header($auth_header);
+        $hdr =~ tr/,/;/;    # "," is used to separate auth-params!!
+        ($hdr) = HTTP::Headers::Util::split_header_words($hdr);
+        my $nonce = {@$hdr}->{nonce};
+        delete $$ua{authen_md5_nonce_count}{$nonce};
+    }
+    return $ret;
+}
+
 sub auth_header {
     my($class, $user, $pass, $request, $ua, $h) = @_;
 
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm
index b4eaad1eaa9..ebe07e2c1af 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Authen/Ntlm.pm
@@ -2,7 +2,7 @@ package LWP::Authen::Ntlm;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 use Authen::NTLM "1.02";
 use MIME::Base64 "2.12";
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm b/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm
index d4cfc66e266..240eacf0910 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/ConnCache.pm
@@ -2,7 +2,7 @@ package LWP::ConnCache;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 our $DEBUG;
 
 sub new {
@@ -201,7 +201,7 @@ The following basic methods are provided:
 
 This method constructs a new L<LWP::ConnCache> object.  The only
 option currently accepted is C<total_capacity>.  If specified it
-initialize the L<LWP::ConnCache/total_capacity> option. It defaults to C<1>.
+initializes the L<LWP::ConnCache/total_capacity> option. It defaults to C<1>.
 
 =head2 total_capacity
 
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm b/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm
index c93a80ade30..7f05c433575 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Debug.pm
@@ -1,6 +1,6 @@
 package LWP::Debug;    # legacy
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require Exporter;
 our @ISA       = qw(Exporter);
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm b/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm
index 0644644616c..febd627e0b6 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Debug/TraceHTTP.pm
@@ -11,7 +11,7 @@ package LWP::Debug::TraceHTTP;
 use strict;
 use base 'LWP::Protocol::http';
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 package # hide from PAUSE
     LWP::Debug::TraceHTTP::Socket;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm b/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm
index f35cdf3426d..8a931ce4b15 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/DebugFile.pm
@@ -1,6 +1,6 @@
 package LWP::DebugFile;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 # legacy stub
 
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm b/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm
index 8c2a8aee334..22d00e3391b 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/MediaTypes.pm
@@ -4,9 +4,11 @@ require Exporter;
 @ISA = qw(Exporter);
 @EXPORT = qw(guess_media_type media_suffix);
 @EXPORT_OK = qw(add_type add_encoding read_media_types);
-$VERSION = "6.02";
+our $VERSION = '6.04';
 
 use strict;
+use Scalar::Util qw(blessed);
+use Carp qw(croak);
 
 # note: These hashes will also be filled with the entries found in
 # the 'media.types' file.
@@ -47,10 +49,17 @@ sub guess_media_type
     return undef unless defined $file;
 
     my $fullname;
-    if (ref($file)) {
-	# assume URI object
-	$file = $file->path;
-	#XXX should handle non http:, file: or ftp: URIs differently
+    if (ref $file) {
+        croak("Unable to determine filetype on unblessed refs") unless blessed($file);
+        if ($file->can('path')) {
+            $file = $file->path;
+        }
+        elsif ($file->can('filename')) {
+            $fullname = $file->filename;
+        }
+        else {
+            $fullname = "" . $file;
+        }
     }
     else {
 	$fullname = $file;  # enable peek at actual file
@@ -124,7 +133,7 @@ sub media_suffix {
 }
 
 
-sub file_exts 
+sub file_exts
 {
     require File::Basename;
     my @parts = reverse split(/\./, File::Basename::basename($_[0]));
@@ -133,7 +142,7 @@ sub file_exts
 }
 
 
-sub add_type 
+sub add_type
 {
     my($type, @exts) = @_;
     for my $ext (@exts) {
@@ -154,7 +163,7 @@ sub add_encoding
 }
 
 
-sub read_media_types 
+sub read_media_types
 {
     my(@files) = @_;
 
@@ -214,9 +223,12 @@ The following functions are exported by default:
 
 =item guess_media_type( $uri )
 
-=item guess_media_type( $filename_or_uri, $header_to_modify )
+=item guess_media_type( $filename_or_object, $header_to_modify )
 
-This function tries to guess media type and encoding for a file or a URI.
+This function tries to guess media type and encoding for a file or objects that
+support the a C<path> or C<filename> method, eg, L<URI> or L<File::Temp> objects.
+When an object does not support either method, it will be stringified to
+determine the filename.
 It returns the content type, which is a string like C<"text/html">.
 In array context it also returns any content encodings applied (in the
 order used to encode the file).  You can pass a URI object
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm b/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm
index 4ed9053cbc2..f32d27df447 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/MemberMixin.pm
@@ -1,6 +1,6 @@
 package LWP::MemberMixin;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 sub _elem {
     my $self = shift;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm
index f5966ab1c16..d1f03f133bf 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol.pm
@@ -2,7 +2,7 @@ package LWP::Protocol;
 
 use base 'LWP::MemberMixin';
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 use strict;
 use Carp ();
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm
index 1f6bd0d91b9..93f1c8a2452 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/cpan.pm
@@ -4,7 +4,7 @@ use strict;
 
 use base qw(LWP::Protocol);
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require URI;
 require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm
index 8460f05be9f..fdbdb2fe93d 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/data.pm
@@ -4,7 +4,7 @@ package LWP::Protocol::data;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require HTTP::Response;
 require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm
index 01c14eeafa7..90c1c1b07cf 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/file.pm
@@ -4,7 +4,7 @@ use base qw(LWP::Protocol);
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require LWP::MediaTypes;
 require HTTP::Request;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm
index d45a877f593..c6d75294a99 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/ftp.pm
@@ -5,7 +5,7 @@ package LWP::Protocol::ftp;
 use base qw(LWP::Protocol);
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 use Carp            ();
 use HTTP::Status    ();
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm
index 6fd6ff710ba..3c3f8c96f61 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/gopher.pm
@@ -9,7 +9,7 @@ package LWP::Protocol::gopher;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require HTTP::Response;
 require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm
index ec53e23d95d..052b773d711 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/http.pm
@@ -2,7 +2,7 @@ package LWP::Protocol::http;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require HTTP::Response;
 require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm
index b7645deee66..a00a53e7103 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/loopback.pm
@@ -2,7 +2,7 @@ package LWP::Protocol::loopback;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require HTTP::Response;
 
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm
index d970edafbe6..15a4d40d9da 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/mailto.pm
@@ -11,7 +11,7 @@ require HTTP::Status;
 use Carp;
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 use base qw(LWP::Protocol);
 our $SENDMAIL;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm
index 3cbde3f4e0a..c667c342041 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nntp.pm
@@ -4,7 +4,7 @@ package LWP::Protocol::nntp;
 
 use base qw(LWP::Protocol);
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require HTTP::Response;
 require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm
index 32f09579bff..5a9fe059078 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Protocol/nogo.pm
@@ -7,7 +7,7 @@ package LWP::Protocol::nogo;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require HTTP::Response;
 require HTTP::Status;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm b/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm
index a418fe32fe5..9fe93324a04 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/RobotUA.pm
@@ -2,7 +2,7 @@ package LWP::RobotUA;
 
 use base qw(LWP::UserAgent);
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require WWW::RobotRules;
 require HTTP::Request;
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm b/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm
index f1b91b13ca6..cf4b4b0c566 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/Simple.pm
@@ -2,7 +2,7 @@ package LWP::Simple;
 
 use strict;
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 require Exporter;
 
diff --git a/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm b/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm
index 58f09e0b2a9..668d1c04886 100644
--- a/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm
+++ b/Master/tlpkg/tlperl/site/lib/LWP/UserAgent.pm
@@ -15,7 +15,7 @@ use LWP::Protocol ();
 use Scalar::Util qw(blessed);
 use Try::Tiny qw(try catch);
 
-our $VERSION = '6.37';
+our $VERSION = '6.43';
 
 sub new
 {
@@ -420,8 +420,11 @@ sub request {
                         "Unsupported authentication scheme '$scheme'");
                 next CHALLENGE;
             }
-            return $class->authenticate($self, $proxy, $challenge, $response,
+            my $re = $class->authenticate($self, $proxy, $challenge, $response,
                 $request, $arg, $size);
+
+            next CHALLENGE if $re->code == HTTP::Status::RC_UNAUTHORIZED;
+            return $re;
         }
         return $response;
     }
@@ -489,6 +492,21 @@ sub head {
     return $self->request( HTTP::Request::Common::HEAD( @parameters ), @suff );
 }
 
+sub patch {
+    require HTTP::Request::Common;
+    my($self, @parameters) = @_;
+    my @suff = $self->_process_colonic_headers(\@parameters, (ref($parameters[1]) ? 2 : 1));
+
+    # this work-around is in place as HTTP::Request::Common
+    # did not implement a patch convenience method until
+    # version 6.12. Once we can bump the prereq to at least
+    # that version, we can use ::PATCH instead of this hack
+    my $req = HTTP::Request::Common::PUT(@parameters);
+    $req->method('PATCH');
+
+    $self->_maybe_copy_default_content_type($req, @parameters);
+    return $self->request($req, @suff);
+}
 
 sub put {
     require HTTP::Request::Common;
@@ -966,6 +984,8 @@ sub mirror
 {
     my($self, $url, $file) = @_;
 
+    die "Local file name is missing" unless defined $file && length $file;
+
     my $request = HTTP::Request->new('GET', $url);
 
     # If the file exists, add a cache-related header
@@ -979,10 +999,10 @@ sub mirror
 
     my $response = $self->request($request, $tmpfile);
     if ( $response->header('X-Died') ) {
-	die $response->header('X-Died');
+        die $response->header('X-Died');
     }
 
-    # Only fetching a fresh copy of the would be considered success.
+    # Only fetching a fresh copy of the file would be considered success.
     # If the file was not modified, "304" would returned, which
     # is considered by HTTP::Status to be a "redirect", /not/ "success"
     if ( $response->is_success ) {
@@ -1017,7 +1037,7 @@ sub mirror
     }
     # The local copy is fresh enough, so just delete the temp file
     else {
-	unlink($tmpfile);
+        unlink($tmpfile);
     }
     return $response;
 }
@@ -1133,22 +1153,48 @@ LWP::UserAgent - Web user agent class
 
 =head1 SYNOPSIS
 
- use strict;
- use warnings;
- use LWP::UserAgent ();
+    use strict;
+    use warnings;
+
+    use LWP::UserAgent ();
 
- my $ua = LWP::UserAgent->new;
- $ua->timeout(10);
- $ua->env_proxy;
+    my $ua = LWP::UserAgent->new(timeout => 10);
+    $ua->env_proxy;
 
- my $response = $ua->get('http://search.cpan.org/');
+    my $response = $ua->get('http://example.com');
 
- if ($response->is_success) {
-     print $response->decoded_content;  # or whatever
- }
- else {
-     die $response->status_line;
- }
+    if ($response->is_success) {
+        print $response->decoded_content;
+    }
+    else {
+        die $response->status_line;
+    }
+
+Extra layers of security (note the C<cookie_jar> and C<protocols_allowed>):
+
+    use strict;
+    use warnings;
+
+    use HTTP::CookieJar::LWP ();
+    use LWP::UserAgent       ();
+
+    my $jar = HTTP::CookieJar::LWP->new;
+    my $ua  = LWP::UserAgent->new(
+        cookie_jar        => $jar,
+        protocols_allowed => ['http', 'https'],
+        timeout           => 10,
+    );
+
+    $ua->env_proxy;
+
+    my $response = $ua->get('http://example.com');
+
+    if ($response->is_success) {
+        print $response->decoded_content;
+    }
+    else {
+        die $response->status_line;
+    }
 
 =head1 DESCRIPTION
 
@@ -1221,7 +1267,7 @@ is passed in with a true value, then proxy settings are read from environment
 variables (see L<LWP::UserAgent/env_proxy>). If C<env_proxy> isn't provided, the
 C<PERL_LWP_ENV_PROXY> environment variable controls if
 L<LWP::UserAgent/env_proxy> is called during initialization.  If the
-C<keep_alive> option is passed in, then a C<LWP::ConnCache> is set up (see
+C<keep_alive> option value is defined and non-zero, then an C<LWP::ConnCache> is set up (see
 L<LWP::UserAgent/conn_cache>).  The C<keep_alive> value is passed on as the
 C<total_capacity> for the connection cache.
 
@@ -1276,7 +1322,16 @@ the cookie jar object must implement the C<extract_cookies($response)> and
 C<add_cookie_header($request)> methods.  These methods will then be
 invoked by the user agent as requests are sent and responses are
 received.  Normally this will be a L<HTTP::Cookies> object or some
-subclass.
+subclass.  You are, however, encouraged to use L<HTTP::CookieJar::LWP>
+instead.  See L</"BEST PRACTICES"> for more information.
+
+    use HTTP::CookieJar::LWP ();
+
+    my $jar = HTTP::CookieJar::LWP->new;
+    my $ua = LWP::UserAgent->new( cookie_jar => $jar );
+
+    # or after object creation
+    $ua->cookie_jar( $cookie_jar );
 
 The default is to have no cookie jar, i.e. never automatically add
 C<Cookie> headers to the requests.
@@ -1592,34 +1647,27 @@ the active handlers:
 Add handler to be invoked in the given processing phase.  For how to
 specify C<%matchspec> see L<HTTP::Config/"Matching">.
 
-The possible values C<$phase> and the corresponding callback signatures are:
+The possible values C<$phase> and the corresponding callback signatures are as
+follows.  Note that the handlers are documented in the order in which they will
+be run, which is:
 
-=over
+    request_preprepare
+    request_prepare
+    request_send
+    response_header
+    response_data
+    response_done
+    response_redirect
 
-=item response_data => sub { my($response, $ua, $handler, $data) = @_; ... }
-
-This handler is called for each chunk of data received for the
-response.  The handler might croak to abort the request.
-
-This handler needs to return a TRUE value to be called again for
-subsequent chunks for the same request.
-
-=item response_done => sub { my($response, $ua, $handler) = @_; ... }
-
-The handler is called after the response has been fully received, but
-before any redirect handling is attempted.  The handler can be used to
-extract information or modify the response.
-
-=item response_header => sub { my($response, $ua, $handler) = @_; ... }
+=over
 
-This handler is called right after the response headers have been
-received, but before any content data.  The handler might set up
-handlers for data and might croak to abort the request.
+=item request_preprepare => sub { my($request, $ua, $handler) = @_; ... }
 
-The handler might set the C<< $response->{default_add_content} >> value to
-control if any received data should be added to the response object
-directly.  This will initially be false if the C<< $ua->request() >> method
-was called with a C<$content_file> or C<$content_cb argument>; otherwise true.
+The handler is called before the C<request_prepare> and other standard
+initialization of the request.  This can be used to set up headers
+and attributes that the C<request_prepare> handler depends on.  Proxy
+initialization should take place here; but in general don't register
+handlers for this phase.
 
 =item request_prepare => sub { my($request, $ua, $handler) = @_; ... }
 
@@ -1634,14 +1682,6 @@ The return value from the callback is ignored.  If an exception is
 raised it will abort the request and make the request method return a
 "400 Bad request" response.
 
-=item request_preprepare => sub { my($request, $ua, $handler) = @_; ... }
-
-The handler is called before the C<request_prepare> and other standard
-initialization of the request.  This can be used to set up headers
-and attributes that the C<request_prepare> handler depends on.  Proxy
-initialization should take place here; but in general don't register
-handlers for this phase.
-
 =item request_send => sub { my($request, $ua, $handler) = @_; ... }
 
 This handler gets a chance of handling requests before they're sent to the
@@ -1651,6 +1691,31 @@ wishes to terminate the processing; otherwise it should return nothing.
 The C<response_header> and C<response_data> handlers will not be
 invoked for this response, but the C<response_done> will be.
 
+=item response_header => sub { my($response, $ua, $handler) = @_; ... }
+
+This handler is called right after the response headers have been
+received, but before any content data.  The handler might set up
+handlers for data and might croak to abort the request.
+
+The handler might set the C<< $response->{default_add_content} >> value to
+control if any received data should be added to the response object
+directly.  This will initially be false if the C<< $ua->request() >> method
+was called with a C<$content_file> or C<$content_cb argument>; otherwise true.
+
+=item response_data => sub { my($response, $ua, $handler, $data) = @_; ... }
+
+This handler is called for each chunk of data received for the
+response.  The handler might croak to abort the request.
+
+This handler needs to return a TRUE value to be called again for
+subsequent chunks for the same request.
+
+=item response_done => sub { my($response, $ua, $handler) = @_; ... }
+
+The handler is called after the response has been fully received, but
+before any redirect handling is attempted.  The handler can be used to
+extract information or modify the response.
+
 =item response_redirect => sub { my($response, $ua, $handler) = @_; ... }
 
 The handler is called in C<< $ua->request >> after C<response_done>.  If the
@@ -1687,7 +1752,7 @@ the given processing phase.
 
     $ua->remove_handler( undef, %matchspec );
     $ua->remove_handler( $phase, %matchspec );
-    $ua->remove_handlers(); # REMOVE ALL HANDLERS IN ALL PHASES
+    $ua->remove_handler(); # REMOVE ALL HANDLERS IN ALL PHASES
 
 Remove handlers that match the given C<%matchspec>.  If C<$phase> is not
 provided, remove handlers from all phases.
@@ -1751,9 +1816,9 @@ Fields names that start with ":" are special.  These will not
 initialize headers of the request but will determine how the response
 content is treated.  The following special field names are recognized:
 
-    :content_file   => $filename
-    :content_cb     => \&callback
-    :read_size_hint => $bytes
+    ':content_file'   => $filename
+    ':content_cb'     => \&callback
+    ':read_size_hint' => $bytes
 
 If a $filename is provided with the C<:content_file> option, then the
 response content will be saved here instead of in the response
@@ -1827,6 +1892,33 @@ forced to match that of the server.
 
 The return value is an L<HTTP::Response> object.
 
+=head2 patch
+    # Any version of HTTP::Message works with this form:
+    my $res = $ua->patch( $url, $field_name => $value, Content => $content );
+
+    # Using hash or array references requires HTTP::Message >= 6.12
+    use HTTP::Request 6.12;
+    my $res = $ua->patch( $url, \%form );
+    my $res = $ua->patch( $url, \@form );
+    my $res = $ua->patch( $url, \%form, $field_name => $value, ... );
+    my $res = $ua->patch( $url, $field_name => $value, Content => \%form );
+    my $res = $ua->patch( $url, $field_name => $value, Content => \@form );
+
+This method will dispatch a C<PATCH> request on the given URL, with
+C<%form> or C<@form> providing the key/value pairs for the fill-in form
+content. Additional headers and content options are the same as for
+the L<LWP::UserAgent/get> method.
+
+CAVEAT:
+
+This method can only accept content that is in key-value pairs when using
+L<HTTP::Request::Common> prior to version C<6.12>. Any use of hash or array
+references will result in an error prior to version C<6.12>.
+
+This method will use the C<PATCH> function from L<HTTP::Request::Common>
+to build the request.  See L<HTTP::Request::Common> for a details on
+how to pass form content and other advanced features.
+
 =head2 post
 
     my $res = $ua->post( $url, \%form );
@@ -1988,6 +2080,47 @@ is in the object's C<requests_redirectable> list,
 false if the proposed redirection is to a C<file://...>
 URL, and true otherwise.
 
+=head1 BEST PRACTICES
+
+The default settings can get you up and running quickly, but there are settings
+you can change in order to make your life easier.
+
+=head2 Handling Cookies
+
+You are encouraged to install L<Mozilla::PublicSuffix> and use
+L<HTTP::CookieJar::LWP> as your cookie jar.  L<HTTP::CookieJar::LWP> provides a
+better security model matching that of current Web browsers when
+L<Mozilla::PublicSuffix> is installed.
+
+    use HTTP::CookieJar::LWP ();
+
+    my $jar = HTTP::CookieJar::LWP->new;
+    my $ua = LWP::UserAgent->new( cookie_jar => $jar );
+
+See L</"cookie_jar"> for more information.
+
+=head2 Managing Protocols
+
+C<protocols_allowed> gives you the ability to whitelist the protocols you're
+willing to allow.
+
+    my $ua = LWP::UserAgent->new(
+        protocols_allowed => [ 'http', 'https' ]
+    );
+
+This will prevent you from inadvertently following URLs like
+C<file:///etc/passwd>.  See L</"protocols_allowed">.
+
+C<protocols_forbidden> gives you the ability to blacklist the protocols you're
+unwilling to allow.
+
+    my $ua = LWP::UserAgent->new(
+        protocols_forbidden => [ 'file', 'mailto', 'ssh', ]
+    );
+
+This can also prevent you from inadvertently following URLs like
+C<file:///etc/passwd>.  See L</protocols_forbidden>.
+
 =head1 SEE ALSO
 
 See L<LWP> for a complete overview of libwww-perl5.  See L<lwpcook>