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} \begin{description}
\item[Used files:] cgi-script.scm \item[Used files:] cgi-script.scm
\item[Name of the package:] cgi-script \item[Name of the package:] cgi-script
\end{description} \end{description}
% %
\subsection{Procedures} \section{Procedures}
\begin{defundesc}{cgi-form-query}{}{data-alist} \begin{defundesc}{cgi-form-query}{}{data-alist}
CGI scripts receive their parameters in various ways, depending on 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{\note}[1]{\{Note #1\}}
\newcommand{\itum}[1]{\item{\bf #1}\\*}
% For use in code. The \llap magicness makes the lambda exactly as wide as % 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 % 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. % 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} \begin{description}
\item[Used files:] ftp.scm, ftp-obsolete.scm \item[Used files:] ftp.scm, ftp-obsolete.scm
\item[Name of the package:] ftp, ftp-obsolete \item[Name of the package:] ftp, ftp-obsolete
\end{description} \end{description}
\subsection{What users want to know} \section{What users want to know}
This module lets you transfer files between networked machines from This module lets you transfer files between networked machines from
the Scheme Shell, using the File Transfer Protocol as described in the Scheme Shell, using the File Transfer Protocol as described in
RFC~959. The protocol specifies the behaviour of a server machine, 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 \\ \ex{ALLO} & allocate space on server \\
\end{tabular} \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 Communication is initiated by the client. The server responds to each
request with a three digit status code and an explanatory message, and request with a three digit status code and an explanatory message, and
occasionally with data (which is sent via a separate, one-off 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} \begin{description}
\item[Used files:] ftpd.scm \item[Used files:] ftpd.scm
\item[Name of the package:] ftpd \item[Name of the package:] ftpd
\end{description} \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} \defun {ftpd} {anonymous-home \ovar{port \ovar{logfile}}} {\noreturn}
\begin{defundescx}{ftp-inetd} {anonymous-home} {\noreturn} \begin{defundescx}{ftp-inetd} {anonymous-home} {\noreturn}
@ -115,7 +115,7 @@ the syslog-daemon):
Following events are logged as Following events are logged as
\begin{description} \begin{description}
\item{\ex{NOTICE} level:} \item[\ex{NOTICE} level:]
\begin{itemize} \begin{itemize}
\item Messages concerning \emph{connections} (establishing connection, \item Messages concerning \emph{connections} (establishing connection,
connection refused, closing connection due to timeout, etc.) connection refused, closing connection due to timeout, etc.)
@ -128,10 +128,10 @@ Following events are logged as
\item Reaching of actually unreachable case branches \item Reaching of actually unreachable case branches
\end{itemize} \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. 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, 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. since the debug-messages may refer to messages of other levels.
\end{description} \end{description}

144
doc/latex/httpd.tex
View File

@ -1,4 +1,4 @@
\section{HTTP server}\label{sec:httpd} \chapter{HTTP server}\label{cha:httpd}
% %
\begin{description} \begin{description}
\item[Used files:] httpd/core.scm, httpd/handlers.scm, httpd/options.scm, \item[Used files:] httpd/core.scm, httpd/handlers.scm, httpd/options.scm,
@ -7,66 +7,58 @@
There are also some other files and packages that are used internally. There are also some other files and packages that are used internally.
% %
\subsection{Introduction} The SUnet web system is a collection of packages of \Scheme code that
provides utilities for interacting with the World-Wide Web. This
The \Scheme underground Web system is a package of \Scheme code includes:
that provides utilities for interacting with the World-Wide Web.
This includes:
\begin{itemize} \begin{itemize}
\item A Web server. \item A Web server.
\item URI and URL parsers and un-parsers (see sections \ref{sec:uri} \item URI and URL parsers and un-parsers (see Chapters \ref{cha:uri}
and \ref{sec:url}). and \ref{cha:url}).
\item RFC822-style header parsers (see section \ref{sec:rfc822}). \item RFC822-style header parsers (see Chapter \ref{cha:rfc822}).
\item Code for performing structured html output \item Code for performing structured html output
\item Code to assist in writing CGI \Scheme programs that can be used by \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). Web server).
\end{itemize} \end{itemize}
The code can be obtained via anonymous The server has three main design goals:
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:
\begin{description} \begin{description}
\item{Extensibility} \\ \item[Extensibility]
The server is designed to make it easy to extend the basic The server is in fact nothing but extensions, using a mechanism
functionality. In fact, the server is nothing but extensions. There called ``path handlers'' to define URL-specific services. It has a
is no distinction between the set of basic services provided by the toolkit of services that can be used as-is, extended or built
server implementation and user extensions -- they are both upon. User extensions have exactly the same status as the base
implemented in Scheme, and have equal status. The design is ``turtles services.
all the way down''.
\item{Mobile code} \\ The extension mechanism allows for easy implementation of new
Because the server is written in \scm, it is simple to use the \scm services without the overhead of the CGI interface. Since the
module system to upload programs to the server for safe execution server is written on top of the Scheme shell, the full set of Unix
within a protected, server-chosen environment. The server comes with system calls and program tools is available to the implementor.
a simple example upload service to demonstrate this capability.
\item{Clarity of implementation} \\ \item[Mobile code]
Because the server is written in a high-level language, it should The server allows Scheme code to be uploaded for direct execution
make for a clearer exposition of the HTTP protocol and the inside the server. The server has complete control over the code,
associated URL and URI notations than one written in a low-level and can safely execute it in restricted environments that do not
language such as C. This also should help to make the server easy to provide access to potentially dangerous primitives (such as the
modify and adapt to different uses. ``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 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} \end{description}
\subsubsection*{Basic server structure} \section{Basic server structure}
The Web server is started by calling the httpd procedure, which takes The Web server is started by calling the httpd procedure, which takes
one argument, a \ex{httpd\=options}-record: 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. handled in a reasonable and robust fashion.
The basic server loop, and the associated request data structure are 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. in the notion of path handlers.
\end{desc} \end{desc}
@ -183,7 +175,7 @@ one argument, a \ex{httpd\=options}-record:
syslog messages (\sharpt) or not (\sharpf). syslog messages (\sharpt) or not (\sharpf).
\end{desc} \end{desc}
\subsubsection*{Path handlers} \section{Path handlers}
\label{httpd:path-handlers} \label{httpd:path-handlers}
A path handler is a procedure taking two arguments: 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 filtering or other processing step interposed on the current I/O ports
by some superior path handler. 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 comes with a useful toolbox of basic path handlers that can be used
and built upon (exported by the \ex{httpd\=basic\=handlers}-structure): 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. requests, always returning a ``404 Not found'' reply to the client.
\end{defundesc} \end{defundesc}
\subsection{HTTP errors} \section{HTTP errors}
Authors of path-handlers need to be able to handle errors in a 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. conditions that correspond to the error replies in the HTTP protocol.
These errors can be raised with the \ex{http\=error} procedure. When 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 the server runs a path handler, it runs it in the context of an error
@ -400,7 +392,7 @@ and closes the transaction.
transaction. transaction.
\end{defundesc} \end{defundesc}
\subsection{Simple directory generation} \section{Simple directory generation}
Most path-handlers that serve files to clients eventually call an Most path-handlers that serve files to clients eventually call an
internal procedure named \ex{file\=serve}, which implements a simple internal procedure named \ex{file\=serve}, which implements a simple
@ -422,7 +414,43 @@ directory-generation service using the following rules:
client. client.
\end{itemize} \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 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. 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: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: man.tex %%% TeX-master: "man"
%%% End: %%% End:

108
doc/latex/intro.tex
View File

@ -1,21 +1,21 @@
\section{Overview}\label{sec:intro} \chapter{Overview}\label{sec:intro}
\subsection{What's in sunet?} \section{What's in sunet?}
The Scheme Underground Network Package contains a set of libraries for The Scheme Underground Network Package contains a set of libraries for
doing Net hacking from Scheme/scsh. It includes: doing Net hacking from Scheme/scsh. It includes:
\begin{description} \begin{description}
\item{An smtp client library.}\\ \item[SMTP client library]
Forge mail from the comfort of your own Scheme process. 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, Read email-style headers. Useful in several contexts (smtp, http,
etc.) etc.)
\item{Simple structured HTML output library} \\ \item[Simple structured HTML output library]
Balanced delimiters, etc. 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. This is a complete implementation of an HTTP 1.0 server in Scheme.
The server contains other standalone packages that may separately be The server contains other standalone packages that may separately be
of use: 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 interfacing to CGI scripts.
\item Server extensions for uploading Scheme code. \item Server extensions for uploading Scheme code.
\end{itemize} \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} \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 The SUnet package contains following parts:
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:
% %
\begin{itemize} \begin{itemize}
\item Several servers (HTTP, CGI, FTP) \item Several servers (HTTP, CGI, FTP)
@ -85,38 +50,17 @@ The sunet package contains following parts:
\item {\dots} \item {\dots}
\end{itemize} \end{itemize}
\subsection{What is in this docu?} \section{How to use the packages}
%
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!).
Currently the ftp server, the ftp client, the modules containing the Scsh is started in the SUnet top-level directory. Then, the
procedures handling URIs and URLs, the module handling RFC~822 description file of the modules is loaded and the \texttt{ftp} module
headers, the netrc package, the save evaluation environment is opened (to use a ftp client). After the things are done, scsh is
\ex{toothless\=eval} and the obsolete library for using strings are finished via the \verb|,exit| command.
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.
\begin{alltt} \begin{alltt}
atari-2600[72] scsh-0.6 atari-2600[72] scsh-0.6.2
Welcome to scsh 0.6.0 (Chinese Democracy) Welcome to scsh 0.6.2 (Gambit-C 4.0)
Type ,? for help. Type ,? for help.
> ,config ,load modules.scm > ,config ,load packages.scm
modules.scm modules.scm
> ,open ftp > ,open ftp
Load structure ftp (y/n)? y Load structure ftp (y/n)? y
@ -130,5 +74,5 @@ atari-2600[73]
%%% Local Variables: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: man %%% TeX-master: "man"
%%% End: %%% End:

3
doc/latex/man.tex
View File

@ -1,4 +1,4 @@
\documentclass{article} \documentclass{report}
\usepackage[latin1]{inputenc} \usepackage[latin1]{inputenc}
\usepackage{alltt} \usepackage{alltt}
@ -25,7 +25,6 @@
\include{intro} \include{intro}
\include{httpd} \include{httpd}
\include{toothless} \include{toothless}
\include{cgi-server}
\include{cgi-script} \include{cgi-script}
\include{ftpd} \include{ftpd}
\include{ftp} \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} \begin{description}
\item[Used files:] netrc.scm \item[Used files:] netrc.scm
\item[Name of the package:] netrc \item[Name of the package:] netrc
\end{description} \end{description}
% %
\subsection{Overview} \section{Overview}
This module provides procedures to parse authentication information This module provides procedures to parse authentication information
contained in \ex{~/.netrc}. 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 What you probably want, is to read out the default netrc-file. Do the
following: following:
@ -119,7 +119,7 @@ a default login / password if the machine is unknown.
is returned by \ex{netrc:\ob{}default\=password}. is returned by \ex{netrc:\ob{}default\=password}.
\end{defundescx} \end{defundescx}
\subsection{Related work} \section{Related work}
\begin{itemize} \begin{itemize}
\item Graham Barr has written a similar library for Perl, called \item Graham Barr has written a similar library for Perl, called
\ex{Netrc.pm}. \ex{Netrc.pm}.
@ -127,7 +127,7 @@ a default login / password if the machine is unknown.
parses the user's netrc file. parses the user's netrc file.
\end{itemize} \end{itemize}
\subsection{Desirable things} \section{Desirable things}
\begin{itemize} \begin{itemize}
\item Remove restrictions (as stated in `\emph{Overview}') and behave like \item Remove restrictions (as stated in `\emph{Overview}') and behave like
\ex{/usr/\ob{}bin/\ob{}ftp} behaves \ex{/usr/\ob{}bin/\ob{}ftp} behaves
@ -138,5 +138,5 @@ a default login / password if the machine is unknown.
%%% Local Variables: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: man.tex %%% TeX-master: "man"
%%% End: %%% 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} \begin{description}
\item[Used files:] nettime.scm nettime-obsolete.scm \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} \begin{description}
\item[Used files:] pop3.scm pop3-obsolete.scm \item[Used files:] pop3.scm pop3-obsolete.scm
\item[Name of the package:] pop3 pop3-obsolete.scm \item[Name of the package:] pop3 pop3-obsolete.scm
\end{description} \end{description}
% %
\subsection{Overview} \section{Overview}
The POP3 protocol allows access to email on a maildrop server. It is The POP3 protocol allows access to email on a maildrop server. It is
often used in configurations where users connect from a client machine 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. messages.
\subsection{Entry points} \section{Entry points}
\begin{defundesc}{pop3-connect}{\ovar{host \ovar{logfile}}}{connection} \begin{defundesc}{pop3-connect}{\ovar{host \ovar{logfile}}}{connection}
Connect to the maildrop server named \semvar{host}. Optionally log 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 names, use the \ex{pop3\=obsolete}-package that maps the old names to
the new ones. the new ones.
\subsection{Related work} \section{Related work}
\begin{itemize} \begin{itemize}
\item Emacs is distributed with a C program called \ex{movemail} which \item Emacs is distributed with a C program called \ex{movemail} which
@ -117,5 +117,5 @@ the new ones.
%%% Local Variables: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: t %%% TeX-master: "man"
%%% End: %%% 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} \begin{description}
\item[Used files:] rfc822.scm \item[Used files:] rfc822.scm
\item[Name of the package:] rfc822 \item[Name of the package:] rfc822
\end{description} \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 Line-terminating sequences are always a drag, because there's no
agreement on them -- the Net protocols and DOS use agreement on them -- the Net protocols and DOS use
carriage-return/line-feed (\ex{cr}/\ex{lf}); Unix uses \ex{lf}; the 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} 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). 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} \defun{read-rfc822-field} {\ovar{port}} {name body}
\begin{defundescx}{\%read-rfc822-field } {read-line 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: Read one field from the port, and return two values:
\begin{description} \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 field name is converted to a symbol using the Scheme
implementation's preferred case. If the implementation reads implementation's preferred case. If the implementation reads
symbols in a case-sensitive fashion (e.g., scsh), lowercase is 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 using \ex{eq?}. When printing these field names out, it looks best
if you capitalize them with \ex{(capitalize\=string (symbol->string field\=name))}. 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 (``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, the field's body, so if the field spreads out over three lines,
then the body is a list of three strings. The terminating 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}.) a doing once a \ex{symbol->string} conversion of \ex{'a}.)
\end{defundesc} \end{defundesc}
\subsubsection*{Desireable functionalities} \section{Desireable functionalities}
\begin{itemize} \begin{itemize}
\item Unfolding long lines. \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} \begin{description}
\item[Used files:] smtp.scm \item[Used files:] smtp.scm
@ -6,11 +6,11 @@
\end{description} \end{description}
% %
\subsection{Philosophy} \section{Philosophy}
SMTP protocol procedures tend to return two values: SMTP protocol procedures tend to return two values:
\begin{description} \begin{description}
\item{\semvar{code}} The integer SMTP reply code returned by server for the transaction. \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{text}] A list of strings -- the text messages tagged by
the code. the code.
\end{description} \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: 600$ to indicate extra-protocol errors. There are two of these:
\begin{description} \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. 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. The server shut down in the middle of a reply.
\end{description} \end{description}
A list of the official protocol return codes can be seen in table A list of the official protocol return codes can be seen in table
\ref{smtp-reply-codes}. \ref{smtp-reply-codes}.
\subsection{Procedures} \section{Procedures}
\begin{defundesc}{sendmail}{to-list body \ovar{host}}{code text-list} \begin{defundesc}{sendmail}{to-list body \ovar{host}}{code text-list}
Mail message \semvar{body} to recipients in list \semvar{to-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} \begin{defundesc}{read-smtp-reply}{port}{code text-list}
Read a reply from the SMTP server. Returns two values: Read a reply from the SMTP server. Returns two values:
\begin{description} \begin{description}
\item{\semvar{code}} Integer. The reply code. \item[\semvar{code}] Integer. The reply code.
\item{\semvar{text}} String list. A list of the text lines comprising \item[\semvar{text}] String list. A list of the text lines comprising
the reply. Each line of text is stripped of the initial the reply. Each line of text is stripped of the initial
reply-code numerals (e.g., the first four chars of the reply), 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 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?} \begin{defundesc}{parse-smtp-reply}{line}{code rest more?}
Parse a line of SMTP reply. Return three values: Parse a line of SMTP reply. Return three values:
\begin{description} \begin{description}
\item{\semvar{code}} integer -- the reply code that prefixes the \item[\semvar{code}] integer -- the reply code that prefixes the
string. string.
\item{\semvar{rest}} string -- the rest of the line. \item[\semvar{rest}] string -- the rest of the line.
\item{\semvar{more?}} boolean -- is there more reply to read (i.e., \item[\semvar{more?}] boolean -- is there more reply to read (i.e.,
was the numeric reply code terminated by a ``\ex{-}'' character?) was the numeric reply code terminated by a ``\ex{-}'' character?)
\end{description} \end{description}
\end{defundesc} \end{defundesc}
@ -193,14 +193,14 @@ A list of the official protocol return codes can be seen in table
call to \ex{smtp\=stuff}. call to \ex{smtp\=stuff}.
\end{defundesc} \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 This material is taken from the RFC. The first digits encode categories
of responses: of responses:
\begin{description} \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, accepted, but the requested action is being held in abeyance,
pending confirmation of the information in this reply. The pending confirmation of the information in this reply. The
sender-SMTP should send another command specifying whether to 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, Note: SMTP does not have any commands that allow this type of reply,
and so does not have the continue or abort commands. and so does not have the continue or abort commands.
\end{leftinset} \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. 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, accepted, but the requested action is being held in abeyance,
pending receipt of further information. The sender-SMTP should send pending receipt of further information. The sender-SMTP should send
another command specifying this information. This reply is used in another command specifying this information. This reply is used in
command sequence groups. 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 not accepted and the requested action did not occur. However, the
error condition is temporary and the action may be requested again. error condition is temporary and the action may be requested again.
The sender should return to the beginning of the command sequence 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 without any change in command form or in properties of the sender or
receiver. (E.g., the command is repeated identically and the receiver. (E.g., the command is repeated identically and the
receiver does not put up a new implementation.) 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 not accepted and the requested action did not occur. The
sender-SMTP is discouraged from repeating the exact request (in the sender-SMTP is discouraged from repeating the exact request (in the
same sequence). Even some ``permanent'' error conditions can be same sequence). Even some ``permanent'' error conditions can be
@ -241,16 +241,16 @@ of responses:
The second digit encodes responses in specific categories: The second digit encodes responses in specific categories:
\begin{description} \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 syntactically correct commands that don't fit any functional
category, and unimplemented or superfluous commands. 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. 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. transmission channel.
\item{\bfseries x3z\,} Unspecified as yet. \item[x3z\,] Unspecified as yet.
\item{\bfseries x4z\,} Unspecified as yet. \item[x4z\,] Unspecified as yet.
\item{\bfseries x5z Mail system\,} These replies indicate the status of the \item[x5z Mail system\,] These replies indicate the status of the
receiver mail system vis-a-vis the requested transfer or other mail receiver mail system vis-a-vis the requested transfer or other mail
system action. system action.
\end{description} \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} \begin{description}
\item[Used files:] none, defined in modules.scm \item[Used files:] none, defined in modules.scm
@ -7,20 +7,20 @@
\end{description} \end{description}
% %
\subsection{Overview} \section{Overview}
\FIXME{Is toothless really R5RS, too?} \FIXME{Is toothless really R5RS, too?}
These modules define an environment that is \RnRS without features that 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 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. 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: The \ex{loser} package exports only one procedure:
\begin{defundesc}{loser}{name}{nothing} \begin{defundesc}{loser}{name}{nothing}
Raises an error like ``Illegal call \var{name}''. Raises an error like ``Illegal call \var{name}''.
\end{defundesc} \end{defundesc}
\subsection{The \protect{\texttt{toothless}} package} \section{The \protect{\texttt{toothless}} package}
The \ex{toothless} package contains everything of \RnRS except The \ex{toothless} package contains everything of \RnRS except
that following procedure cause an error if called: that following procedure cause an error if called:
\begin{itemize} \begin{itemize}
@ -40,7 +40,7 @@ that following procedure cause an error if called:
So, \ex{toothless} creates an environment as described in So, \ex{toothless} creates an environment as described in
\emph{Overview} above. \emph{Overview} above.
\subsection{The \protect{\texttt{toothless-eval}} package} \section{The \protect{\texttt{toothless-eval}} package}
\begin{defundesc}{eval-safely} {expression} {any result} \begin{defundesc}{eval-safely} {expression} {any result}
Creates a brand new package, imports the \ex{toothless} structure, 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} \begin{description}
\item[Used files:] uri.scm \item[Used files:] uri.scm
@ -6,7 +6,7 @@
\end{description} \end{description}
% %
\subsection{Overview} \section{Overview}
A URI (Uniform Resource Identifier) is of following syntax: A URI (Uniform Resource Identifier) is of following syntax:
\begin{inset} \begin{inset}
\ovar{scheme\/} : \semvar{path} \ovar{{\normalfont?\/} search} \ovar{{\normalfont\#} fragmentid} \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 character 97). This module provides procedures to escape and unescape
strings that are meant to be used in a URI. strings that are meant to be used in a URI.
\subsection{Procedures} \section{Procedures}
\begin{defundesc}{parse-uri} {uri-string } {scheme path search \begin{defundesc}{parse-uri} {uri-string } {scheme path search
frag-id} \label{proc:parse-uri} frag-id} \label{proc:parse-uri}
@ -188,7 +188,7 @@ Perhaps I find it out later.}
\codex{\sharpf ; tries to back up root} \codex{\sharpf ; tries to back up root}
\end{defundesc} \end{defundesc}
\subsection*{Unexported names} \section{Unexported names}
\defvar{uri-reserved}{char-set} \defvar{uri-reserved}{char-set}
\begin{desc} \begin{desc}
@ -223,5 +223,5 @@ Perhaps I find it out later.}
%%% Local Variables: %%% Local Variables:
%%% mode: latex %%% mode: latex
%%% TeX-master: man.tex %%% TeX-master: "man"
%%% End: %%% End:

16
doc/latex/url.tex
View File

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