Use the real name of the module: "smtplib", not "smtp".
Use logical (& consistent) markup.
Added a see-also section at the end.
diff --git a/Doc/lib/libsmtplib.tex b/Doc/lib/libsmtplib.tex
index 90bbc1e..9d42ee1 100644
--- a/Doc/lib/libsmtplib.tex
+++ b/Doc/lib/libsmtplib.tex
@@ -1,52 +1,56 @@
% Documentation by ESR
-\section{Standard Module \module{smtp}}
-\stmodindex{smtp}
-\label{module-smtp}
+\section{Standard Module \module{smtplib}}
+\stmodindex{smtplib}
+\label{module-smtplib}
-The \code{smtp} module defines an SMTP session object that can be used
-to send mail to any Internet machine with an SMTP or ESMTP listener daemon.
-For details of SMTP and ESMTP operation, consult RFC 821 (Simple Mail
-Transfer Protocol) and RFC1869 (SMTP Service Extensions).
+The \module{smtplib} module defines an SMTP session object that can be
+used to send mail to any Internet machine with an SMTP or ESMTP
+listener daemon. For details of SMTP and ESMTP operation, consult
+\rfc{821} (\emph{Simple Mail Transfer Protocol}) and \rfc{1869}
+(\emph{SMTP Service Extensions}).
\begin{classdesc}{SMTP}{\optional{host, port}}
A \class{SMTP} instance encapsulates an SMTP connection. It has
methods that support a full repertoire of SMTP and ESMTP
operations. If the optional host and port parameters are given, the
-SMTP connect method is called with those parameters during
+SMTP \method{connect()} method is called with those parameters during
initialization.
For normal use, you should only require the initialization/connect,
-\var{sendmail}, and \var{quit} methods An example is included below.
+\method{sendmail()}, and \method{quit()} methods An example is
+included below.
\end{classdesc}
\subsection{SMTP Objects}
\label{SMTP-objects}
-A \class{SMTP} instance has the following methods:
+An \class{SMTP} instance has the following methods:
\begin{methoddesc}{set_debuglevel}{level}
-Set the debug output level. A non-false value results in debug
-messages for connection and for all messages sent to and received from
-the server.
+Set the debug output level. A true value for \var{level} results in
+debug messages for connection and for all messages sent to and
+received from the server.
\end{methoddesc}
-\begin{methoddesc}{connect}{\optional{host='localhost',port=0}}
+\begin{methoddesc}{connect}{\optional{host='localhost'\optional{, port=0}}}
Connect to a host on a given port.
-If the hostname ends with a colon (`:') followed by a number,
-that suffix will be stripped off and the number interpreted as
+If the hostname ends with a colon (\character{:}) followed by a
+number, that suffix will be stripped off and the number interpreted as
the port number to use.
-Note: This method is automatically invoked by __init__,
-if a host is specified during instantiation.
+Note: This method is automatically invoked by the constructor if a
+host is specified during instantiation.
\end{methoddesc}
\begin{methoddesc}{docmd}{cmd, \optional{, argstring}}
-Send a command to the server. The optional argument
-string is simply concatenated to the command.
+Send a command \var{cmd} to the server. The optional argument
+\var{argstring} is simply concatenated to the command, separated by a
+space.
-Get back a 2-tuple composed of a numeric response code and the actual
-response line (multiline responses are joined into one long line.)
+This returns a 2-tuple composed of a numeric response code and the
+actual response line (multiline responses are joined into one long
+line.)
In normal operation it should not be necessary to call this method
explicitly. It is used to implement other methods and may be useful
@@ -58,29 +62,29 @@
argument defaults to the FQDN of the local host.
In normal operation it should not be necessary to call this method
-explicitly. It will be implicitly called by the \var{sendmail} method
+explicitly. It will be implicitly called by the \method{sendmail()}
when necessary.
\end{methoddesc}
\begin{methoddesc}{ehlo}{\optional{hostname}}
Identify yourself to an ESMTP server using HELO. The hostname
argument defaults to the FQDN of the local host. Examine the
-response for ESMTP option and store them for use by the
-\var{has_option} method.
+response for ESMTP option and store them for use by
+\method{has_option()}.
-Unless you wish to use the \var{has_option} method before sending
+Unless you wish to use \method{has_option()} before sending
mail, it should not be necessary to call this method explicitly. It
-will be implicitly called by the \var{sendmail} method when necessary.
+will be implicitly called by \method{sendmail()} when necessary.
\end{methoddesc}
\begin{methoddesc}{has_option}{name}
-Return 1 if name is in the set of ESMTP options returned by the
-server, 0 otherwise. Case is ignored.
+Return \code{1} if \var{name} is in the set of ESMTP options returned
+by the server, \code{0} otherwise. Case is ignored.
\end{methoddesc}
\begin{methoddesc}{verify}{address}
Check the validity of an address on this server using SMTP VRFY.
-Returns a tuple consisting of code 250 and a full RFC822 address
+Returns a tuple consisting of code 250 and a full \rfc{822} address
(including human name) if the user address is valid. Otherwise returns
an SMTP error code of 400 or greater and an error string.
@@ -88,8 +92,8 @@
\end{methoddesc}
\begin{methoddesc}{sendmail}{from_addr, to_addrs, msg\optional{, options=[]}}
-Send mail. The required arguments are an RFC822 from-address string,
-a list of RFC822 to-address strings, and a message string. The caller
+Send mail. The required arguments are an \rfc{822} from-address string,
+a list of \rfc{822} to-address strings, and a message string. The caller
may pass a list of ESMTP options to be used in MAIL FROM commands.
If there has been no previous EHLO or HELO command this session, this
@@ -100,11 +104,12 @@
This method will return normally if the mail is accepted for at least
one recipient. Otherwise it will throw an exception (either
-SMTPSenderRefused, SMTPRecipientsRefused, or SMTPDataError)
+\exception{SMTPSenderRefused}, \exception{SMTPRecipientsRefused}, or
+\exception{SMTPDataError}).
That is, if this method does not throw an exception, then someone
should get your mail. If this method does not throw an exception,
it returns a dictionary, with one entry for each recipient that was
-refused.
+refused.
\end{methoddesc}
\begin{methoddesc}{quit}{}
@@ -116,29 +121,41 @@
these do not need to be called directly, so they are not documented
here. For details, consult the module code.
-Example:
+
+\subsection{SMTP Example}
+\label{SMTP-example}
+
+% really need a little description here...
\begin{verbatim}
- import sys, rfc822
+import sys, rfc822
- def prompt(prompt):
- sys.stdout.write(prompt + ": ")
- return string.strip(sys.stdin.readline())
+def prompt(prompt):
+ sys.stdout.write(prompt + ": ")
+ return string.strip(sys.stdin.readline())
- fromaddr = prompt("From")
- toaddrs = string.splitfields(prompt("To"), ',')
- print "Enter message, end with ^D:"
- msg = ''
- while 1:
- line = sys.stdin.readline()
- if not line:
- break
- msg = msg + line
- print "Message length is " + `len(msg)`
+fromaddr = prompt("From")
+toaddrs = string.splitfields(prompt("To"), ',')
+print "Enter message, end with ^D:"
+msg = ''
+while 1:
+ line = sys.stdin.readline()
+ if not line:
+ break
+ msg = msg + line
+print "Message length is " + `len(msg)`
- server = SMTP('localhost')
- server.set_debuglevel(1)
- server.sendmail(fromaddr, toaddrs, msg)
- server.quit()
+server = SMTP('localhost')
+server.set_debuglevel(1)
+server.sendmail(fromaddr, toaddrs, msg)
+server.quit()
\end{verbatim}
+
+\begin{seealso}
+\seetext{\rfc{821}, \emph{Simple Mail Transfer Protocol}. Available
+online at \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc821.txt}.}
+
+\seetext{\rfc{1869}, \emph{SMTP Service Extensions}. Available online
+at \url{http://info.internet.isi.edu/in-notes/rfc/files/rfc1869.txt}.}
+\end{seealso}