From c1b264b9b139106c95c2923f3377dfb6c04b1a3f Mon Sep 17 00:00:00 2001 From: interp Date: Thu, 29 Jul 2004 16:20:20 +0000 Subject: [PATCH] Prepare for SUrflet API documentation. --- doc/latex/surflethowto.tex | 66 ++++++++++++++++++++------------------ doc/latex/surflets.tex | 9 ++++-- 2 files changed, 41 insertions(+), 34 deletions(-) diff --git a/doc/latex/surflethowto.tex b/doc/latex/surflethowto.tex index db4cea9..b69a0bb 100644 --- a/doc/latex/surflethowto.tex +++ b/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. diff --git a/doc/latex/surflets.tex b/doc/latex/surflets.tex index 577675f..cb36060 100644 --- a/doc/latex/surflets.tex +++ b/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}