Fine tuning the manual...

doc/ftp.html

@@ -54,7 +54,8 @@ To really benefit from this module, a good understanding of
 LTN012, Filters sources and sinks</a> is necessary. 
 </p>
 
-<p class=description> To obtain the <tt>ftp</tt> namespace, run:
+<p> 
+To obtain the <tt>ftp</tt> namespace, run:
 </p>
 
 <pre class=example>
@@ -99,7 +100,7 @@ ftp.<b>get{</b><br>
 &nbsp;&nbsp;[command = <i>string</i>,]<br>
 &nbsp;&nbsp;[port = <i>number</i>,]<br>
 &nbsp;&nbsp;[type = <i>string</i>,]<br>
-&nbsp;&nbsp;[step = <i>LTN12 pump step</i>],<br>
+&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
 <b>}</b>
 </p>
 
@@ -115,7 +116,9 @@ If the argument of the <tt>get</tt> function is a table, the function
 expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of 
 <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
 precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
-the <em>simple</em> LTN12 sink that will receive the downloaded data. <tt>Argument</tt> or
+the <em>simple</em> 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
+sink that will receive the downloaded data. <tt>Argument</tt> or
 <tt>path</tt> give the target path to the resource in the server. The
 optional arguments are the following:
 </p>
@@ -127,7 +130,9 @@ authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
 <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
 <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
 "<tt>a</tt>". Defaults to whatever is the server default;
-<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
 server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
 </ul>
 
@@ -177,7 +182,7 @@ ftp.<b>put{</b><br>
 &nbsp;&nbsp;[command = <i>string</i>,]<br>
 &nbsp;&nbsp;[port = <i>number</i>,]<br>
 &nbsp;&nbsp;[type = <i>string</i>,]<br>
-&nbsp;&nbsp;[step = <i>LTN12 pump step</i>],<br>
+&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
 <b>}</b>
 </p>
 
@@ -192,7 +197,9 @@ If the argument of the <tt>put</tt> function is a table, the function
 expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of 
 <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
 precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
-the <em>simple</em> LTN12 source that will provide the contents to be uploaded. 
+the <em>simple</em> 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+source that will provide the contents to be uploaded. 
 <tt>Argument</tt> or
 <tt>path</tt> give the target path to the resource in the server. The
 optional arguments are the following:
@@ -205,7 +212,9 @@ authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
 <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
 <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
 "<tt>a</tt>". Defaults to whatever is the server default;
-<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
 server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
 </ul>
 

doc/http.html

@@ -50,11 +50,13 @@ implementation    conforms     to    the    HTTP/1.1     standard,
 The module exports functions that provide HTTP functionality in different
 levels of abstraction, from the simple 
 <a href="#get"><tt>get</tt></a> function, through the generic
-LTN12 based <a href="#request"><tt>request</tt></a> function, down to
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based 
+<a href="#request"><tt>request</tt></a> function, down to
 even lower-level if you bother to look through the source code.
 </p>
 
-<p class=description> To obtain the <tt>ftp</tt> namespace, run:
+<p> 
+To obtain the <tt>http</tt> namespace, run:
 </p>
 
 <pre class=example>
@@ -85,12 +87,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>,
+&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
-</tt></td></tr>
+&nbsp;&nbsp;...<br>
-<tr><td align=center><tt>
-&nbsp;&nbsp;...
-</tt></td></tr>
-<tr><td><tt>
 &nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
 }
 </tt></td></tr>
@@ -188,7 +186,7 @@ Note: This function is also trivially implemented with the use of the
 <p class=name id=request>
 http.<b>request{</b><br>
 &nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;[sink = <i>LTN12 sink</i>],]<br>
+&nbsp;&nbsp;[sink = <i>LTN12 sink</i>,]<br>
 &nbsp;&nbsp;[method = <i>string</i>,]<br>
 &nbsp;&nbsp;[headers = <i>header-table</i>,]<br>
 &nbsp;&nbsp;[source = <i>LTN12 source</i>],<br>
@@ -203,7 +201,9 @@ Performs the generic HTTP request, controlled by a request table.
 </p>
 
 <p class=parameters>
-The most important parameters are the <tt>url</tt> and the <em>simple</em> LTN12 <tt>sink</tt> that will receive the downloaded content.  
+The most important parameters are the <tt>url</tt> and the <em>simple</em>
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+<tt>sink</tt> that will receive the downloaded content.  
 Any part of the <tt>url</tt> can be overridden by including
 the appropriate field in the request table.
 If authentication information is provided, the function
@@ -215,11 +215,15 @@ following:
 <ul>
 <li><tt>method</tt>: The HTTP request method. Defaults to "GET"; 
 <li><tt>headers</tt>: Any additional HTTP headers to send with the request; 
-<li><tt>source</tt>: <em>simple</em> LTN12 source to provide the request body. If there
+<li><tt>source</tt>: <em>simple</em> 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+source to provide the request body. If there
 is a body, you need to provide an appropriate "<tt>content-length</tt>"
 request header field, or the function will attempt to send the body as
 "<tt>chunked</tt>" (something few servers support). Defaults to the empty source; 
-<li><tt>step</tt>: LTN12 pump step function used to move data.  
+<li><tt>step</tt>: 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
+pump step function used to move data.  
 Defaults to the LTN12 <tt>pump.step</tt> function.
 <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; 
 <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the 

doc/index.html

@@ -51,13 +51,21 @@ and Unix platforms.
 </p>
 
 <p>
-The most used modules implement the SMTP (sending  e-mails),  HTTP
+The most used modules implement the 
-(WWW access)  and  FTP  (uploading  and downloading files) client
+<a href=smtp.html>SMTP</a>
+(sending  e-mails),  
+<a href=http.html>HTTP</a>
+(WWW access)  and  
+<a href=ftp.html>FTP</a>  
+(uploading  and downloading files) client
 protocols. These provide a very natural and generic interface to the e
 functionality covered by the protocols. 
-In addition, you will find that the MIME (common encodings), URL (anything you
+In addition, you will find that the 
-could possible want to do with one) and LTN12 (filters, sinks, sources
+<a href=mime.html>MIME</a> (common encodings), 
-and pumps) modules can be very handy. 
+<a href=url.html>URL</a> 
+(anything you could possible want to do with one) and 
+<a href=ltn12.html>LTN12</a> 
+(filters, sinks, sources and pumps) modules can be very handy. 
 </p>
 
 <p>

doc/introduction.html

@@ -122,7 +122,7 @@ from the "<tt>socket</tt>" namespace.
 <pre class="example">
 socket = require("socket")
 print(socket.VERSION)
--- LuaSocket 2.0
+--&gt; LuaSocket 2.0
 </pre>
 
 <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

doc/ltn12.html

@@ -42,7 +42,8 @@ functions. Please refer to the LTN for a deeper explanation of the
 functionality provided by this module.
 </p>
 
-<p class=description> To obtain the <tt>ltn12</tt> namespace, run:
+<p> 
+To obtain the <tt>ltn12</tt> namespace, run:
 </p>
 
 <pre class=example>

doc/mime.html

@@ -55,7 +55,8 @@ follows the ideas presented in
 LTN012, Filters sources and sinks</a>. 
 </p>
 
-<p class=description> To obtain the <tt>mime</tt> namespace, run:
+<p> 
+To obtain the <tt>mime</tt> namespace, run:
 </p>
 
 <pre class=example>
@@ -109,10 +110,6 @@ Returns a filter that decodes data from a given transfer content
 encoding.
 </p>
 
-<p class=return>
-The function returns the created filter.
-</p>
-
 <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id="encode">
@@ -131,10 +128,6 @@ textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
 "<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
 </p>
 
-<p class=return>
-The function returns the created filter.
-</p>
-
 <p class=note>
 Although both transfer content encodings specify a limit for the line
 length, the encoding filters do <em>not</em> break text into lines (for
@@ -186,10 +179,6 @@ not to break lines in the middle of an escaped character. In that case, the
 line length is fixed at 76.
 </p>
 
-<p class=return>
-The function returns the created filter.
-</p>
-
 <p class=note>
 For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
 </p>
@@ -260,9 +249,7 @@ the context is returned after each new chunk.
 ASCII value of the last character of the previous chunk, if it was a
 candidate for line break, or 0 otherwise. 
 <tt>B</tt> is the same as <tt>C</tt>, but for the current
-chunk.  If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> includes a
+chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
-new end-of-line marker, depending on <tt>C</tt>.
-<tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
 </p>
 
 <pre class=example>

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
+<p> The  <tt>smtp</tt> namespace provides functionality to send e-mail
-messages. The implementation conforms to the Simple Mail Transfer Protocol,
+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>,
+&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
-</tt></td></tr>
+&nbsp;&nbsp;...<br>
-<tr><td align=center><tt>
-&nbsp;&nbsp;...
-</tt></td></tr>
-<tr><td><tt>
 &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;[user = <i>string</i>,]<br>
-&nbsp;&nbsp;[password = <i>string</i>],<br>
+&nbsp;&nbsp;[password = <i>string</i>,]<br>
-&nbsp;&nbsp;[server = <i>string</i>],<br>
+&nbsp;&nbsp;[server = <i>string</i>,]<br>
-&nbsp;&nbsp;[port = <i>string</i>]<br>
+&nbsp;&nbsp;[port = <i>string</i>,]<br>
-&nbsp;&nbsp;[domain = <i>string</i>],<br>
+&nbsp;&nbsp;[domain = <i>string</i>,]<br>
-&nbsp;&nbsp;[step = <i>LTN12 pump step</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
+The contents of the message are given by a <em>simple</em> 
-arguments are optional:
+<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
+Returns a <em>simple</em>
-(arbitrarily deep). 
+<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
+or as a <em>simple</em> 
-recursively defines each part as an independent message, plus a preamble
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 
-and an epilogue.
+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
+The function returns a <em>simple</em> 
-message contents as defined by <tt>mesgt</tt>.  Hopefully, the following
+<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] = { 

doc/socket.html

@@ -39,6 +39,16 @@
 The <tt>socket</tt> namespace contains the core functionality of LuaSocket. 
 </p>
 
+<p> 
+To obtain the <tt>socket</tt> namespace, run:
+</p>
+
+<pre class=example>
+-- loads the socket module 
+local socket = require("socket")
+</pre>
+
+
 <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=debug> 
@@ -62,8 +72,9 @@ Converts a function that throws exceptions into a safe function.
 </p>
 
 <p class=parameters>
-<tt>Funct</tt> is a function that calls 
+<tt>Func</tt> is a function that calls 
-<a href=#try><tt>try</tt></a> to throw exceptions. 
+<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) 
+to throw exceptions. 
 </p>
 
 <p class=return>
@@ -71,6 +82,13 @@ Returns an equivalent function that instead of throwing exceptions,
 returns <tt><b>nil</b></tt> followed by an error message. 
 </p>
 
+<p class=note>
+Note: Beware that if your function performs some illegal operation that
+raises an error, the protected function will catch the error and return it
+as a string. This is because the <a href=#try><tt>try</tt></a> function
+uses errors as the mechanism to throw exceptions.  
+</p>
+
 <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=select> 
@@ -88,8 +106,8 @@ see if it is OK to immediately write on them.  <tt>Timeout</tt> is the
 maximum amount of time (in seconds) to wait for a change in status.  A
 <tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
 function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
-be empty tables or <tt><b>nil</b></tt>. Non-socket values in the arrays
+be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
-will be silently ignored.
+non-numeric indices) in the arrays will be silently ignored.
 </p>
 
 <p class=return> The function returns a table with the sockets ready for
@@ -186,7 +204,7 @@ The function returns a source with the appropriate behavior.
 <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=try> 
-socket.<b>try(</b>ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub><b>)</b>
+socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
 </p>
 
 <p class=description>
@@ -194,16 +212,14 @@ Throws an exception in case of error.
 </p>
 
 <p class=parameters>
-<tt>Ret</tt><sub>1</sub>, <tt>ret</tt><sub>2</sub> ... <tt>ret</tt><sub>N</sub> can be arbitrary
+<tt>Ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> can be arbitrary
-arguments, but are usually the return values of a function call that 
+arguments, but are usually the return values of a function call 
-nested with the call to <tt>try</tt>. 
+nested with <tt>try</tt>. 
 </p>
 
 <p class=return> 
-The function returns <tt>ret</tt><sub>1</sub>, <tt>ret</tt><sub>2</sub> ...
+The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
-<tt>ret</tt><sub>N</sub> if
+<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub>.
-<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt>. Otherwise, calls <tt>error</tt>
-passing <tt>ret</tt><sub>2</sub>.
 </p>
 
 <pre class=example>
@@ -211,7 +227,7 @@ passing <tt>ret</tt><sub>2</sub>.
 c = socket.try(socket.connect("localhost", 80))
 </pre>
 
-<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=version> 
 socket.<b>VERSION</b>