From 0093759c8eaa8f4f466250010dc78e7c8c680907 Mon Sep 17 00:00:00 2001
From: interp <interp>
Date: Thu, 29 Jul 2004 16:21:14 +0000
Subject: [PATCH] The (complete?) SUrflet API documentation.

---
 doc/latex/surfletapi.tex | 1474 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 1474 insertions(+)
 create mode 100644 doc/latex/surfletapi.tex

diff --git a/doc/latex/surfletapi.tex b/doc/latex/surfletapi.tex
new file mode 100644
index 0000000..a4a1a4d
--- /dev/null
+++ b/doc/latex/surfletapi.tex
@@ -0,0 +1,1474 @@
+\section{API description}
+\label{sec:surflet-api}
+
+The \surflet server comes with an extensive set of modules.  This
+section describes the modules and the programming interfaces.  See the
+howto section \ref{sec:surflethowto} for a practical guide.  Note that
+most of the procedures mentioned here are meant to be called from
+within a \surflet.
+
+
+\subsection{The \surflet server}
+
+The \surflet server provides basic procedures to send web content to a
+client.  To enable the SUnet webserver to serve \surflets, you have to
+add the \surflet handler to it, which resides in the
+\exi{surflet-handler} structure.  \Eg:
+
+\begin{alltt}
+(httpd 
+  (make-httpd-options
+   \dots
+   with-request-handler 
+   (alist-path-dispatcher
+    (list
+     (cons "surflet" (surflet-handler (with-surflet-path 
+                                       "web-server/root/surflets"))))
+     (rooted-file-or-directory-handler "web-server/root/htdocs"))))
+\end{alltt}
+
+This will set up the \surflet handler to handle requests directed to
+the directory \ex{/surflet/}.  The \surflet handler can only handle
+requests directed to \surflets.  Here's the interface description:
+
+\defun{surflet-handler}{options}{request-handler}
+\begin{desc}
+  This procedures sets up the \surflet handler and returns the request
+  handler for the SUnet webserver.  The options argument is similar to
+  the one passed to \ex{httpd} and is exlpained below.
+
+  The \surflet handler accepts requests (solely) to \surflets whose
+  file name must have the extension \ex{.scm}.  The structure of
+  \surflets is explained below.  The \surflet handler receives the
+  \ex{request} from \ex{httpd}, translates it to a
+  \ex{surflet-request} and passes it to the requested \surflet.  The
+  \surflet in turn is expected to return a \ex{surflet-response},
+  which the \surflet handler translates to a \ex{repsonse} for
+  \ex{httpd}.  Thus, the \surflet deals only with \ex{surflet-request}
+  and \ex{surflet-response} objects.  The structure of these objects
+  and how they are passed around is explained below.
+
+  A \surflet may also return a \ex{redirect} \ex{response}, which the
+  \surflet handler passes to the \ex{httpd} untouched.  See
+  \ref{sec:http-responses} for details.
+
+  The \surflet handler calls the \surflet wrapped into an error
+  handler that catches any error the \surflet may yield.  In this
+  case, it terminates the \surflets session (see below for more on
+  sessions) and returns an \ex{error} \ex{response} to \ex{httpd} with
+  the error code 500 "Internal Server Error" and a description of
+  the error.
+\end{desc}
+
+The \var{options} argument can be constructed in a similar way to the
+options argument of \ex{httpd}.  The procedures' names are of the form
+\ex{with-\ldots} and they all either create a new option or add a
+new parameter to a given option.  The new parameter is always the
+first argument while the (old) option the optional second one.  The
+following procedures reside in the  \exi{surflet-handler/options}
+structure.
+
+\defun{with-surflet-path}{surflet-path [options]}{options}
+\begin{desc}
+  This specifies the path in which the \surflet handler looks for
+  \surflets.  The \var{surflet-path} is a string.  This option must be
+  given for the handler to work.
+\end{desc}
+
+\defun{with-session-lifetime}{seconds [options]}{options}
+\begin{desc}
+  This specifies the initial lifetime of a session.  The lifetime of a
+  session is the number of seconds the \surflet handler waits for a
+  response from a client for that session, before she automatically
+  finishes it.  See below for details on sessions.  Defaults to 600,
+  \ie 10 minutes.
+\end{desc}
+
+\defun{with-cache-surflets?}{cache-surflets? [options]}{options}
+\begin{desc}
+  This specifices whether the \surflet handler caches \surflets.  The
+  caching of \surflets is a prerequisite for \surflet wide global
+  variables.  See below for details on the scope of variables in
+  \surflets.  Defaults to \sharpt.
+\end{desc}
+
+\defun{with-make-session-timeout-text}{timeout-text-procedure
+  [options]}{options}
+\begin{desc}
+  This specifies a procedure that generates the timeout text.  The
+  \surflet handler displays the timeout text when she receives a
+  request for a \surflet session that does not exist, either because
+  the \surflet finished its session, the session has timed out, or the
+  URL is illformed.  The default is an English text with an
+  explanation of the possible reasons and a link to a new session of
+  the requested \surflet.  \var{timeout-text-procedure} accepts the
+  string path to the \surflet that was requested and returns a string.
+\end{desc}
+
+Similar to the \ex{httpd} options there exists a procedure to avoid
+parenthisis:
+
+\defun{make-surflet-options} {transformer value \ldots}{options}
+\begin{desc}
+  This constructs an options value from an argument list of parameter
+  transformers and parameter values.  The arguments come in pairs,
+  each an option transformer from the list above, and a value for that
+  parameter. \ex{make-surflet-options} returns the resulting options
+  value.
+\end{desc}
+
+For example,
+
+\begin{alltt}
+(surflet-handler 
+  (make-surflet-options
+   with-surflet-path "root/surflets"
+   with-session-timeout 3600))
+\end{alltt}
+
+defines the \surflet handler to serve \surflets from the directory
+\ex{root/surflets} and to timeout unused session after one hour.
+
+The \surflet handler allows runtime read and write access to her
+options:
+
+\defun{options-surflet-path}{options}{string}
+\defunx{options-session-lifetime}{options}{integer}
+\defunx{options-cache-surflets?}{options}{boolean}
+\defunx{options-make-session-timeout-text}{options}{procedure}
+\begin{desc}
+  These procedures return the stored value for the respective option.
+  See above for the description of the options.
+\end{desc}
+
+\defun{set-options-surflet-path!}{options surflet-path}{\undefined}
+\defunx{set-options-session-lifetime!}{options seconds}{\undefined}
+\defunx{set-options-cache-surflets?!}{options cache-surflets?}{\undefined}
+\defunx{set-options-make-session-timeout-text!}
+       {options timeout-text-procedure} {\undefined}
+\begin{desc}
+  These procedures change the respective option value.  See above for
+  the description of the arguments.  Note that changing the
+  \var{surflet-path} within a \surflet may result in the \surflets
+  being unreachable.  Turning the cache off will not empty the
+  \surflet cache.
+\end{desc}
+
+
+\subsection{\surflets}
+
+Technically, \surflets are Scheme48 structures, that have the name
+\ex{surflet} and export a \ex{main} procedure.  The file in which their
+definition reside must have the extension \ex{.scm}.  The \ex{main}
+procedure must accept the initial \ex{surflet-request} as an argument.
+She may or may not return, but if she does, she must return either a
+\ex{surflet response} or a \ex{redirect response}.  For example, this
+is a valid \surflet definition:
+
+\begin{alltt}
+(define-structure surflet surflet-interface
+  (open scheme-with-scsh
+        surflets)
+  (begin
+    (define (main req)
+       (send-html/finish
+         '(html (body (p "Hello world!")))))
+))
+\end{alltt}
+
+\ex{surflet-interface} is a predefined interface description that
+exports the \ex{main} procedure.  It is recommended to use this
+interface.  \exi{surflets} is a structure that combines the most
+commonly used structures to write \surflets.  \ex{send-html/finish} is
+one of the procedures that sends HTML to the client.  More on this
+below.
+
+As \surflets are Scheme48 structures, you can use all capabilities of
+the Scheme48 module language.  See the documentation of Scheme48 for
+details.
+
+\surflets should not use the \ex{shift-reset} structure, as this might
+confuse the \surflet handler. 
+
+\subsection{\surflet management}
+
+Upon an initial client request, the \surflet handler looks for the
+requested \surflet, dynamically loads it, installs an error handler
+and calls the \ex{main} function of the \surflet with the initial
+\ex{surflet-request}.   To minimize the time of loading a \surflet,
+the \surflet handler caches the structure of the \surflet in a cache,
+the \surflet cache.  As the \surflet is cached, its global values will
+remain unchanged even through times when there are no active sessions
+of the \surflet.  Changing global \surflet values is a possibility to
+exchange data between different sessions of the same \surflet.  Note
+that you have to take care to serialize the access to commonly shared,
+mutated data.
+
+The \surflet handler allows access to its cache via the following
+procedures.  The access to these procedures is currently
+unrestricted but may be restricted in future versions of the
+\surflet server.
+
+\defun{get-loaded-surflets}{}{list}
+\begin{desc}
+  This returns a list of the file names of the loaded \surflets. 
+\end{desc}
+
+\defun{unload-surflet}{surflet}{undefined}
+\begin{desc}
+  This removes the \var{surflet} from the \surflet cache.  The
+  \var{surflet} is identified by its file name, as returned from
+  \ex{get-loaded-surflets}.
+\end{desc}
+
+\defun{reset-surflet-cache!}{}{undefined}
+\begin{desc}
+  This empties the \surflet cache.
+\end{desc}
+
+Of course, when a \surflet is removed from the cache, the values in
+its sessions remain untouched.  However, if the \surflet is newly
+loaded into the \surflet cache, the \surflet handler treats it like a
+new \surflet, \ie the sessions of the "old" and the "new" \surflet
+(though physically the same) do \emph{not} share their global data in
+any way.
+
+\subsection{Surflet Request}
+
+\surflets get their input from \ex{surflet-request} objects.   The
+relevant procedures are the following.  They are all exported by the
+\exi{surflet-handler/requests} alias \exi{surflet-requests} structure.
+
+\defun{surflet-request?}{object}{boolean}
+\defunx{surflet-request-method}{surflet-request}{string}
+\defunx{surflet-request-input-port}{surflet-request}{input-port/undefined}
+\defunx{surflet-request-uri}{surflet-request}{string}
+\defunx{surflet-request-url}{surflet-request}{url}
+\defunx{surflet-request-version}{surflet-request}{pair}
+\defunx{surflet-request-headers}{surflet-request}{alist}
+\begin{desc}
+  The procedures inspect \ex{surflet-request} values.  Most of them
+  return the values of the underlying \ex{request} object from
+  \ex{httpd}.  \ex{surflet-request?} is a predicate for \ex{surflet
+  request}s.  \ex{surflet-request-method} extracts the method of the
+  HTTP request; it's a string and either \ex{"GET"} or \ex{"POST"}.
+  \surflets won't receive requests with other methods.
+  \ex{surflet-request-input-port} returns an input-port that contains
+  data from the client on \ex{POST} requests and that the \surflet can
+  safely read.  If the request is no \ex{POST} request, its value is
+  undefined.  \ex{surflet-request-uri} returns the escaped URI string
+  as read from the request line.  \ex{surflet-request-url} returns the
+  respective HTTP URL value (see the description of the \ex{url}
+  structure in chapter \ref{cha:url}).  \ex{surflet-request-version}
+  returns a \verb|(major . minor)| integer pair representing the
+  version specified in the HTTP request.  \ex{surflet-request-headers}
+  returns an association lists of header field names and their values,
+  each represented by a list of strings, one for each line.
+\end{desc}
+
+For some unknown weird cases, there are also these two procedures:
+
+\defun{surflet-request-socket}{surflet-request}{socket}
+\defunx{surflet-request-request}{surflet-request}{request}
+\begin{desc}
+  \ex{surflet-request-socket} returns the socket connected to the
+  client.  As with \ex{request}s, \surflets should not perform I/O on
+  this socket.  See section \ref{httpd:requests} for reasoning.
+  \ex{surflet-request-requst} allows access to the underlying
+  \ex{request} object from \ex{httpd}.  Both procedures should not be
+  necessary in normal operation and their usage is discouraged.
+\end{desc}
+
+
+\subsection{Surflet Response}
+
+\surflets answer to a request by sending an \ex{surflet-response} to
+the \surflet handler.  The next section deals with how the surflet
+responses are sent to the \surflet handler.  The relevant procedures
+for \ex{surflet-response} are the following.  They are all exported by
+the \exi{surflet-handler/responses} alias \exi{surflet-response}
+structure.
+
+\defun{make-surflet-response}{status content-type headers
+  data}{surflet-response}
+\begin{desc}
+  This creates a \ex{surflet-response}.  \var{status} is the status
+  code of the response.  See section \ref{sec:http-responses} for
+  details on this.  \var{content-type} is the MIME type of the data,
+  \eg \ex{"text/html"}.  \var{headers} is an association list of
+  headers to be added to the response, each of which consists of a
+  symbol representing the field name and a string representing the
+  field value.  \var{data} is the actual data.  It must be either a
+  string or a list of values that will be \ex{display}ed.
+\end{desc}
+
+\defun{valid-surflet-response-data?}{object}{boolean}
+\begin{desc}
+  This is a predicate on objects that may be surflet data, \ie a
+  string or a list (of objects that will be \ex{display}ed).
+\end{desc}
+
+\defun{surflet-response?}{object}{boolean}
+\defunx{surflet-response-status}{surflet-response}{status-code}
+\defunx{surflet-response-content-type}{surflet-response}{string}
+\defunx{surflet-response-headers}{surflet-response}{alist}
+\defunx{surflet-response-data}{surflet-response}{surflet-data}
+\begin{desc}
+  The procedures return \ex{surflet-response} values.
+  \ex{surflet-response?} is a predicate for \ex{surflet-response}s.
+  \ex{surflet-response-status} returns the status code of the
+  response.  See section \ref{sec:http-responses} for details on the
+  status code.  \ex{surflet-response-content-type} returns the MIME
+  type of the response.  \ex{surflet-response-headers} returns the
+  association list of header field names and their values, each
+  represented by a list of strings, one for each line.
+  \ex{surflet-response-data} returns the data of the
+  \ex{surflet-response}, the actual answer of the \surflet.
+\end{desc}
+
+\subsection{Sessions}
+
+A \keyword{session} is a set of web pages that logically belong
+together, \eg a user surfing through her webmail.  A session starts
+with the initial request for a \surflet and ends either explicitly by
+the \surflet, or implicitly after a timeout.  A third, not so common
+case is its deletion from the session table.
+
+The procedures presented in this subsection are all accessible via the
+\exi{surflets/sessions} structure.
+
+\subsubsection{Session management}
+
+The \surflet handler automatically manages the sessions for each
+\surflet, thus the \surflet does not have to deal with sessions or
+state control (as it is the case with most other programming
+interfaces for web applications).  In particular, a \surflet does not
+have to take care of saving the contents of variables before emitting
+a web page and restoring the values later upon the next request, or
+determining how far the user has proceeded in the application.  The
+only thing a \surflet may want to do is to tell the \surflet handler
+when a session finished by calling \ex{send/finish} or an equivalent
+procedure (see below).
+
+Although a \surflet does not have to deal with the management of the
+sessions, the \surflet handler allows access to its management
+structures.
+
+\defun{instance-session-id}{}{session-id}
+\begin{desc}
+  This returns the session ID for the current session.  The current
+  session is the session from which the function is called.
+\end{desc}
+
+\defun{get-session}{session-id}{session}
+\begin{desc}
+  This returns the session for the given session ID.
+\end{desc}
+
+\defun{get-sessions}{}{alist}
+\begin{desc}
+  This returns the complete list of all active session of the \surflet
+  handler.  The list is an association list with the session-id as key
+  and the session as value.
+
+  The access to this procedure is currently unrestricted but may be
+  restricted in future versions of the \surflet server.
+\end{desc}
+
+\defun{delete-session!}{session}{undefined}
+\begin{desc}
+  This deletes the specified session from the session table.  Future
+  requests to the session are answered with the timeout text.
+\end{desc}
+
+\defun{session-alive?}{session}{boolean}
+\begin{desc}
+  This returns \sharpt, if the specified session is alive, \ie
+  requests to it will be answered by the appropriate \surflet.
+  Otherwise, she returns \sharpf.
+\end{desc}
+
+\defun{session-surflet-name}{session}{string}
+\defunx{session-session-id}{session}{session-id}
+\begin{desc}
+  These procedures inspect values of a session.
+  \ex{session-surflet-name} returns the name of the \surflet for which
+  the session was created.  \ex{session-session-id} returns the
+  session ID of the session. 
+\end{desc}
+
+For each session, the \surflet handler has a counter running.  She
+resets the counter each time she receives a request for the session.
+When the counter reaches a particular number of seconds, the
+\keyword{lifetime} of the session, the \surflet handler deletes the
+session and removes it from its session table.  She will answer all
+future requests for the session with the timeout text.  The following
+procedures deal with the lifetime of a session.
+
+\defun{session-lifetime}{session}{integer}
+\defunx{set-session-lifetime!}{session new-lifetime}{undefined}
+\begin{desc}
+  \ex{session-lifetime} returns the number of seconds the \surflet
+  handler will initially wait before she automatically finishes the
+  session.  \ex{set-session-lifetime!} changes the initial lifetime of
+  the \var{session} to \var{new-lifetime} and also resets the counter
+  for that session.
+\end{desc}
+
+\defun{session-adjust-timeout!}{session [lifetime]}{undefined}
+\defunx{adjust-timeout!}{[lifetime]}{undefined}
+\begin{desc}
+  These reset the counter for the lifetime of either the given
+  \var{session} (\ex{session-adjust-timeout!}) or the current session
+  (\ex{adjust-timeout!}).  Both procedures give the session a lifetime
+  of either \var{lifetime} seconds or of the lifetime seconds stored
+  for the according \var{session}.
+\end{desc}
+
+In order to allow easy web programming, the \surflet handler
+automatically saves and reifies continuations of a session.  This is
+totally transparent to the web programmer.  For adminstration
+purposes, the \surflet handler offers access to the continuation table
+of a session via the following procedures.
+
+\defun{session-continuation-table}{session}{table}
+\defunx{session-continuation-table-lock}{session}{lock}
+\defunx{session-continuation-counter}{session}{thread-safe-counter}
+\begin{desc}
+  These functions the continuation table, the lock for the
+  continuation table and the counter for the continuations.  The
+  continuation \var{table} is a hash table with the continuation ID as
+  key and the continuation as value, based on the \ex{tables}
+  structure of Scheme48.  The \var{lock} is based on the \ex{locks}
+  structure of Scheme48.  The \var{thread-safe-counter} is based on
+  the \ex{thread-safe-counter} structure that is part of the
+  \surflets.
+
+  The access to these functions is currently unrestricted but may be
+  restricted in future versions of the \surflet server.
+\end{desc}
+
+
+\subsubsection{Session data}
+The \surflet handler distinguishes three kinds of \keyword{session
+data}: session data that is local to a session of a \surflet and not
+mutated, session data that is local to a session of a \surflet and
+mutated and session data that is global to all sessions of a \surflet.
+Every variable value that is never mutated is automatically local to
+the session of the \surflet.  Variable values that are mutated are
+automatically global to all sessions of the \surflet.  Values that
+have to be mutated but should be local to a session of the \surflet
+must be stored in a special place, the session data field of the
+\surflet handler.\footnote{The reason for this distinction is the fact
+  that the \surflet handler saves and reifies the continuation of a
+  \surflet to realize the easy programming of web applications.
+  Mutations of values remain visible after reifying the continuation.}
+
+\defun{get-session-data}{}{object}
+\defunx{set-session-data!}{new-value}{undefined}
+\begin{desc}
+  These procedures allow read/write access to the session data field
+  of the \surflet handler.  The \surflet handler installs a session
+  data field for each session she creates.  \ex{get-session-data}
+  reads the contents of this field, which is initially \sharpf.
+  \ex{set-session-data!} sets the contents of the field to
+  \var{new-value}.  Mutations to the values, no matter when they
+  occur, are local to the session from which the procedures are
+  called, \ie the changes are only visible within a particular session
+  of the \surflet.  The procedures are exported by the
+  \exi{surflet-handler/session-data} structure.
+\end{desc}
+
+
+\subsection{Basic I/O}
+
+The \surflet communicates with the web client basically with the
+following \ex{send} primitives.  They are exported by the
+\exi{surflet-handler/primitives} structure along with the procedures
+from \ex{surflet-handler/requests}, \ex{surflet-handler/responses} and
+the \ex{status-code} syntax.
+
+\defun{send}{surflet-response}{\noreturn}
+\begin{desc}
+  This procedure send the data of the \var{surflet-response} to the
+  client and does not return.
+\end{desc}
+
+\defun{send/finish}{surflet-response}{\noreturn}
+\begin{desc}
+  This procedure does the same as \ex{send}, but it also finishes the
+  session of the \surflet.  Future requests to the \surflet will be
+  answered with the timeout text (see above).
+\end{desc}
+
+\defun{send/suspend}{surflet-response-maker}{surflet-request}
+\begin{desc}
+  This procedure suspends the current computation of the \surflet and
+  calls \var{surflet-response-maker} with the continuation-URL of the
+  current session to create the actual \ex{surflet-response}.  When a
+  client requests the continuation-URL, the computation of the
+  \surflet will resume with \ex{send/suspend} returning that request
+  of the client.  See \ref{sec:continuation-url} for details on
+  continuation-URLs.
+\end{desc}
+
+\defun{send/error}{status-code surflet-request [messages]}{\noreturn}
+\begin{desc}
+  This sends an error response to the client.  \var{status-code} is
+  the status code of the error, see section \ref{sec:http-responses} for
+  details.  \var{surflet-request} is the last \ex{surflet-request} the
+  \surflet received; if unknown this argument may be \sharpf.
+  \var{messages} may contain some further information about the cause
+  of the error.
+\end{desc}
+
+
+\subsection{Web I/O}
+
+Most of the time, a \surflet won't send arbitrary data but HTML to the
+client.  For this purpose, the \surflets provide extensive support.
+First of all, they provide procedures specially designed for
+submitting HTML.
+
+\defun{send-html}{sxml}{\noreturn}
+\defunx{send-html/finish}{sxml}{\noreturn}
+\defunx{send-html/suspend}{sxml-maker}{surflet-request}
+\begin{desc}
+  These are the equivalent procedures to the \ex{send} primitives.
+  \ex{send-html} and \ex{send-html/finish} accept an SXML object (more
+  on that below), translate it into HTML and send it to the client,
+  the latter finishing the session.  \ex{send-html/suspend} suspends
+  the current computation, calls \var{sxml-maker} with the
+  continuation-URL, translates the resulting SXML into HTML and sends
+  it to the client.  When the client requests the continuation-URL,
+  the computation is resumed and \ex{send-html/suspend} returns with
+  the \ex{surflet-request}.
+\end{desc}
+
+
+\subsubsection{SXML}
+
+For easy creation of HTML output, the \ex{send-html} procedures
+mentioned above represent the HTML in SXML.  SXML is a creation of
+Oleg Kiselyov.  Basically, SXML is a list whose \ex{car} is an SXML
+tag, a symbol representing the HTML tag, and the \ex{cdr} are other
+SXML elements that will be enclosed by the HTML tag.  For example,
+
+\codex{'(h2 "Result")}
+represents the tag \ex{h2}, that encloses the text "Result".  The
+represented HTML is
+\codex{<h2>Result</h2>\textnormal{.}}
+
+As in HTML, elements may be nested:
+\codex{'(body (h2 "Result") (p "Example"))}
+represents
+\codex{<body><h2>Result</h2><p>Example</p>\textnormal{.}}
+
+The @ symbol marks HTML attributes.  The attributes follow the @
+symbol in two element lists, the first element being the name of the
+attribute and the last its value.  For example, this is a link:
+\codex{'(a (@ (href "add-surflet.scm") (name "linklist")) "Make new calculation.")}
+representing the following HTML
+\codex{<a href="add-surflet.scm" 
+name="linklist">Make new calculation.</a>\textnormal{.}}  The
+attributes form will only be recognized as such if it is the second
+element of a list, right after the SXML tag.  
+
+\defun{sxml-attribute?}{object}{boolean}
+\defunx{sxml-attribute-attributes}{sxml-attribute}{list}
+\begin{desc}
+  These are procedures on SXML attribute forms.  \ex{sxml-attribute?}
+  is  a predicate for SXML attribute forms.
+  \ex{sxml-attribute-attributes} returns the list of name-value-lists
+  of the attributes form.  Both procedures are exported by the
+  \exi{surflets/sxml} structure.
+\end{desc}
+
+The translator translates list elements which are numbers and symbols
+to their string representation (except for the first element, of
+course).  She scans strings for the special characters \verb'&',
+\verb'"', \verb'>' and \verb'<' and replaces them by their HTML
+equivalents, and she ignores \sharpf and the emtpy list.  See below
+the special SXML tag \ex{plain-html} to see how to insert HTML code
+untranslated.  Furthermore, the translator accepts \ex{input-fields}
+as list elements, which are translated to their HTML representation.
+See below for details on input fields.
+
+Using lists to represent HTML allows the programmer to define
+operations on it.  Most programmers construct their lists dynamically,
+often by using \ex{quasiquote} (the symbol \ex{`}) and \ex{unquote}
+(the symbol \ex{,}).  \Eg
+
+\begin{alltt}
+ `(html (title ,my-title) 
+        (body (p "Hello, " ,(get-user-full-name))))
+\end{alltt}
+
+See below for how to create your own SXML.
+
+\subsubsection{Special SXML tags}
+
+The SXML to HTML translator accepts some special SXML tags that don't
+directly translate to an HTML tag.
+
+\newcommand{\defsxmltag}     {\par\medskip\defsxmltagx}
+\newcommand{\defsxmltagx}[2]%
+{\hbox to \linewidth{\ttchars%
+     {\ttt(#1\testvoid{#2}{}{\ }{\sem{#2}}\testvoid{#2}{}{\/})
+%\hskip 1em minus 0.5em$\longrightarrow$\hskip 1em minus 0.5em
+%{\sem{#3}}
+\hfill\quad\textnormal{SXML-tag}}}\index{#1}}
+
+
+\defsxmltag{url}{URL [text]}
+\begin{desc}
+  Inserts a link to \var{URL}, named with \var{text}.  \var{text}
+  defaults to \var{URL}.  Takes at least one argument.  \Eg
+  
+  \begin{alltt}
+  (url "/" "Main menu") \ensuremath{\Longrightarrow} <a href="/">Main menu</a>
+  (url "go.html")       \ensuremath{\Longrightarrow} <a href="go.html">go.html</a>
+  \end{alltt}  
+
+\oops{\ex{url} does not accept extra attributes for the `\ex{A}' tag of
+  HTML.  This should be fixed in a future version.} 
+\end{desc}
+
+\defsxmltag{nbsp}{}
+\begin{desc}
+  Inserts the HTML sequence \ex{"\&nbsp;"}.  Takes no arguments.
+\end{desc}
+
+\defsxmltag{plain-html}{html \ldots}
+\begin{desc}
+  Inserts \var{html} without any changes, thus it works like a quote.
+  Takes any number of arguments.
+\end{desc}
+
+\defsxmltag{*COMMENT*}{comment \ldots}
+\begin{desc}
+  Inserts a comment, \ie \var{comment} enclosed between \verb|<!--|
+  and \verb|-->|.  Takes any number of arguments.
+\end{desc}
+
+\defsxmltag{surflet-form}{k-url [method] [attributes] [SXML \ldots]}
+\begin{desc}
+  Inserts HTML code for a web form.  See below for details.
+  \var{k-url} usually is a continuation-URL.  \var{method} is the
+  method to be used by the client to transfer the webform data.
+  Possible values are the symbols \ex{GET}, \ex{get}, \ex{POST},
+  \ex{post}, the first two specifying the GET method, the last two the
+  POST method.  \var{method} defaults to the GET method.
+  \ex{attributes} are attributes for the created web form, \eg \ex{(@
+  (enc-type "text/plain"))}.  The remaining arguments are taken as
+  SXML and translated as usually.  Takes at least one argument.  Note
+  that the attributes form may come at position three.
+\end{desc}
+
+\subsubsection{Do it yourself: your own SXML}
+
+The \ex{send-html} procedures use a standard set of translation rules
+to translate from SXML to HTML.  However, you may define your own set
+of translation rules or extend the given ones as you see fit.  For
+this, a short introduction to the translation process.
+
+The translation process takes place in two steps.  Step one translates
+the given SXML to low level SXML, essentially a rough form of HTML in
+list notation.  Step two takes this low level SXML and prints to a
+port.  Step one is performed by \ex{sxml->low-level-sxml}, step two by
+\ex{display-low-level-sxml}.  All procedures and rules presented in
+this subsection are exported from \exi{surflets/sxml}.
+
+\defun{sxml->low-level-sxml}{sxml rules}{low-level-sxml}
+\begin{desc}
+  Takes an SXML object (which essentially is a list) and a list of
+  SXML rules (more on this below) and translates it to low level SXML.
+  This procedure is an alias to the \ex{pre-post-order} procedure of
+  Oleg Kiselyov's SSAX module.  It is an error if no rule triggers
+  (see below for when a rule triggers).  However, it is no error if
+  multiple rules trigger; the first rule in the \var{rules} list wins.
+\end{desc}
+
+\defun{display-low-level-sxml}{low-level-sxml port}{boolean}
+\begin{desc}
+  Takes low level SXML and \ex{display}s it to a port.  She traverses
+  the list \var{low-level-sxml} depth-first, ignores the empty list
+  and \sharpf, executes thunks and \ex{display}s all other elements,
+  usually strings and characters, to \var{port}.  Returns \sharpt if
+  she wrote anything, \sharpf otherwise.  This function is basically
+  the \ex{SRV:send-reply} procedure of Oleg Kiselyov's SSAX module.
+\end{desc}
+
+\defun{sxml->string}{sxml rules}{string}
+\begin{desc}
+  Combines step one and two of the translation process and returns the
+  resulting string, \ie it calls \ex{display-low-level-sxml} with the
+  result of a call to \ex{sxml->low-level-sxml} and a string port,
+  returning the content of the string port.
+\end{desc}
+
+%\defun{sxml->string/internal}{sxml rules}{list}
+%\begin{desc}
+%  I forgot what this function was good for.  I probably used it
+%  internally in one of the \surflet rules.
+%\end{desc}
+
+An \keyword{SXML-rule} consists of a \textit{trigger}, which is a
+symbol, and the \textit{handler}, which is a translation procedure.
+
+There are three types of rules, each of which is a dotted list:
+\begin{description}
+\item[\ex{(\synvar{trigger} *preorder* . \synvar{handler})}] \mbox{}\\
+When \ex{sxml->low-level-sxml} sees the \synvar{trigger} as the
+first element of a list, she calls \synvar{handler} with the
+\emph{whole} list as arguments and replaces the list with the result
+of that call (which must be a single value).  Note that the arity of
+the handler determines how many elements the list with the trigger may
+or must contain.
+
+\item[\ex{(\synvar{trigger} . \synvar{handler})}] \mbox{}\\
+When \ex{sxml->low-level-sxml} sees the \synvar{trigger} as the first
+element of a list, she calls herself on the remaining elements of the
+list and then calls the \synvar{handler} with the trigger and the
+results of those calls as arguments.
+
+\item[\ex{(\synvar{trigger} \synvar{new-rules} . \synvar{handler})}] \mbox{} \\
+When \ex{sxml->low-level-sxml} sees the \synvar{trigger} as the first
+element of a list, she temporarily prepends \synvar{new-rules} to the
+current rule set while calling herself on the remaining elements of
+the list.  She then calls the \synvar{handler} with the trigger and
+the results of those calls as arguments.  As the new rules are
+prepended, this rule allows the temporary override of some rules.
+\end{description}
+
+There are two special triggers, who may trigger for all elements of
+the SXML, not only the first element of a list:
+\begin{itemize}
+\item  \ex{*text*} triggers for atoms in the SXML list, \ie usually
+strings and characters.  The handler is called with the symbol
+\ex{*text*} and the atom as arguments.
+
+\item \ex{*default*} triggers whenever no rule triggered, including
+\ex{*text*}.  If called for a list whose first element did not trigger
+a rule, the handler is called with the whole list.  If called for an
+atom, the handler is called with the symbol \ex{*text*} and the atom
+as arguments.
+\end{itemize}
+
+The \exi{surflets/sxml} structure defines some basic rules:
+
+\defvar{default-rule}{SXML-rule}
+\defvarx{text-rule}{SXML-rule}
+\defvarx{attribute-rule}{SXML-rule}
+\begin{desc}
+  These are the three basic rules exported by the \ex{surflets/sxml}
+  structure.  \ex{default-rule} creates the leading and trailing HTML
+  tag and encloses the attributes.  \ex{text-rule} just inserts the
+  given text with the special HTML characters \verb'&', \verb'"',
+  \verb'>' and \verb'<' escaped.  \ex{attribute-rule} triggers for the
+  attributes form and creates attributes like \ex{selected} or
+  \ex{color="red"}.
+\end{desc}
+
+The \exi{surflets/surflet-sxml} add the rules for the special SXML
+tags to this list:
+
+\defvar{url-rule}{SXML-rule}
+\defvarx{nbsp-rule}{SXML-rule}
+\defvarx{plain-html-rule}{SXML-rule}
+\defvarx{comment-rule}{SXML-rule}
+\defvarx{surflet-form-rule}{SXML-rule}
+\begin{desc}
+  These are the rules for the special SXML tags mentioned above,
+  namely \ex{url}, \ex{nbsp}, \ex{plain-html}, \ex{*COMMENT*} and
+  \ex{surflet-form}. 
+\end{desc}
+
+\defvar{default-rules}{list}
+\defvarx{surflet-sxml-rules}{list}
+\begin{desc}
+  These are rule sets.  \ex{default-rule} contains the rulese
+  \ex{default-rule}, \ex{attribute-rule}, \ex{text-rule},
+  \ex{comment-rule}, \ex{url-rule}, \ex{plain-html-rule} and
+  \ex{nbsp-rule}.  \ex{surflet-sxml-rules} extends this list by
+  \ex{surflet-form-rule} and a rule for input fields.
+\end{desc}
+
+\defun{surflet-sxml->low-level-sxml}{sxml}{low-level-sxml}
+\begin{desc}
+  This uses the \ex{surflet-sxml-rules} to translate \var{sxml} to low
+  level SXML, performin step one of the translation process.
+\end{desc}
+
+
+\subsection{Continuation-URL}
+\label{sec:continuation-url}
+
+The \keyword{continuation-URL} represents the point in the computation
+of a session of a \surflet where the computation was halted by the
+\surflet handler.  When a browser requests a continuation-URL, the
+\surflet handler looks up the continuation in its tables and reifies
+it, allowing the session of the \surflet to resume its computation.
+
+The procedures to access the continuation-URL are the following.  They
+are exported by the \exi{surflet-handler/resume-url} structure.  Sorry
+for the double naming \ex{resume-url} and continuation-URL.
+
+\defun{resume-url?}{string}{boolean}
+\defunx{resume-url-ids}{resume-url}{session-id continuation-id}
+\defunx{resume-url-session-id}{resume-url}{session-id}
+\defunx{resume-url-continuation-id}{resume-url}{continuation-id}
+\begin{desc}
+  These inspect values of a resume url.  \ex{resume-url?} is predicate
+  for resume urls.  Note that it only operates on strings.
+  \ex{resume-url-ids} returns the session- and the continuation-id
+  that is stored in the \var{resume-url}.  \ex{resume-url-session-id}
+  and \ex{resume-url-continuation-id} return only the session- or the
+  continuation-id, respectively.
+\end{desc}
+
+
+\subsection{Input fields}
+
+The \surflets support all input fields defined for HTML~2.0 and allow
+  the creation of own input fields.  \ex{input-field}s are first order
+  values, that represent the actual input field of the web page in the
+  \surflet.  For that, this documentation distinguishes the
+  \emph{browser} value from the \emph{Scheme} value of an input field.
+  The browser value is the string representation of the input field
+  data the browser sends.  The Scheme value is the value in the
+  \surflet the input field reports as its value, which may be of any
+  type, not only strings.
+
+Here is a short overview, how to use input fields.  See also the howto
+  for more informations.  First, you create the \ex{input-field} that
+  represents the input field you want to use.  Then you put this
+  \ex{input-field} into the SXML of the web page at the place the
+  input field shall appear.  After \ex{send-html/suspend} has returned
+  with the next \ex{surflet-request}, you call \ex{get-bindings} with
+  that \ex{surlfet-request} and collect the resulting bindings.  Last,
+  you call \ex{input-field-value} (or \ex{raw-input-field-value}) with
+  your \ex{input-field} and the collected bindings to get the Scheme
+  representation of the value the user has entered.  Here is a small
+  example:
+
+\begin{alltt}
+(define-structure surflets surflet-interface
+  (open scheme-with-scsh
+        surflets)
+  (begin
+    
+    (define (main req)
+      (let* ((text-input (make-text-field))
+             (req (send-html/suspend
+                   (lambda (k-url)
+                     `(html
+                       (body
+                        (surflet-form
+                         ,k-url
+                         (p "Enter some asd  text: " ,text-input)
+                         ,(make-submit-button)))))))
+             (bindings (get-bindings req))
+             (text (input-field-value text-input bindings)))
+        (send-html/finish 
+         `(html
+           (body
+            (p "You've entered `" ,text "'."))))))
+))
+\end{alltt}
+
+\paragraph{Getting the bindings}
+
+The \exi{surflets/bindings} structures exports the necessary functions
+  to create bindings and extract values from them:
+
+\defun{get-bindings}{surflet-request}{bindings}
+\begin{desc}
+  This returns an association list representing the data the browser
+  has sent, usually the content of a webform.  The name of the input
+  fields are the keys, their browser values the values.  The values
+  are already unescaped.  \ex{get-bindings} can (currently) only
+  handle \ex{application/x-www-form-urlencoded} data.  You can call
+  \ex{get-bindings} on both \ex{GET} and \ex{POST} requests, even
+  multiple times (even on \ex{POST} requests).
+\end{desc}
+
+\defun{extract-bindings}{key bindings}{list}
+\defunx{extract-single-binding}{key bindings}{string}
+\begin{desc}
+  These extract values from the \var{bindings} as returned by
+  \ex{get-bindings}.  \var{key} may be a string or a symbol which will
+  be translated to a string before use.  \ex{extract-bindings} returns
+  a list of all values from \var{bindings} whose key is \var{key}.
+  \ex{extract-single-binding} returns the value from the binding whose
+  key is \var{key} and raises an error if there more than one such
+  binding.  The two procedures are the same as in PLT's webserver.
+\end{desc}
+
+\ex{get-bindings} must acces the "Content-length" header field to
+  handle \ex{POST} request.  \ex{surflets/bindings} therefore also
+  exports the procedure that does that job:
+
+\defun{get-content-length}{headers}{number}
+\begin{desc}
+  Returns the value of the "Content-length" header as a number, as
+  present in \var{headers}, \eg from \ex{surflet-request-headers}.
+  Will raise an error if there is no "Content-length" header or the
+  header is illformed, \eg contains no number.
+\end{desc}
+
+\paragraph{Retrieving the Scheme values}
+
+The \exi{surflets/input-field-value} structure provides the functions
+  necessary to retrieve the Scheme value of input fields.
+
+\defun{raw-input-field-value}{input-field bindings}{any type}
+\defunx{input-field-value}{input-field bindings [error-value]}{any type}
+\begin{desc}
+  These extract the Scheme value of an \var{input-field}, given the
+  \var{bindings} of the last request.  Asking for a Scheme value may
+  raise an error.  Some error conditions are: the input field was not
+  present in the bindings, the transformer could not generate a Scheme
+  value for the browser value, or some other error occured in a maybe
+  malfunctioning transformer.  In any case, \ex{raw-input-field-value}
+  won't catch that error, while \ex{input-field-value} will catch it
+  and provide \var{error-value} as the \var{input-field}'s Scheme
+  value, which defaults to \sharpf.
+\end{desc}
+
+\defun{input-field-binding}{input-field bindings}{binding}
+\begin{desc}
+  This returns the first binding in \var{bindings} that belongs to the
+  given \var{input-field} (\ie has \var{input-field}'s name as key).
+\end{desc}
+
+\paragraph{Creating and using input fields}
+
+The procedures for the creation of the input fields mentioned in
+  HTML~2.0 are the following.  They are exported by the
+  \exi{surflets/surflet-input-fields}.  Note that most of the time,
+  you may omit any of the optional arguments, \eg you may only specify
+  some further attributes to \ex{make-text-field} without specifying a
+  default value.  Keep in mind that \ex{input-field-value} catches the
+  error that may occur if an \ex{input-field} is asked for its Scheme
+  value and may return any (previously chosen) value instead.
+
+\defun{make-text-field}{[default] [attributes]}{input-field}
+\defunx{make-number-field}{[value] [attributes]}{input-field}
+\defunx{make-password-field}{[default] [attributes]}{input-field}
+\defunx{make-textarea}{[default] [rows] [columns] [readonly?] [attributes]}{input-field}
+\begin{desc}
+  These create various input field where the user types something in.
+  \var{default} is the text or the number that the browser initially
+  displays in the input field.  \var{attributes} are some further
+  attributes for the input field in SXML notation.
+  \ex{make-text-field} creates a regular text input field.  Its Scheme
+  value is a string.  \ex{make-number-field} creates a regular text
+  input field, whose Scheme value is a number.  It is an error if the
+  input field does not contain a number.  \ex{make-password-field}
+  creates a text input field that will display stars instead of the
+  typed text.  Its Scheme value is a string.  \ex{make-textarea}
+  creates a possibly multi line text input field.  \var{rows}
+  specifies how many rows of the text the browser will display at once
+  and defaults to 5.  \var{columns} specifies how many columns the
+  browser will display at once and defaults to 20.  Note that if you
+  only supply one number, it will be interpreted as the \var{rows}
+  argument.  \var{readonly?} is a boolean that tells the browser
+  whether to disallow changes of the displayed text.
+\end{desc}
+
+
+\defun{make-hidden-input-field}{[default] [attributes]}{input-field}
+\begin{desc}
+  Creates a hidden input field, \ie a input field that the browser
+  won't display but whose value the browser will send.  This input
+  field is provided for completeness; you usually won't need it, as
+  all values in your \surflet will survive the emission of a web page.
+  \var{default} is this value the browser will send.  Note that
+  although the argument is marked as optional you usually want to
+  provide it.  \var{attributes} are some further attributes for the
+  input field in SXML notation.
+\end{desc}
+
+\defun{set-text-field-value!}{input-field}{undefined}
+\defunx{set-number-field-value!}{input-field}{undefined}
+\defunx{set-hidden-field-value!}{input-field}{undefined}
+\defunx{set-password-field-value!}{input-field}{undefined}
+\defunx{set-textarea-value!}{input-field}{undefined}
+\begin{desc}
+  These set the default value of the according input field after it
+  has been created.  Although the procedure may not complain, it is an
+  error, if \var{input-field} is not the expected type of
+  \ex{input-field}, \eg if the argument to \ex{set-text-field-value}
+  was not created by \ex{make-text-field}.
+\end{desc}
+
+\defun{make-submit-button}{[caption] [attributes]}{input-field}
+\defunx{make-reset-button}{[caption] [attributes]}{input-field}
+\defunx{make-image-button}{image-source [attributes]}{input-field}
+\begin{desc}
+  These create buttons on the web page which the user can click on.
+  \var{caption} is the text that is displayed on the button.  If not
+  specified, the browser will choose a text, usually depending on the
+  local language setting on the browser side.  \var{attributes} are
+  some further attributes for the input field in SXML notation.
+  \ex{make-submit-button} creates the regular button to submit the web
+  form data.  As HTML~2.0 specifies that the value of a submit button
+  is its caption, its Scheme value is its caption, too.
+  \ex{make-reset-button} creates the button to reset all input fields
+  of the web form to their default values.  As the browser does not
+  send data for reset buttons, it does not have a Scheme value, \ie
+  asking for a value will raise an error.  \ex{make-image-button}
+  creates a picture button.  Its Scheme value is a pair indicating the
+  x- and y-coordinates of the picture where the user has clicked to.
+  The argument \var{image-source} is not optional and is the string
+  URL of the displayed picture.
+\end{desc}
+
+\defun{make-checkbox}{[checked?] [attributes]}{input-field}
+\defunx{make-annotated-checkbox}{value [checked?]
+  [attributes]}{input-field}
+\begin{desc}
+  These create checkboxes.  \var{checked?} says whether the browser
+  should initially mark the checkbox as checked.  \var{attributes} are
+  some further attributes for the input field in SXML notation.  If it
+  was checked the Scheme value of a checkbox made by
+  \ex{make-checkbox} is \sharpt.  If it was checked, the Scheme value
+  of a checkbox made by \ex{make-annotated-checkbox} is its
+  \var{value} provided during its creation where \var{value} may be
+  chosen arbitrarily.  Note that HTML~2.0 specifies that browsers
+  should not send data for unmarked checkboxes, thus asking for the
+  Scheme value of an unmarked checkbox will raise an error.  It is
+  recommended to use \ex{input-field-value} to ask for the Scheme
+  value of a checkbox.  This will catch the error and will instead
+  return \sharpf by default.
+\end{desc}
+
+\defun{check-checkbox!}{input-field}{undefined}
+\defunx{uncheck-checkbox!}{input-field}{undefined}
+\defunx{set-checkbox-checked?!}{input-field checked?}{undefined}
+\begin{desc}
+  These change the \ex{checked?} field of a checkbox that tells the
+  browser whether it should initially mark the checkbox as checked.
+  \ex{check-checkbox!} tells the browser to do so,
+  \ex{uncheck-checkbox!} does not tell the browser to do so, and
+  \ex{set-checkbox-checked?!} does so depending on \var{checked?}.  It
+  is an error if \var{input-field} was not created by
+  \ex{make-checkbox} or \ex{make-annotated-checkbox}.
+\end{desc}
+
+\defun{make-radio-group}{}{procedure}
+\defunx{make-annotated-radio-group}{}{procedure}
+\begin{desc}
+  These return generators for radio buttons.  Radio buttons usually
+  are part of a group of radio buttons of which only one may be
+  selected at any time.  The procedures return a procedure that
+  creates radio button \ex{input-field}s that belong to the same
+  group.  
+
+  The returned procedures accept a \var{value} argument, an optional
+  \var{checked?} argument and an optional \var{attributes} argument.
+  They return an \ex{input-field}, the actual radio button.  For
+  \ex{make-radio-group}, \var{value} must be a string, for
+  \ex{make-annotated-radio-group}, \var{value} may be any Scheme
+  value.  The Scheme value of any member of the group of radio buttons
+  is the \var{value} of the marked radio button that was provided
+  during its creation.  \var{checked?} determines whether the browser
+  will initially mark the radio button.  Note that you are able to
+  tell the browser to initially mark more than one radio button, but
+  in which case the browser's behavior is undefined.  \var{attributes}
+  are some further attributes for the input field in SXML notation.
+
+%The procedure returned by \ex{make-radio-group} is of the
+%  form of \ex{\textit{radio-generator}} explained below, the one
+%  returned by \ex{make-annotated-radio-group} is of the form of
+%  \ex{\textit{annotated-radio-generator}}.
+
+%\defun{\textit{radio-generator}}{text [checked?]
+%  [attributes]}{input-field}
+%\defunx{\textit{annotated-radio-generator}}{value [checked?]
+%  [attributes]}{input-field} 
+%\begin{desc}
+%  A further description.
+%\end{desc}
+\end{desc}
+
+\defun{check-radio!}{input-field}{undefined}
+\defunx{uncheck-radio!}{input-field}{undefined}
+\defunx{set-radio-checked?!}{input-field \var{checked?}}{undefined}
+\begin{desc}
+  These change the \ex{checked?} field of a radio button that tells
+  the browser whether it should initially mark the radio button as
+  checked.  \ex{check-radio!} tells the browser to do so,
+  \ex{uncheck-radio!} does not tell the browser to do so, and
+  \ex{set-radio-checked?!} does so depending on \var{checked?}.  It is
+  an error if \var{input-field} was not created by the procedures
+  returned by \ex{make-radio-group} or
+  \ex{make-annotated-radio-group}.
+\end{desc}
+
+\defun{make-select}{select-options [multiple?]
+  [attributes]}{input-field}
+\begin{desc}
+  This creates a select boxes.  Other names are ``drop down menu'' or
+  simply ``list''.  \var{select-options} is either a list of
+  \ex{select-options} created with the procedures presented below or a
+  list of strings.  In the latter case the strings are automatically
+  translated into \ex{select-options}.  \var{multiple?}  allows
+  multiple selections in the select box.  \var{attributes} are some
+  further attributes for the input field in SXML notation.  Note that
+  you will only get multiple Scheme values for a select box that
+  allows multiple selections, if you specify the \var{multiple?}
+  argument; providing the according attribute in \var{attributes}
+  won't work (you will get the value of the first selection only).
+\end{desc}
+
+\defun{make-simple-select-option}{tag [selected?]
+  [attributes]}{select-option}
+\defunx{make-annotated-select-option}{tag value [selected?]
+  [attributes]}{select-option}
+\begin{desc}
+  These create the options for a select box, to be used as arguments
+  to \ex{make-select}.  \var{tag} is a string that will be displayed
+  as an option of a select box.  \var{value} is an arbitrary Scheme
+  value that will be the Scheme value of the select input field 
+  that contains the option.  For simple select options this is the same as
+  \var{tag}.  \var{selected?} determines whether the browser should
+  preselect the option.  \var{attributes} are some further attributes
+  for the input field in SXML notation.
+\end{desc}
+
+\defun{select-option?}{object}{boolean}
+\begin{desc}
+  This is a predicate for \ex{select-option}s.
+\end{desc}
+
+\defun{select-select-option!}{tag input-field}{undefined}
+\defunx{unselect-select-option!}{tag input-field}{undefined}
+\defunx{set-select-option-selected?!}{tag input-field
+  selected?}{undefined}
+\begin{desc}
+  These change the \ex{selected?} field of a select option that tells
+  the browser to preselect it.  \ex{select-select-option!} tells the
+  browser to preselect it, \ex{unselect-select-option!} does not tell
+  it to do so and \ex{set-select-option-selected!} does so depending
+  on \var{selected?}.  Note that you access the select option by
+  providing the \var{tag} and the select \var{input-field} in which
+  the select option is saved.  \var{tag} is either the tag of the
+  select option or an index with 0 being the first select option of
+  that select input field.  However, the change will affect all select
+  input fields that use the same select option.  If there are
+  different select options with the same tag in a select input field,
+  the procedures will only touch one of them.
+
+\oops{Unfortunetaly, the order of the arguments (index, object) is the
+  opposite of what is usual in Scheme (object, index).  This should be
+  fixed in a future version.}
+\end{desc}
+
+\defun{add-select-option!}{input-field select-option}{undefined}
+\defunx{delete-select-option!}{input-field select-option}{undefined}
+\begin{desc}
+  These add or remove \var{select-option} to or from the select
+  \var{input-field}, respectively.
+\end{desc}
+	   
+
+\subsubsection{Do it yourself: your own input fields}
+
+The \surflets library allows the creation of arbitrary own input
+  fields.  The relevant procedures are exported by the
+  \exi{surflets/my-input-fields} structure.
+
+\defun{make-input-field}{name type transformer attributes
+  html-tree-maker}{input-field}
+\defunx{make-multi-input-field}{name type transformer attributes
+  html-tree-maker}{input-field} 
+\begin{desc}
+  These are the two constructors for \ex{input-field}s.  
+
+  \var{name} is the name of the input field as used in the HTML.  You
+  have to make sure that this name is unique across your web page, \eg
+  by using \ex{generate-input-field-name} presented below.  
+
+  \var{type} is the type of the input field and mainly meant as a
+  label for debugging.  You may choose an arbitrary value for it.
+  
+  \var{transformer} is a procedure that accepts the created
+  \ex{input-field} and some other value as arguments and returns the
+  (single) Scheme value of the input field.  For
+  \ex{make-input-field}, the other value is the string representation
+  of the value the user has entered in the represented input field, as
+  sent by the browser.  For \ex{make-multi-input-field}, the other
+  value is an association list of all data the browser has sent, the
+  names being the key and the entered data being the value.  This is
+  the very same list as returned by \ex{get-bindings}, see above.
+  When the \var{transformer} cannot create a Scheme value for the
+  \ex{input-field}, she should raise an error.
+
+  \var{attributes} takes some extra information you want to store
+  along with the \ex{input-field}.  You may choose an arbitrary value
+  for it. 
+
+  \var{html-tree-maker} is a procedure that takes the created
+  \ex{input-field} as argument and returns its representation in SXML.
+\end{desc}
+
+\defun{generate-input-field-name}{prefix}{string}
+\begin{desc}
+  This generates a pseudo unique name based on prefix.  Subsequent
+  calls with the same prefix are guaranteed to never return the same
+  string.\footnote{Well, never say never:  if the structure is
+  reloaded, the counter is reset and \ex{generate-input-field-name}
+  will return the same names again.} 
+\end{desc}
+
+
+\defun{input-field-name}{input-field}{string}
+\defunx{input-field-type}{input-field}{any type}
+\defunx{input-field-transformer}{input-field}{procedure}
+\defunx{input-field-attributes }{input-field}{any type}
+\defunx{input-field-html-tree-maker}{input-field}{procedure}
+\defunx{input-field-html-tree}{input-field}{sxml}
+\defunx{input-field-multi?}{input-field}{boolean}
+\begin{desc}
+  These inspect input field values.  \ex{input-field-name} returns the
+  name of the input field as used in its HTML representation.
+  \ex{input-field-type} returns a string indicating the type of the
+  input field, \eg "\ex{radio}" or "\ex{text}".  For individual input
+  fields it may return a value of any type.
+  \ex{input-field-transformer} returns the transformer procedure that
+  is used the transform the browser value of the input field to a
+  Scheme value.  \ex{input-field-attributes} returns the attributes
+  that were stored along with the input field.
+  \ex{input-field-html-tree-maker} returns the procedure that creates
+  the SXML representation of the input field.
+  \ex{input-field-html-tree} returns the SXML representation of the
+  input field.  \ex{input-field-multi?} returns \sharpt if the input
+  field was created with \ex{make-multi-input-field}, \sharpf
+  otherwise.  The transformer of an multi-\ex{input-field} gets the
+  browser bindings as second argument while the transformer of a
+  normal (non-multi) \ex{input-field} gets the string representation
+  of the entered data as second argument.
+\end{desc}
+
+
+\defun{set-input-field-attributes!}{input-field
+  new-attributes}{undefined}
+\begin{desc}
+  This allows the mutation of the attributes of the \var{input-field}
+  to \var{new-attributes}.
+\end{desc}
+
+\defun{touch-input-field!}{input-field}{undefined}
+\begin{desc}
+  This forces the recalculation of the SXML representation of the
+  \var{input-field} using its html-tree-maker procedure.
+\end{desc}
+
+
+\subsection{Web addresses}
+
+The \surflets library allow you to determine which link or button a
+  user used to leave a page.  The links are called evaluatable web
+  addresses.  The \exi{surflets/returned-via} structure provides
+  procedures and syntax for this.
+
+\defun{returned-via}{return-object bindings}{any value}
+\defunx{returned-via?}{return-object bindings}{any value}
+\begin{desc}
+  Determines, whether the user left the web page using
+  \var{return-object}.  \var{bindings} are the bindings as returned by
+  \ex{get-bindings}.  If \var{return-object} is an \ex{input-field},
+  \ex{returned-via} returns its Scheme value as reported by
+  \ex{input-field-value}.  The input field usually can only be a
+  submit or an image button.  If \var{return-object} is not an
+  \ex{input-field}, \ex{returned-via} assumes it is an evaluatable web
+  address.  If the user did not use the evaluatable web address to
+  leave the web page, \ex{returned-via} returns \sharpf.  Otherwise,
+  when the evaluatable web address is annotated, \ex{returned-via}
+  returns its annotation, otherwise just \sharpt.  \ex{returned-via?}
+  is an alias for \ex{returned-via}.  The type of the return value
+  depends on the type of \var{return-object}.
+\end{desc}
+
+% There is \defsyn or \defsyntax command yet, so I hack it on my own.
+{\par\medskip{\index{case-returned-via}
+   \hbox to \linewidth{\ttchars{{\ttt{(case-returned-via \synvar{key} \synvar{clause} \ldots)}} \hfill syntax}}}%
+% This said:
+% (case-returned-via \synvar{key} \synvar{clause} \ldots)      syntax
+%\defvar{(case-returned-via \synvar{key} \synvar{clause} \ldots)}{syntax}
+\begin{desc}
+  This works like \ex{case} with some flavor of \ex{cond}.  Instead of
+  \ex{eq?}  it uses \ex{returned-via} to determine which
+  \synvar{clause} applies.  \synvar{key} is the \var{bindings}
+  argument to \ex{returned-via} (see above for the arguments of
+  \ex{returned-via}).  
+
+  A clause is of the form
+\codex{((\synvar{datum} \ldots) \synvar{expression} \ldots)}
+  where each \synvar{datum} is the \var{return-object} argument of
+  \ex{returned-via}.   If for any of the \synvar{datum}
+  \ex{returned-via} returns a true value, the \synvar{expression}s are
+  evaluated.  
+
+  Alternatively, a clause may be of the form
+\codex{((\synvar{datum} \ldots) => \synvar{procedure} \ldots)}
+  If for any of the \synvar{datum} \ex{returned-via} returns a true
+  value, \synvar{proc} is called with that value.  
+
+  The last possible clause is an "else" clause of the form
+\codex{(else \synvar{expression} \ldots)}
+  which applies when the previous clauses don't apply.
+
+  \ex{case-returned-via} returns the value(s) of the
+  \synvar{expression} that was evaluated last.
+\end{desc}
+
+\subsubsection{Evaluatable web addresses}
+
+The \exi{surflets/addresses} structure provides procedures to create
+  evaluatable web addresses.  Evaluatable web addresses are used just
+  like web addresses with the difference that \ex{returned-via} can
+  tell whether the user used this web address to leave the web page.
+
+\defun{make-address}{}{address-procedure}
+\begin{desc}
+  This creates an evaluatable web address.  \var{address-procedure} is
+  a procedure that accepts messages.  If the message is a string,
+  \var{address-procedure} will assume it is a continuation URL and
+  will return a web address that can be used as a link.  If the
+  message is the symbol \ex{address}, \var{address-procedure} will
+  return the real \ex{address} object.
+\end{desc}
+
+\defun{make-annotated-address}{}{address-procedure}
+\begin{desc}
+  This creates an annotated evaluatable wewb address.
+  \var{address-procedure} is a procedure that accepts messages.  The
+  procedure accepts either a string and an optional annotation which
+  may be any Scheme value, or it accepts only the symbol \ex{address}.
+  In the first case, it will assume the string is a continuation URL
+  and will return a web address that can be used as a link.  In the
+  latter case, it will return the real \ex{address} object.
+\end{desc}
+
+\oops{Evaluatable web address cannot be used as the action URL of web
+  forms.} 
+
+\defun{address-name}{address}{string}
+\defunx{address-annotated?}{address}{boolean}
+\defunx{address-annotation}{address}{any type}
+\begin{desc}
+  These inspect real \ex{address} objects as returned by the
+  evaluatable web addresses when given the symbol \ex{address}.
+  \ex{address-name} returns the name of the \var{address} as used in
+  the browser data.  \ex{address-annotated?} indicates whether
+  \var{address} is annotated.  \ex{address-annotation} returns the
+  annotation of \var{address}.  If \var{address} is not annotated, it
+  returns \sharpf.
+\end{desc}
+
+\subsection{Callbacks}
+
+The \surflets library allows to add a callback to a link.  When the
+  user of a web page clicks on the link, the callback will be
+  executed. \ex{send-html/suspend} (usually) won't return in that
+  case.
+
+
+\defun{make-callback}{callback-procedure}{continuation-URL}
+\begin{desc}
+  This creates a callback.  When a user clicks on a link to the
+  continuation URL \ex{make-callback} has returned,
+  \var{callback-procedure} will be called with the according
+  \ex{surflet-request}.  \var{callback-procedure} should not return.
+
+  \ex{make-callback} works with continuations.  Therefore, it is not
+  sensible to create callbacks on toplevel, nor is it sensible to
+  reuse callbacks.  Instead, create your callback every time and right
+  before you need it.
+
+  If \var{callback-procedure} returns, \ex{make-callback} will return
+  \emph{again}, this time with the value returned by
+  \var{callback-procedure}.  Note that in this case the continuation
+  that was active at the time of the call to \ex{make-callback} is
+  restored.  Or, in short, don't let \var{callback-procedure} return
+  if you want to avoid headaches.
+\end{desc}
+
+\defun{make-annotated-callback}{callback-procedure}{procedure}
+\begin{desc}
+  This creates a callback generator.  The returned procedure accepts
+  any number of arguments \var{args} and returns a continuation URL.
+  When the user clicks on a link to the continuation URL,
+  \var{callback-procedure} will be called with the arguments
+  \var{args} previously provided.  
+
+  It is an error, if \var{callback-procedure} returns.  You should
+  create a fresh annotated callback every time and right before you
+  need it, as the continuation that was active at the time of the call
+  to \ex{make-annotated-callback} is restored.
+\end{desc}
+
+\defvar{callback-function}{procedure}
+\begin{desc}
+  Use this procedure as the \var{callback-procedure} argument to
+  \ex{make-annotated-callback} to call arbitrary procedures with
+  arbitrary arguments.
+\end{desc}
+
+Here are some examples.  The first example shows how you can use an
+  annotated callback.  Note that it does not need to use
+  \ex{send-html/suspend}.
+
+\begin{alltt}
+(define-structure surflet surflet-interface
+  (open surflets
+        surflets/callbacks
+        scheme-with-scsh)
+  (begin
+    
+    (define (main req)
+      (let ((language (make-annotated-callback result-page)))
+        (send-html
+         `(html 
+           (head (title "Multi-lingual"))
+           (body 
+            (h2 "Select your language:")
+            (ul
+             (li (url ,(language "Hello, how are you?") 
+                      "English")
+             (li (url ,(language "Hallo, wie geht es Ihnen?")
+                      "Deutsch")))))))))
+
+    (define (result-page req text)
+      (send-html/finish
+       `(html 
+         (head (title "Greeting"))
+         (body
+          (h2 ,text)))))
+                        
+    ))
+\end{alltt}
+
+
+Replacing the \ex{main} procedure with the following definition will
+  have the same result:
+
+\begin{alltt}
+    (define (main req)
+      (let ((language (make-annotated-callback  callback-function)))
+        (send-html
+         `(html 
+           (head (title "Multi-lingual"))
+           (body 
+            (h2 "Select your language:")
+            (ul
+             (li (url ,(language result-page "Hello, how are you?") 
+                      "English")
+             (li (url ,(language result-page "Hallo, wie geht es Ihnen?")
+                      "Deutsch")))))))))
+\end{alltt}
+
+