Almost done with manual...

5 files changed, 166 insertions, 195 deletions

diff --git a/doc/dns.html b/doc/dns.html
index 8e63407..226a604 100644
--- a/doc/dns.html
+++ b/doc/dns.html
@@ -70,7 +70,7 @@ The function returns a string with the host name.
 <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=tohostname> 
-socket.dns.<b>tohostname()</b>
+socket.dns.<b>tohostname(</b>address<b>)</b>
 </p>
 
 <p class=description>
@@ -91,7 +91,7 @@ followed by an error message.
 <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=toip> 
-socket.dns.<b>toip()</b>
+socket.dns.<b>toip(</b>address<b>)</b>
 </p>
 
 <p class=description>
diff --git a/doc/http.html b/doc/http.html
index 16595f7..39eb2e4 100644
--- a/doc/http.html
+++ b/doc/http.html
@@ -98,36 +98,36 @@ Note: MIME headers are independent of order. Therefore, there is no problem
 in representing them in a Lua table. 
 </p>
 
+<p>
+The following constants can be set to control the default behaviour of
+the HTTP module: 
+</p>
+
+<ul>
+<li> <tt>PORT</tt>: default port used for connections; 
+<li> <tt>PROXY</tt>: default proxy used for connections; 
+<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
+<li> <tt>USERAGENT</tt>: default user agent reported to server.
+</ul>
+
 <!-- http.get +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=get>
-socket.http.<b>get(</b>url<b>)</b><br>
-socket.http.<b>get{</b><br>
-&nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;headers = <i>header-table</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br>
-&nbsp;&nbsp;password = <i>string</i>,<br>
-&nbsp;&nbsp;stay = <i>bool</i>,<br>
-<b>}</b>
+http.<b>get(</b>url<b>)</b><br>
 </p>
 
 <p class=description>
-Performs  the HTTP method <tt>GET</tt>. 
+Performs the HTTP method <tt>GET</tt>. 
 </p>
 
 <p class=parameters>
-The  function can  be
-called either directly with a <tt>url</tt>  or with a <em>request table</em>. 
-The use of  a request table allows  complete control over the  components of
-the  request.  Values  passed explicitly  as fields of the request table
-override those given by the <tt>url</tt>. For a description of the fields,
-see the <a href=#request><tt>request</tt></a> function.
+<tt>Url</tt> identifies the entity to retrieve. 
 </p>
 
 <p class=return>
-The function  returns the response  message body, the mime  headers, the
-status  code and  an  error message (if  any). In  case  of failure,  the
-function returns all information it managed to gather.
+If successful, the function  returns the response  message body, the mime
+headers, and the status  code. In  case  of failure,  the
+function returns <tt><b>nil</b></tt> followed by an error message. 
 </p>
 
 <p class=note>
@@ -136,35 +136,30 @@ Note: The function is trivially implemented with the use of the
 </p>
 
 <pre class=example>
+-- load the http module
+http = require("http")
+
 -- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
 -- file from "/luasocket/http.html"
-b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
+b, h, c = http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
 
 -- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
 -- "~diego/auth/index.html". Fails because authentication is needed.
-b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
+b, h, c = http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
 -- b returns some useless page telling about the denied access, 
 -- h returns authentication information
 -- and c returns with value 401 (Authentication Required)
 
 -- tries to connect to server "wrong.host" to retrieve "/"
 -- and fails because the host does not exist.
-b, h, c, e = socket.http.get("http://wrong.host/")
--- b, h, c are nil, and e returns with value "host not found"
+r, e = http.get("http://wrong.host/")
+-- r is nil, and e returns with value "host not found"
 </pre>
 
 <!-- http.post ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=post>
-socket.http.<b>post(</b>url, body<b>)</b><br>
-socket.http.<b>post{</b><br>
-&nbsp;&nbsp; url = <i>string</i>,<br>
-&nbsp;&nbsp; headers = <i>header-table</i>,<br>
-&nbsp;&nbsp; body = <i>string</i>,<br>
-&nbsp;&nbsp; user = <i>string</i>,<br>
-&nbsp;&nbsp; password = <i>string</i>,<br>
-&nbsp;&nbsp; stay = <i>bool</i>,<br>
-<b>}</b>
+http.<b>post(</b>url, body<b>)</b><br>
 </p>
 
 <p class=description>
@@ -181,50 +176,64 @@ Note: This function is also trivially implemented with the use of the
 <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=request>
-socket.http.<b>request{</b><br>
-&nbsp;&nbsp;method = <i>string</i>,<br>
+http.<b>request{</b><br>
 &nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;headers = <i>header-table</i>,<br>
-&nbsp;&nbsp;body = <i>string</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br>
-&nbsp;&nbsp;password = <i>string</i>,<br>
-&nbsp;&nbsp;stay = <i>string</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>
+&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
+&nbsp;&nbsp;[proxy = <i>string</i>,]<br>
+&nbsp;&nbsp;[redirect = <i>boolean</i>]<br>
 <b>}</b>
 </p>
 
 <p class=description>
-Performs the generic HTTP  request using.
+Performs the generic HTTP request, controled by a request table.
 </p>
 
 <p class=parameters>
-The request uses <tt>method</tt> on <tt>url</tt>
-sending the  request <tt>headers</tt>  and request <tt>body</tt>  in the
-request message. If authentication information is provided, the function
+The most important parameters are the <tt>url</tt> and the LTN12 
+<tt>sink</tt> that will receive the downloaded content.  
+Any part of the <tt>url</tt> can be overriden by including
+the appropriate field in the request table.
+If authentication information is provided, the function
 uses the  Basic Authentication Scheme (see  <a href="#authentication">note</a>)
-to retrieve  the document. <tt>User</tt> and  <tt>password</tt> provided
-explicitly override  those given by the  <tt>url</tt>. The <tt>stay</tt>
-parameter, when set to anything  but <b><tt>nil</tt></b>, prevents the function
-from automatically following 301 or 302 server redirect messages. 
-</p>
+to retrieve  the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the
+function discards the downloaded data. The optional parameters are the
+following:
+</p>
+<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>: LTN12 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.  
+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 
+function from  automatically following 301 or 302 server redirect messages. 
+</ul>
 
 <p class=return>
-The function returns a table with all components of the response message
-it managed to retrieve. The response table has the following form:
+In case of failure, the function returns <tt><b>nil</b></tt> followed by an
+error message. If successful, the function returns a table 
+with all components of the response message. The response table has the following form:
 </p>
 
 <blockquote><tt>
-response = {<br>
-&nbsp;&nbsp;body = <i>string</i>,<br>
+respt = {<br>
 &nbsp;&nbsp;headers = <i>header-table</i>,<br>
 &nbsp;&nbsp;status = <i>string</i>,<br>
 &nbsp;&nbsp;code = <i>number</i>,<br>
-&nbsp;&nbsp;error = <i>string</i><br>
 }
 </tt></blockquote>
 
 <p class=return>
 Even  when there  was failure  (URL not  found, for  example), the
-function may succeed retrieving a message body (a web page informing the
+function usually succeeds retrieving a message body (a web page informing the
 URL  was  not found  or  some  other useless  page).  To  make sure  the
 operation was successful, check  the returned status <tt>code</tt>. For
 a  list  of  the  possible  values  and  their  meanings,  refer  to  <a
@@ -233,15 +242,18 @@ href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
 </p>
 
 <pre class=example>
+-- load the http module
+http = require("http")
+
 -- Requests information about a document, without downloading it.
 -- Useful, for example, if you want to display a download gauge and need
 -- to know the size of the document in advance
-response = socket.http.request {
+respt = http.request {
   method = "HEAD",
   url = "http://www.tecgraf.puc-rio.br/~diego"
 }
 -- Would return the following headers:
--- response.headers = {
+-- respt.headers = {
 --   date = "Tue, 18 Sep 2001 20:42:21 GMT",
 --   server = "Apache/1.3.12 (Unix)  (Red Hat/Linux)",
 --   ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
@@ -276,10 +288,14 @@ authentication is required.
 </p>
 
 <pre class=example>
+-- load required modules
+http = require("http")
+mime = require("mime")
+
 -- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
 -- "~diego/auth/index.html", using the provided name and password to
 -- authenticate the request
-response = socket.http.request{
+respt = http.request{
   url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
   user = "diego",
   password = "password"
@@ -287,83 +303,12 @@ response = socket.http.request{
 
 -- Alternatively, one could fill the appropriate header and authenticate
 -- the request directly.
-headers = {
-  authentication = "Basic " .. socket.code.base64("diego:password")
-}
-response = socket.http.request {
+respt = http.request {
   url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
-  headers = headers
+  headers = { authentication = "Basic " .. (mime.b64("diego:password")) }
 }
 </pre>
 
-<!-- request_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id=request_cb>
-socket.http.<b>request_cb(</b>request, response<b>)</b>
-</p>
-
-<p class=description>
-Performs the generic HTTP  request.
-</p>
-
-<p class=parameters>
-The function receives two tables as parameters. The <tt>request</tt> table
-provides information about the request: 
-</p>
-
-<blockquote><tt>
-request = {<br>
-&nbsp;&nbsp;method = <i>string</i>,<br>
-&nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;headers = <i>header-table</i>,<br>
-&nbsp;&nbsp;body_cb = <i>send-callback</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br>
-&nbsp;&nbsp;password = <i>string</i>,<br>
-&nbsp;&nbsp;stay = <i>string</i>,<br>
-}</tt>
-</blockquote>
-
-<p class=parameters>
-The function uses the HTTP method specified in 
-<tt>request.method</tt> on the URL <tt>request.url</tt>,
-sending <tt>request.headers</tt> along with the request. The request
-message  body  is sent  via the send  callback <tt>request.body_cb</tt>.
-If authentication information is provided, the function    uses   the Basic
-Authentication    Scheme   (see    <a href="#authentication">note</a>)  to
-retrieve  the document.  <tt>Request.user</tt> and
-<tt>request.password</tt>  override  those  given  by the
-<tt>request.url</tt>.  The <tt>request.stay</tt>  parameter,  when set  to
-anything but <b><tt>nil</tt></b>, prevents the function  from automatically
-following 301 or 302 server redirect messages.  
-</p>
-
-<p class=parameters>
-The <tt>response</tt> table specifies information about the desired
-response:
-</p>
-
-<blockquote><tt>
-response = {<br>
-&nbsp;&nbsp;body_cb = <i>receive-callback</i><br>
-}</tt>
-</blockquote>
-
-<p class=return>
-The function  returns the same  response table  as that returned  by the
-<tt>socket.http.request</tt>  function, except  the  response  message body  is
-returned    to    the    receive   callback   given    by    the
-<tt>response.body_cb</tt> field. 
-</p>
-
-<p class=note>
-Note: For more information on callbacks, please refer to 
-<a href="stream.html#stream">Streaming with callbacks</a>.
-</p>
-
-<p class=note>
-Note: Method names are case <em>sensitive</em>
-</p>
-
 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <div class=footer>
diff --git a/doc/index.html b/doc/index.html
index a2c2d59..c4c1e2f 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -47,7 +47,7 @@ applications that deal with the Internet.
 <p>
 Network support has been  implemented so that it  is both efficient and
 simple to use.  LuaSocket can be used by any Lua application once it has
-been properly linked with and initialized by the interpreter running the
+been properly initialized by the interpreter running the
 Lua application.  The code has been tested and runs well on several Windows
 and Unix platforms. 
 </p>
@@ -61,7 +61,7 @@ LuaSocket.
 </p>
 
 <p>
-Copyright &copy; 1999-2003 Tecgraf/PUC-Rio. All rights reserved. <br>
+Copyright &copy; 1999-2004 Tecgraf/PUC-Rio. All rights reserved. <br>
 Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
 </p>
 
@@ -70,7 +70,7 @@ Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
 <h2 id=download>Download</h2>
 
 <p>
-LuaSocket version  2.0 alpha is now  available for download! It  is
+LuaSocket version  2.0 beta is now  available for download! It  is
 compatible with   Lua&nbsp;5.0   and   has    been   tested   on
 Windows&nbsp;XP, Linux, and Mac OS X. 
 </p>
@@ -81,8 +81,8 @@ The library can be downloaded in source code from the following links:
 
 <blockquote>
 <p>
-<a href="luasocket-2.0-alpha.tar.gz">luasocket-2.0-alpha.tar.gz</a> <br>
-<a href="luasocket-2.0-alpha.zip">luasocket-2.0-alpha.zip</a>
+<a href="luasocket-2.0-beta.tar.gz">luasocket-2.0-beta.tar.gz</a> <br>
+<a href="luasocket-2.0-beta.zip">luasocket-2.0-beta.zip</a>
 </p>
 </blockquote>
 
@@ -112,11 +112,11 @@ option, and  should be able to run the automatic test procedures.
 <h2 id=thanks>Special thanks</h2>
 
 <p>
-Throughout LuaSocket its history, many people gave sugestions that helped
+Throughout LuaSocket's history, many people gave sugestions that helped
 improve it. For that, I thank the Lua comunity. 
 Special thanks go to
 David Burgess, who has pushed the library to a new level of quality and
-from whom I have learned a lot stuff that doesn't show up in RFCs.
+from whom I have learned a lot of stuff that doesn't show up in RFCs.
 Special thanks also to Carlos Cassino, who played a big part in the 
 extensible design seen in the C core of LuaSocket 2.0. 
 </p>
@@ -127,7 +127,7 @@ extensible design seen in the C core of LuaSocket 2.0.
 
 
 <p>
-Most of  the changes for  2.0 happened in the C layer, which
+Everything is new! Many changes for  2.0 happened in the C layer, which
 has been almost completely rewritten. The code has been ported to Lua 5.0
 and greatly improved.  There have also been some API changes
 that made  the interface simpler and  more consistent. Here are  some of
@@ -140,58 +140,85 @@ the changes that made it into version 2.0:
      pipes (on Unix) and named pipes (on windows) as a bonus;
 
 <li> Following the Lua 5.0 trend, all functions provided by the library are
-     in the namespace <tt>socket</tt>.  Functions such as
+     in namespaces. These should be obtained with calls to the
+    <tt>require</tt> function. Functions such as
      send/receive/timeout/close etc do not exist anymore as stand-alone
      functions. They are now only available as methods of the appropriate
      objects;
 
 <li> All functions return a non-nil value as first return value if successful.
-     All functions return whatever could be retrieved followed by error message
-     in case of error. The best way to check for errors is to check for the
-     presence of an error message;  
+     All functions return <b><tt>nil</tt></b> followed by error message
+     in case of error; 
 
-<li> UDP connected   sockets can break association with peer by calling
+<li> Better error messages and parameter checking;
+
+<li> Should be interrupt safe; 
+
+<li> UDP connected sockets can break association with peer by calling
      <tt>setpeername</tt> with address '<tt>*</tt>';
 
 <li> TCP has been changed to become more uniform.  First create an object,
      then connect or bind if needed, and finally use I/O functions. The
      <tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still
      provided for simplicity, but they just call <tt>socket.tcp</tt> followed 
-     by the <tt>connect</tt> or <tt>bind</tt> methods;
+     by the <tt>connect</tt> or <tt>bind/listen</tt> methods;
 
-<li> Better error messages and parameter checking;
+<li> Greatly reduced the number of times select is called during data
+     transfers, by calling only on failure;
+
+<li> TCP can set timeout value before connecting and also bind to local
+     address before connecting; 
+
+<li> <tt>socket.select</tt> returns associative sets and checks if 
+     sockets had buffered data; 
 
 <li> <tt>socket.sleep</tt> and <tt>socket.time</tt> are now part of the
      library and are supported. They used to be available only when
      LUASOCKET_DEBUG was defined, but it turns out they might be useful for
      applications;
 
-<li> Socket options interface has been improved and TCP objects also 
-     support socket options.
+<li> <tt>socket.try</tt> and <tt>socket.protect</tt> provide a simple
+     interface to exceptions that proved very in the implementation of
+     high-level modules; 
+
+<li> Socket options interface has been improved. TCP objects also 
+     support socket options and many other options were added.
+
+</ul>
+
+<p>
+Lots of changes in the Lua modules, too. The new MIME and LTN12 modules
+make all other modules much more powerful. The main new functionality is
+the support for multipart messages in the SMTP module.
+</p>
+
+<ul>
+
+<li> 
 
 </ul>
 
+
 <!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <h3 id=incompatible>Incompatibilities with previous versions</h3>
 
 <ul>
+
 <li> The introduction of namespaces affects all programs that use LuaSocket,
 specially code that relies on global functions. These are no longer
 available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt>
-etc) have been moved to the namespace (i.e.  <tt>socket.http</tt>,
-<tt>socket.smtp</tt> etc);
+etc) are independent now and should be "<tt>require</tt>ed"; 
+
+<li> FTP, SMTP and HTTP are completely new; I am sure you will
+agree the new stuff is better; 
 
-<li> WARNING: The new <tt>send</tt>,
+<li> WARNING: The new <tt>send</tt>, <tt><b>receive</b></tt>,
 <tt>sendto</tt>, <tt>setpeername</tt> and <tt>setsockname</tt>, 
-<tt>ftp.put</tt>, <tt>ftp.put_cb</tt> return convention WILL break old code; 
+return convention WILL break old code; 
 
 <li> Interface to options has changed;
 
-<li> <tt>socket.select</tt> refuses tables that have anything that is not
-an object from the group <tt>select{able}</tt>. This includes even the
-'<tt>n</tt>' field. Silently ignoring objects was a source of bugs for Lua
-programs.
 </ul>
 
 <!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
diff --git a/doc/introduction.html b/doc/introduction.html
index e6f0ea2..86c552b 100644
--- a/doc/introduction.html
+++ b/doc/introduction.html
@@ -37,12 +37,12 @@
 
 <p>
 Communication in LuaSocket is performed via I/O objects. These can
-represent different network domains. Currently, support is
-provided for TCP and UDP, but there is work in progress to implement SSL,
-Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard
+represent different network domains. Currently, support is provided for TCP
+and UDP, but nothing prevents other developers from implementing SSL, Local
+Domain, Pipes, File Descriptors etc. I/O objects provide a standard
 interface to I/O across different domains and operating systems.
 LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future
-addition of new domains.
+addition of new domains.  
 </p>
 
 <p>
@@ -93,7 +93,7 @@ Previous versions of LuaSocket provided global functions for operating on
 I/O objects. To give the library a Lua 5.0 feel, these have been eliminated
 from LuaSocket 2.0. I/O operations are only available as methods of the
 corresponding I/O objects.  Naturally, different I/O objects accept
-different operations. The core functionality for TCP and UDP objects is
+different operations. The TCP and UDP objects are
 introduced in the following sections, following a few words about
 initialization. 
 </p>
@@ -103,18 +103,23 @@ initialization.
 <h3>Initializing the library</h3>
 
 <p>
+The core LuaSocket functionality is implemented in C, and usually available as 
+a dynamic library which the interpreter can load when required. 
 Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket
-functionality is defined inside a table (or rather a namespace) stored with
-the global name <tt>socket</tt>.  To  have this table created and its
-contents made available to a Lua script, the interpreter running the script
-must  be linked to the LuaSocket library, and  to whatever libraries  the
-host OS  requires  for network access (Windows requires ws2_32.lib, for
-instance). LuaSocket is initialized in  the
-Lua state given as the argument  to  the  function
-<tt>luaopen_socket</tt>, the  only  C function  exported  by  the  library.
-After initialization, scripts are free to use all of the LuaSocket API. 
+functionality is defined inside a tables (or rather a namespaces). No global
+variables are ever created.
+Namespaces are obtained with the <tt>require</tt> Lua function, which loads
+and initializes any required libraries and return the namespace. 
+For example, the core functionality or LuaSocket is usually available
+from the "<tt>socket</tt>" namespace. 
 </p>
 
+<pre class="example">
+socket = require("socket")
+print(socket.VERSION)
+-- LuaSocket 2.0
+</pre>
+
 <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <h3 id=tcp>TCP</h3>
@@ -185,29 +190,25 @@ program.
 </p>
 
 <pre class=example>
--- create a new TCP object
-server, err = socket.tcp()
-assert(server, err)
--- bind it to the local host, at any port
-ret, err = server:bind("*", 0)
-assert(ret, err)
+-- load namespace
+local socket = require("socket")
+-- create a TCP socket and bind it to the local host, at any port
+local server = socket.try(socket.bind("*", 0))
 -- find out which port the OS chose for us
-ip, port = server:getsockname()
+local ip, port = server:getsockname()
 -- print a message informing what's up
 print("Please telnet to localhost on port " .. port)
 print("After connecting, you have 10s to enter a line to be echoed")
 -- loop forever waiting for clients
 while 1 do
   -- wait for a conection from any client
-  client, err = server:accept()
+  local client = server:accept()
   -- make sure we don't block waiting for this client's line
   client:settimeout(10)
   -- receive the line
-  line, err = client:receive()
+  local line, err = client:receive()
   -- if there was no error, send it back to the client
-  if not err then 
-    client:send(line .. "\n") 
-  end
+  if not err then client:send(line .. "\n") end
   -- done with client, close the object
   client:close()
 end
@@ -286,21 +287,19 @@ error message.
 </p>
 
 <pre class=example>
-host = "localhost" -- change here to the host you want to contact
-port = port or 13
+-- change here to the host an port you want to contact
+host = "localhost" 
+port = 13
+-- load namespace
+local socket = require("socket")
 -- convert host name to ip address
-ip, err = socket.dns.toip(host)
-assert(ip, err)
+local ip = socket.try(socket.dns.toip(host))
 -- create a new UDP object
-udp = socket.udp()
+local udp = socket.udp()
 -- contact daytime host
-nsent, err = udp:sendto("anything", ip, port)
-assert(not err, err)
--- retrieve the answer
-dgram, err = udp:receive()
-assert(dgram, err)
--- display to user
-print(dgram)
+socket.try(udp:sendto("anything", ip, port))
+-- retrieve the answer and print results
+io.write(socket.try((udp:receive())))
 </pre>
 </blockquote>
 
diff --git a/doc/mime.html b/doc/mime.html
index d2fcc3c..286e41c 100644
--- a/doc/mime.html
+++ b/doc/mime.html
@@ -44,7 +44,7 @@ MIME is described mainly in
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC 2045</a>,
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2046.txt">2046</a>,
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2047</a>,
-<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2048</a> and
+<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2047.txt">2048</a>, and
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2048.txt">2049</a>.
 </p>