mass changes; fix titles; add examples; correct typos; clarifications;

unified style; etc.

Doc/lib/libhttplib.tex

@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{httplib}}
+\section{Standard Module \sectcode{httplib}}
 \stmodindex{httplib}
 \index{HTTP}
 
@@ -15,7 +15,15 @@ instantiated passing it a host and optional port number.  If no port
 number is passed, the port is extracted from the host string if it has
 the form \code{host:port}, else the default HTTP port (80) is used.
 If no host is passed, no connection is made, and the \code{connect}
-method should be used to connect to a server.
+method should be used to connect to a server.  For example, the
+following calls all create instances that connect to the server at the
+same host and port:
+
+\begin{verbatim}
+>>> h1 = httplib.HTTP('www.cwi.nl')
+>>> h2 = httplib.HTTP('www.cwi.nl:80')
+>>> h3 = httplib.HTTP('www.cwi.nl', 80)
+\end{verbatim}
 
 Once an \code{HTTP} instance has been connected to an HTTP server, it
 should be used as follows:
@@ -27,7 +35,7 @@ should be used as follows:
 \item[2.] Make zero or more calls to the \code{putheader()} method.
 
 \item[3.] Call the \code{endheaders()} method (this can be omitted if
-step 4. makes no calls).
+step 4 makes no calls).
 
 \item[4.] Optional calls to the \code{send()} method.
 
@@ -93,3 +101,22 @@ Return a file object from which the data returned by the server can be
 read, using the \code{read()}, \code{readline()} or \code{readlines()}
 methods.
 \end{funcdesc}
+
+\subsection{Example}
+
+Here is an example session:
+
+\begin{verbatim}
+>>> import httplib
+>>> h = httplib.HTTP('www.cwi.nl')
+>>> h.putrequest('GET', '/index.html')
+>>> h.putheader('Accept', 'text/html')
+>>> h.putheader('Accept', 'text/plain')
+>>> h.endheaders()
+>>> errcode, errmsg, headers = h.getreply()
+>>> print errcode # Should be 200
+>>> f = h.getfile()
+>>> data f.read() # Get the raw HTML
+>>> f.close()
+>>> 
+\end{verbatim}