mass changes; fix titles; add examples; correct typos; clarifications;
unified style; etc.
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index b826601..9b3c228 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -37,8 +37,8 @@
argument types and out-of-memory conditions can be raised; errors
related to socket or address semantics raise the error \code{socket.error}.
-Non-blocking and asynchronous mode are not supported; see module
-\code{select} for a way to do non-blocking socket I/O.
+Non-blocking mode is supported through the \code{setblocking()}
+method.
The module \code{socket} exports the following constants and functions:
@@ -95,7 +95,7 @@
Return a string containing the hostname of the machine where
the Python interpreter is currently executing. If you want to know the
current machine's IP address, use
-\code{socket.gethostbyname(socket.gethostname())} instead.
+\code{socket.gethostbyname(socket.gethostname())}.
\end{funcdesc}
\begin{funcdesc}{gethostbyaddr}{ip_address}
@@ -133,7 +133,7 @@
daemon).
\end{funcdesc}
-\subsection{Socket Object Methods}
+\subsection{Socket Objects}
\noindent
Socket objects have the following methods. Except for
@@ -187,28 +187,30 @@
\begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}}
Return the value of the given socket option (see the \UNIX{} man page
-{\it getsockopt}(2)). The needed symbolic constants are defined in
-the \code{socket} module (\code{SO_*} etc.). If the optional third
-argument is absent, an integer option is assumed and its integer value
+{\it getsockopt}(2)). The needed symbolic constants (\code{SO_*} etc.)
+are defined in this module. If \var{buflen}
+is absent, an integer option is assumed and its integer value
is returned by the function. If \var{buflen} is present, it specifies
the maximum length of the buffer used to receive the option in, and
-this buffer is returned as a string. It's up to the caller to decode
+this buffer is returned as a string. It is up to the caller to decode
the contents of the buffer (see the optional built-in module
\code{struct} for a way to decode C structures encoded as strings).
\end{funcdesc}
\begin{funcdesc}{listen}{backlog}
-Listen for connections made to the socket.
-The argument specifies the maximum number of queued connections and
-should be at least 1; the maximum value is system-dependent.
+Listen for connections made to the socket. The \var{backlog} argument
+specifies the maximum number of queued connections and should be at
+least 1; the maximum value is system-dependent (usually 5).
\end{funcdesc}
-\begin{funcdesc}{makefile}{mode}
-Return a \dfn{file object} associated with the socket.
-(File objects were described earlier under Built-in Types.)
-The file object references a \code{dup}ped version of the socket file
-descriptor, so the file object and socket object may be closed or
-garbage-collected independently.
+\begin{funcdesc}{makefile}{\optional{mode\optional{\, bufsize}}}
+Return a \dfn{file object} associated with the socket. (File objects
+were described earlier under Built-in Types.) The file object
+references a \code{dup()}ped version of the socket file descriptor, so
+the file object and socket object may be closed or garbage-collected
+independently. The optional \var{mode} and \var{bufsize} arguments
+are interpreted the same way as by the built-in
+\code{open()} function.
\end{funcdesc}
\begin{funcdesc}{recv}{bufsize\optional{\, flags}}
@@ -219,23 +221,26 @@
zero.
\end{funcdesc}
-\begin{funcdesc}{recvfrom}{bufsize}
+\begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}}
Receive data from the socket. The return value is a pair
\code{(\var{string}, \var{address})} where \var{string} is a string
representing the data received and \var{address} is the address of the
-socket sending the data.
+socket sending the data. The optional \var{flags} argument has the
+same meaning as for \code{recv()} above.
(The format of \var{address} depends on the address family --- see above.)
\end{funcdesc}
-\begin{funcdesc}{send}{string}
+\begin{funcdesc}{send}{string\optional{\, flags}}
Send data to the socket. The socket must be connected to a remote
-socket. Return the number of bytes sent.
+socket. The optional \var{flags} argument has the same meaning as for
+\code{recv()} above. Return the number of bytes sent.
\end{funcdesc}
-\begin{funcdesc}{sendto}{string\, address}
+\begin{funcdesc}{sendto}{string\optional{\, flags}\, address}
Send data to the socket. The socket should not be connected to a
remote socket, since the destination socket is specified by
-\code{address}. Return the number of bytes sent.
+\code{address}. The optional \var{flags} argument has the same
+meaning as for \code{recv()} above. Return the number of bytes sent.
(The format of \var{address} depends on the address family --- see above.)
\end{funcdesc}