From a9033bfc76bf58ba4191b24fe3379f1381e0022d Mon Sep 17 00:00:00 2001
From: interp <interp>
Date: Sun, 14 Apr 2002 17:04:26 +0000
Subject: [PATCH] Added docu on CGI server and CGI scripts package.

---
 doc/latex/cgi-script.tex | 15 ++++++++++++-
 doc/latex/cgi-server.tex | 47 +++++++++++++++++++++++++++++++++++++++-
 doc/latex/httpd.tex      |  1 +
 3 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/doc/latex/cgi-script.tex b/doc/latex/cgi-script.tex
index 14d0c56..632abb0 100644
--- a/doc/latex/cgi-script.tex
+++ b/doc/latex/cgi-script.tex
@@ -5,4 +5,17 @@
 \item[Name of the package:] cgi-script
 \end{description}
 %
-Not implemented yet.
+\subsection{Procedures}
+
+\begin{defundesc}{cgi-form-query}{}{data-alist}
+ CGI scripts receive their parameters in various ways, depending on
+ how they were called (e.g. by ``GET'' method). This procedure
+ translates the delivered form data into an alist of decoded strings,
+ using the environment variables set by the server
+ (\ex{REQUEST\_METHOD}, \ex{QUERY\_STRING} (``GET'' script),
+ \ex{CONTENT\_LENGTH} (``POST'' script)). So a query string like
+ \codex{button=on\&\ob{}reply=Oh,\ob{}\%20yes} becomes alist
+ \codex{(("button" . "on") ("reply" . "Oh, yes"))} This only works for
+ GET and POST methods.
+\end{defundesc}
+
diff --git a/doc/latex/cgi-server.tex b/doc/latex/cgi-server.tex
index 459c8b4..d73441b 100644
--- a/doc/latex/cgi-server.tex
+++ b/doc/latex/cgi-server.tex
@@ -5,4 +5,49 @@
 \item[Name of the package:] cgi-server
 \end{description}
 %
-Not implemented yet.
+\subsection{Variables}
+
+\defvar{cgi-default-bin-path}{string}
+\begin{desc}
+  This variable contains the path for scripts. Its value is
+  \codex{/bin:/usr/bin:/usr/ucb:/usr/bsd:/usr/local/bin}
+\end{desc}
+
+\subsection{Procedures}
+
+\begin{defundesc}{cgi-handler}{bin-dir}{path-handler}
+  Returns a path handler (see \ref{httpd:path-handlers} for details
+  about path handlers) for cgi-scripts located in
+  \semvar{bin-dir}. The scripts are called as specified by
+  CGI/1.1\footnote{see
+\ex{http://hoohoo.ncsa.uiuc.edu/cgi/interface.html} for a sort of
+specification.}.
+
+\begin{itemize}
+\item Various environment variables are set (like
+  \ex{QUERY\_STRING} or \ex{REMOTE\_HOST}).
+\item ISINDEX queries get their arguments as command line arguments.
+\item Scripts are handled differently according to their name:
+
+  \begin{itemize}
+
+    \item If the name of the script starts with `\ex{nph-}', its reply
+    is read, the RFC~822-fields like ``Content-Type'' and ``Status''
+    are parsed and the client is sent back a real HTTP reply,
+    containing the rest of the script's output.  
+
+    \item If the name of the script doesn't start with `\ex{nph-}',
+    its output is sent back to the client directly. If its return code
+    is not zero, an error message is generated.
+
+\end{itemize}
+\end{itemize}
+\end{defundesc}
+
+\begin{defundesc}{initialise-request-invariant-cgi-env}{}{\noreturn}
+  Initializes the environment variables that are invariant from
+  cgi-call to cgi-call in order to save calculation time. Call this
+  procedure before you start your httpd. You have to do this, if you
+  use cgi-scripts, that read out the environment variables \ex{PATH},
+  \ex{SERVER\_SOFTWARE}, \ex{SERVER\_NAME} or \ex{GATEWAY\_INTERFACE}.
+\end{defundesc}
diff --git a/doc/latex/httpd.tex b/doc/latex/httpd.tex
index 8d76cbb..f5436eb 100644
--- a/doc/latex/httpd.tex
+++ b/doc/latex/httpd.tex
@@ -181,6 +181,7 @@ one argument, a \ex{httpd\=options}-record:
 \end{desc}   
 
 \subsubsection*{Path handlers}
+\label{httpd:path-handlers}
   
    A path handler is a procedure taking two arguments:
 \defun{path-handler}{path req}{value}