Move SUrflet howto into main documentation.

Merge 2 decls.tex together.
Drawback: can't use url package anymore.

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

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}

doc/latex/surflethowto.tex

@@ -1,27 +1,27 @@
-\documentclass{article}
+%%documentclass{article}
-
+%%
-\usepackage[latin1]{inputenc}
+%%usepackage[latin1]{inputenc}
-\usepackage{fontenc}
+%%usepackage{fontenc}
-\usepackage{alltt}
+%%usepackage{alltt}
-\usepackage{url,xspace}
+%%usepackage{url,xspace}
-\usepackage{tabularx}
+%%usepackage{tabularx}
-\usepackage{theorem,ulem,float,afterpage}
+%%usepackage{theorem,ulem,float,afterpage}
-\normalem			%usually, don't use ulem
+%%normalem			%usually, don't use ulem
-
+%%
-
+%%
-\input{decls}
+%%input{decls}
-
+%%
-\title{Howto write \surflets}
+%%title{Howto write \surflets}
-\author{Andreas Bernauer}
+%%author{Andreas Bernauer}
-
+%%
-\begin{document}
+%%begin{document}
-\maketitle
+%%maketitle
-
+%%
-\tableofcontents
+%%tableofcontents
-\sloppy
+%%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 \typew{cd \$SSAX}
-      \item \code{patch -p1 < \$sunet/httpd/surflets/SSAX-goodhtml-patch}
+      \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 \typew{cd \$sunet/httpd/surflets}
-  \item \code{SSAX=\$SSAX ./start-surflet-server}
+  \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
+HTML: \> \texttt{\htmltag{a href="attr2.html" target="\_blank"}2
-attributes.\tag{/a}}
+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
+that the argument starts with a backquote (\typew{`}) rather than with
-a regular quote (\code{'}) as in the previous example.
+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
+introduced by a backquote (\typew{`}) and its dynamic contents are
-noted by commata (\code{,}).  Thus, if the \surflet is executed while
+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
+There are also some other abbreviations.  \typew{(nbsp)} inserts
-`\code{\&nbsp;}' into the HTML, \code{(*COMMENT* \dots)} inserts a
+`\typew{\&nbsp;}' into the HTML, \typew{(*COMMENT* \dots)} inserts a
-comment, and with \code{(plain-html \dots)} you can insert arbitrary
+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)))

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}

scheme/httpd/surflets/decls.tex

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