AMK's megapatch:
* \bcode, \ecode added everywhere
* \label{module-foo} added everywhere
* A few \seealso sections added.
* Indentation fixed inside verbatim in lib*tex files
diff --git a/Doc/libcgi.tex b/Doc/libcgi.tex
index 4768f0f..56643d0 100644
--- a/Doc/libcgi.tex
+++ b/Doc/libcgi.tex
@@ -1,4 +1,5 @@
\section{Standard Module \sectcode{cgi}}
+\label{module-cgi}
\stmodindex{cgi}
\indexii{WWW}{server}
\indexii{CGI}{protocol}
@@ -39,21 +40,21 @@
telling the client what kind of data is following. Python code to
generate a minimal header section looks like this:
-\begin{verbatim}
- print "Content-type: text/html" # HTML is following
- print # blank line, end of headers
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print "Content-type: text/html" # HTML is following
+print # blank line, end of headers
+\end{verbatim}\ecode
+%
The second section is usually HTML, which allows the client software
to display nicely formatted text with header, in-line images, etc.
Here's Python code that prints a simple piece of HTML:
-\begin{verbatim}
- print "<TITLE>CGI script output</TITLE>"
- print "<H1>This is my first CGI script</H1>"
- print "Hello, world!"
-\end{verbatim}
-
+\bcode\begin{verbatim}
+print "<TITLE>CGI script output</TITLE>"
+print "<H1>This is my first CGI script</H1>"
+print "Hello, world!"
+\end{verbatim}\ecode
+%
(It may not be fully legal HTML according to the letter of the
standard, but any browser will understand it.)
@@ -76,19 +77,19 @@
\code{Content-type} header and blank line have already been printed) checks that
the fields \code{name} and \code{addr} are both set to a non-empty string:
-\begin{verbatim}
- form = cgi.FieldStorage()
- form_ok = 0
- if form.has_key("name") and form.has_key("addr"):
- if form["name"].value != "" and form["addr"].value != "":
- form_ok = 1
- if not form_ok:
- print "<H1>Error</H1>"
- print "Please fill in the name and addr fields."
- return
- ...further form processing here...
-\end{verbatim}
-
+\bcode\begin{verbatim}
+form = cgi.FieldStorage()
+form_ok = 0
+if form.has_key("name") and form.has_key("addr"):
+ if form["name"].value != "" and form["addr"].value != "":
+ form_ok = 1
+if not form_ok:
+ print "<H1>Error</H1>"
+ print "Please fill in the name and addr fields."
+ return
+...further form processing here...
+\end{verbatim}\ecode
+%
Here the fields, accessed through \code{form[key]}, are themselves instances
of \code{FieldStorage} (or \code{MiniFieldStorage}, depending on the form encoding).
@@ -100,40 +101,40 @@
instance or a list of instances. For example, here's code that
concatenates any number of username fields, separated by commas:
-\begin{verbatim}
- username = form["username"]
- if type(username) is type([]):
- # Multiple username fields specified
- usernames = ""
- for item in username:
- if usernames:
- # Next item -- insert comma
- usernames = usernames + "," + item.value
- else:
- # First item -- don't insert comma
- usernames = item.value
- else:
- # Single username field specified
- usernames = username.value
-\end{verbatim}
-
+\bcode\begin{verbatim}
+username = form["username"]
+if type(username) is type([]):
+ # Multiple username fields specified
+ usernames = ""
+ for item in username:
+ if usernames:
+ # Next item -- insert comma
+ usernames = usernames + "," + item.value
+ else:
+ # First item -- don't insert comma
+ usernames = item.value
+else:
+ # Single username field specified
+ usernames = username.value
+\end{verbatim}\ecode
+%
If a field represents an uploaded file, the value attribute reads the
entire file in memory as a string. This may not be what you want. You can
test for an uploaded file by testing either the filename attribute or the
file attribute. You can then read the data at leasure from the file
attribute:
-\begin{verbatim}
- fileitem = form["userfile"]
- if fileitem.file:
- # It's an uploaded file; count lines
- linecount = 0
- while 1:
- line = fileitem.file.readline()
- if not line: break
- linecount = linecount + 1
-\end{verbatim}
-
+\bcode\begin{verbatim}
+fileitem = form["userfile"]
+if fileitem.file:
+ # It's an uploaded file; count lines
+ linecount = 0
+ while 1:
+ line = fileitem.file.readline()
+ if not line: break
+ linecount = linecount + 1
+\end{verbatim}\ecode
+%
The file upload draft standard entertains the possibility of uploading
multiple files from one field (using a recursive \code{multipart/*}
encoding). When this occurs, the item will be a dictionary-like
@@ -251,10 +252,10 @@
that the first line of the script contains \code{\#!} starting in column 1
followed by the pathname of the Python interpreter, for instance:
-\begin{verbatim}
- #!/usr/local/bin/python
-\end{verbatim}
-
+\bcode\begin{verbatim}
+#!/usr/local/bin/python
+\end{verbatim}\ecode
+%
Make sure the Python interpreter exists and is executable by ``others''.
Make sure that any files your script needs to read or write are
@@ -273,12 +274,12 @@
default module search path, you can change the path in your script,
before importing other modules, e.g.:
-\begin{verbatim}
- import sys
- sys.path.insert(0, "/usr/home/joe/lib/python")
- sys.path.insert(0, "/usr/local/lib/python")
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+sys.path.insert(0, "/usr/home/joe/lib/python")
+sys.path.insert(0, "/usr/local/lib/python")
+\end{verbatim}\ecode
+%
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
@@ -311,10 +312,10 @@
in the standard \code{cgi-bin} directory, it should be possible to send it a
request by entering a URL into your browser of the form:
-\begin{verbatim}
- http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
-\end{verbatim}
-
+\bcode\begin{verbatim}
+http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
+\end{verbatim}\ecode
+%
If this gives an error of type 404, the server cannot find the script
-- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
@@ -328,10 +329,10 @@
The next step could be to call the \code{cgi} module's test() function from
your script: replace its main code with the single statement
-\begin{verbatim}
- cgi.test()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+cgi.test()
+\end{verbatim}\ecode
+%
This should produce the same results as those gotten from installing
the \code{cgi.py} file itself.
@@ -363,19 +364,19 @@
For example:
-\begin{verbatim}
- import sys
- import traceback
- print "Content-type: text/html"
- print
- sys.stderr = sys.stdout
- try:
- ...your code here...
- except:
- print "\n\n<PRE>"
- traceback.print_exc()
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+import traceback
+print "Content-type: text/html"
+print
+sys.stderr = sys.stdout
+try:
+ ...your code here...
+except:
+ print "\n\n<PRE>"
+ traceback.print_exc()
+\end{verbatim}\ecode
+%
Notes: The assignment to \code{sys.stderr} is needed because the traceback
prints to \code{sys.stderr}. The \code{print "$\backslash$n$\backslash$n<PRE>"} statement is necessary to
disable the word wrapping in HTML.
@@ -384,14 +385,14 @@
module, you can use an even more robust approach (which only uses
built-in modules):
-\begin{verbatim}
- import sys
- sys.stderr = sys.stdout
- print "Content-type: text/plain"
- print
- ...your code here...
-\end{verbatim}
-
+\bcode\begin{verbatim}
+import sys
+sys.stderr = sys.stdout
+print "Content-type: text/plain"
+print
+...your code here...
+\end{verbatim}\ecode
+%
This relies on the Python interpreter to print the traceback. The
content type of the output is set to plain text, which disables all
HTML processing. If your script works, the raw HTML will be displayed