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

Various reorganizations. 

Convert to report document class.
This commit is contained in:
sperber 2002-08-21 14:52:34 +00:00
parent ed74bc29c1
commit bb4d6c43a9
16 changed files with 193 additions and 266 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/latex/cgi-script.tex
View File

@ -1,11 +1,11 @@
\section{CGI scripts}\label{sec:cgi-scripts}
\chapter{CGI scripts}\label{cha:cgi-scripts}
%
\begin{description}
\item[Used files:] cgi-script.scm
\item[Name of the package:] cgi-script
\end{description}
%
\subsection{Procedures}
\section{Procedures}
\begin{defundesc}{cgi-form-query}{}{data-alist}
CGI scripts receive their parameters in various ways, depending on

42
doc/latex/cgi-server.tex
View File

@ -1,42 +0,0 @@
\section{CGI server}\label{sec:cgi-server}
%
\begin{description}
\item[Used files:] cgi-server.scm
\item[Name of the package:] cgi-server
\end{description}
%
\subsection{Procedures}
\begin{defundesc}{cgi-handler}{bin-dir \ovar{cgi-bin-dir}}{path-handler}
Returns a path handler (see \ref{httpd:path-handlers} for details
about path handlers) for cgi-scripts located in
\semvar{bin-dir}. \semvar{cgi-bin-dir} specifies the value of the
\ex{PATH} variable of the environment the cgi-scripts run in. It defaults
to
``\ex{/bin:\ob{}/usr/bin:\ob{}/usr/ucb:\ob{}/usr/bsd:\ob{}/usr/local/bin}''
but is overwritten by the current \ex{PATH} environment variable at
the time \ex{cgi-handler} ist called. The cgi-scripts are called as
specified by CGI/1.1\footnote{see
\ex{http://hoohoo.ncsa.uiuc.edu/cgi/interface.html} for a sort of
specification.}.
\begin{itemize}
\item Various environment variables are set (like
\ex{QUERY\_STRING} or \ex{REMOTE\_HOST}).
\item ISINDEX queries get their arguments as command line arguments.
\item Scripts are handled differently according to their name:
\begin{itemize}
\item If the name of the script starts with `\ex{nph-}', its reply
is read, the RFC~822-fields like ``Content-Type'' and ``Status''
are parsed and the client is sent back a real HTTP reply,
containing the rest of the script's output.
\item If the name of the script doesn't start with `\ex{nph-}',
its output is sent back to the client directly. If its return code
is not zero, an error message is generated.
\end{itemize}
\end{itemize}
\end{defundesc}

2
doc/latex/decls.tex
View File

@ -82,8 +82,6 @@
\newcommand{\note}[1]{\{Note #1\}}
\newcommand{\itum}[1]{\item{\bf #1}\\*}
% For use in code. The \llap magicness makes the lambda exactly as wide as
% the other chars in \tt; the \hskip shifts it right a bit so it doesn't
% crowd the left paren -- which is necessary if \tt is cmtt.

8
doc/latex/ftp.tex
View File

@ -1,10 +1,10 @@
\section{FTP client}\label{sec:ftp}
\chapter{FTP client}\label{cha:ftp}
\begin{description}
\item[Used files:] ftp.scm, ftp-obsolete.scm
\item[Name of the package:] ftp, ftp-obsolete
\end{description}
\subsection{What users want to know}
\section{What users want to know}
This module lets you transfer files between networked machines from
the Scheme Shell, using the File Transfer Protocol as described in
RFC~959. The protocol specifies the behaviour of a server machine,
@ -191,9 +191,9 @@ The following rfc959 commands are not implemented:
\ex{ALLO} & allocate space on server \\
\end{tabular}
\subsection{What programmers want to know}
\section{What programmers want to know}
\subsection*{Overview}
\section{Overview}
Communication is initiated by the client. The server responds to each
request with a three digit status code and an explanatory message, and
occasionally with data (which is sent via a separate, one-off

12
doc/latex/ftpd.tex
View File

@ -1,13 +1,13 @@
\section{FTP server}\label{sec:ftpd}
\chapter{FTP server}\label{cha:ftpd}
\begin{description}
\item[Used files:] ftpd.scm
\item[Name of the package:] ftpd
\end{description}
\subsection{What users want to know}
\section{What users want to know}
\subsubsection*{Entry points}
\section{Entry points}
\defun {ftpd} {anonymous-home \ovar{port \ovar{logfile}}} {\noreturn}
\begin{defundescx}{ftp-inetd} {anonymous-home} {\noreturn}
@ -115,7 +115,7 @@ the syslog-daemon):
Following events are logged as
\begin{description}
\item{\ex{NOTICE} level:}
\item[\ex{NOTICE} level:]
\begin{itemize}
\item Messages concerning \emph{connections} (establishing connection,
connection refused, closing connection due to timeout, etc.)
@ -128,10 +128,10 @@ Following events are logged as
\item Reaching of actually unreachable case branches
\end{itemize}
\item{\ex{INFO} level:} Messages concerning all \emph{other commands},
\item[\ex{INFO} level:] Messages concerning all \emph{other commands},
including the \ex{RETR} command.
\item{\ex{DEBUG} level:} All other messages, including debug messages.
\item[\ex{DEBUG} level:] All other messages, including debug messages.
If you want to debug ftpd, put all the messages in one single file,
since the debug-messages may refer to messages of other levels.
\end{description}

148
doc/latex/httpd.tex
View File

@ -1,72 +1,64 @@
\section{HTTP server}\label{sec:httpd}
\chapter{HTTP server}\label{cha:httpd}
%
\begin{description}
\item[Used files:] httpd/core.scm, httpd/handlers.scm, httpd/options.scm,
\item[Name of the packages:] httpd-core, httpd-basic-handler, httpd-make-options
\end{description}
There are also some other files and packages that are used internally.
%
%
\subsection{Introduction}
The \Scheme underground Web system is a package of \Scheme code
that provides utilities for interacting with the World-Wide Web.
This includes:
The SUnet web system is a collection of packages of \Scheme code that
provides utilities for interacting with the World-Wide Web. This
includes:
\begin{itemize}
\item A Web server.
\item URI and URL parsers and un-parsers (see sections \ref{sec:uri}
and \ref{sec:url}).
\item RFC822-style header parsers (see section \ref{sec:rfc822}).
\item URI and URL parsers and un-parsers (see Chapters \ref{cha:uri}
and \ref{cha:url}).
\item RFC822-style header parsers (see Chapter \ref{cha:rfc822}).
\item Code for performing structured html output
\item Code to assist in writing CGI \Scheme programs that can be used by
any CGI-compliant HTTP server (such as NCSA's httpd, or the S.U.
any CGI-compliant HTTP server (such as NCSA's httpd, or the SUnet
Web server).
\end{itemize}
The code can be obtained via anonymous
ftp\footnote{\ttt{}ftp://ftp-swiss.ai.mit.edu/pub/scsh/contrib/net/net.tar.gz}
and is implemented in \scm, using the system calls and support
procedures of scsh, the \Scheme Shell. The code was written to be
clear and modifiable -- it is voluminously commented and all non-\RnRS
dependencies are described at the beginning of each source file.
\FIXME{We should remove the note to read the source files and insert
the essentials here instead.}
I do not have the time to write detailed documentation for these
packages. However, they are very thoroughly commented, and I strongly
recommend reading the source files; they were written to be read, and
the source code comments should provide a clear description of the
system. The remainder of this note gives an overview of the server's
basic architecture and interfaces.
\subsection{The Scheme Underground Web Server}
The server was designed with three principle goals in mind:
The server has three main design goals:
\begin{description}
\item{Extensibility} \\
The server is designed to make it easy to extend the basic
functionality. In fact, the server is nothing but extensions. There
is no distinction between the set of basic services provided by the
server implementation and user extensions -- they are both
implemented in Scheme, and have equal status. The design is ``turtles
all the way down''.
\item[Extensibility]
The server is in fact nothing but extensions, using a mechanism
called ``path handlers'' to define URL-specific services. It has a
toolkit of services that can be used as-is, extended or built
upon. User extensions have exactly the same status as the base
services.
\item{Mobile code} \\
Because the server is written in \scm, it is simple to use the \scm
module system to upload programs to the server for safe execution
within a protected, server-chosen environment. The server comes with
a simple example upload service to demonstrate this capability.
The extension mechanism allows for easy implementation of new
services without the overhead of the CGI interface. Since the
server is written on top of the Scheme shell, the full set of Unix
system calls and program tools is available to the implementor.
\item{Clarity of implementation} \\
Because the server is written in a high-level language, it should
make for a clearer exposition of the HTTP protocol and the
associated URL and URI notations than one written in a low-level
language such as C. This also should help to make the server easy to
modify and adapt to different uses.
\end{description}
\item[Mobile code]
The server allows Scheme code to be uploaded for direct execution
inside the server. The server has complete control over the code,
and can safely execute it in restricted environments that do not
provide access to potentially dangerous primitives (such as the
``delete file'' procedure.)
\subsubsection*{Basic server structure}
\item[Clarity]
I\footnote{That's Olin Shivers (\ex{shivers@ai.mit.edu},
\ex{http://www.\ob{}ai.\ob{}mit.\ob{}edu/\ob{}people/\ob{}shivers/}).
For the rest of the documentation, if not mentioned otherwise,
`I' refers to him.} wrote this server to help myself understand
the Web. It is voluminously commented, and I hope it will prove to
be an aid in understanding the low-level details of the Web
protocols.
The SUnet web server has the ability to upload code from Web clients
and execute that code on behalf of the client in a protected
environment.
Some simple documentation on the server is available.
\end{description}
\section{Basic server structure}
The Web server is started by calling the httpd procedure, which takes
one argument, a \ex{httpd\=options}-record:
@ -93,7 +85,7 @@ one argument, a \ex{httpd\=options}-record:
handled in a reasonable and robust fashion.
The basic server loop, and the associated request data structure are
the fixed architecture of the S.U. Web server; its flexibility lies
the fixed architecture of the SUnet Web server; its flexibility lies
in the notion of path handlers.
\end{desc}
@ -183,7 +175,7 @@ one argument, a \ex{httpd\=options}-record:
syslog messages (\sharpt) or not (\sharpf).
\end{desc}
\subsubsection*{Path handlers}
\section{Path handlers}
\label{httpd:path-handlers}
A path handler is a procedure taking two arguments:
@ -226,9 +218,9 @@ recursively, and doing I/O directly to the socket might bypass a
filtering or other processing step interposed on the current I/O ports
by some superior path handler.
\subsubsection*{Basic path handlers}
\section{Basic path handlers}
Although the user can write any path-handler he likes, the S.U. server
Although the user can write any path-handler he likes, the SUnet web server
comes with a useful toolbox of basic path handlers that can be used
and built upon (exported by the \ex{httpd\=basic\=handlers}-structure):
@ -366,10 +358,10 @@ Tag & Icon's file name \\
requests, always returning a ``404 Not found'' reply to the client.
\end{defundesc}
\subsection{HTTP errors}
\section{HTTP errors}
Authors of path-handlers need to be able to handle errors in a
reasonably simple fashion. The S.U. Web server provides a set of error
reasonably simple fashion. The SUnet Web server provides a set of error
conditions that correspond to the error replies in the HTTP protocol.
These errors can be raised with the \ex{http\=error} procedure. When
the server runs a path handler, it runs it in the context of an error
@ -400,7 +392,7 @@ and closes the transaction.
transaction.
\end{defundesc}
\subsection{Simple directory generation}
\section{Simple directory generation}
Most path-handlers that serve files to clients eventually call an
internal procedure named \ex{file\=serve}, which implements a simple
@ -422,7 +414,43 @@ directory-generation service using the following rules:
client.
\end{itemize}
\subsection{Support procs}
\section{CGI Server}
\begin{defundesc}{cgi-handler}{bin-dir \ovar{cgi-bin-dir}}{path-handler}
Returns a path handler (see \ref{httpd:path-handlers} for details
about path handlers) for cgi-scripts located in
\semvar{bin-dir}. \semvar{cgi-bin-dir} specifies the value of the
\ex{PATH} variable of the environment the cgi-scripts run in. It defaults
to
``\ex{/bin:\ob{}/usr/bin:\ob{}/usr/ucb:\ob{}/usr/bsd:\ob{}/usr/local/bin}''
but is overwritten by the current \ex{PATH} environment variable at
the time \ex{cgi-handler} ist called. The cgi-scripts are called as
specified by CGI/1.1\footnote{see
\ex{http://hoohoo.ncsa.uiuc.edu/cgi/interface.html} for a sort of
specification.}.
\begin{itemize}
\item Various environment variables are set (like
\ex{QUERY\_STRING} or \ex{REMOTE\_HOST}).
\item ISINDEX queries get their arguments as command line arguments.
\item Scripts are handled differently according to their name:
\begin{itemize}
\item If the name of the script starts with `\ex{nph-}', its reply
is read, the RFC~822-fields like ``Content-Type'' and ``Status''
are parsed and the client is sent back a real HTTP reply,
containing the rest of the script's output.
\item If the name of the script doesn't start with `\ex{nph-}',
its output is sent back to the client directly. If its return code
is not zero, an error message is generated.
\end{itemize}
\end{itemize}
\end{defundesc}
\section{Support procs}
The source files contain a host of support procedures which will be of
utility to anyone writing a custom path-handler. Read the files first.
@ -430,5 +458,5 @@ utility to anyone writing a custom path-handler. Read the files first.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: man.tex
%%% TeX-master: "man"
%%% End:

108
doc/latex/intro.tex
View File

@ -1,21 +1,21 @@
\section{Overview}\label{sec:intro}
\subsection{What's in sunet?}
\chapter{Overview}\label{sec:intro}
\section{What's in sunet?}
The Scheme Underground Network Package contains a set of libraries for
doing Net hacking from Scheme/scsh. It includes:
\begin{description}
\item{An smtp client library.}\\
\item[SMTP client library]
Forge mail from the comfort of your own Scheme process.
\item{rfc822 header library}\\
\item[RFC822 header library]
Read email-style headers. Useful in several contexts (smtp, http,
etc.)
\item{Simple structured HTML output library} \\
\item[Simple structured HTML output library]
Balanced delimiters, etc.
\item{The SU Web server}\\
\item[The SUnet Web server]
This is a complete implementation of an HTTP 1.0 server in Scheme.
The server contains other standalone packages that may separately be
of use:
@ -25,56 +25,21 @@ doing Net hacking from Scheme/scsh. It includes:
\item Server extensions for interfacing to CGI scripts.
\item Server extensions for uploading Scheme code.
\end{itemize}
The server has three main design goals:
\begin{description}
\item{Extensibility}\\
The server is in fact nothing but extensions, using a mechanism
called ``path handlers'' to define URL-specific services. It has a
toolkit of services that can be used as-is, extended or built
upon. User extensions have exactly the same status as the base
services.
The extension mechanism allows for easy implementation of new
services without the overhead of the CGI interface. Since the
server is written on top of the Scheme shell, the full set of Unix
system calls and program tools is available to the implementor.
\item{Mobile code}\\
The server allows Scheme code to be uploaded for direct execution
inside the server. The server has complete control over the code,
and can safely execute it in restricted environments that do not
provide access to potentially dangerous primitives (such as the
``delete file'' procedure.)
\item{Clarity}\\
I\footnote{That's Olin Shivers (\ex{shivers@ai.mit.edu},
\ex{http://www.\ob{}ai.\ob{}mit.\ob{}edu/\ob{}people/\ob{}shivers/}).
For the rest of the documentation, if not mentioned otherwise,
`I' refers to him.} wrote this server to help myself understand
the Web. It is voluminously commented, and I hope it will prove to
be an aid in understanding the low-level details of the Web
protocols.
The S.U. server has the ability to upload code from Web clients
and execute that code on behalf of the client in a protected
environment.
Some simple documentation on the server is available.
\end{description}
\end{description}
%
\section{Obtaining the system}
\subsection{Obtaining the system}
The network code is available
\urlhd{http://www.scsh.net/sunet/}{here}{from
\url{http://www.scsh.net/sunet/}}.
To run the server, you
need version 0.6.3 or later of \urlhd{http://www.scsh.net/}{scsh}{scsh
from \url{http://www.scsh.net/}}.
Beyond actually running the server, the separate parser libraries and
other utilites may be of use as separate modules.
The network code is available by
ftp\footnote{\ex{ftp://ftp-swiss.ai.mit.edu/pub/scsh/contrib/net/net.tar.gz}}.
To run the server, you need our 0.6 release of
scsh\footnote{http://www.scsh.net}. Beyond actually running the
server, the separate parser libraries and other utilites may be of use
as separate modules.
The sunet package contains following parts:
The SUnet package contains following parts:
%
\begin{itemize}
\item Several servers (HTTP, CGI, FTP)
@ -85,38 +50,17 @@ The sunet package contains following parts:
\item {\dots}
\end{itemize}
\subsection{What is in this docu?}
%
Unfortunately not all parts of sunet are documented here. If you miss
something, have a look in the source files -- they are alle well
documented (I hope so!).
\section{How to use the packages}
Currently the ftp server, the ftp client, the modules containing the
procedures handling URIs and URLs, the module handling RFC~822
headers, the netrc package, the save evaluation environment
\ex{toothless\=eval} and the obsolete library for using strings are
documented.
\subsection{How to use the modules}
%
% I think it is a good idea to tell the people how to use
% scsh / sunet as the docu of scsh does not really do this
% (as long as concerning my experience). Additionally, possible
% programmers should be introduced how to create own modules,
% including those in sunet.
%FIXME
\FIXME{Does anybody have a good idea how to tell newbies how to use
the packages? I do not feel capable enough for this.}
For the time being, it may help to look at the following. Scsh is started
in the sunet directory. Then, the description file of the modules is
loaded and the ftp-module is opened (to use a ftp client). After the
things are done, scsh is finished via the \verb|,exit| command.
Scsh is started in the SUnet top-level directory. Then, the
description file of the modules is loaded and the \texttt{ftp} module
is opened (to use a ftp client). After the things are done, scsh is
finished via the \verb|,exit| command.
\begin{alltt}
atari-2600[72] scsh-0.6
Welcome to scsh 0.6.0 (Chinese Democracy)
atari-2600[72] scsh-0.6.2
Welcome to scsh 0.6.2 (Gambit-C 4.0)
Type ,? for help.
> ,config ,load modules.scm
> ,config ,load packages.scm
modules.scm
> ,open ftp
Load structure ftp (y/n)? y
@ -130,5 +74,5 @@ atari-2600[73]
%%% Local Variables:
%%% mode: latex
%%% TeX-master: man
%%% TeX-master: "man"
%%% End:

3
doc/latex/man.tex
View File

@ -1,4 +1,4 @@
\documentclass{article}
\documentclass{report}
\usepackage[latin1]{inputenc}
\usepackage{alltt}
@ -25,7 +25,6 @@
\include{intro}
\include{httpd}
\include{toothless}
\include{cgi-server}
\include{cgi-script}
\include{ftpd}
\include{ftp}

12
doc/latex/netrc.tex
View File

@ -1,11 +1,11 @@
\section{Reading netrc-files}\label{sec:netrc}
\chapter{Reading netrc-files}\label{cha:netrc}
%
\begin{description}
\item[Used files:] netrc.scm
\item[Name of the package:] netrc
\end{description}
%
\subsection{Overview}
\section{Overview}
This module provides procedures to parse authentication information
contained in \ex{~/.netrc}.
@ -35,7 +35,7 @@ Note following restrictions and differences:
\subsection{Entry points}
\section{Entry points}
What you probably want, is to read out the default netrc-file. Do the
following:
@ -119,7 +119,7 @@ a default login / password if the machine is unknown.
is returned by \ex{netrc:\ob{}default\=password}.
\end{defundescx}
\subsection{Related work}
\section{Related work}
\begin{itemize}
\item Graham Barr has written a similar library for Perl, called
\ex{Netrc.pm}.
@ -127,7 +127,7 @@ a default login / password if the machine is unknown.
parses the user's netrc file.
\end{itemize}
\subsection{Desirable things}
\section{Desirable things}
\begin{itemize}
\item Remove restrictions (as stated in `\emph{Overview}') and behave like
\ex{/usr/\ob{}bin/\ob{}ftp} behaves
@ -138,5 +138,5 @@ a default login / password if the machine is unknown.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: man.tex
%%% TeX-master: "man"
%%% End:

2
doc/latex/nettime.tex
View File

@ -1,4 +1,4 @@
\section{Using Time and Daytime Protocol}\label{sec:ntp}
\chapter{Using Time and Daytime Protocol}\label{cha:ntp}
%
\begin{description}
\item[Used files:] nettime.scm nettime-obsolete.scm

10
doc/latex/pop3.tex
View File

@ -1,11 +1,11 @@
\section{Using POP3}\label{sec:pop3}
\section{Using POP3}\label{cha:pop3}
%
\begin{description}
\item[Used files:] pop3.scm pop3-obsolete.scm
\item[Name of the package:] pop3 pop3-obsolete.scm
\end{description}
%
\subsection{Overview}
\section{Overview}
The POP3 protocol allows access to email on a maildrop server. It is
often used in configurations where users connect from a client machine
@ -29,7 +29,7 @@ size of the messages waiting on the server, download selected messages
messages.
\subsection{Entry points}
\section{Entry points}
\begin{defundesc}{pop3-connect}{\ovar{host \ovar{logfile}}}{connection}
Connect to the maildrop server named \semvar{host}. Optionally log
@ -101,7 +101,7 @@ after the prefix `\ex{pop3-}'. This is now changed to a hyphen
names, use the \ex{pop3\=obsolete}-package that maps the old names to
the new ones.
\subsection{Related work}
\section{Related work}
\begin{itemize}
\item Emacs is distributed with a C program called \ex{movemail} which
@ -117,5 +117,5 @@ the new ones.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% TeX-master: "man"
%%% End:

14
doc/latex/rfc822.tex
View File

@ -1,13 +1,13 @@
\section{Handle RFC822 headers}\label{sec:rfc822}
\chapter{Handle RFC822 headers}\label{cha:rfc822}
%
\begin{description}
\item[Used files:] rfc822.scm
\item[Name of the package:] rfc822
\end{description}
%
\subsection{What users want to know}
\section{What users want to know}
\subsubsection*{A note on line-terminators}
\section{A note on line-terminators}
Line-terminating sequences are always a drag, because there's no
agreement on them -- the Net protocols and DOS use
carriage-return/line-feed (\ex{cr}/\ex{lf}); Unix uses \ex{lf}; the
@ -35,7 +35,7 @@ not the terminators get trimmed. However, your read-line procedure
must indicate the header-terminating empty line by returning \emph{either}
the empty string or the two-char string \ex{cr}/\ex{lf} (or the EOF object).
\subsubsection*{Description of the procedures}
\section{Description of the procedures}
\defun{read-rfc822-field} {\ovar{port}} {name body}
\begin{defundescx}{\%read-rfc822-field } {read-line port} {name body}
@ -43,7 +43,7 @@ the empty string or the two-char string \ex{cr}/\ex{lf} (or the EOF object).
Read one field from the port, and return two values:
\begin{description}
\item{\var{name}} Symbol such as \ex{'subject} or \ex{'to}. The
\item[\var{name}] Symbol such as \ex{'subject} or \ex{'to}. The
field name is converted to a symbol using the Scheme
implementation's preferred case. If the implementation reads
symbols in a case-sensitive fashion (e.g., scsh), lowercase is
@ -51,7 +51,7 @@ the empty string or the two-char string \ex{cr}/\ex{lf} (or the EOF object).
using \ex{eq?}. When printing these field names out, it looks best
if you capitalize them with \ex{(capitalize\=string (symbol->string field\=name))}.
\item{\var{body}} List of strings which are the field's body, e.g.
\item[\var{body}] List of strings which are the field's body, e.g.
(``shivers\discretionary{@}{}{@}lcs.mit.edu''). Each list element is one line from
the field's body, so if the field spreads out over three lines,
then the body is a list of three strings. The terminating
@ -156,7 +156,7 @@ RFC~822 headers:
a doing once a \ex{symbol->string} conversion of \ex{'a}.)
\end{defundesc}
\subsubsection*{Desireable functionalities}
\section{Desireable functionalities}
\begin{itemize}
\item Unfolding long lines.

50
doc/latex/smtp.tex
View File

@ -1,4 +1,4 @@
\section{Using SMTP}\label{sec:smtp}
\chapter{Using SMTP}\label{cha:smtp}
%
\begin{description}
\item[Used files:] smtp.scm
@ -6,11 +6,11 @@
\end{description}
%
\subsection{Philosophy}
\section{Philosophy}
SMTP protocol procedures tend to return two values:
\begin{description}
\item{\semvar{code}} The integer SMTP reply code returned by server for the transaction.
\item{\semvar{text}} A list of strings -- the text messages tagged by
\item[\semvar{code}] The integer SMTP reply code returned by server for the transaction.
\item[\semvar{text}] A list of strings -- the text messages tagged by
the code.
\end{description}
@ -21,16 +21,16 @@ are not part of the official SMTP spec. This module uses codes $>=
600$ to indicate extra-protocol errors. There are two of these:
\begin{description}
\item{600 Server reply could not be parsed.}
\item[600 Server reply could not be parsed.]
The server sent back some sort of incomprehensible garbage reply.
\item{621 Premature EOF while reading server reply.}
\item[621 Premature EOF while reading server reply.]
The server shut down in the middle of a reply.
\end{description}
A list of the official protocol return codes can be seen in table
\ref{smtp-reply-codes}.
\subsection{Procedures}
\section{Procedures}
\begin{defundesc}{sendmail}{to-list body \ovar{host}}{code text-list}
Mail message \semvar{body} to recipients in list \semvar{to-list}.
@ -152,8 +152,8 @@ A list of the official protocol return codes can be seen in table
\begin{defundesc}{read-smtp-reply}{port}{code text-list}
Read a reply from the SMTP server. Returns two values:
\begin{description}
\item{\semvar{code}} Integer. The reply code.
\item{\semvar{text}} String list. A list of the text lines comprising
\item[\semvar{code}] Integer. The reply code.
\item[\semvar{text}] String list. A list of the text lines comprising
the reply. Each line of text is stripped of the initial
reply-code numerals (e.g., the first four chars of the reply),
and the trailing cr/lf. We are in fact generous about what we
@ -167,10 +167,10 @@ A list of the official protocol return codes can be seen in table
\begin{defundesc}{parse-smtp-reply}{line}{code rest more?}
Parse a line of SMTP reply. Return three values:
\begin{description}
\item{\semvar{code}} integer -- the reply code that prefixes the
\item[\semvar{code}] integer -- the reply code that prefixes the
string.
\item{\semvar{rest}} string -- the rest of the line.
\item{\semvar{more?}} boolean -- is there more reply to read (i.e.,
\item[\semvar{rest}] string -- the rest of the line.
\item[\semvar{more?}] boolean -- is there more reply to read (i.e.,
was the numeric reply code terminated by a ``\ex{-}'' character?)
\end{description}
\end{defundesc}
@ -193,14 +193,14 @@ A list of the official protocol return codes can be seen in table
call to \ex{smtp\=stuff}.
\end{defundesc}
\subsection{Additional information about SMTP}
\section{Additional information about SMTP}
\subsubsection*{Reply codes}
\section{Reply codes}
This material is taken from the RFC. The first digits encode categories
of responses:
\begin{description}
\item{\bfseries 1yz Positive Preliminary reply\,} The command has been
\item[1yz Positive Preliminary reply\,] The command has been
accepted, but the requested action is being held in abeyance,
pending confirmation of the information in this reply. The
sender-SMTP should send another command specifying whether to
@ -209,14 +209,14 @@ of responses:
Note: SMTP does not have any commands that allow this type of reply,
and so does not have the continue or abort commands.
\end{leftinset}
\item{\bfseries 2yz Positive Completion reply\,} The requested action has
\item[2yz Positive Completion reply\,] The requested action has
been successfully completed. A new request may be initiated.
\item{\bfseries 3yz Positive Intermediate reply\,} The command has been
\item[3yz Positive Intermediate reply\,] The command has been
accepted, but the requested action is being held in abeyance,
pending receipt of further information. The sender-SMTP should send
another command specifying this information. This reply is used in
command sequence groups.
\item{\bfseries 4yz Transient Negative Completion reply\,} The command was
\item[4yz Transient Negative Completion reply\,] The command was
not accepted and the requested action did not occur. However, the
error condition is temporary and the action may be requested again.
The sender should return to the beginning of the command sequence
@ -229,7 +229,7 @@ of responses:
without any change in command form or in properties of the sender or
receiver. (E.g., the command is repeated identically and the
receiver does not put up a new implementation.)
\item{\bfseries 5yz Permanent Negative Completion reply\,} The command was
\item[5yz Permanent Negative Completion reply\,] The command was
not accepted and the requested action did not occur. The
sender-SMTP is discouraged from repeating the exact request (in the
same sequence). Even some ``permanent'' error conditions can be
@ -241,16 +241,16 @@ of responses:
The second digit encodes responses in specific categories:
\begin{description}
\item{\bfseries x0z Syntax\,} These replies refer to syntax errors,
\item[x0z Syntax\,] These replies refer to syntax errors,
syntactically correct commands that don't fit any functional
category, and unimplemented or superfluous commands.
\item{\bfseries x1z Information\,} These are replies to requests for
\item[x1z Information\,] These are replies to requests for
information, such as status or help.
\item{\bfseries x2z Connections\,} These are replies referring to the
\item[x2z Connections\,] These are replies referring to the
transmission channel.
\item{\bfseries x3z\,} Unspecified as yet.
\item{\bfseries x4z\,} Unspecified as yet.
\item{\bfseries x5z Mail system\,} These replies indicate the status of the
\item[x3z\,] Unspecified as yet.
\item[x4z\,] Unspecified as yet.
\item[x5z Mail system\,] These replies indicate the status of the
receiver mail system vis-a-vis the requested transfer or other mail
system action.
\end{description}

10
doc/latex/toothless.tex
View File

@ -1,4 +1,4 @@
\section{Evaluating expression in ``safe'' environments}
\chapter{Evaluating expression in ``safe'' environments}
%
\begin{description}
\item[Used files:] none, defined in modules.scm
@ -7,20 +7,20 @@
\end{description}
%
\subsection{Overview}
\section{Overview}
\FIXME{Is toothless really R5RS, too?}
These modules define an environment that is \RnRS without features that
could examine or effect the file system. You can also use it as a
model of how to execute code in other protected environments in \scm.
\subsection{The \protect{\texttt{loser}} package}
\section{The \protect{\texttt{loser}} package}
The \ex{loser} package exports only one procedure:
\begin{defundesc}{loser}{name}{nothing}
Raises an error like ``Illegal call \var{name}''.
\end{defundesc}
\subsection{The \protect{\texttt{toothless}} package}
\section{The \protect{\texttt{toothless}} package}
The \ex{toothless} package contains everything of \RnRS except
that following procedure cause an error if called:
\begin{itemize}
@ -40,7 +40,7 @@ that following procedure cause an error if called:
So, \ex{toothless} creates an environment as described in
\emph{Overview} above.
\subsection{The \protect{\texttt{toothless-eval}} package}
\section{The \protect{\texttt{toothless-eval}} package}
\begin{defundesc}{eval-safely} {expression} {any result}
Creates a brand new package, imports the \ex{toothless} structure,

10
doc/latex/uri.tex
View File

@ -1,4 +1,4 @@
\section{Handle URIs}\label{sec:uri}
\chapter{Handle URIs}\label{cha:uri}
%
\begin{description}
\item[Used files:] uri.scm
@ -6,7 +6,7 @@
\end{description}
%
\subsection{Overview}
\section{Overview}
A URI (Uniform Resource Identifier) is of following syntax:
\begin{inset}
\ovar{scheme\/} : \semvar{path} \ovar{{\normalfont?\/} search} \ovar{{\normalfont\#} fragmentid}
@ -25,7 +25,7 @@ number refers to the (US) ASCII code of the escaped character, e.g.\
character 97). This module provides procedures to escape and unescape
strings that are meant to be used in a URI.
\subsection{Procedures}
\section{Procedures}
\begin{defundesc}{parse-uri} {uri-string } {scheme path search
frag-id} \label{proc:parse-uri}
@ -188,7 +188,7 @@ Perhaps I find it out later.}
\codex{\sharpf ; tries to back up root}
\end{defundesc}
\subsection*{Unexported names}
\section{Unexported names}
\defvar{uri-reserved}{char-set}
\begin{desc}
@ -223,5 +223,5 @@ Perhaps I find it out later.}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: man.tex
%%% TeX-master: "man"
%%% End:

16
doc/latex/url.tex
View File

@ -1,15 +1,15 @@
\section{URL}\label{sec:url}
\chapter{URL}\label{cha:url}
%
\begin{description}
\item[Used files:] url.scm
\item[Name of the package:] url
\end{description}
%
\subsection{Overview}
\section{Overview}
This modules contains procedures to parse and unparse URLs. Till now,
only the parsing of http URLs is implemented.
\subsection{Entry points}
\section{Entry points}
\defun{make-userhost}{user password host port}{userhost-record}
\defunx{userhost?}{thing}{boolean}
\defunx{userhost:user}{userhost-record}{value}
@ -68,8 +68,8 @@ only the parsing of http URLs is implemented.
"foo\%20bar:se\%20ret@www.scsh.net:80"
\end{alltt}
For details about escaping and unescaping see section ``Handle
URIs'' at page \pageref{sec:uri}.
For details about escaping and unescaping see Chapter ``Handle
URIs'' at page \pageref{cha:uri}.
\end{defundescx}
@ -93,8 +93,8 @@ only the parsing of http URLs is implemented.
These elements are in raw, unescaped format. To convert them back to
a string, use \ex{(uri\=path\=list->path (map escape\=uri
pathlist))}. \semvar{search} and \semvar{frag\=id} are the last
two parts of the URL (see section \ref{sec:uri} on page
\pageref{sec:uri} about parts of an URI).
two parts of the URL (see Chapter \ref{cha:uri} on page
\pageref{cha:uri} about parts of an URI).
\ex{http\=url:userhost}, \ex{http\=url:path}, \ex{http\=url:search}
and \ex{http\=url:frag\=id} are the corresponding selectors,
@ -128,5 +128,5 @@ only the parsing of http URLs is implemented.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: man.tex
%%% TeX-master: "man"
%%% End: