scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Move SUrflet howto into main documentation. 

Merge 2 decls.tex together.
Drawback: can't use url package anymore.
This commit is contained in:
interp 2004-01-17 01:35:16 +00:00
parent 25e03fe5e4
commit 63d708b219
5 changed files with 125 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
doc/latex/decls.tex
View File

@ -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

3
doc/latex/man.tex
View File

@ -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}

100
scheme/httpd/surflets/howto.tex → doc/latex/surflethowto.tex
View File

@ -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{\&amp;}) so you don't have to worry about that when you use
\typew{\&amp;}) 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{\&nbsp;}' 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{\&nbsp;}' 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)))

11
doc/latex/surflets.tex Normal file
View File

@ -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}

73
scheme/httpd/surflets/decls.tex
View File

@ -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