Logical markup.

1 files changed, 86 insertions, 83 deletions

diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index 9b71f1f..913bb8f 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -1,7 +1,7 @@
 \section{Built-in Module \sectcode{socket}}
 \label{module-socket}
-
 \bimodindex{socket}
+
 This module provides access to the BSD \emph{socket} interface.
 It is available on \UNIX{} systems that support this interface.
 
@@ -16,17 +16,17 @@ socket semantics.
 
 The Python interface is a straightforward transliteration of the
 \UNIX{} system call and library interface for sockets to Python's
-object-oriented style: the \code{socket()} function returns a
+object-oriented style: the \function{socket()} function returns a
 \dfn{socket object} whose methods implement the various socket system
 calls.  Parameter types are somewhat higher-level than in the C
-interface: as with \code{read()} and \code{write()} operations on Python
-files, buffer allocation on receive operations is automatic, and
-buffer length is implicit on send operations.
+interface: as with \method{read()} and \method{write()} operations on
+Python files, buffer allocation on receive operations is automatic,
+and buffer length is implicit on send operations.
 
 Socket addresses are represented as a single string for the
-\code{AF_UNIX} address family and as a pair
-\code{(\var{host}, \var{port})} for the \code{AF_INET} address family,
-where \var{host} is a string representing
+\constant{AF_UNIX} address family and as a pair
+\code{(\var{host}, \var{port})} for the \constant{AF_INET} address
+family, where \var{host} is a string representing
 either a hostname in Internet domain notation like
 \code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'},
 and \var{port} is an integral port number.  Other address families are
@@ -35,8 +35,8 @@ socket object is automatically selected based on the address family
 specified when the socket object was created.
 
 For IP addresses, two special forms are accepted instead of a host
-address: the empty string represents \code{INADDR_ANY}, and the string
-\code{"<broadcast>"} represents \code{INADDR_BROADCAST}.
+address: the empty string represents \constant{INADDR_ANY}, and the string
+\code{"<broadcast>"} represents \constant{INADDR_BROADCAST}.
 
 All errors raise exceptions.  The normal exceptions for invalid
 argument types and out-of-memory conditions can be raised; errors
@@ -45,9 +45,9 @@ related to socket or address semantics raise the error \code{socket.error}.
 Non-blocking mode is supported through the \code{setblocking()}
 method.
 
-The module \code{socket} exports the following constants and functions:
+The module \module{socket} exports the following constants and functions:
+
 
-\setindexsubitem{(in module socket)}
 \begin{excdesc}{error}
 This exception is raised for socket- or address-related errors.
 The accompanying value is either a string telling what went wrong or a
@@ -61,8 +61,9 @@ names for the error codes defined by the underlying operating system.
 \begin{datadesc}{AF_UNIX}
 \dataline{AF_INET}
 These constants represent the address (and protocol) families,
-used for the first argument to \code{socket()}.  If the \code{AF_UNIX}
-constant is not defined then this protocol is unsupported.
+used for the first argument to \function{socket()}.  If the
+\constant{AF_UNIX} constant is not defined then this protocol is
+unsupported.
 \end{datadesc}
 
 \begin{datadesc}{SOCK_STREAM}
@@ -71,9 +72,9 @@ constant is not defined then this protocol is unsupported.
 \dataline{SOCK_RDM}
 \dataline{SOCK_SEQPACKET}
 These constants represent the socket types,
-used for the second argument to \code{socket()}.
-(Only \code{SOCK_STREAM} and
-\code{SOCK_DGRAM} appear to be generally useful.)
+used for the second argument to \function{socket()}.
+(Only \constant{SOCK_STREAM} and
+\constant{SOCK_DGRAM} appear to be generally useful.)
 \end{datadesc}
 
 \begin{datadesc}{SO_*}
@@ -86,8 +87,8 @@ used for the second argument to \code{socket()}.
 \dataline{IP_*}
 Many constants of these forms, documented in the \UNIX{} documentation on
 sockets and/or the IP protocol, are also defined in the socket module.
-They are generally used in arguments to the \code{setsockopt} and
-\code{getsockopt} methods of socket objects.  In most cases, only
+They are generally used in arguments to the \method{setsockopt()} and
+\method{getsockopt()} methods of socket objects.  In most cases, only
 those symbols that are defined in the \UNIX{} header files are defined;
 for a few symbols, default values are provided.
 \end{datadesc}
@@ -101,20 +102,19 @@ is an IP address itself it is returned unchanged.
 \begin{funcdesc}{gethostname}{}
 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())}.
-Note: \code{gethostname()} doesn't always return the fully qualified
-domain name; use \code{socket.gethostbyaddr(socket.gethostname())}
+current machine's IP address, use \code{gethostbyname(gethostname())}.
+Note: \function{gethostname()} doesn't always return the fully qualified
+domain name; use \code{gethostbyaddr(gethostname())}
 (see below).
 \end{funcdesc}
 
 \begin{funcdesc}{gethostbyaddr}{ip_address}
-Return a triple \code{(hostname, aliaslist, ipaddrlist)} where
-\code{hostname} is the primary host name responding to the given
-\var{ip_address}, \code{aliaslist} is a (possibly empty) list of
-alternative host names for the same address, and \code{ipaddrlist} is
-a list of IP addresses for the same interface on the same
-host (most likely containing only a single address).
+Return a triple \code{(\var{hostname}, \var{aliaslist},
+\var{ipaddrlist})} where \var{hostname} is the primary host name
+responding to the given \var{ip_address}, \var{aliaslist} is a
+(possibly empty) list of alternative host names for the same address,
+and \var{ipaddrlist} is a list of IP addresses for the same interface
+on the same host (most likely containing only a single address).
 To find the fully qualified domain name, check \var{hostname} and the
 items of \var{aliaslist} for an entry containing at least one period.
 \end{funcdesc}
@@ -122,29 +122,29 @@ items of \var{aliaslist} for an entry containing at least one period.
 \begin{funcdesc}{getprotobyname}{protocolname}
 Translate an Internet protocol name (e.g. \code{'icmp'}) to a constant
 suitable for passing as the (optional) third argument to the
-\code{socket()} function.  This is usually only needed for sockets
-opened in ``raw'' mode (\code{SOCK_RAW}); for the normal socket modes,
-the correct protocol is chosen automatically if the protocol is
+\function{socket()} function.  This is usually only needed for sockets
+opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
+modes, the correct protocol is chosen automatically if the protocol is
 omitted or zero.
 \end{funcdesc}
 
-\begin{funcdesc}{getservbyname}{servicename\, protocolname}
+\begin{funcdesc}{getservbyname}{servicename, protocolname}
 Translate an Internet service name and protocol name to a port number
 for that service.  The protocol name should be \code{'tcp'} or
 \code{'udp'}.
 \end{funcdesc}
 
-\begin{funcdesc}{socket}{family\, type\optional{\, proto}}
+\begin{funcdesc}{socket}{family, type\optional{, proto}}
 Create a new socket using the given address family, socket type and
-protocol number.  The address family should be \code{AF_INET} or
-\code{AF_UNIX}.  The socket type should be \code{SOCK_STREAM},
-\code{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants.
+protocol number.  The address family should be \constant{AF_INET} or
+\constant{AF_UNIX}.  The socket type should be \constant{SOCK_STREAM},
+\constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants.
 The protocol number is usually zero and may be omitted in that case.
 \end{funcdesc}
 
-\begin{funcdesc}{fromfd}{fd\, family\, type\optional{\, proto}}
+\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
 Build a socket object from an existing file descriptor (an integer as
-returned by a file object's \code{fileno} method).  Address family,
+returned by a file object's \method{fileno()} method).  Address family,
 socket type and protocol number are as for the \code{socket} function
 above.  The file descriptor should refer to a socket, but this is not
 checked --- subsequent operations on the object may fail if the file
@@ -180,15 +180,14 @@ no-op; otherwise, it performs a 2-byte swap operation.
 
 \begin{datadesc}{SocketType}
 This is a Python type object that represents the socket object type.
-It is the same as \code{type(socket.socket(...))}.
+It is the same as \code{type(socket(...))}.
 \end{datadesc}
 
 \subsection{Socket Objects}
 
-\noindent
 Socket objects have the following methods.  Except for
-\code{makefile()} these correspond to \UNIX{} system calls applicable to
-sockets.
+\method{makefile()} these correspond to \UNIX{} system calls
+applicable to sockets.
 
 \setindexsubitem{(socket method)}
 \begin{funcdesc}{accept}{}
@@ -213,19 +212,20 @@ Sockets are automatically closed when they are garbage-collected.
 
 \begin{funcdesc}{connect}{address}
 Connect to a remote socket at \var{address}.
-(The format of \var{address} depends on the address family --- see above.)
+(The format of \var{address} depends on the address family --- see
+above.)
 \end{funcdesc}
 
 \begin{funcdesc}{connect_ex}{address}
 Like \code{connect(\var{address})}, but return an error indicator
 instead of raising an exception.  The error indicator is 0 if the
-operation succeeded, otherwise the value of the \code{errno}
+operation succeeded, otherwise the value of the \cdata{errno}
 variable.  This is useful e.g. for asynchronous connects.
 \end{funcdesc}
 
 \begin{funcdesc}{fileno}{}
 Return the socket's file descriptor (a small integer).  This is useful
-with \code{select}.
+with \function{select.select()}.
 \end{funcdesc}
 
 \begin{funcdesc}{getpeername}{}
@@ -242,16 +242,16 @@ number of an IP socket, for instance.
 see above.)
 \end{funcdesc}
 
-\begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}}
+\begin{funcdesc}{getsockopt}{level, optname\optional{, buflen}}
 Return the value of the given socket option (see the \UNIX{} man page
-\emph{getsockopt}(2)).  The needed symbolic constants (\code{SO_*} etc.)
-are defined in this module.  If \var{buflen}
+\manpage{getsockopt}{2}).  The needed symbolic constants
+(\constant{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 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).
+\module{struct} for a way to decode C structures encoded as strings).
 \end{funcdesc}
 
 \begin{funcdesc}{listen}{backlog}
@@ -262,42 +262,42 @@ least 1; the maximum value is system-dependent (usually 5).
 
 \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.
+were described earlier in \ref{bltin-file-objects}, ``File Objects.'')
+The file object references a \cfunction{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 \function{open()} function.
 \end{funcdesc}
 
-\begin{funcdesc}{recv}{bufsize\optional{\, flags}}
+\begin{funcdesc}{recv}{bufsize\optional{, flags}}
 Receive data from the socket.  The return value is a string representing
 the data received.  The maximum amount of data to be received
 at once is specified by \var{bufsize}.  See the \UNIX{} manual page
-for the meaning of the optional argument \var{flags}; it defaults to
-zero.
+\manpage{recv}{2} for the meaning of the optional argument
+\var{flags}; it defaults to zero.
 \end{funcdesc}
 
-\begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}}
+\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.  The optional \var{flags} argument has the
-same meaning as for \code{recv()} above.
+same meaning as for \method{recv()} above.
 (The format of \var{address} depends on the address family --- see above.)
 \end{funcdesc}
 
-\begin{funcdesc}{send}{string\optional{\, flags}}
+\begin{funcdesc}{send}{string\optional{, flags}}
 Send data to the socket.  The socket must be connected to a remote
 socket.  The optional \var{flags} argument has the same meaning as for
-\code{recv()} above.  Return the number of bytes sent.
+\method{recv()} above.  Returns the number of bytes sent.
 \end{funcdesc}
 
 \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}.  The optional \var{flags} argument has the same
-meaning as for \code{recv()} above.  Return the number of bytes sent.
+\var{address}.  The optional \var{flags} argument has the same
+meaning as for \method{recv()} above.  Return the number of bytes sent.
 (The format of \var{address} depends on the address family --- see above.)
 \end{funcdesc}
 
@@ -305,30 +305,32 @@ meaning as for \code{recv()} above.  Return the number of bytes sent.
 Set blocking or non-blocking mode of the socket: if \var{flag} is 0,
 the socket is set to non-blocking, else to blocking mode.  Initially
 all sockets are in blocking mode.  In non-blocking mode, if a
-\code{recv} call doesn't find any data, or if a \code{send} call can't
-immediately dispose of the data, a \code{socket.error} exception is
+\method{recv()} call doesn't find any data, or if a \code{send} call can't
+immediately dispose of the data, a \exception{error} exception is
 raised; in blocking mode, the calls block until they can proceed.
 \end{funcdesc}
 
 \begin{funcdesc}{setsockopt}{level\, optname\, value}
 Set the value of the given socket option (see the \UNIX{} man page
-\emph{setsockopt}(2)).  The needed symbolic constants are defined in
-the \code{socket} module (\code{SO_*} etc.).  The value can be an
+\manpage{setsockopt}{2}).  The needed symbolic constants are defined in
+the \module{socket} module (\code{SO_*} etc.).  The value can be an
 integer or a string representing a buffer.  In the latter case it is
 up to the caller to ensure that the string contains the proper bits
 (see the optional built-in module
-\code{struct} for a way to encode C structures as strings).
+\module{struct}\refbimodindex{struct} for a way to encode C structures
+as strings). 
 \end{funcdesc}
 
 \begin{funcdesc}{shutdown}{how}
-Shut down one or both halves of the connection.  If \var{how} is \code{0},
-further receives are disallowed.  If \var{how} is \code{1}, further sends are
-disallowed.  If \var{how} is \code{2}, further sends and receives are
-disallowed.
+Shut down one or both halves of the connection.  If \var{how} is
+\code{0}, further receives are disallowed.  If \var{how} is \code{1},
+further sends are disallowed.  If \var{how} is \code{2}, further sends
+and receives are disallowed.
 \end{funcdesc}
 
-Note that there are no methods \code{read()} or \code{write()}; use
-\code{recv()} and \code{send()} without \var{flags} argument instead.
+Note that there are no methods \method{read()} or \method{write()};
+use \method{recv()} and \method{send()} without \var{flags} argument
+instead.
 
 \subsection{Example}
 \nodename{Socket Example}
@@ -336,12 +338,13 @@ Note that there are no methods \code{read()} or \code{write()}; use
 Here are two minimal example programs using the TCP/IP protocol:\ a
 server that echoes all data that it receives back (servicing only one
 client), and a client using it.  Note that a server must perform the
-sequence \code{socket}, \code{bind}, \code{listen}, \code{accept}
-(possibly repeating the \code{accept} to service more than one client),
-while a client only needs the sequence \code{socket}, \code{connect}.
-Also note that the server does not \code{send}/\code{receive} on the
+sequence \function{socket()}, \method{bind()}, \method{listen()},
+\method{accept()} (possibly repeating the \method{accept()} to service
+more than one client), while a client only needs the sequence
+\function{socket()}, \method{connect()}.  Also note that the server
+does not \method{send()}/\method{recv()} on the 
 socket it is listening on but on the new socket returned by
-\code{accept}.
+\method{accept()}.
 
 \begin{verbatim}
 # Echo server program
@@ -359,7 +362,7 @@ while 1:
     conn.send(data)
 conn.close()
 \end{verbatim}
-%
+
 \begin{verbatim}
 # Echo client program
 from socket import *
@@ -372,7 +375,7 @@ data = s.recv(1024)
 s.close()
 print 'Received', `data`
 \end{verbatim}
-%
+
 \begin{seealso}
 \seemodule{SocketServer}{classes that simplify writing network servers}
 \end{seealso}