added WWW sections

Doc/Makefile

@@ -32,23 +32,27 @@ ref.dvi: ref.tex ref1.tex ref2.tex ref3.tex ref4.tex ref5.tex ref6.tex \
 LIBFILES = lib.tex \
 libal.tex libaifc.tex libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \
 libbltin.tex \
-libcopy.tex libcrypto.tex \
+libcgi.tex libcopy.tex libcrypto.tex \
 libdbm.tex \
 libexcs.tex \
-libfcntl.tex libfl.tex libfm.tex libfuncs.tex \
-libgdbm.tex libgetopt.tex libgl.tex libgrp.tex \
+libfcntl.tex libfl.tex libfm.tex libftplib.tex libfuncs.tex \
+libgdbm.tex libgetopt.tex libgl.tex libgopherlib.tex libgrp.tex \
+libhtmllib.tex libhttplib.tex \
 libimageop.tex libimgfile.tex libintro.tex \
 libjpeg.tex \
 libmac.tex libmain.tex libmarshal.tex libmath.tex \
-	libmd5.tex libmm.tex libmods.tex libmpz.tex \
+	libmd5.tex libmimetools.tex libmm.tex libmods.tex libmpz.tex \
+libnntplib.tex \
 libobjs.tex libos.tex \
 libpanel.tex libposix.tex libposixfile.tex libppath.tex libpickle.tex \
 	libpwd.tex \
-librand.tex libregex.tex libregsub.tex librgbimg.tex librotor.tex \
-libselect.tex libsgi.tex libshelve.tex libsocket.tex libstd.tex libstdwin.tex \
+librand.tex libregex.tex libregsub.tex \
+	librfc822.tex librgbimg.tex librotor.tex \
+libselect.tex libsgi.tex libsgmllib.tex \
+	libshelve.tex libsocket.tex libstd.tex libstdwin.tex \
 	libstring.tex libstruct.tex libsun.tex libsys.tex \
-libthread.tex libtime.tex libtypes.tex \
-libunix.tex \
+libthread.tex libtime.tex libtypes.tex libtypes2.tex \
+libunix.tex liburllib.tex liburlparse.tex \
 libwhrandom.tex libwww.tex
 
 lib.dvi: $(LIBFILES)

Doc/lib.tex

@@ -70,6 +70,7 @@
 \input{libpickle}
 \input{libshelve}
 \input{libcopy}
+\input{libtypes2}		% types is already taken :-(
 
 \input{libunix}			% UNIX ONLY
 \input{libdbm}
@@ -86,6 +87,7 @@
 \input{libthread}
 
 \input{libwww}			% WWW EXTENSIONS
+\input{libcgi}
 \input{libftplib}
 \input{libgopherlib}
 \input{libhtmllib}

Doc/lib/lib.tex

@@ -70,6 +70,7 @@
 \input{libpickle}
 \input{libshelve}
 \input{libcopy}
+\input{libtypes2}		% types is already taken :-(
 
 \input{libunix}			% UNIX ONLY
 \input{libdbm}
@@ -86,6 +87,7 @@
 \input{libthread}
 
 \input{libwww}			% WWW EXTENSIONS
+\input{libcgi}
 \input{libftplib}
 \input{libgopherlib}
 \input{libhtmllib}

Doc/lib/libcgi.tex

@@ -0,0 +1,130 @@
+\section{Built-in module \sectcode{cgi}}
+\stmodindex{cgi}
+\indexii{WWW}{server}
+\indexii{CGI}{protocol}
+\indexii{HTTP}{protocol}
+\indexii{MIME}{headers}
+\index{URL}
+
+This module makes it easy to write Python scripts that run in a WWW
+server using the Common Gateway Interface.  It was written by Michael
+McLay and subsequently modified by Steve Majewski and Guido van
+Rossum.
+
+When a WWW server finds that a URL contains a reference to a file in a
+particular subdirectory (usually \code{/cgibin}), it runs the file as
+a subprocess.  Information about the request such as the full URL, the
+originating host etc., is passed to the subprocess in the shell
+environment; additional input from the client may be read from
+standard input.  Standard output from the subprocess is sent back
+across the network to the client as the response from the request.
+The CGI protocol describes what the environment variables passed to
+the subprocess mean and how the output should be formatted.  The
+official reference documentation for the CGI protocol can be found on
+the World-Wide Web at
+\code{<URL:http://hoohoo.ncsa.uiuc.edu/cgi/overview.html>}.  The
+\code{cgi} module was based on version 1.1 of the protocol and should
+also work with version 1.0.
+
+The \code{cgi} module defines several classes that make it easy to
+access the information passed to the subprocess from a Python script;
+in particular, it knows how to parse the input sent by an HTML
+``form'' using either a POST or a GET request (these are alternatives
+for submitting forms in the HTTP protocol).
+
+The formatting of the output is so trivial that no additional support
+is needed.  All you need to do is print a minimal set of MIME headers
+describing the output format, followed by a blank line and your actual
+output.  E.g. if you want to generate HTML, your script could start as
+follows:
+
+\begin{verbatim}
+# Header -- one or more lines:
+print "Content-type: text/html"
+# Blank line separating header from body:
+print
+# Body, in HTML format:
+print "<TITLE>The Amazing SPAM Homepage!</TITLE>"
+# etc...
+\end{verbatim}
+
+The server will add some header lines of its own, but it won't touch
+the output following the header.
+
+The \code{cgi} module defines the following functions:
+
+\begin{funcdesc}{parse}{}
+Read and parse the form submitted to the script and return a
+dictionary containing the form's fields.  This should be called at
+most once per script invocation, as it may consume standard input (if
+the form was submitted through a POST request).  The keys in the
+resulting dictionary are the field names used in the submission; the
+values are {\em lists} of the field values (since field name may be
+used multiple times in a single form).  As a side effect, it sets
+\code{environ['QUERY_STRING']} to the raw query string, if it isn't
+already set.
+\end{funcdesc}
+
+\begin{funcdesc}{print_environ_usage}{}
+Print a piece of HTML listing the environment variables that may be
+set by the CGI protocol.
+This is mainly useful when learning about writing CGI scripts.
+\end{funcdesc}
+
+\begin{funcdesc}{print_environ}{}
+Print a piece of HTML text showing the entire contents of the shell
+environment.  This is mainly useful when debugging a CGI script.
+\end{funcdesc}
+
+\begin{funcdesc}{print_form}{form}
+Print a piece of HTML text showing the contents of the \var{form}.
+This is mainly useful when debugging a CGI script.
+\end{funcdesc}
+
+\begin{funcdesc}{escape}{string}
+Convert special characters in \var{string} to HTML escapes.  In
+particular, ``\code{\&}'' is replaced with ``\code{\&amp;}'',
+``\code{<}'' is replaced with ``\code{\&lt;}'', and ``\code{>}'' is
+replaced with ``\code{\&gt;}''.  This is useful when printing (almost)
+arbitrary text in an HTML context.  Note that for inclusion in quoted
+tag attributes (e.g. \code{<A HREF="...">}), some additional
+characters would have to be converted --- in particular the string
+quote.  There is currently no function that does this.
+\end{funcdesc}
+
+The module defines the following classes.  Since the base class
+initializes itself by calling \code{parse()}, at most one instance of
+at most one of these classes should be created per script invocation:
+
+\begin{funcdesc}{FormContentDict}{}
+This class behaves like a (read-only) dictionary and has the same keys
+and values as the dictionary returned by \code{parse()} (i.e. each
+field name maps to a list of values).  Additionally, it initializes
+its data member \code{query_string} to the raw query sent from the
+server.
+\end{funcdesc}
+
+\begin{funcdesc}{SvFormContentDict}{}
+This class, derived from \code{FormContentDict}, is a little more
+user-friendly when you are expecting that each field name is only used
+once in the form.  When you access for a particular field (using
+\code{form[fieldname]}), it will return the string value of that item
+if it is unique, or raise \code{IndexError} if the field was specified
+more than once in the form.  (If the field wasn't specified at all,
+\code{KeyError} is raised.)  To access fields that are specified
+multiple times, use \code{form.getlist(fieldname)}.  The
+\code{values()} and \code{items()} methods return mixed lists --
+containing strings for singly-defined fields, and lists of strings for
+multiply-defined fields.
+\end{funcdesc}
+
+(It currently defines some more classes, but these are experimental
+and/or obsolescent, and are thus not documented --- see the source for
+more informations.)
+
+The module defines the following variable:
+
+\begin{datadesc}{environ}
+The shell environment, exactly as received from the http server.  See
+the CGI documentation for a description of the various fields.
+\end{datadesc}

Doc/lib/libftplib.tex

@@ -0,0 +1,3 @@
+\section{Built-in module \sectcode{ftplib}}
+\stmodindex{ftplib}
+To be provided.

Doc/lib/libgopherlib.tex

@@ -0,0 +1,3 @@
+\section{Built-in module \sectcode{gopherlib}}
+\stmodindex{gopherlib}
+To be provided.

Doc/lib/libhtmllib.tex

@@ -0,0 +1,3 @@
+\section{Built-in module \sectcode{htmllib}}
+\stmodindex{htmllib}
+To be provided.

Doc/lib/libhttplib.tex

@@ -0,0 +1,93 @@
+\section{Built-in module \sectcode{httplib}}
+\stmodindex{httplib}
+\index{HTTP}
+
+This module defines a class which implements the client side of the
+HTTP protocol.  It is normally not used directly --- the module
+\code{urlllib} module uses it to handle URLs that use HTTP.
+\stmodindex{urllib}
+
+The module defines one class, \code{HTTP}.  An \code{HTTP} instance
+represents one transaction with an HTTP server.  It should be
+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.
+
+Once an \code{HTTP} instance has been connected to an HTTP server, it
+should be used as follows:
+
+\begin{enumerate}
+
+\item[1.] Make exactly one call to the \code{putrequest()} method.
+
+\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).
+
+\item[4.] Optional calls to the \code{send()} method.
+
+\item[5.] Call the \code{getreply()} method.
+
+\item[6.] Call the \code{getfile()} method and read the data off the
+file object that it returns.
+
+\end{enumerate}
+
+\code{HTTP} instances have the following methods:
+
+\begin{funcdesc}{set_debuglevel}{level}
+Set the debugging level (the amount of debugging output printed).
+The default debug level is \code{0}, meaning no debugging output is
+printed.
+\end{funcdesc}
+
+\begin{funcdesc}{connect}{host\optional{\, port}}
+Connect to the server given by \var{host} and \var{port}.  See the
+intro for the default port.  This should be called directly only if
+the instance was instantiated without passing a host.
+\end{funcdesc}
+
+\begin{funcdesc}{send}{data}
+Send data to the server.  This should be used directly only after the
+\code{endheaders()} method has been called and before
+\code{getreply()} has been called.
+\end{funcdesc}
+
+\begin{funcdesc}{putrequest}{request\, selector}
+This should be the first call after the connection to the server has
+been made.  It sends a line to the server consisting of the
+\var{request} string, the \var{selector} string, and the HTTP version
+(\code{HTTP/1.0}).
+\end{funcdesc}
+
+\begin{funcdesc}{putheader}{header\, argument\optional{\, ...}}
+Send an RFC-822 style header to the server.  It sends a line to the
+server consisting of the header, a colon and a space, and the first
+argument.  If more arguments are given, continuation lines are sent,
+each consisting of a tab and an argument.
+\end{funcdesc}
+
+\begin{funcdesc}{endheaders}{}
+Send a blank line to the server, signalling the end of the headers.
+\end{funcdesc}
+
+\begin{funcdesc}{getreply}{}
+Complete the request by shutting down the sending end of the socket,
+read the reply from the server, and return a triple (\var{replycode},
+\var{message}, \var{headers}).  Here \var{replycode} is the integer
+reply code from the request (e.g. \code{200} if the request was
+handled properly); \var{message} is the message string corresponding
+to the reply code; and \var{header} is an instance of the class
+\code{rfc822.Message} containing the headers received from the server.
+See the description of the \code{rfc822} module.
+\stmodindex{rfc822}
+\end{funcdesc}
+
+\begin{funcdesc}{getfile}{}
+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}

Doc/lib/libmimetools.tex

@@ -0,0 +1,3 @@
+\section{Built-in module \sectcode{mimetools}}
+\stmodindex{mimetools}
+To be provided.

Doc/lib/libnntplib.tex

@@ -0,0 +1,3 @@
+\section{Built-in module \sectcode{nntplib}}
+\stmodindex{nntplib}
+To be provided.