Fix a variety of typographical, grammatical, and clarity problems reported
by Detlef Lannert.
diff --git a/Doc/lib/liburllib2.tex b/Doc/lib/liburllib2.tex
index 46d4f66..02a3cc3 100644
--- a/Doc/lib/liburllib2.tex
+++ b/Doc/lib/liburllib2.tex
@@ -15,7 +15,7 @@
The \module{urllib2} module defines the following functions:
\begin{funcdesc}{urlopen}{url\optional{, data}}
-Open the url \var{url}, which can either a string or a \class{Request}
+Open the URL \var{url}, which can be either a string or a \class{Request}
object (currently the code checks that it really is a \class{Request}
instance, or an instance of a subclass of \class{Request}).
@@ -37,7 +37,7 @@
\end{funcdesc}
\begin{funcdesc}{install_opener}{opener}
-Install a \class{OpenerDirector} instance as the default opener.
+Install an \class{OpenerDirector} instance as the default opener.
The code does not check for a real \class{OpenerDirector}, and any
class with the appropriate interface will work.
\end{funcdesc}
@@ -47,8 +47,8 @@
handlers in the order given. \var{handler}s can be either instances
of \class{BaseHandler}, or subclasses of \class{BaseHandler} (in
which case it must be possible to call the constructor without
-any parameters. Instances of the following classes will be in
-the front of the \var{handler}s, unless the \var{handler}s contain
+any parameters). Instances of the following classes will be in
+front of the \var{handler}s, unless the \var{handler}s contain
them, instances of them or subclasses of them:
\code{ProxyHandler, UnknownHandler, HTTPHandler, HTTPDefaultErrorHandler,
@@ -62,8 +62,8 @@
The following exceptions are raised as appropriate:
\begin{excdesc}{URLError}
-The error handlers raise when they run into a problem. It is a
-subclass of \exception{IOError}.
+The handlers raise this exception (or derived exceptions) when they
+run into a problem. It is a subclass of \exception{IOError}.
\end{excdesc}
\begin{excdesc}{HTTPError}
@@ -84,7 +84,7 @@
\begin{classdesc}{Request}{url\optional{, data\optional{, headers}}}
This class is an abstraction of a URL request.
-\var{url} should be a string which is a valid URL. For descrtion
+\var{url} should be a string which is a valid URL. For a description
of \var{data} see the \method{add_data()} description.
\var{headers} should be a dictionary, and will be treated as if
\method{add_header()} was called with each key and value as arguments.
@@ -134,41 +134,45 @@
\begin{classdesc}{AbstractBasicAuthHandler}{\optional{password_mgr}}
This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
-
-\var{password_mgr} should be something that is compatible with
-\class{HTTPPasswordMgr} --- supplies the documented interface above.
+\var{password_mgr}, if given, should be something that is compatible
+with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
+for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{HTTPBasicAuthHandler}{\optional{password_mgr}}
Handle authentication with the remote host.
-Valid \var{password_mgr}, if given, are the same as for
-\class{AbstractBasicAuthHandler}.
+\var{password_mgr}, if given, should be something that is compatible
+with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
+for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{ProxyBasicAuthHandler}{\optional{password_mgr}}
Handle authentication with the proxy.
-Valid \var{password_mgr}, if given, are the same as for
-\class{AbstractBasicAuthHandler}.
+\var{password_mgr}, if given, should be something that is compatible
+with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
+for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{AbstractDigestAuthHandler}{\optional{password_mgr}}
-This is a mixin class, that helps with HTTP authentication, both
+This is a mixin class that helps with HTTP authentication, both
to the remote host and to a proxy.
-
-\var{password_mgr} should be something that is compatible with
-\class{HTTPPasswordMgr} --- supplies the documented interface above.
+\var{password_mgr}, if given, should be something that is compatible
+with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
+for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{HTTPDigestAuthHandler}{\optional{password_mgr}}
Handle authentication with the remote host.
-Valid \var{password_mgr}, if given, are the same as for
-\class{AbstractBasicAuthHandler}.
+\var{password_mgr}, if given, should be something that is compatible
+with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
+for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{ProxyDigestAuthHandler}{\optional{password_mgr}}
Handle authentication with the proxy.
-\var{password_mgr}, if given, shoudl be the same as for
-the constructor of \class{AbstractDigestAuthHandler}.
+\var{password_mgr}, if given, should be something that is compatible
+with \class{HTTPPasswordMgr}; refer to section~\ref{http-password-mgr}
+for information on the interface that must be supported.
\end{classdesc}
\begin{classdesc}{HTTPHandler}{}
@@ -207,28 +211,28 @@
and so all must be overridden in subclasses.
\begin{methoddesc}[Request]{add_data}{data}
-Set the \class{Request} data to \var{data} is ignored
+Set the \class{Request} data to \var{data}. This is ignored
by all handlers except HTTP handlers --- and there it should be an
\mimetype{application/x-www-form-encoded} buffer, and will change the
-request to be \code{POST} rather then \code{GET}.
+request to be \code{POST} rather than \code{GET}.
\end{methoddesc}
-\begin{methoddesc}[Request]{has_data}{data}
+\begin{methoddesc}[Request]{has_data}{}
Return whether the instance has a non-\code{None} data.
\end{methoddesc}
-\begin{methoddesc}[Request]{get_data}{data}
+\begin{methoddesc}[Request]{get_data}{}
Return the instance's data.
\end{methoddesc}
\begin{methoddesc}[Request]{add_header}{key, val}
Add another header to the request. Headers are currently ignored by
all handlers except HTTP handlers, where they are added to the list
-of headers sent to the server. Note that there cannot be more then
+of headers sent to the server. Note that there cannot be more than
one header with the same name, and later calls will overwrite
previous calls in case the \var{key} collides. Currently, this is
no loss of HTTP functionality, since all headers which have meaning
-when used more then once have a (header-specific) way of gaining the
+when used more than once have a (header-specific) way of gaining the
same functionality using only one header.
\end{methoddesc}
@@ -241,7 +245,7 @@
\end{methoddesc}
\begin{methoddesc}[Request]{get_host}{}
-Return the host to which connection will be made.
+Return the host to which a connection will be made.
\end{methoddesc}
\begin{methoddesc}[Request]{get_selector}{}
@@ -250,8 +254,8 @@
\end{methoddesc}
\begin{methoddesc}[Request]{set_proxy}{host, type}
-Make the request by connecting to a proxy server. The \var{host} and
-\var{type} will replace those of the instance, and the instance's
+Prepare the request by connecting to a proxy server. The \var{host}
+and \var{type} will replace those of the instance, and the instance's
selector will be the original URL given in the constructor.
\end{methoddesc}
@@ -277,13 +281,13 @@
Explicitly break cycles, and delete all the handlers.
Because the \class{OpenerDirector} needs to know the registered handlers,
and a handler needs to know who the \class{OpenerDirector} who called
-it is, there is a reference cycles. Even though recent versions of Python
+it is, there is a reference cycle. Even though recent versions of Python
have cycle-collection, it is sometimes preferable to explicitly break
the cycles.
\end{methoddesc}
\begin{methoddesc}[OpenerDirector]{open}{url\optional{, data}}
-Open the given \var{url}. (which can be a request object or a string),
+Open the given \var{url} (which can be a request object or a string),
optionally passing the given \var{data}.
Arguments, return values and exceptions raised are the same as those
of \function{urlopen()} (which simply calls the \method{open()} method
@@ -292,9 +296,11 @@
\begin{methoddesc}[OpenerDirector]{error}{proto\optional{,
arg\optional{, \moreargs}}}
-Handle an error in a given protocol. The HTTP protocol is special cased to
-use the code as the error. This will call the registered error handlers
-for the given protocol with the given arguments (which are protocol specific).
+Handle an error in a given protocol. This will call the registered
+error handlers for the given protocol with the given arguments (which
+are protocol specific). The HTTP protocol is a special case which
+uses the HTTP response code to determine the specific error handler;
+refer to the \method{http_error_*()} methods of the handler classes.
Return values and exceptions raised are the same as those
of \function{urlopen()}.
@@ -315,7 +321,7 @@
Remove any parents.
\end{methoddesc}
-The following members and methods should be used only be classes
+The following members and methods should only be used by classes
derived from \class{BaseHandler}:
\begin{memberdesc}[BaseHandler]{parent}
@@ -327,13 +333,13 @@
This method is \emph{not} defined in \class{BaseHandler}, but
subclasses should define it if they want to catch all URLs.
-This method, if exists, will be called by the \member{parent}
+This method, if implemented, will be called by the parent
\class{OpenerDirector}. It should return a file-like object as
described in the return value of the \method{open()} of
-\class{OpenerDirector} or \code{None}. It should raise
+\class{OpenerDirector}, or \code{None}. It should raise
\exception{URLError}, unless a truly exceptional thing happens (for
example, \exception{MemoryError} should not be mapped to
-\exception{URLError}.
+\exception{URLError}).
This method will be called before any protocol-specific open method.
\end{methoddesc}
@@ -343,7 +349,7 @@
subclasses should define it if they want to handle URLs with the given
protocol.
-This method, if defined, will be called by the \member{parent}
+This method, if defined, will be called by the parent
\class{OpenerDirector}. Return values should be the same as for
\method{default_open()}.
\end{methoddescni}
@@ -351,9 +357,9 @@
\begin{methoddesc}[BaseHandler]{unknown_open}{req}
This method is \var{not} defined in \class{BaseHandler}, but
subclasses should define it if they want to catch all URLs with no
-specific registerd handler to open it.
+specific registered handler to open it.
-This method, if exists, will be called by the \member{parent}
+This method, if implemented, will be called by the \member{parent}
\class{OpenerDirector}. Return values should be the same as for
\method{default_open()}.
\end{methoddesc}
@@ -448,10 +454,12 @@
\begin{methoddesc}[AbstractBasicAuthHandler]{handle_authentication_request}
{authreq, host, req, headers}
-Handle an authentication request by getting user/password pair, and retrying.
-\var{authreq} should be the name of the header where the information about
-the realm, \var{host} is the host to authenticate too, \var{req} should be the
-(failed) \class{Request} object, and \var{headers} should be the error headers.
+Handle an authentication request by getting a user/password pair, and
+re-trying the request. \var{authreq} should be the name of the header
+where the information about the realm is included in the request,
+\var{host} is the host to authenticate to, \var{req} should be the
+(failed) \class{Request} object, and \var{headers} should be the error
+headers.
\end{methoddesc}
@@ -460,7 +468,7 @@
\begin{methoddesc}[HTTPBasicAuthHandler]{http_error_401}{req, fp, code,
msg, hdrs}
-Retry the request with authentication info, if available.
+Retry the request with authentication information, if available.
\end{methoddesc}
@@ -469,7 +477,7 @@
\begin{methoddesc}[ProxyBasicAuthHandler]{http_error_407}{req, fp, code,
msg, hdrs}
-Retry the request with authentication info, if available.
+Retry the request with authentication information, if available.
\end{methoddesc}
@@ -479,9 +487,9 @@
\begin{methoddesc}[AbstractDigestAuthHandler]{handle_authentication_request}
{authreq, host, req, headers}
\var{authreq} should be the name of the header where the information about
-the realm, \var{host} should be the host to authenticate too, \var{req}
-should be the (failed) \class{Request} object, and \var{headers} should be the
-error headers.
+the realm is included in the request, \var{host} should be the host to
+authenticate to, \var{req} should be the (failed) \class{Request}
+object, and \var{headers} should be the error headers.
\end{methoddesc}
@@ -490,7 +498,7 @@
\begin{methoddesc}[HTTPDigestAuthHandler]{http_error_401}{req, fp, code,
msg, hdrs}
-Retry the request with authentication info, if available.
+Retry the request with authentication information, if available.
\end{methoddesc}
@@ -506,7 +514,7 @@
\subsection{HTTPHandler Objects \label{http-handler-objects}}
\begin{methoddesc}[HTTPHandler]{http_open}{req}
-Send an HTTP request, whcih can be either GET or POST, depending on
+Send an HTTP request, which can be either GET or POST, depending on
\code{\var{req}.has_data()}.
\end{methoddesc}