[Python-checkins] CVS: python/dist/src/Doc/lib libcgi.tex,1.34,1.35 libcgitb.tex,1.2,1.3

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv23304/lib

Modified Files:
	libcgi.tex libcgitb.tex 
Log Message:
Re-commit Ping's patch to the cgi and cgitb documentation, using the
right version this time.  Thanks, Ping!
(This was from SF patch #494582, "\index -> \indexii" version.)


Index: libcgi.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libcgi.tex,v
retrieving revision 1.34
retrieving revision 1.35
diff -C2 -d -r1.34 -r1.35
*** libcgi.tex	2001/11/28 07:26:15	1.34
--- libcgi.tex	2001/12/20 17:13:09	1.35
***************
*** 67,71 ****
  backward compatibility that you don't want in your namespace.
  
! It's best to use the \class{FieldStorage} class.  The other classes
  defined in this module are provided mostly for backward compatibility.
  Instantiate it exactly once, without arguments.  This reads the form
--- 67,93 ----
  backward compatibility that you don't want in your namespace.
  
! When you write a new script, consider adding the line:
! 
! \begin{verbatim}
! import cgitb; cgitb.enable()
! \end{verbatim}
! 
! This activates a special exception handler that will display detailed
! reports in the Web browser if any errors occur.  If you'd rather not
! show the guts of your program to users of your script, you can have
! the reports saved to files instead, with a line like this:
! 
! \begin{verbatim}
! import cgitb; cgitb.enable(display=0, logdir="/tmp")
! \end{verbatim}
! 
! It's very helpful to use this feature during script development.
! The reports produced by \refmodule{cgitb} provide information that
! can save you a lot of time in tracking down bugs.  You can always
! remove the \code{cgitb} line later when you have tested your script
! and are confident that it works correctly.
! 
! To get at submitted form data,
! it's best to use the \class{FieldStorage} class.  The other classes
  defined in this module are provided mostly for backward compatibility.
  Instantiate it exactly once, without arguments.  This reads the form
***************
*** 390,394 ****
  
  
! \subsection{Caring about security}
  
  There's one important rule: if you invoke an external program (via the
--- 412,418 ----
  
  
! \subsection{Caring about security \label{cgi-security}}
! 
! \indexii{CGI}{security}
  
  There's one important rule: if you invoke an external program (via the
***************
*** 467,471 ****
  
  
! \subsection{Debugging CGI scripts}
  
  First of all, check for trivial installation errors --- reading the
--- 491,495 ----
  
  
! \subsection{Debugging CGI scripts} \indexii{CGI}{debugging}
  
  First of all, check for trivial installation errors --- reading the
***************
*** 509,557 ****
  exits.  While the Python interpreter will still do this when your CGI
  script raises an exception, most likely the traceback will end up in
! one of the HTTP server's log file, or be discarded altogether.
  
  Fortunately, once you have managed to get your script to execute
! \emph{some} code, it is easy to catch exceptions and cause a traceback
! to be printed.  The \function{test()} function below in this module is
! an example.  Here are the rules:
! 
! \begin{enumerate}
! \item Import the traceback module before entering the \keyword{try}
!    ... \keyword{except} statement
! 
! \item Assign \code{sys.stderr} to be \code{sys.stdout}
! 
! \item Make sure you finish printing the headers and the blank line
!    early
! 
! \item Wrap all remaining code in a \keyword{try} ... \keyword{except}
!    statement
! 
! \item In the except clause, call \function{traceback.print_exc()}
! \end{enumerate}
! 
! 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}
  
! Notes: The assignment to \code{sys.stderr} is needed because the
! traceback prints to \code{sys.stderr}.
! The \code{print "{\e}n{\e}n<PRE>"} statement is necessary to
! disable the word wrapping in HTML.
  
! If you suspect that there may be a problem in importing the traceback
! module, you can use an even more robust approach (which only uses
! built-in modules):
  
  \begin{verbatim}
--- 533,554 ----
  exits.  While the Python interpreter will still do this when your CGI
  script raises an exception, most likely the traceback will end up in
! one of the HTTP server's log files, or be discarded altogether.
  
  Fortunately, once you have managed to get your script to execute
! \emph{some} code, you can easily send tracebacks to the Web browser
! using the \refmodule{cgitb} module.  If you haven't done so already,
! just add the line:
  
  \begin{verbatim}
! import cgitb; cgitb.enable()
  \end{verbatim}
  
! to the top of your script.  Then try running it again; when a
! problem occurs, you should see a detailed report that will
! likely make apparent the cause of the crash.
  
! If you suspect that there may be a problem in importing the
! \refmodule{cgitb} module, you can use an even more robust approach
! (which only uses built-in modules):
  
  \begin{verbatim}
***************
*** 568,572 ****
  by your client.  If it raises an exception, most likely after the
  first two lines have been printed, a traceback will be displayed.
! Because no HTML interpretation is going on, the traceback will
  readable.
  
--- 565,569 ----
  by your client.  If it raises an exception, most likely after the
  first two lines have been printed, a traceback will be displayed.
! Because no HTML interpretation is going on, the traceback will be
  readable.
  
***************
*** 587,592 ****
  like \samp{python script.py}.
  
! \item When using any of the debugging techniques, don't forget to add
! \samp{import sys} to the top of the script.
  
  \item When invoking external programs, make sure they can be found.
--- 584,589 ----
  like \samp{python script.py}.
  
! \item If your script does not have any syntax errors, try adding
! \samp{import cgitb; cgitb.enable()} to the top of the script.
  
  \item When invoking external programs, make sure they can be found.

Index: libcgitb.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libcgitb.tex,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** libcgitb.tex	2001/12/18 15:51:55	1.2
--- libcgitb.tex	2001/12/20 17:13:09	1.3
***************
*** 10,22 ****
  \index{CGI!exceptions}
  \index{CGI!tracebacks}
! \index{exception!in CGI scripts}
! \index{traceback!in CGI scripts}
  
  The \module{cgitb} module provides a special exception handler for CGI
! scripts.  After this module is activated using the \function{enable()}
! function, if an uncaught exception occurs, a detailed, formatted
! report will be sent to the Web browser.  The report includes a
! traceback showing excerpts of the source code for each level, as well
! as the values of the arguments and local variables to currently
  running functions, to help you debug the problem.  Optionally, you can
  save this information to a file instead of sending it to the browser.
--- 10,21 ----
  \index{CGI!exceptions}
  \index{CGI!tracebacks}
! \index{exceptions!in CGI scripts}
! \index{tracebacks!in CGI scripts}
  
  The \module{cgitb} module provides a special exception handler for CGI
! scripts.  After this module is activated, if an uncaught exception occurs,
! a detailed, formatted report will be sent to the Web browser.  The report
! includes a traceback showing excerpts of the source code for each level,
! as well as the values of the arguments and local variables to currently
  running functions, to help you debug the problem.  Optionally, you can
  save this information to a file instead of sending it to the browser.