explain usage of httpd-options-transformers.

doc/latex/httpd.tex

@@ -72,37 +72,8 @@ one argument, a \ex{httpd\=options}-record:
 
 \defun{httpd}{options}{\noreturn}
 \begin{desc}
-  The \semvar{options} can be set via the various options-transformers
+  This procedure starts the server. The various \semvar{options} can
-  that can be found in the \ex{httpd\=make\=options}-structure:
+  be set via the options transformers that are explained below.
-  \ex{with\=port}, \ex{with\=root\=directory}, \ex{with\=fqdn},
-  \ex{with\=reported-port}, \ex{with\=path\=handler},
-  \ex{with\=server\=admin}, \ex{with\=simultaneous-requests},
-  \ex{with\=logfile}, \ex{with\=syslog?} that set the port the server
-  is listening to, the root-directory of the server, the FQDN of the
-  server, the port the server assumes it is listening to, the
-  path-handler of the server (see below), the mail-address of the
-  server-admin, the maximum number of simultaneous handled requests,
-  the name of the file or the port logging in the Common Log Format
-  (CLF) is output to and if the server shall create syslog messages,
-  respectively. The port defaults to 80, the root directory defaults
-  to ``\ex{/}'', the mail address of the server-admin defaults to
-  ``\ex{sperber@\ob{}informatik.\ob{}uni\=tuebingen.\ob{}de}'',
-  \FIXME{Why does the server admin mail address have
-    sperber@informatik... as default value?}logging is done to
-  ``\ex{httpd.log}'' and syslog is enabled. All other options default
-  to \sharpf.
-
-  For example
-  \begin{code}
-(httpd (with-path-handler 
-        (rooted-file-handler "/usr/local/etc/httpd")
-        (with-root-directory "/usr/local/etc/httpd")))
-  \end{code}
-  
-  starts the server on port 80 with
-  ``\ex{/usr/\ob{}local/\ob{}etc/\ob{}httpd}'' as root directory and
-  let it serve any files out from this directory. Note that
-  \ex{with\=root\=directory} is nested in \ex{with\=path\=handler}.
 
   The server's basic loop is to wait on the port for a connection from
   an HTTP client. When it receives a connection, it reads in and
@@ -125,6 +96,93 @@ one argument, a \ex{httpd\=options}-record:
   The basic server loop, and the associated request data structure are
   the fixed architecture of the S.U. Web server; its flexibility lies
   in the notion of path handlers.
+\end{desc}
+
+\defun{with-port}{port \ovar{options}}{options}
+\defunx{with-root-directory}{root-directory
+  \ovar{options}}{options} 
+\defunx{with-fqdn}{fqdn \ovar{options}}{options}
+\defunx{with-reported-port}{reported-port
+  \ovar{options}}{options}
+\defunx{with-path-handler}{path-handler
+  \ovar{options}}{options}
+\defunx{with-server-admin}{mail-address
+  \ovar{options}}{options}
+\defunx{with-simultaneous-requests}{requests
+  \ovar{options}}{options}
+\defunx{with-logfile}{logfile \ovar{options}}{options}
+\defunx{with-syslog?}{syslog? \ovar{options}}{options}
+\begin{desc}
+  As noted above, these transformers set the options for the web
+  server. Every transformer changes one aspect of the
+  \semvar{options} (for the \ex{httpd}). If this optional argument is missing, the
+  default values are used. These are the following:
+
+  \begin{tabular}{ll}
+    \bf{transformer} & \bf{default value} \\
+    \hline
+    \ex{with\=port} & 80 \\
+    \ex{with\=root\=directory} & ``\ex{/}'' \\
+    \ex{with\=fqdn} & \sharpf \\
+    \ex{with\=reported-port} & \sharpf \\
+    \ex{with\=path\=handler} & \sharpf \\
+    \ex{with\=server\=admin} & ``\ex{sperber@\ob{}informatik.} \\
+    & \ex{\ob{}uni\=tuebingen.\ob{}de}'' 
+    \FIXME{Why does the server admin mail address have
+      sperber@informatik... as default value?}\\
+    \ex{with\=simultaneous\=requests} & \sharpf \\
+    \ex{with\=logfile} & ``\ex{/httpd.log}''\\
+    \ex{with\=syslog?} & \sharpt \\
+  \end{tabular}
+
+%  that can be found in the \ex{httpd\=make\=options}-structure:
+%  \ex{with\=port}, \ex{with\=root\=directory}, \ex{with\=fqdn},
+%  \ex{with\=reported-port}, \ex{with\=path\=handler},
+%  \ex{with\=server\=admin}, \ex{with\=simultaneous-requests},
+%  \ex{with\=logfile}, \ex{with\=syslog?} that set the port the server
+%  is listening to, the root-directory of the server, the FQDN of the
+%  server, the port the server assumes it is listening to, the
+%  path-handler of the server (see below), the mail-address of the
+%  server-admin, the maximum number of simultaneous handled requests,
+%  the name of the file or the port logging in the Common Log Format
+%  (CLF) is output to and if the server shall create syslog messages,
+%  respectively. The port defaults to 80, the root directory defaults
+%  to ``\ex{/}'', the mail address of the server-admin defaults to
+%  ``\ex{sperber@\ob{}informatik.\ob{}uni\=tuebingen.\ob{}de}'',
+%  \FIXME{Why does the server admin mail address have
+%   sperber@informatik... as default value?}logging is done to
+%  ``\ex{httpd.log}'' and syslog is enabled. All other options default
+%  to \sharpf.
+
+  For example
+  \begin{code}
+(httpd (with-path-handler 
+        (rooted-file-handler "/usr/local/etc/httpd")
+        (with-root-directory "/usr/local/etc/httpd")))
+  \end{code}
+  
+  starts the server on port 80 with
+  ``\ex{/usr/\ob{}local/\ob{}etc/\ob{}httpd}'' as root directory and
+  lets it serve any file out from this directory.
+  \ex{rooted\=file\=handler} creates a path handler and is explained
+  below. You see, the transformers are used nested. So, every
+  transformer changes one aspect of the options that the following
+  transformer returns and the last transformer (here:
+  \ex{with\=root\=directory}) changes an aspect of the default values
+
+  
+  \semvar{port} is the port the server is listening to,
+  \semvar{root-directory} is the directory in the file system the
+  server uses as root, \semvar{fqdn} is the fully qualified domain
+  name the server reports, \semvar{reported-port} is the port the
+  server reports it is listening to and \semvar{server-admin} is the
+  mail address of the server admin. \semvar{requests} denote the
+  maximum number of allowed simultaneous requests to the server.
+  \sharpf\ means infinite. \semvar{logfile} is either a string, then
+  it is the file name of the logfile, or a port, where the log entries
+  are written to, or \sharpf, that means no logging is made. The
+  logfile is in Common Log Format (CLF). \semvar{syslog?} tells the
+  server to write syslog messages (\sharpt) or not (\sharpf).
 \end{desc}   
 
 \subsubsection*{Path handlers}