--- AnyEvent-HTTP/README	2009/07/07 00:15:32	1.8
+++ AnyEvent-HTTP/README	2010/06/16 19:17:30	1.13
@@ -56,10 +56,22 @@
         response headers as second argument.
 
         All the headers in that hash are lowercased. In addition to the
-        response headers, the "pseudo-headers" "HTTPVersion", "Status" and
-        "Reason" contain the three parts of the HTTP Status-Line of the same
-        name. The pseudo-header "URL" contains the original URL (which can
-        differ from the requested URL when following redirects).
+        response headers, the "pseudo-headers" (uppercase to avoid clashing
+        with possible response headers) "HTTPVersion", "Status" and "Reason"
+        contain the three parts of the HTTP Status-Line of the same name.
+
+        The pseudo-header "URL" contains the actual URL (which can differ
+        from the requested URL when following redirects - for example, you
+        might get an error that your URL scheme is not supported even though
+        your URL is a valid http URL because it redirected to an ftp URL, in
+        which case you can look at the URL pseudo header).
+
+        The pseudo-header "Redirect" only exists when the request was a
+        result of an internal redirect. In that case it is an array
+        reference with the "($data, $headers)" from the redirect response.
+        Note that this response could in turn be the result of a redirect
+        itself, and "$headers->{Redirect}[1]{Redirect}" will then contain
+        the original response, and so on.
 
         If the server sends a header multiple times, then their contents
         will be joined together with a comma (","), as per the HTTP spec.
@@ -92,20 +104,23 @@
             The request headers to use. Currently, "http_request" may
             provide its own "Host:", "Content-Length:", "Connection:" and
             "Cookie:" headers and will provide defaults for "User-Agent:"
-            and "Referer:".
+            and "Referer:" (this can be suppressed by using "undef" for
+            these headers in which case they won't be sent at all).
 
         timeout => $seconds
             The time-out to use for various stages - each connect attempt
-            will reset the timeout, as will read or write activity. Default
-            timeout is 5 minutes.
+            will reset the timeout, as will read or write activity, i.e.
+            this is not an overall timeout.
+
+            Default timeout is 5 minutes.
 
         proxy => [$host, $port[, $scheme]] or undef
             Use the given http proxy for all requests. If not specified,
             then the default proxy (as specified by $ENV{http_proxy}) is
             used.
 
-            $scheme must be either missing or "http" for HTTP, or "https"
-            for HTTPS.
+            $scheme must be either missing, "http" for HTTP or "https" for
+            HTTPS.
 
         body => $string
             The request body, usually empty. Will be-sent as-is (future
@@ -139,6 +154,15 @@
             The default for this option is "low", which could be interpreted
             as "give me the page, no matter what".
 
+        on_prepare => $callback->($fh)
+            In rare cases you need to "tune" the socket before it is used to
+            connect (for exmaple, to bind it on a given IP address). This
+            parameter overrides the prepare callback passed to
+            "AnyEvent::Socket::tcp_connect" and behaves exactly the same way
+            (e.g. it has to provide a timeout). See the description for the
+            $prepare_cb argument of "AnyEvent::Socket::tcp_connect" for
+            details.
+
         on_header => $callback->($headers)
             When specified, this callback will be called with the header
             hash as soon as headers have been successfully received from the
@@ -176,7 +200,10 @@
             processed incrementally.
 
             It is usually preferred over doing your own body handling via
-            "want_body_handle".
+            "want_body_handle", but in case of streaming APIs, where HTTP is
+            only used to create a connection, "want_body_handle" is the
+            better alternative, as it allows you to install your own event
+            handler, reducing resource usage.
 
         want_body_handle => $enable
             When enabled (default is disabled), the behaviour of
@@ -199,7 +226,7 @@
             JSON/XML stream).
 
             If you think you need this, first have a look at "on_body", to
-            see if that doesn'T solve your problem in a better way.
+            see if that doesn't solve your problem in a better way.
 
         Example: make a simple HTTP GET request for http://www.nethype.de/
 
@@ -231,10 +258,21 @@
 
            undef $request;
 
+  DNS CACHING
+    AnyEvent::HTTP uses the AnyEvent::Socket::tcp_connect function for the
+    actual connection, which in turn uses AnyEvent::DNS to resolve
+    hostnames. The latter is a simple stub resolver and does no caching on
+    its own. If you want DNS caching, you currently have to provide your own
+    default resolver (by storing a suitable resolver object in
+    $AnyEvent::DNS::RESOLVER).
+
   GLOBAL FUNCTIONS AND VARIABLES
     AnyEvent::HTTP::set_proxy "proxy-url"
         Sets the default proxy server to use. The proxy-url must begin with
-        a string of the form "http://host:port" (optionally "https:...").
+        a string of the form "http://host:port" (optionally "https:..."),
+        croaks otherwise.
+
+        To clear an already-set proxy, use "undef".
 
     $AnyEvent::HTTP::MAX_RECURSE
         The default value for the "recurse" request parameter (default: 10).
@@ -245,7 +283,7 @@
         +http://software.schmorp.de/pkg/AnyEvent)").
 
     $AnyEvent::HTTP::MAX_PER_HOST
-        The maximum number of concurrent conenctions to the same host
+        The maximum number of concurrent connections to the same host
         (identified by the hostname). If the limit is exceeded, then the
         additional requests are queued until previous connections are
         closed.