added documentation for pop3.scm

doc/latex/pop3.tex

@@ -5,4 +5,109 @@
 \item[Name of the package:] pop3 
 \end{description}
 %
-Not implemented yet.
+\subsection{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
+which doesn't have a permanent network connection or isn't always
+turned on, situations which make local SMTP delivery impossible. It is
+the most common form of email access provided by Internet Service
+Providers.
+
+Two types of authentication are commonly used. The first, most basic
+type involves sending a user's password in clear over the network, and
+should be avoided. Unfortunately many POP3 clients only implement this
+basic authentication. The digest authentication system involves the
+server sending the client a ``challenge'' token; the client encodes
+this token with the pass phrase and sends the coded information to the
+server. This method avoids sending sensitive information over the
+network.
+
+Once connected, a client may request information about the number and
+size of the messages waiting on the server, download selected messages
+(either their headers or the entire content), and delete selected
+messages.
+
+
+\subsection{Entry points}
+
+\begin{defundesc}{pop3:connect}{\ovar{host \ovar{logfile}}}{connection}
+  Connect to the maildrop server named \semvar{host}. Optionally log
+  the conversation with the server to \semvar{logfile}, which will be
+  appended to if it exists, and created otherwise. The environment
+  variable \ex{MAILHOST}, if set, will override the value of
+  \semvar{host}.
+\end{defundesc}
+
+In the further descriptions of the procedures, \semvar{connection}
+always refers to the result of \ex{pop3:\ob{}connect}.
+
+\begin{defundesc}{pop3:login} {connection \ovar{login \ovar{password}}}{status}
+  Log in to the mailhost. If a \semvar{login} and \semvar{password}
+  are not provided, they are first searched for in the user's ~/.netrc
+  file. USER/PASS authentication will be tried first, and if
+  this fails, APOP authentication (secure) will be tried.
+\end{defundesc}
+
+\begin{defundesc}{pop3:login/APOP} {connection login password}{status}
+  Log in to the mailhost using APOP authentication. \footnote{The encryption
+  (MD5) is currently done by an extern program that your system must
+  provide. The expected name of the program is \ex{md5sum}. If your system
+  uses another program for computing a MD5 message digest, change the
+  program's name in \ex{md5-digest}.}
+\end{defundesc}
+
+\begin{defundesc}{pop3:stat}{connection}{number bytes}
+  Return the number of messages and the number of bytes waiting in the
+  maildrop.
+\end{defundesc}
+
+\begin{defundesc}{pop3:get}{connection msgid}{status}
+  Download message number \semvar{msgid} from the mailhost.
+  \semvar{msgid} must be positive and less than the number of messages
+  returned by the \ex{pop3:\ob{}stat} call. The message contents are sent to
+  \ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}.
+\end{defundesc}
+
+\begin{defundesc}{pop3:headers}{connection msgid}{status}
+  Download the headers of message number \semvar{msgid}. The data is sent to
+  \ex{(cur\ob{}rent-\ob{}out\ob{}put-\ob{}port)}.
+\end{defundesc}
+
+\begin{defundesc}{pop3:last}{connection}{msgid}
+  Return the highest accessed message-id number for the current
+  session. This isn't in the RFC, but seems to be supported by several
+  servers.
+\end{defundesc}
+
+\begin{defundesc}{pop3:delete}{connection msgid}{status}
+  Mark message number \semvar{msgid} for deletion. The message will
+  not be deleted until the client logs out.
+\end{defundesc}
+
+\begin{defundesc}{pop3:reset}{connection}{status}
+  Any messages which have been marked for deletion are unmarked.
+\end{defundesc}
+
+\begin{defundesc}{pop3:quit}{connection}{status}
+  Close the connection with the mailhost.
+\end{defundesc}
+
+\subsection{Related work}
+
+\begin{itemize}
+\item Emacs is distributed with a C program called \ex{movemail} which
+  can be compiled with support for the POP protocol. There is also an
+  Emacs Lisp library called \ex{pop3.el} by Richard Pieri which
+  includes APOP support.
+\item Shriram Krishnamurth has written a POP3 library for MzScheme (as
+  well as support for the NNTP protocol, for SMTP, \ldots).
+\item Siod (a small-footprint Scheme implementation by George Carette)
+  includes support for the POP3 protocol.
+\item rfc1939 describes the POP3 protocol.
+\end{itemize}
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: t
+%%% End: