Fine tuning the manual...

1 files changed, 49 insertions, 28 deletions

diff --git a/doc/smtp.html b/doc/smtp.html
index 0fdc4a4..6b348e0 100644
--- a/doc/smtp.html
+++ b/doc/smtp.html
@@ -35,8 +35,15 @@
 
 <h2 id=smtp>SMTP</h2> 
 
-<p> The  <tt>smtp.lua</tt> module  provides functionality to send e-mail
-messages. The implementation conforms to the Simple Mail Transfer Protocol,
+<p> The  <tt>smtp</tt> namespace provides functionality to send e-mail
+messages. The high-level API consists of two functions: one to 
+define an e-mail message, and another to actually send the message.
+Although almost all users will find that these functions provide more than
+enough functionality, the underlying implementation allows for even more
+control (if you bother to read the code).  
+</p>
+
+<p>The implementation conforms to the Simple Mail Transfer Protocol,
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
 Another RFC of interest is <a
 href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
@@ -52,6 +59,15 @@ sources and sinks</a> and the  <a href=mime.html>MIME</a> module is
 assumed.  In fact, the SMTP module was the main reason for their 
 creation. </p>
 
+<p> 
+To obtain the <tt>smtp</tt> namespace, run:
+</p>
+
+<pre class=example>
+-- loads the SMTP module and everything it requires
+local smtp = require("smtp")
+</pre>
+
 <p>
 MIME headers are represented as a Lua table in the form:
 </p>
@@ -62,12 +78,8 @@ MIME headers are represented as a Lua table in the form:
 headers = {<br>
 &nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
 &nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
-&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
-</tt></td></tr>
-<tr><td align=center><tt>
-&nbsp;&nbsp;...
-</tt></td></tr>
-<tr><td><tt>
+&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
+&nbsp;&nbsp;...<br>
 &nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
 }
 </tt></td></tr>
@@ -105,12 +117,12 @@ smtp.<b>send{</b><br>
 &nbsp;&nbsp;from = <i>string</i>,<br>
 &nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
 &nbsp;&nbsp;source = <i>LTN12 source</i>,<br>
-&nbsp;&nbsp;[user = <i>string</i>],<br>
-&nbsp;&nbsp;[password = <i>string</i>],<br>
-&nbsp;&nbsp;[server = <i>string</i>],<br>
-&nbsp;&nbsp;[port = <i>string</i>]<br>
-&nbsp;&nbsp;[domain = <i>string</i>],<br>
-&nbsp;&nbsp;[step = <i>LTN12 pump step</i>],<br>
+&nbsp;&nbsp;[user = <i>string</i>,]<br>
+&nbsp;&nbsp;[password = <i>string</i>,]<br>
+&nbsp;&nbsp;[server = <i>string</i>,]<br>
+&nbsp;&nbsp;[port = <i>string</i>,]<br>
+&nbsp;&nbsp;[domain = <i>string</i>,]<br>
+&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
 <b>}</b>
 </p>
 
@@ -127,8 +139,9 @@ The sender is given by the e-mail address in the <tt>from</tt> field.
 <tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
 address, or a string
 in case there is just one recipient. 
-The contents of the message are given by a <em>simple</em> LTN12 <tt>source</tt>. Several
-arguments are optional:
+The contents of the message are given by a <em>simple</em> 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+<tt>source</tt>. Several arguments are optional:
 </p>
 <ul>
 <li> <tt>user</tt>, <tt>password</tt>: User and password for
@@ -138,7 +151,9 @@ methods if supported by the server (both are unsafe);
 <li> <tt>port</tt>: Port to connect to. Defaults to 25;
 <li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
 local machine host name; 
-<li> <tt>step</tt>: LTN12 pump step function used to pass data from the
+<li> <tt>step</tt>: 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+pump step function used to pass data from the
 source to the server. Defaults to the LTN12 <tt>pump.step</tt> function.
 </ul>
 
@@ -166,7 +181,8 @@ exact opposite of what you expect.
 Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the
 message.  Each recipient of an SMTP mail message receives a copy of the
 message body along with the headers, and nothing more.  The headers
-<em>are</em> part of the message and should be produced by the LTN12 
+<em>are</em> part of the message and should be produced by the 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
 <tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
 part of the message and will not be sent to anyone.
 </p>
@@ -258,8 +274,8 @@ smtp.<b>message(</b>mesgt<b>)</b>
 </p>
 
 <p class=description>
-Returns a LTN12 source that sends an SMTP message body, possibly multipart
-(arbitrarily deep). 
+Returns a <em>simple</em>
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep). 
 </p>
 
 <p class=parameters>
@@ -277,12 +293,12 @@ mesgt = {<br>
 }<br>
 &nbsp;<br>
 multipart-mesgt = {<br>
-&nbsp;&nbsp;preamble = <i>string</i><br>
+&nbsp;&nbsp;[preamble = <i>string</i>,]<br>
 &nbsp;&nbsp;[1] = <i>mesgt</i>,<br>
 &nbsp;&nbsp;[2] = <i>mesgt</i>,<br>
 &nbsp;&nbsp;...<br>
 &nbsp;&nbsp;[<i>n</i>] = <i>mesgt</i>,<br>
-&nbsp;&nbsp;epilogue = <i>string</i>,<br>
+&nbsp;&nbsp;[epilogue = <i>string</i>,]<br>
 }<br>
 </tt></td></tr>
 </table>
@@ -291,14 +307,19 @@ multipart-mesgt = {<br>
 <p class=parameters>
 For a simple message, all that is needed is a set of <tt>headers</tt>
 and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
-or as a LTN12 source. For multipart messages, the body is a table that
-recursively defines each part as an independent message, plus a preamble
-and an epilogue.
+or as a <em>simple</em> 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+source. For multipart messages, the body is a table that
+recursively defines each part as an independent message, plus an optional
+<tt>preamble</tt> and <tt>epilogue</tt>.
 </p>
 
 <p class=return> 
-The function returns a <em>simple</em> LTN12 source that produces the
-message contents as defined by <tt>mesgt</tt>.  Hopefully, the following
+The function returns a <em>simple</em> 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+source that produces the
+message contents as defined by <tt>mesgt</tt>, chunk by chunk. 
+Hopefully, the following
 example will make things clear. When in doubt, refer to the appropriate RFC
 as listed in the introduction.  </p>
 
@@ -320,7 +341,7 @@ source = smtp.message{
   body = {
     preamble = "If your client doesn't understand attachments, \r\n" ..
                "it will still display the preamble and the epilogue.\r\n" ..
-               "Preamble might show up even in a MIME enabled client.",
+               "Preamble will probably appear even in a MIME enabled client.",
     -- first part: no headers means plain text, us-ascii.
     -- The mime.eol low-level filter normalizes end-of-line markers.
     [1] = {