Prepare for SUrflet API documentation.

doc/latex/surflethowto.tex

@@ -20,13 +20,16 @@
 %%tableofcontents
 %%sloppy
 
-\section{Introduction}
+\section{Howto}
+\label{sec:surflethowto}
+
 This howto gives a short introduction in how to write a \surflet.  It
 is concentrated on the practical side rather on describing the
 \surflet API in detail to give you instant succes in running your own
-surflets.  The \surflet API will be described in the SUnet
-documentation eventually.
+surflets.  See section \ref{sec:surflet-api} for the (technical) API
+description. 
 
+\subsection{Introduction}
 %\marginpar{\surflets are pieces of code for web site scripting.}
 For those who don't know it already, \surflets are pieces of code that
 can be executed interactively through a website.  There is a \surflet
@@ -55,7 +58,7 @@ of the SUnet webserver and scsh.  The environment variable
 \typew{\$sunet} refers to the top level directory of your sunet
 installation.  On my system this is \name{/home/andreas/sw/sunet}.
 
-\section{How to run the SUnet webserver that handles \surflets}
+\subsection{How to run the SUnet webserver that handles \surflets}
 
 The following sections will show pieces of \surflet code you might
 want to try out.  Therefore you need the SUnet webserver running with
@@ -160,12 +163,12 @@ The \typew{--help} option will show you more parameters that you can
 adjust, but you won't need them for this howto.
 
 
-\section{How to send web pages}
+\subsection{How to send web pages}
 
 This section will discuss some of the various ways in which you can
 send a web page to a browser that contacted your \surflet.
 
-\subsection{My first \surflet}
+\subsubsection{My first \surflet}
 \label{sec:first-surflet}
 
 Traditionally,  your first program in any programming language prints
@@ -300,7 +303,7 @@ strings.  Everything else like using valid HTML tags or valid
 attributes is your responsibility.
 
 
-\subsection{Dynamic content}
+\subsubsection{Dynamic content}
 
 Let's extend our first \surflet example by some dynamic content, \eg
 by displaying the current time using scsh's \name{format-date}
@@ -348,7 +351,7 @@ unquote feature.  Of course, you can build your list in any way you
 want; the quasiquote notation is just a convenient way to do it.
 
 
-\subsection{Several web pages in a row}
+\subsubsection{Several web pages in a row}
 
 The previous example \surflets only showed one page and finished
 afterwards.  Here, we want to present to web pages in a row.  We use
@@ -400,11 +403,11 @@ variables keep their modified values, allowing communication between
 sessions of the same \surflet.\footnote{If you want to change a
 variable via side effects but you don't want to interfere with other
 session, you can use \name{set-session-data!} and
-\name{get-session-data}.  See the API documentation for further
-information.}
+\name{get-session-data}.  See the API documentation in section
+\ref{sec:surflet-api}for further information.}
 
 
-\subsection{Begin and end of sessions}
+\subsubsection{Begin and end of sessions}
 
 So far I don't have mentioned too much details about sessions.  The
 reason is, as mentioned before, that the \surflet handler takes of the
@@ -431,7 +434,7 @@ sending function is \name{send-html} which just sends a web page.
 \name{send-html} does not return and does not touch the session of
 your \surflet instance.
 
-\subsection{Abbreviations in SXML}
+\subsubsection{Abbreviations in SXML}
 \label{sxml-abbrvs}
 
 The example in subsection ``Several web pages in a row'' wrote down
@@ -456,14 +459,14 @@ The last abbreviation, \name{surflet-form}, is discussed in the next
 section.
 
 
-\section{How to write web forms}
+\subsection{How to write web forms}
 
 The \surflets come along with a libary for easy user interaction.  The
 following subsections will show how to write web forms and how to get
 the data the user has entered.
 
 
-\subsection{Simple web forms}
+\subsubsection{Simple web forms}
 
 Let's write a \surflet that reads user input and prints it out on the
 next page:
@@ -605,9 +608,9 @@ user data with \name{input-field-value}.
 \end{itemize}
 
 The complete list of functions that create \name{input-fields} can be
-found in the API.
+found in the API in section \ref{sec:surflet-api}.
 
-\subsection{Return types other than strings}
+\subsubsection{Return types other than strings}
 \label{subsec:input-return}
 
 As the user interaction elements are first class values in a \surflet,
@@ -680,7 +683,7 @@ the user's input, we will get the associated price for the sweet.
 Again, this works not only with numbers, but with any arbitrary Scheme
 value (\eg functions or records).
 
-\subsection{Sending error messages}
+\subsubsection{Sending error messages}
 
 If a user tries to forge a \surflet-URL (\eg by extracting the
 continuation URL from the HTML source and editing it), your \surflet
@@ -783,14 +786,15 @@ does not appear in the data the browser sends to the server.  Thus,
 raise an error which is not a ``real'' error as you migh expect it.
 
 
-\subsection{Your own input fields}
+\subsubsection{Your own input fields}
 
 The \surflet library contains constructors for all input fields that
-are described in the HTML~2.0 standard.  See the \surflet API for a
-complete list.  The \surflet library also allows you to create your
-own input fields, \eg an input field that only accepts valid dates as
-its input.  This subsection gives you a short overview how to do
-this.  You will find the details in the \surflet API.
+are described in the HTML~2.0 standard.  See the \surflet API in
+section \ref{sec:surflet-api} for a complete list.  The \surflet
+library also allows you to create your own input fields, \eg an input
+field that only accepts valid dates as its input.  This subsection
+gives you a short overview how to do this.  You will find the details
+in the \surflet API.
 
 Let's have a look at an \surflet that uses its own input field.  The
 ``input field'', called nibble input field, consists of eight check
@@ -923,7 +927,7 @@ again.  We create, use and evaluate the nibble input field as we do
 with every other input field.
 
 
-\section{Program flow control}
+\subsection{Program flow control}
 
 With the techniques shown so far it is rather difficult to create a
 web page that has several different successor webpages rather than
@@ -934,7 +938,7 @@ the mark after \name{send-html/suspend} has returned.  The other
 method is to bind a callback function to each link that is called when
 the user selects the link.  This section shows both methods.
 
-\subsection{Dispatching to more than one successor web page}
+\subsubsection{Dispatching to more than one successor web page}
 
 The basic idea of dispatching is to add a mark to a link and evaluate
 it after the user has clicked on a link and \name{send-html/suspend}
@@ -1037,7 +1041,7 @@ shortly.  Of course, it is your choice if you want to use
 \name{case-returned-via} or explicitly \name{returned-via}.
 
 
-\subsection{Annotated dispatching}
+\subsubsection{Annotated dispatching}
 
 The approach shown in the previous subsection has one major drawback:
 the meaning of an address becomes clear only when you look at the
@@ -1127,7 +1131,7 @@ via which the user has left the web page.  \name{returned-via} returns
 created with this address (which is not really possible in this
 example).
 
-\subsection{Callbacks}
+\subsubsection{Callbacks}
 
 The other method to lead to different successor web pages is using
 callbacks.  A callback is a function that is called if the user leaves
@@ -1212,7 +1216,7 @@ calling a function with several arguments and of different amount each
 time is also possible if you only use a single function for the
 callback.
 
-\section{Data management}
+\subsection{Data management}
 
 When you write web programs, there are usually two kinds of data that
 you use: data that is local to each instance of a \surflet, \eg the
@@ -1341,13 +1345,13 @@ endless states of the \surflet.
 \name{cancel} shows the final page with the amount of clicks
 performed.  
 
-\section{My own SXML}
+\subsection{My own SXML}
 
 Section \ref{sec:SXML} introduced SXML, the way how \surflets
 represent HTML.   This section will show you, how you can create your
 own rules to translate from SXML to HTML.
 
-\subsection{Terms and theoretical background}
+\subsubsection{Terms and theoretical background}
 
 This subsection will introduce the main concepts of the translation
 process and some necessary terms we will use in the following.
@@ -1401,7 +1405,7 @@ standard conversion rule set the text conversion rule performs HTML
 escaping, \eg for the ampersand (\&).
 
 
-\section{Outlook}
+\subsubsection{Outlook}
 
 More to come soon about \surflets consisting of different parts and
 individual SXML.

doc/latex/surflets.tex

@@ -3,9 +3,12 @@
 \newcommand{\typew}[1]{\texttt{#1}}
 
 The \surflet server enables you to write server side scripted web
-programs in Scheme.  Currently, there is only the howto available.
-The complete API is supposed to come soon.  There are lot of example
-files in \typew{httpd/surflet/webserver/root/surflets} from which you
+programs in Scheme.  
+%Currently, there is only the howto available.
+%The complete API is supposed to come soon.  
+There are lot of example files in
+\typew{scheme/httpd/surflet/webserver/root/surflets} from which you
 can copy freely.
 
 \input{surflethowto}
+\input{surfletapi}