Add other sections. Fix typo.

doc/latex/surfletapi.tex

@@ -448,6 +448,54 @@ of a session via the following procedures.
   restricted in future versions of the \surflet server.
 \end{desc}
 
+The \exi{surflets/continuations} also offers procedures to access the
+  continuations.
+
+\defun{get-continuations}{session}{list}
+\begin{desc}
+  Returns a list of all continuations of the \var{session}.  The list
+  elements are pairs with the \ex{car} being the session and the
+  \ex{cdr} being the continuation.
+\end{desc}
+
+\defun{delete-continuation!}{session-continuation}{undefined}
+\begin{desc}
+  Removes the specified continuation from the continuation table.
+  \var{session-continuation} is a pair as returned from
+  \ex{get-continuations}.  It is no error if the session or the
+  continuation does not exist anymore.
+
+  The access to this functions is currently unrestricted but may be
+  restricted in future versions of the \surflet server.
+\end{desc}
+
+\defun{continuation-id}{session-continuation}{number}
+\begin{desc}
+  Returns the continuation ID of the continuation specified by
+  \var{session-continuation} which is a pair as returned by
+  \ex{get-continuations}. 
+\end{desc}
+
+The \exi{surflets/ids} structure provides procedures to determine the
+  session and continuation IDs of the current session.  See also the
+  entry for \ex{resume-url-ids} some where else in this document.
+
+\defun{my-session-id}{surlfet-request}{number}
+\defunx{my-continuation-id}{surlfet-request}{number}
+\defunx{my-ids}{surlfet-request}{number number}
+\begin{desc}
+  These return the session and continuation ID that where used to
+  access the current session.  The procedures work for every
+  \var{surflet-request} except for the inital one that \ex{main}
+  gets.  The values returned by \ex{my-ids} are the session and the
+  continuation ID in this order.
+\end{desc}
+
+\defun{surflet-file-name}{surlfet-request}{string}
+\begin{desc}
+  This returns the name of the \surflet of the current session.
+\end{desc}
+
 
 \subsubsection{Session data}
 The \surflet handler distinguishes three kinds of \keyword{session
@@ -512,7 +560,7 @@ the \ex{status-code} syntax.
   continuation-URLs.
 \end{desc}
 
-\defun{send/error}{status-code surflet-request [messages]}{\noreturn}
+\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
@@ -828,6 +876,7 @@ for the double naming \ex{resume-url} and continuation-URL.
 \end{desc}
 
 
+
 \subsection{Input fields}
 
 The \surflets support all input fields defined for HTML~2.0 and allow
@@ -1293,8 +1342,7 @@ The \surflets library allow you to determine which link or button a
 \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}}}%
+\defsyn{case-returned-via}{\synvar{key} \synvar{clause} \ldots}
 % This said:
 % (case-returned-via \synvar{key} \synvar{clause} \ldots)      syntax
 %\defvar{(case-returned-via \synvar{key} \synvar{clause} \ldots)}{syntax}
@@ -1472,3 +1520,145 @@ Replacing the \ex{main} procedure with the following definition will
 \end{alltt}
 
 
+\subsection{Outdater}
+
+The \surflets library allows the user to navigate through the web
+  pages back and forth as she sees fit.  However, sometimes you want
+  to make sure, that a submission is done only once.  For this, the
+  \surflets provide \ex{outdater} objects that take care of this.
+
+\defun{make-outdater}{}{outdater}
+\begin{desc}
+  Creates an outdater object.
+\end{desc}
+
+\defsyn{if-outdated}{\synvar{outdater} \synvar{consequence}
+  \synvar{alternative}}
+\begin{desc}
+  Using the \synvar{outdater}, this makes sure, the
+  \synvar{alternative} is executed at most once, \ie the first time
+  the \synvar{outdater} is used in such a form, the
+  \synvar{alternative} is evaluated.  Every subsequent evaluation of
+  the \ex{if-outdated} form with the \synvar{outdater} will evaluate
+  the \synvar{consequence}, usually something similar to what
+  \ex{show-outdated} does.
+\end{desc}
+
+\defun{show-outdated}{url}{\noreturn}
+\begin{desc}
+  Emits a regular web page to the client informing the user (in
+  English) that ``the page or action you requested relies on outdated
+  data''.  It offers a ``reload'' link that points to \var{url} to get
+  current data.  Usually, \var{url} is a callback URL the calls the
+  according procedure.  See the admin \surlets for examples, \eg
+  \ex{scheme/web-server/root/surlfets/admin-surflet.scm}. 
+\end{desc}
+
+
+\subsection{Simple SUrflets}
+
+PLT offers an API to create simple servlets (which are their analogues
+  to our \surflets).  The \exi{simple-surflet-api} structure offers
+  the procedures with the same name as in the PLT API.  With that,
+  \surflets can look as simple as this
+  (\ex{scheme/web-server/root/surlfets/add-simple.scm, see also
+  \ex{simple-surflet.scm} in the same directory for a larger example}:
+
+\begin{alltt}
+(define-structure surflet surflet-interface
+  (open scheme-with-scsh
+        surflets
+        simple-surflet-api
+        )
+  (begin
+
+    (define (main req)
+      (let* ((number-1 (single-query (make-number "First number:")))
+             (number-2 (single-query (make-number "Second number:"))))
+        (inform (format #f "~a + ~a = ~a"
+                        number-1
+                        number-2
+                        (+ number-1 number-2))))
+      (final-page "Session finished."))
+
+))
+\end{alltt}
+
+The procedures are the following.
+
+\defun{single-query}{query}{any type}
+\begin{desc}
+  Asks the user one single questions based on \var{query} and returns
+  her answer.
+\end{desc}
+
+\defun{queries}{queries}{list}
+\begin{desc}
+  Asks the user multiple questions based on the list of \var{queries}
+  and returns her answers in a list.
+\end{desc}
+
+\defun{form-query}{named-queries}{list}
+\begin{desc}
+  Asks the user multiple queries based on the list of
+  \var{named-queries} and returns her answers in a pseudo association
+  list.  \var{named-queries} is a list of two element lists.  The
+  first element of those lists is a symbol identifying the query, the
+  second is the query.  The resulting pseudo association list contains
+  two element lists, where the first element is the symbol and the
+  second element the user's answer to the query.  The result can be
+  read using the \ex{extract/single} and \ex{extract} procedures.
+\end{desc}
+
+\defun{inform}{title [text \ldots]}{surflet-request}
+\begin{desc}
+  Sends a web page title \var{title} with the \var{text} to the user
+  as an information.  The returned \ex{surflet-request} is usually
+  discarded.  Takes at least one argument.
+\end{desc}
+
+\defun{final-page}{title [text \ldots]}{\noreturn}
+\begin{desc}
+  This sends the last page of the session to the user, titled
+  \var{title} and containing \var{text}.  This is the analog to
+  \ex{send/finish}.  Takes at least one argument.
+\end{desc}
+
+\defun{make-text}{invitation}{query}
+\defun{make-number}{invitation}{query}
+\defun{make-password}{text}{query}
+\defun{make-boolean}{invitation}{query}
+\defun{make-radio}{invitation choices}{query}
+\defun{make-yes-no}{invitation yes-text no-text}{query}
+\begin{desc}
+  These create the various queries.  \var{invitation} is a text
+  displayed in front of the input field, \eg ``Please enter your
+  password:''.  \ex{make-text} creates a text input field,
+  \ex{make-number} creates a number input field (\ie a text input field
+  that only accepts numbers as inputs), \ex{make-password} creates a
+  password input field, \ex{make-boolean} creates a checkbox,
+  \ex{make-radio} creates a group of radio buttons of which only one
+  can be selected and \ex{make-yes-no} creates a radio group that
+  allows the choices \var{yes-text} and \var{no-text}. 
+
+  The value of \ex{make-text}, \ex{make-number} and \ex{make-password}
+  is the text or number entered into the input field.  The value of
+  \ex{make-boolean} is \sharpt or \sharpf.  The value of
+  \ex{make-radio} and \ex{make-yes-no} is the selected choice, a
+  string.
+\end{desc}
+
+\defun{extract/single}{symbol table}{any value}
+\defunx{extract}{symbol table}{list}
+\begin{desc}
+  Return the answer of a user to a query.  \var{table} is the result
+  of \ex{form-query}, \var{symbol} the symbol used to identify the
+  query of interest.  For \ex{extract/single}, it is an error if there
+  is more than one query in \var{table} that is identified by
+  \var{symbol}.
+\end{desc}
+
+% shift-reset
+% profiling
+% handle-fatal
+% thread safe counter