diff --git a/doc/latex/cgi-script.tex b/doc/latex/cgi-script.tex index 632abb0..f364f87 100644 --- a/doc/latex/cgi-script.tex +++ b/doc/latex/cgi-script.tex @@ -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 diff --git a/doc/latex/cgi-server.tex b/doc/latex/cgi-server.tex deleted file mode 100644 index f4a9f10..0000000 --- a/doc/latex/cgi-server.tex +++ /dev/null @@ -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} \ No newline at end of file diff --git a/doc/latex/decls.tex b/doc/latex/decls.tex index 3607561..e9dde42 100644 --- a/doc/latex/decls.tex +++ b/doc/latex/decls.tex @@ -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. diff --git a/doc/latex/ftp.tex b/doc/latex/ftp.tex index 56d616e..ed7e23c 100644 --- a/doc/latex/ftp.tex +++ b/doc/latex/ftp.tex @@ -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 diff --git a/doc/latex/ftpd.tex b/doc/latex/ftpd.tex index 6d8826a..7c1c0c3 100644 --- a/doc/latex/ftpd.tex +++ b/doc/latex/ftpd.tex @@ -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} diff --git a/doc/latex/httpd.tex b/doc/latex/httpd.tex index 1ae5084..3910305 100644 --- a/doc/latex/httpd.tex +++ b/doc/latex/httpd.tex @@ -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: - -\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''. +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 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. -\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. - -\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} + Some simple documentation on the server is available. + \end{description} -\subsubsection*{Basic server structure} +\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 @@ -421,8 +413,44 @@ directory-generation service using the following rules: \item If the filename names a regular file, it is served to the 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: diff --git a/doc/latex/intro.tex b/doc/latex/intro.tex index 0d50ce0..5b9e557 100644 --- a/doc/latex/intro.tex +++ b/doc/latex/intro.tex @@ -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: diff --git a/doc/latex/man.tex b/doc/latex/man.tex index ca032bf..d09eee3 100644 --- a/doc/latex/man.tex +++ b/doc/latex/man.tex @@ -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} diff --git a/doc/latex/netrc.tex b/doc/latex/netrc.tex index ac01016..7b4cec0 100644 --- a/doc/latex/netrc.tex +++ b/doc/latex/netrc.tex @@ -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: diff --git a/doc/latex/nettime.tex b/doc/latex/nettime.tex index 37136cc..04b0c2f 100644 --- a/doc/latex/nettime.tex +++ b/doc/latex/nettime.tex @@ -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 diff --git a/doc/latex/pop3.tex b/doc/latex/pop3.tex index 847b157..0892b36 100644 --- a/doc/latex/pop3.tex +++ b/doc/latex/pop3.tex @@ -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: diff --git a/doc/latex/rfc822.tex b/doc/latex/rfc822.tex index 00a8154..77824ba 100644 --- a/doc/latex/rfc822.tex +++ b/doc/latex/rfc822.tex @@ -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. diff --git a/doc/latex/smtp.tex b/doc/latex/smtp.tex index b10b205..ce6e7d8 100644 --- a/doc/latex/smtp.tex +++ b/doc/latex/smtp.tex @@ -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} diff --git a/doc/latex/toothless.tex b/doc/latex/toothless.tex index 0f41a76..54d67bb 100644 --- a/doc/latex/toothless.tex +++ b/doc/latex/toothless.tex @@ -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, diff --git a/doc/latex/uri.tex b/doc/latex/uri.tex index 5f8e306..bd8cf4f 100644 --- a/doc/latex/uri.tex +++ b/doc/latex/uri.tex @@ -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: diff --git a/doc/latex/url.tex b/doc/latex/url.tex index 1d7eb43..a159981 100644 --- a/doc/latex/url.tex +++ b/doc/latex/url.tex @@ -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: