From 63d708b2198bdd63f66dccbce5b293e6954c8603 Mon Sep 17 00:00:00 2001 From: interp Date: Sat, 17 Jan 2004 01:35:16 +0000 Subject: [PATCH] Move SUrflet howto into main documentation. Merge 2 decls.tex together. Drawback: can't use url package anymore. --- doc/latex/decls.tex | 60 +++++++++++ doc/latex/man.tex | 3 + .../howto.tex => doc/latex/surflethowto.tex | 100 +++++++++--------- doc/latex/surflets.tex | 11 ++ scheme/httpd/surflets/decls.tex | 73 ------------- 5 files changed, 125 insertions(+), 122 deletions(-) rename scheme/httpd/surflets/howto.tex => doc/latex/surflethowto.tex (95%) create mode 100644 doc/latex/surflets.tex delete mode 100644 scheme/httpd/surflets/decls.tex diff --git a/doc/latex/decls.tex b/doc/latex/decls.tex index 873fcac..d7948b3 100644 --- a/doc/latex/decls.tex +++ b/doc/latex/decls.tex @@ -5,6 +5,8 @@ \def\Eg{\mbox{\emph{E.g.}}} \def\etc{{\em etc.}} + + \def\Lisp{\textsc{Lisp}} \def\CommonLisp{\textsc{Common Lisp}} \def\Ascii{\textsc{Ascii}} @@ -275,4 +277,62 @@ {\begin{figure}[#1]\begin{boxedminipage}{\linewidth}\vskip 1.5ex} {\end{boxedminipage}\end{figure}} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%for surflet howto +\def\surflet{SUrflet\xspace} +\def\surflets{SUrflets\xspace} +\def\scsh{scsh\xspace} +\def\sunet{SUnet\xspace} + +%From surflet/decls.tex +{\theoremstyle{break} +\theoremheaderfont{\normalfont\bfseries\em} + \newtheorem{proglist}{Listing}[section]} +\setlength{\theorempreskipamount}{1.5ex plus0.2ex minus0.2ex} +\setlength{\theorempostskipamount}{2ex plus0.5ex minus0.2ex} + +% These environments differ from the other definition by the +% positioning of \normalem +\newenvironment{listing} + {\ULforem\begin{proglist}\begin{alltt}\small\normalem} + {\end{alltt}\end{proglist}} + +\newenvironment{reflisting}[1] + {\ULforem\begin{proglist}[\refinlisting{#1}]\begin{alltt}\small\normalem} + {\end{alltt}\end{proglist}} + +\newcommand{\contatlisting}[1]{% +{\normalfont\textit{$<$continued in listing~\ref{#1}\/$>$}}} +\newcommand{\contfromlisting}[1]{% +{\normalfont\textit{$<$continued from listing~\ref{#1}\/$>$}}} +\newcommand{\refinlisting}[1]{% +{\normalfont\textit{referenced in listing~\ref{#1}}}} +\newcommand{\seelisting}[1]{% +{\normalfont{\textit{$<$see listing~\ref{#1}\/$>$}}}} + +\newfloat{program}{t}{lop} +\floatname{program}{Programm} +\newenvironment{floatprog}[2] + {\begin{program}[ht] \caption{#1} \label{#2} \begin{alltt}} + {\end{alltt} \end{program}% + % Force output of even long floating figs + \afterpage{\clearpage}} + +% Use url-package to get function names line-breaked at - / + +% by infos in /usr/share/texmf/tex/latex/misc/url.sty +%%\newcommand\breakfuntt{\begingroup \urlstyle{tt}% +%%\@ifundefined{selectfont}{\def\UrlFont{\tt}}{\def\UrlFont{\ttfamily}}% +%%\def\UrlBreaks{\do\-\do\/\do\+}\def\UrlNoBreaks{\do\!}\Url +%%} + +\newcommand{\name}[1]{\texttt{#1}} +%\newcommand{\object}[1]{\breakfuntt{#1}} +\newcommand{\file}[1]{\textttt{#1}} +\newcommand{\codemph}[1]{\emph{#1}} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + \makeatother + + diff --git a/doc/latex/man.tex b/doc/latex/man.tex index e2d3661..8c33368 100644 --- a/doc/latex/man.tex +++ b/doc/latex/man.tex @@ -9,6 +9,8 @@ \usepackage[latin1]{inputenc} \usepackage{alltt} \usepackage{xspace} +\usepackage{tabularx,theorem,ulem,float,afterpage} % need url +\normalem % usually, don't use ulem \texonly % tex2page defines \url and hyperref loads the package url @@ -61,6 +63,7 @@ \include{uri} \include{url} \include{cgi-script} +\include{surflets} \include{ftpd} \include{ftp} \include{netrc} diff --git a/scheme/httpd/surflets/howto.tex b/doc/latex/surflethowto.tex similarity index 95% rename from scheme/httpd/surflets/howto.tex rename to doc/latex/surflethowto.tex index 931b3dc..3617495 100644 --- a/scheme/httpd/surflets/howto.tex +++ b/doc/latex/surflethowto.tex @@ -1,27 +1,27 @@ -\documentclass{article} - -\usepackage[latin1]{inputenc} -\usepackage{fontenc} -\usepackage{alltt} -\usepackage{url,xspace} -\usepackage{tabularx} -\usepackage{theorem,ulem,float,afterpage} -\normalem %usually, don't use ulem - - -\input{decls} - -\title{Howto write \surflets} -\author{Andreas Bernauer} - -\begin{document} -\maketitle - -\tableofcontents -\sloppy +%%documentclass{article} +%% +%%usepackage[latin1]{inputenc} +%%usepackage{fontenc} +%%usepackage{alltt} +%%usepackage{url,xspace} +%%usepackage{tabularx} +%%usepackage{theorem,ulem,float,afterpage} +%%normalem %usually, don't use ulem +%% +%% +%%input{decls} +%% +%%title{Howto write \surflets} +%%author{Andreas Bernauer} +%% +%%begin{document} +%%maketitle +%% +%%tableofcontents +%%sloppy \section{Introduction} -This report gives a short introduction in how to write a \surflet. It +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 @@ -52,7 +52,7 @@ website and use them to read out the user input. The following sections probably assume that you have basic knowledge of the SUnet webserver and scsh. The environment variable -\code{\$sunet} refers to the top level directory of your sunet +\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} @@ -63,7 +63,7 @@ the ability to serve \surflets. This section tells you how to do it. \begin{enumerate} \item You need Oleg's SSAX package (for scsh), to be able to use -\surflets: +surflets: \begin{itemize} \item Download Oleg's SSAX package from @@ -71,14 +71,14 @@ the ability to serve \surflets. This section tells you how to do it. \item Uncompress and untar it to any directory. This will create a directory called \name{SSAX}, to which I will refer to as - \code{\$SSAX}. + \typew{\$SSAX}. \item Unfortunately, this distribution (plt200-4.9) has a typo in the package definition for scsh. Apply the patch that comes with the \surflets distribution to get rid of this typo: \begin{itemize} - \item \code{cd \$SSAX} - \item \code{patch -p1 < \$sunet/httpd/surflets/SSAX-goodhtml-patch} + \item \typew{cd \$SSAX} + \item \typew{patch -p1 < \$sunet/httpd/surflets/SSAX-goodhtml-patch} \end{itemize} \end{itemize} @@ -87,8 +87,8 @@ the ability to serve \surflets. This section tells you how to do it. does this for you: \begin{itemize} - \item \code{cd \$sunet/httpd/surflets} - \item \code{SSAX=\$SSAX ./start-surflet-server} + \item \typew{cd \$sunet/httpd/surflets} + \item \typew{SSAX=\$SSAX ./start-surflet-server} \end{itemize} @@ -136,7 +136,7 @@ Error: 98 In this case, pass another port number to the script, \eg 8000: \codex{ssax=\$SSAX ./start-surflet-server -p 8000} -The \code{--help} option will show you more parameters that you can +The \typew{--help} option will show you more parameters that you can adjust, but you won't need them for this howto. \end{enumerate} @@ -237,17 +237,17 @@ SXML list are the contents that are enclosed by this HTML tag. The contents can be other SXML list, too. Here are some examples of SXML lists and how they translate to HTML: -\newcommand{\tag}[1]{$\mathtt{<}$#1$\mathtt{>}$} +\newcommand{\htmltag}[1]{$\mathtt{<}$#1$\mathtt{>}$} \begin{tabbing} HTML: \medskip\=\kill SXML: \> \texttt{'(p "A paragraph.")} \\ -HTML: \> \texttt{\tag{p}A paragraph.\tag{/p}}\\ +HTML: \> \texttt{\htmltag{p}A paragraph.\htmltag{/p}}\\ \\ SXML: \> \texttt{'(p "A paragraph." (br) "With break line.")} \\ -HTML: \> \texttt{\tag{p}A paragraph.\tag{br}With break line.\tag{/p}}\\ +HTML: \> \texttt{\htmltag{p}A paragraph.\htmltag{br}With break line.\htmltag{/p}}\\ \\ SXML: \> \texttt{'(p "Nested" (p "paragraphs"))}\\ -HTML: \> \texttt{\tag{p}Nested\tag{p}paragraphs\tag{/p}\tag{/p}}\\ +HTML: \> \texttt{\htmltag{p}Nested\htmltag{p}paragraphs\htmltag{/p}\htmltag{/p}}\\ \end{tabbing} Attributes are stated by a special list whose first element is the @@ -256,12 +256,12 @@ at-symbol. The attribute list must be the second element in the list: \begin{tabbing} HTML: \medskip\=\kill SXML: \> \texttt{'(a (@ (href "attr.html")) "Attributed HTML tags.")} \\ -HTML: \> \texttt{\tag{a href="attr.html"}Attributed HTML tags.\tag{/a}}\\ +HTML: \> \texttt{\htmltag{a href="attr.html"}Attributed HTML tags.\htmltag{/a}}\\ \\ SXML: \> \texttt{'(a (@ (href "attr2.html") (target "\_blank")) "2 attributes.")} \\ -HTML: \> \texttt{\tag{a href="attr2.html" target="\_blank"}2 -attributes.\tag{/a}} +HTML: \> \texttt{\htmltag{a href="attr2.html" target="\_blank"}2 +attributes.\htmltag{/a}} \end{tabbing} As you see from the \surflet example, \name{send-html/finish} expects @@ -275,9 +275,9 @@ following HTML code: Please note, that there is no check for valid HTML or even XHTML here. The only thing the translation process takes care of are -special characters in strings like the ampersand (\code{\&}). The +special characters in strings like the ampersand (\typew{\&}). The translation process replaces them by their HTML representation (\eg, -\code{\&}) so you don't have to worry about that when you use +\typew{\&}) so you don't have to worry about that when you use strings. Everything else like using valid HTML tags or valid attributes is your responsibility. @@ -306,15 +306,15 @@ can be done like this: This \surflet can be found in \name{howto/hello-date.scm}. The beginning of this \surflet is the same as in the previous example. The difference lies in the argument to \name{send-html/finish}. Note -that the argument starts with a backquote (\code{`}) rather than with -a regular quote (\code{'}) as in the previous example. +that the argument starts with a backquote (\typew{`}) rather than with +a regular quote (\typew{'}) as in the previous example. Instead of passing a ``static'' list, \ie a list whose contents are given before execution, this \surflet uses the quasiquote and unquote feature of Scheme to create a ``dynamic'' list, \ie list whose contents are given only during execution. A ``dynamic'' list is -introduced by a backquote (\code{`}) and its dynamic contents are -noted by commata (\code{,}). Thus, if the \surflet is executed while +introduced by a backquote (\typew{`}) and its dynamic contents are +noted by commata (\typew{,}). Thus, if the \surflet is executed while I am writing this howto, the argument to \name{send-html/finish} above is translated to @@ -394,7 +394,7 @@ session automatically as described in the previous paragraph. %, \ie it starts the session automatically when an %instance of your \surflet starts and takes care of the saving and %restoring of all variable values during suspensions of your \surflet -%instance, except for \code{set!}ed values. +%instance, except for \typew{set!}ed values. The only thing you have to worry about is when your session \emph{ends}. As long as your session hasn't been finished by @@ -430,9 +430,9 @@ snippets are equivalent: \name{url} expects the target address as the next element and includes every text afterwards as part of the link. -There are also some other abbreviations. \code{(nbsp)} inserts -`\code{\ }' into the HTML, \code{(*COMMENT* \dots)} inserts a -comment, and with \code{(plain-html \dots)} you can insert arbitrary +There are also some other abbreviations. \typew{(nbsp)} inserts +`\typew{\ }' into the HTML, \typew{(*COMMENT* \dots)} inserts a +comment, and with \typew{(plain-html \dots)} you can insert arbitrary HTML code (\ie strings) directly , without any string conversions. The last abbreviation, \name{surflet-form}, is discussed in the next section. @@ -538,7 +538,9 @@ add the symbol \name{'POST} after the URL: \end{alltt} The web page \name{send-html/suspend} sends to the browser looks like -in figure \ref{fig:user1-1}. After the user has entered his data into +in figure [missing] +%\ref{fig:user1-1}. +After the user has entered his data into the web form, \name{send-html/suspend} returns with the request object of the browser for the next page. This request object contains the data the user has entered. @@ -550,7 +552,7 @@ data the user has entered. With the function \name{get-bindings} we pull out the user data of the request object. Here we save the user data into the variable \name{bindings}. \name{get-bindings} works for both request methods -\code{GET} and \code{POST}. +\typew{GET} and \typew{POST}. \begin{alltt} (user-input (input-field-value text-input bindings))) diff --git a/doc/latex/surflets.tex b/doc/latex/surflets.tex new file mode 100644 index 0000000..577675f --- /dev/null +++ b/doc/latex/surflets.tex @@ -0,0 +1,11 @@ +\chapter{SUrflet server} + +\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 +can copy freely. + +\input{surflethowto} diff --git a/scheme/httpd/surflets/decls.tex b/scheme/httpd/surflets/decls.tex deleted file mode 100644 index d7335d4..0000000 --- a/scheme/httpd/surflets/decls.tex +++ /dev/null @@ -1,73 +0,0 @@ - -\makeatletter - -\def\surflet{SUrflet\xspace} -\def\surflets{SUrflets\xspace} -\def\scsh{scsh\xspace} -\def\sunet{SUnet\xspace} - -%From sunet/decls.tex -\def\ie{\mbox{\emph{i.e.}\xspace}} % \mbox keeps the last period from -\def\Ie{\mbox{\emph{I.e.}\xspace}} % looking like an end-of-sentence. -\def\eg{\mbox{\emph{e.g.}\xspace}} -\def\Eg{\mbox{\emph{E.g.}\xspace}} - -%From surflet/decls.tex -{\theoremstyle{break} -\theoremheaderfont{\normalfont\bfseries\em} - \newtheorem{proglist}{Listing}[section]} -\setlength{\theorempreskipamount}{1.5ex plus0.2ex minus0.2ex} -\setlength{\theorempostskipamount}{2ex plus0.5ex minus0.2ex} - -% These environments differ from the other definition by the -% positioning of \normalem -\newenvironment{listing} - {\ULforem\begin{proglist}\begin{alltt}\small\normalem} - {\end{alltt}\end{proglist}} - -\newenvironment{reflisting}[1] - {\ULforem\begin{proglist}[\refinlisting{#1}]\begin{alltt}\small\normalem} - {\end{alltt}\end{proglist}} - -\newcommand{\contatlisting}[1]{% -{\normalfont\textit{$<$wird fortgesetzt in Listing~\ref{#1}\/$>$}}} -\newcommand{\contfromlisting}[1]{% -{\normalfont\textit{$<$fortgesetzt von Listing~\ref{#1}\/$>$}}} -\newcommand{\refinlisting}[1]{% -{\normalfont\textit{referenziert in Listing~\ref{#1}}}} -\newcommand{\seelisting}[1]{% -{\normalfont{\textit{$<$siehe Listing~\ref{#1}\/$>$}}}} - -\newfloat{program}{t}{lop} -\floatname{program}{Programm} -\newenvironment{floatprog}[2] - {\begin{program}[ht] \caption{#1} \label{#2} \begin{alltt}} - {\end{alltt} \end{program}% - % Force output of even long floating figs - \afterpage{\clearpage}} - -% stolen from sunet/doc/latex/decls.tex (Olin) -\newenvironment{leftinset} - {\bgroup\parskip=1ex plus 1ex\begin{list}{}% - {\topsep=0pt}% - \item[]}% - {\end{list}\leavevmode\egroup\global\@ignoretrue} -%\newcommand{\code}[1]{{\normalfont\texttt{\ttchars #1}}} -\newcommand{\code}[1]{\frenchspacing\texttt{#1}} -\newcommand{\codex}[1]{\begin{leftinset}\code{#1}\end{leftinset}\ignorespaces} - -% Use url-package to get function names line-breaked at - / + -% by infos in /usr/share/texmf/tex/latex/misc/url.sty -\newcommand\breakfuntt{\begingroup \urlstyle{tt}% -\@ifundefined{selectfont}{\def\UrlFont{\tt}}{\def\UrlFont{\ttfamily}}% -\def\UrlBreaks{\do\-\do\/\do\+}\def\UrlNoBreaks{\do\!}\Url -} - -\newcommand{\name}[1]{\breakfuntt{#1}} -\newcommand{\object}[1]{\breakfuntt{#1}} -\newcommand{\file}[1]{\breakfuntt{#1}} -\def\sharpf{\textnormal{\texttt{\#f}}} -\def\sharpt{\textnormal{\texttt{\#t}}} -\newcommand{\codemph}[1]{\emph{#1}} - -\makeatother