Manual is almost done. HTTP is missing.

Implemented new distribution scheme.
Select is now purely C.
HTTP reimplemented seems faster dunno why.
LTN12 functions that coroutines fail gracefully.

10 files changed, 1296 insertions, 287 deletions

diff --git a/doc/ftp.html b/doc/ftp.html
index 6776a17..a0c9268 100644
--- a/doc/ftp.html
+++ b/doc/ftp.html
@@ -35,9 +35,9 @@
 
 <p>
 FTP  (File Transfer  Protocol)  is a  protocol  used  to transfer  files
-between hosts.  The module  <tt>ftp.lua</tt> offers simple  FTP support,
-allowing applications to  download and upload files,  and list directory
-contents. The implementation conforms to
+between hosts.  The module  <tt>ftp.lua</tt> offers simple  FTP support.
+Applications can easily download and upload files. 
+The implementation conforms to
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
 </p>
 
@@ -49,175 +49,191 @@ URLs MUST conform to
 
 <blockquote>
 <tt>
-[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i|d]</tt>
+[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i]</tt>
 </blockquote>
 
+<p>
+High level functions are provided supporting the most common operations.
+These high level functions are implemented on top of a lower level
+interface. By using the low-level interface, users can easily create their
+own functions to access <em>any</em> operation supported by the FTP
+protocol.  For that, check the implementation.  
+</p>
+
+<p>
+To use some of the functions in this module, a good understanding of 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
+LTN012, Filters sources and sinks</a> is necessary. 
+</p>
+
+<p>
+The following constants can be set to control the default behaviour of
+the FTP module: 
+</p>
+
+<ul>
+<li> <tt>PASSWORD</tt>: default anonymous password.
+<li> <tt>PORT</tt>: default port used for the control connection;
+<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
+<li> <tt>USER</tt>: default anonymous user;
+</ul>
+
 <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=get>
-socket.ftp.<b>get(</b>url<b>)</b><br>
-socket.ftp.<b>get{</b><br>
-&nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;type = <i>string</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br> 
-&nbsp;&nbsp;password = <i>string</i><br>
+ftp.<b>get(</b>url<b>)</b><br>
+ftp.<b>get{</b><br>
+&nbsp;&nbsp;host = <i>string</i>,<br>
+&nbsp;&nbsp;sink = <i>LTN12 sink</i>,<br>
+&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
+&nbsp;&nbsp;[user = <i>string</i>,]<br>
+&nbsp;&nbsp;[password = <i>string</i>]<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>
 <b>}</b>
 </p>
 
 <p class=description>
-Downloads an URL from a FTP server.
+The <tt>get</tt> function has two forms. The simple form has fixed
+functionality: it downloads the contents of a URL and returns it as a
+string. The generic form allows a <em>lot</em> more control, as explained
+below.
 </p>
 
 <p class=parameters>
-The function can be  called either  directly with  a <tt>url</tt>  
-or with  a <em>request table</em>. 
-Fields passed  explicitly in  the request  table override  those
-present in the <tt>url</tt>.
-</p>
-
-<p class=parameters>
-The parameter <tt>type</tt> accepts values '<tt>a</tt>' (ASCII, the
-default), '<tt>i</tt>' (binary) or  '<tt>d</tt>' (directory listing) and
-determines  the  transfer type.  If  <tt>&lt;path&gt;</tt>  ends with  a
-'<tt>/</tt>' or  <tt>type</tt> is  '<tt>d</tt>', a directory  listing of
-<tt>&lt;path&gt;</tt> is  returned.  If no <tt>user</tt> is provided in the
-<tt>url</tt> or explicitly, the function tries to log in as user
-'<tt>anonymous</tt>'.
+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 LTN12 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>
+<ul>
+<li><tt>user</tt>, <tt>password</tt>: User name and password used for
+authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
+<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
+"<tt>retr</tt>", but see example below;
+<li><tt>port</tt>: The port to contacct the server at. 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
+server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
+</ul>
 
 <p class=return>
-If successful, the  function returns
-the file  content as a string.  In case of error,  the function returns
-<b><tt>nil</tt></b> and an error message describing the error. 
+If successful, the simple version returns the URL  contents as a
+string, and the generic function returns 1.  In case of error,  both
+functions return <b><tt>nil</tt></b> and an error message describing the
+error.  
 </p>
 
 <pre class=example>
--- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
--- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
-f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
+-- load the ftp support
+local ftp = require("ftp")
 
 -- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
--- go to director "pub" and retrieve directory listing of directory "lua"
-f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d")
-
--- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br",
--- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe"
--- (actually, fails because of wrong password, of course)
-f, e = socket.ftp.get{
-  url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe",
-  user = "diego",
-  password = "nehab",
-  type = "i"
-}
--- f returns nil, and e returns an appropriate error message
+-- and get file "lua.tar.gz" from directory "pub/lua" as binary.
+f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
 </pre>
 
-<!-- get_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id=get_cb>
-socket.ftp.<b>get_cb{</b><br>
-&nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;type = <i>string</i>,<br>
-&nbsp;&nbsp;content_cb = <i>receive-callback</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br>
-&nbsp;&nbsp;password = <i>string</i><br>
-<b>}</b>
-</p>
-
-<p class=description>
-Same as <a href="#get"><tt>get</tt></a>, but the library returns
-the  content of  the  downloaded file  to  the receive callback
-<tt>content_cb</tt>. 
-</p>
-
-<p class=note>
-Note: for more information on callbacks, refer to 
-<a href="stream.html#stream">Streaming with callbacks</a>.
-</p>
+<pre class=example>
+-- load needed modules
+local ftp = require("ftp")
+local ltn12 = require("ltn12")
+local url = require("url")
+
+-- a function that returns a directory listing
+function ls(u)
+    local t = {}
+    local p = url.parse(u)
+    p.command = "nlst"
+    p.sink = ltn12.sink.table(t)
+    local r, e = ftp.get(p)
+    return r and table.concat(t), e
+end
+</pre>
 
 <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=put>
-socket.ftp.<b>put(</b>url, content<b>)</b><br>
-socket.ftp.<b>put{</b><br>
-&nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;content = <i>string</i>,<br>
-&nbsp;&nbsp;type = <i>string</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br>
-&nbsp;&nbsp;password = <i>string</i><br>
+ftp.<b>put(</b>url, content<b>)</b><br>
+ftp.<b>put{</b><br>
+&nbsp;&nbsp;host = <i>string</i>,<br>
+&nbsp;&nbsp;source = <i>LTN12 sink</i>,<br>
+&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
+&nbsp;&nbsp;[user = <i>string</i>,]<br>
+&nbsp;&nbsp;[password = <i>string</i>]<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>
 <b>}</b>
 </p>
 
 <p class=description>
-Upload a file to a  FTP server. 
+The <tt>put</tt> function has two forms. The simple form has fixed
+functionality: it uploads a string of content into a URL. The generic form
+allows a <em>lot</em> more control, as explained below.  
 </p>
 
 <p class=parameters>
-The  function   can  be   called  directly   with  a
-<tt>url</tt> and  <tt>content</tt> parameters, or with  a 
-<em>request table</em>.
-Values passed  explicitly in the  request table override those  present in
-the   <tt>url</tt>.   The   parameter   <tt>type</tt>   accept   values
-'<tt>a</tt>'  (ASCII,   the  default)   or  '<tt>i</tt>'   (binary)  and
-determines  the transfer  type.  If no  <tt>user</tt>  is provided,  the
-function tries to log in as '<tt>anonymous</tt>'.
+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 LTN12 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:
 </p>
+<ul>
+<li><tt>user</tt>, <tt>password</tt>: User name and password used for
+authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
+<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
+"<tt>retr</tt>", but see example below;
+<li><tt>port</tt>: The port to contacct the server at. 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
+server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function.
+</ul>
 
 <p class=return>
-If successful, the function returns  1. In case of error, the
-function returns <b><tt>nil</tt></b> followed by a string describing the error. 
+Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
+message describing the reason for failure.
 </p>
 
 <pre class=example>
--- Log as user "anonymous" on server "ftp.free.org" and store file
--- "hello" with contents "hello world!", using binary mode for the transfer
-r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n")
-
--- Does exactly the same, but logging in as diego
-r, e = socket.ftp.put{
-  url = "ftp://ftp.free.org/hello",
-  type = "i",
-  user = "diego",
-  password = "nehab",
-  content = "hello world\n"
-}
-</pre>
-</blockquote>
-
-<!-- put_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id=put_cb>
-socket.ftp.<b>put_cb{</b><br>
-&nbsp;&nbsp;url = <i>string</i>,<br>
-&nbsp;&nbsp;type = <i>string</i>,<br>
-&nbsp;&nbsp;content_cb = <i>send-callback</i>,<br>
-&nbsp;&nbsp;user = <i>string</i>,<br>
-&nbsp;&nbsp;password = <i>string</i><br>
-<b>}</b>
-</p>
-
-<p class=description>
-Same as <a href="#put"><tt>put</tt></a>, but the
-library obtains the contents of  the file to be uploaded using  the send
-callback <tt>content_cb</tt>. 
-</p>
+-- load the ftp support
+local ftp = require("ftp")
 
-<p class=note>
-Note: for more information on callbacks, refer to 
-<a href="stream.html#stream">Streaming with callbacks</a>.
-</p>
+-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
+-- using password "nehab", and store a file "README" with contents 
+-- "wrong password, of course"
+f, e = ftp.put("ftp://diego:nehab@ftp.tecgraf.puc-rio.br/README", "wrong password, of course")
+</pre>
 
 <pre class=example>
--- Log as user "anonymous" on server "ftp.free.org" and store file
--- "hello" with contents of the same file in the current directory, 
--- using binary mode for the transfer
-r, e = socket.ftp.put_cb{
-  url = "ftp://ftp.free.org/hello",
-  type = "i",
-  content_cb = socket.callback.send_file(io.open("hello", "r"))
+-- load the ftp support
+local ftp = require("ftp")
+local ltn12 = require("ltn12")
+
+-- Log as user "diego" on server "ftp.tecgraf.puc-rio.br",
+-- using password "nehab", and append to the file "LOG", sending the
+-- contents of a local file 
+f, e = ftp.put{
+  host = "ftp.tecgraf.puc-rio.br", 
+  user = "diego",
+  password = "nehab",
+  command = "appe",
+  argument = "LOG",
+  source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
 }
 </pre>
-</blockquote>
+
 
 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
diff --git a/doc/ltn12.html b/doc/ltn12.html
new file mode 100644
index 0000000..363ce43
--- /dev/null
+++ b/doc/ltn12.html
@@ -0,0 +1,421 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+
+<head>
+<title>LuaSocket: Network support for the Lua language</title>
+<link rel="stylesheet" href="reference.css" type="text/css">
+</head>
+
+<body>
+
+<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<div class=header>
+<hr>
+<center>
+<table summary="LuaSocket logo">
+<tr><td align=center><a href="http://www.lua.org">
+<img border=0 alt="LuaSocket" src="luasocket.png">
+</a></td></tr>
+<tr><td align=center valign=top>Network support for the Lua language
+</td></tr>
+</table>
+<p class=bar>
+<a href="home.html">home</a> &middot;
+<a href="home.html#download">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a> 
+</p>
+</center>
+<hr>
+</div>
+
+<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h2 id=ltn12>LTN12</h2> 
+
+<p> The LTN12 module implements the ideas described in
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
+LTN012, Filters sources and sinks</a>. This manual simply describe the
+functions. Please refer to the LTN for a deeper explanation of the
+functionality provided by this module.
+</p>
+
+<!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h3 id="filter">Filters</h3>
+
+<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="filter.chain">
+ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> 
+[, ... filter<sub>N</sub>]<b>)</b>
+</p>
+
+<p class=description>
+Returns a filter that passes all data it receives through each of a
+series of given filters. 
+</p>
+
+<p class=parameters>
+<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
+filters. 
+</p>
+
+<p class=return>
+The function returns the chained filter.
+</p>
+
+<p class=note>
+The nesting of filters can be arbritrary. For instance, the useless filter
+below doesn't do anything but return the data that was passed to it,
+unaltered.
+</p>
+
+<pre class=example>
+-- load required modules
+ltn12 = require("ltn12")
+mime = require("mime")
+
+-- create a silly identity filter
+id = ltn12.filter.chain(
+  mime.encode("quoted-printable"),
+  mime.encode("base64"),
+  mime.decode("base64"),
+  mime.decode("quoted-printable")
+)
+</pre>
+
+<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="filter.cycle">
+ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
+</p>
+
+<p class=description>
+Returns a high-level filter that cycles though a low-level filter by
+passing it each chunk and updating a context between calls. 
+</p>
+
+<p class=parameters>
+<tt>Low</tt> is the low-level filter to be cycled, 
+<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra
+argument the low-level filter might take.
+</p>
+
+<p class=return>
+The function returns the high-level filter. 
+</p>
+
+<pre class=example>
+-- load the ltn12 module
+local ltn12 = require("ltn12")
+
+-- the base64 mime filter factory
+encodet['base64'] = function()
+    return ltn12.filter.cycle(b64, "")
+end
+</pre>
+
+<!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h3 id="pump">Pumps</h3>
+
+<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="pump.all">
+ltn12.pump.<b>all(</b>source, sink<b>)</b>
+</p>
+
+<p class=description>
+Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. 
+</p>
+
+<p class=return>
+If successful, the function returns a value that evaluates to
+<b><tt>true</tt></b>. In case
+of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
+</p>
+
+<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="pump.step">
+ltn12.pump.<b>step(</b>source, sink<b>)</b>
+</p>
+
+<p class=description>
+Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. 
+</p>
+
+<p class=return>
+If successful, the function returns a value that evaluates to
+<b><tt>true</tt></b>. In case
+of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
+</p>
+
+<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h3 id="sink">Sinks</h3>
+
+<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="sink.chain">
+ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
+</p>
+
+<p class=description>
+Creates a new sink that passes data through a <tt>filter</tt> before sending 
+it to a given <tt>sink</tt>. 
+</p>
+
+<p class=return>
+The function returns the new sink.
+</p>
+
+<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="sink.error">
+ltn12.sink.<b>error(</b>message<b>)</b>
+</p>
+
+<p class=description>
+Creates and returns a sink that aborts transmission with an error
+<tt>message</tt>.
+</p>
+
+<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="sink.file">
+ltn12.sink.<b>file(</b>handle, message<b>)</b>
+</p>
+
+<p class=description>
+Creates a sink that sends data to a file. 
+</p>
+
+<p class=parameters>
+<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, 
+<tt>message</tt> should give the reason for failure. 
+</p>
+
+<p class=return>
+The function returns a sink that sends all data to the given <tt>handle</tt>
+and closes the file when done, or a sink that aborts the transmission with
+an error <tt>message</tt>
+</p>
+
+<p class=note>
+In the following example, notice how the prototype is designed to 
+fit nicely with the <tt>io.open</tt> function.
+</p>
+
+<pre class=example>
+-- load the ltn12 module
+local ltn12 = require("ltn12")
+
+-- copy a file
+ltn12.pump.all(
+  ltn12.source.file(io.open("original.png")),
+  ltn12.sink.file(io.open("copy.png"))
+)
+</pre>
+
+<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="sink.null">
+ltn12.sink.<b>null()</b>
+</p>
+
+<p class=description>
+Returns a sink that ignores all data it receives. 
+</p>
+
+<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="sink.simplify">
+ltn12.sink.<b>simplify(</b>sink<b>)</b>
+</p>
+
+<p class=description>
+Creates and returns a simple sink given a fancy <tt>sink</tt>. 
+</p>
+
+<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="sink.table">
+ltn12.sink.<b>table(</b>[table]<b>)</b>
+</p>
+
+<p class=description>
+Creates a sink that stores all chunks in a table. The chunks can later be
+efficiently concatenated into a single string.
+</p>
+
+<p class=parameters>
+<tt>Table</tt> is used to hold the chunks. If
+<tt><b>nil</b></tt>, the function creates its own table. 
+</p>
+
+<p class=return>
+The function returns the sink and the table. 
+</p>
+
+<pre class=example>
+-- load needed modules
+local http = require("http")
+local ltn12 = require("ltn12")
+
+-- the http.get function
+function get(u)
+  local t = {}
+  local respt = request{
+    url = u,
+    sink = ltn12.sink.table(t)
+  }
+  return table.concat(t), respt.headers, respt.code, respt.error
+end
+</pre>
+
+<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h3 id="source">Sources</h3>
+
+<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.cat">
+ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
+source<sub>N</sub>]<b>)</b>
+</p>
+
+<p class=description>
+Creates a new source that produces the concatenation of the data produced
+by a number of sources. 
+</p>
+
+<p class=parameters>
+<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
+sources. 
+</p>
+
+<p class=return>
+The function returns the new source.
+</p>
+
+<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.chain">
+ltn12.source.<b>chain(</b>source, filter<b>)</b>
+</p>
+
+<p class=description>
+Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> 
+before returning it. 
+</p>
+
+<p class=return>
+The function returns the new source.
+</p>
+
+<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.empty">
+ltn12.source.<b>empty()</b>
+</p>
+
+<p class=description>
+Creates and returns an empty source. 
+</p>
+
+<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.error">
+ltn12.source.<b>error(</b>message<b>)</b>
+</p>
+
+<p class=description>
+Creates and returns a source that aborts transmission with an error
+<tt>message</tt>.
+</p>
+
+<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.file">
+ltn12.source.<b>file(</b>handle, message<b>)</b>
+</p>
+
+<p class=description>
+Creates a source that produces the contents of a file. 
+</p>
+
+<p class=parameters>
+<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, 
+<tt>message</tt> should give the reason for failure. 
+</p>
+
+<p class=return>
+The function returns a source that reads chunks of data from 
+given <tt>handle</tt> and returns it to the user,
+closing the file when done, or a source that aborts the transmission with
+an error <tt>message</tt>
+</p>
+
+<p class=note>
+In the following example, notice how the prototype is designed to 
+fit nicely with the <tt>io.open</tt> function.
+</p>
+
+<pre class=example>
+-- load the ltn12 module
+local ltn12 = require("ltn12")
+
+-- copy a file
+ltn12.pump.all(
+  ltn12.source.file(io.open("original.png")),
+  ltn12.sink.file(io.open("copy.png"))
+)
+</pre>
+
+<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.simplify">
+ltn12.source.<b>simplify(</b>source<b>)</b>
+</p>
+
+<p class=description>
+Creates and returns a simple source given a fancy <tt>source</tt>. 
+</p>
+
+<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="source.string">
+ltn12.source.<b>string(</b>string<b>)</b>
+</p>
+
+<p class=description>
+Creates and returns a source that produces the contents of a
+<tt>string</tt>, chunk by chunk. 
+</p>
+
+<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<div class=footer>
+<hr>
+<center>
+<p class=bar>
+<a href="home.html">home</a> &middot;
+<a href="home.html#down">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a>
+</p>
+<p>
+<small>
+Last modified by Diego Nehab on <br>
+Sat Aug 9 01:00:41 PDT 2003
+</small>
+</p>
+</center>
+</div>
+
+</body>
+</html>
diff --git a/doc/mime.html b/doc/mime.html
new file mode 100644
index 0000000..d2fcc3c
--- /dev/null
+++ b/doc/mime.html
@@ -0,0 +1,428 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+
+<head>
+<title>LuaSocket: Network support for the Lua language</title>
+<link rel="stylesheet" href="reference.css" type="text/css">
+</head>
+
+<body>
+
+<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<div class=header>
+<hr>
+<center>
+<table summary="LuaSocket logo">
+<tr><td align=center><a href="http://www.lua.org">
+<img border=0 alt="LuaSocket" src="luasocket.png">
+</a></td></tr>
+<tr><td align=center valign=top>Network support for the Lua language
+</td></tr>
+</table>
+<p class=bar>
+<a href="home.html">home</a> &middot;
+<a href="home.html#download">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a> 
+</p>
+</center>
+<hr>
+</div>
+
+<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h2 id=mime>MIME</h2> 
+
+<p>
+The MIME module offers filters that apply and remove common
+content transfer encodings, such as Base64 and Quoted-Printable.
+It also provides functions to break text into lines and change
+the end-of-line convention.
+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/rfc2048.txt">2049</a>.
+</p>
+
+<p>
+All functionality provided by the MIME module 
+follows the ideas presented in 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
+LTN012, Filters sources and sinks</a>. 
+</p>
+
+<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h3 id=high>High-level filters</h3>
+
+<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="normalize">
+mime.<b>normalize(</b>[marker]<b>)</b>
+</p>
+
+<p class=description>
+Converts most common end-of-line markers to a specific given marker. 
+</p>
+
+<p class=parameters>
+<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic 
+end-of-line marker defined by the MIME standard.
+</p>
+
+<p class=return>
+The function returns a filter that performs the conversion. 
+</p>
+
+<p class=note>
+Note: There is no perfect solution to this problem. Different end-of-line
+markers are an evil that will probably plague developers forever. 
+This function, however, will work perfectly for text created with any of
+the most common end-of-line markers, i.e. the MacOS (CR), the Unix (LF), 
+or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
+markers, the function will still work well, although it doesn't 
+guarantee that the number of empty lines will be correct.
+</p>
+
+<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="decode">
+mime.<b>decode(</b>"base64"<b>)</b><br>
+mime.<b>decode(</b>"quoted-printable"<b>)</b>
+</p>
+
+<p class=description>
+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">
+mime.<b>encode(</b>"base64"<b>)</b><br>
+mime.<b>encode(</b>"quoted-printable" [, mode])</b>
+</p>
+
+<p class=description>
+Returns a filter that encodes data according to a given transfer content
+encoding.
+</p>
+
+<p class=parameters>
+In the Quoted-Printable case, the user can specify whether the data is
+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
+added flexibility). 
+Below is a filter that converts binary data to the Base64 transfer content
+encoding and breaks it into lines of the correct size.
+</p>
+
+<pre class=example>
+base64 = ltn12.filter.chain(
+  mime.encode("base64"),
+  mime.wrap("base64")
+)
+</pre>
+
+<p class=note>
+Note: Text data <em>has</em> to be converted to canonic form
+<em>before</em> being encoded.
+</p>
+
+<pre class=example>
+base64 = ltn12.filter.chain(
+  mime.normalize(),
+  mime.encode("base64"),
+  mime.wrap("base64")
+)
+</pre>
+
+<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="wrap">
+mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
+mime.<b>wrap(</b>"base64"<b>)</b><br>
+mime.<b>wrap(</b>"quoted-printable"<b>)</b>
+</p>
+
+<p class=description>
+Returns a filter that breaks data into lines. 
+</p>
+
+<p class=parameters>
+The "<tt>text</tt>" line-wrap filter simply breaks text into lines by 
+inserting CRLF end-of-line markers at appropriate positions. 
+<tt>Length</tt> defaults 76. 
+The "<tt>base64</tt>" line-wrap filter works just like the default
+"<tt>text</tt>" line-wrap filter with default length. 
+The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
+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>
+
+<pre class=example>
+qp = ltn12.filter.chain(
+  mime.normalize(),
+  mime.encode("quoted-printable"),
+  mime.wrap("quoted-printable")
+)
+</pre>
+
+<p class=note>
+Note: To break into lines with a different end-of-line convention, apply
+a normalization filter after the line break filter. 
+</p>
+
+<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h3 id=low>Low-level filters</h3>
+
+<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="b64">
+A, B = mime.<b>b64(</b>C [, D]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to perform Base64 encoding. 
+</p>
+
+<p class=description>
+<tt>A</tt> is the encoded version of the largest prefix of 
+<tt>C..D</tt> 
+that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of 
+<tt>C..D</tt>, <em>before</em> encoding. 
+If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with 
+the encoding of the remaining bytes of <tt>C</tt>. 
+</p>
+
+<p class=note>
+Note: The simplest use of this function is to encode a string into it's
+Base64 transfer content encoding. Notice the extra parenthesis around the
+call to <tt>mime.b64</tt>, to discard the second return value.
+</p>
+
+<pre class=example>
+print((mime.b64("diego:password")))
+--&gt; ZGllZ286cGFzc3dvcmQ=
+</pre>
+
+<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="eol">
+A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to perform end-of-line marker translation. 
+For each chunk, the function needs to know if the last character of the
+previous chunk could be part of an end-of-line marker or not. This is the
+context the function receives besides the chunk.  An updated version of
+the context is returned after each new chunk. 
+</p>
+
+<p class=description>
+<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
+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
+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>
+-- translates the end-of-line marker to UNIX
+unix = mime.eol(0, dos, "\n") 
+</pre>
+
+<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="qp">
+A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to perform Quoted-Printable encoding. 
+</p>
+
+<p class=description>
+<tt>A</tt> is the encoded version of the largest prefix of 
+<tt>C..D</tt> 
+that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of 
+<tt>C..D</tt>, <em>before</em> encoding. 
+If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with 
+the encoding of the remaining bytes of <tt>C</tt>. 
+Throughout encoding, occurences of CRLF are replaced by the 
+<tt>marker</tt>, which itself defaults to CRLF.
+</p>
+
+<p class=note>
+Note: The simplest use of this function is to encode a string into it's
+Quoted-Printable transfer content encoding. 
+Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
+</p>
+
+<pre class=example>
+print((mime.qp("maçã")))
+--&gt; ma=E7=E3=
+</pre>
+
+<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="qpwrp">
+A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to break Quoted-Printable text into lines. 
+</p>
+
+<p class=description>
+<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most 
+<tt>length</tt> bytes (defaults to 76). 
+'<tt>n</tt>' should tell how many bytes are left for the first 
+line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes 
+left in the last line of <tt>A</tt>. 
+</p>
+
+<p class=note>
+Note: Besides breaking text into lines, this function makes sure the line
+breaks don't fall in the middle of an escaped character combination. Also,
+this function only breaks lines that are bigger than <tt>length</tt> bytes.
+</p>
+
+<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="unb64">
+A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to perform Base64 decoding. 
+</p>
+
+<p class=description>
+<tt>A</tt> is the decoded version of the largest prefix of 
+<tt>C..D</tt> 
+that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of 
+<tt>C..D</tt>, <em>before</em> decoding. 
+If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
+and <tt>B</tt> returns whatever couldn't be decoded. 
+</p>
+
+<p class=note>
+Note: The simplest use of this function is to decode a string from it's
+Base64 transfer content encoding. 
+Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
+</p>
+
+<pre class=example>
+print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
+--&gt; diego:password
+</pre>
+
+<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="unqp">
+A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to remove the Quoted-Printable transfer content encoding
+from data. 
+</p>
+
+<p class=description>
+<tt>A</tt> is the decoded version of the largest prefix of 
+<tt>C..D</tt> 
+that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of 
+<tt>C..D</tt>, <em>before</em> decoding. 
+If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with 
+the encoding of the remaining bytes of <tt>C</tt>. 
+</p>
+
+<p class=note>
+Note: The simplest use of this function is to decode a string from it's
+Quoted-Printable transfer content encoding. 
+Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
+</p>
+
+<pre class=example>
+print((mime.qp("ma=E7=E3=")))
+--&gt; maçã
+</pre>
+
+<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="wrp">
+A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
+</p>
+
+<p class=description>
+Low-level filter to break text into lines with CRLF marker. 
+Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form.
+</p>
+
+<p class=description>
+<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most 
+<tt>length</tt> bytes (defaults to 76). 
+'<tt>n</tt>' should tell how many bytes are left for the first 
+line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes 
+left in the last line of <tt>A</tt>. 
+</p>
+
+<p class=note>
+Note: This function only breaks lines that are bigger than 
+<tt>length</tt> bytes. The resulting line length does not include the CRLF
+marker.
+</p>
+
+
+<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<div class=footer>
+<hr>
+<center>
+<p class=bar>
+<a href="home.html">home</a> &middot;
+<a href="home.html#down">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a>
+</p>
+<p>
+<small>
+Last modified by Diego Nehab on <br>
+Sat Aug 9 01:00:41 PDT 2003
+</small>
+</p>
+</center>
+</div>
+
+</body>
+</html>
diff --git a/doc/reference.css b/doc/reference.css
index 607ac4f..7c8148d 100644
--- a/doc/reference.css
+++ b/doc/reference.css
@@ -10,6 +10,9 @@ tt {
 
 h1, h2, h3, h4 { margin-left: 0em; }
 
+
+h3 { padding-top: 1em; }
+
 p { margin-left: 1em; }
 
 p.name { 
diff --git a/doc/reference.html b/doc/reference.html
index ba519c0..ebcfb5b 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -36,7 +36,7 @@
 <h2>Reference</h2>
 
 <blockquote>
-<a href="dns.html">DNS services (socket.dns)</a>
+<a href="dns.html">DNS (in socket)</a>
 <blockquote>
 <a href="dns.html#toip">toip</a>,
 <a href="dns.html#tohostname">tohostname</a>,
@@ -47,31 +47,17 @@
 <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="ftp.html">FTP (socket.ftp)</a>
+<a href="ftp.html">FTP</a>
 <blockquote>
 <a href="ftp.html#get">get</a>,
-<a href="ftp.html#put">put</a>,
-<a href="ftp.html#open">open</a>.
+<a href="ftp.html#put">put</a>
 </blockquote>
 </blockquote>
 
-<!-- global +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<blockquote>
-<a href="global.html">Global symbols</a>
-<blockquote>
-<a href="global.html#LUASOCKET_LIBNAME">LUASOCKET_LIBNAME</a>,
-<a href="global.html#mime">mime</a>,
-<a href="global.html#ltn12">ltn12</a>,
-<a href="global.html#socket">socket</a>.
-</blockquote>
-</blockquote>
-</table>
-
 <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="http.html">HTTP (socket.http)</a>
+<a href="http.html">HTTP</a>
 <blockquote>
 <a href="http.html#get">get</a>,
 <a href="http.html#post">post</a>,
@@ -82,46 +68,45 @@
 <!-- ltn12 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="ltn12.html">LTN012 (ltn12)</a>
+<a href="ltn12.html">LTN12</a>
 <blockquote>
 <a href="ltn12.html#filter">filter</a>:
-<a href="ltn12.html#chain">chain</a>,
-<a href="ltn12.html#cycle">cycle</a>.
+<a href="ltn12.html#filter.chain">chain</a>,
+<a href="ltn12.html#filter.cycle">cycle</a>.
 </blockquote>
 <blockquote>
 <a href="ltn12.html#pump">pump</a>:
-<a href="ltn12.html#all">all</a>,
-<a href="ltn12.html#step">step</a>.
+<a href="ltn12.html#pump.all">all</a>,
+<a href="ltn12.html#pump.step">step</a>.
 </blockquote>
 <blockquote>
 <a href="ltn12.html#sink">sink</a>:
-<a href="ltn12.html#chain">chain</a>,
-<a href="ltn12.html#error">error</a>,
-<a href="ltn12.html#chain">file</a>,
-<a href="ltn12.html#file">null</a>,
-<a href="ltn12.html#simplify">simplify</a>,
-<a href="ltn12.html#table">table</a>.
+<a href="ltn12.html#sink.chain">chain</a>,
+<a href="ltn12.html#sink.error">error</a>,
+<a href="ltn12.html#sink.file">file</a>,
+<a href="ltn12.html#sink.null">null</a>,
+<a href="ltn12.html#sink.simplify">simplify</a>,
+<a href="ltn12.html#sink.table">table</a>.
 </blockquote>
 <blockquote>
 <a href="ltn12.html#source">source</a>: 
-<a href="ltn12.html#cat">cat</a>,
-<a href="ltn12.html#chain">chain</a>,
-<a href="ltn12.html#empty">empty</a>,
-<a href="ltn12.html#file">file</a>,
-<a href="ltn12.html#simplify">simplify</a>,
-<a href="ltn12.html#simplify">rewind</a>,
-<a href="ltn12.html#simplify">string</a>.
+<a href="ltn12.html#source.cat">cat</a>,
+<a href="ltn12.html#source.chain">chain</a>,
+<a href="ltn12.html#source.empty">empty</a>,
+<a href="ltn12.html#source.error">error</a>,
+<a href="ltn12.html#source.file">file</a>,
+<a href="ltn12.html#source.simplify">simplify</a>,
+<a href="ltn12.html#source.string">string</a>.
 </blockquote>
 </blockquote>
 
 <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="mime.html">MIME (mime) </a>
+<a href="mime.html">MIME</a>
 <blockquote>
 <a href="mime.html#high">high-level</a>:
 <a href="mime.html#normalize">normalize</a>,
-<a href="mime.html#chain">chain</a>,
 <a href="mime.html#decode">decode</a>,
 <a href="mime.html#encode">encode</a>,
 <a href="mime.html#wrap">wrap</a>.
@@ -141,9 +126,8 @@
 <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="smtp.html">SMTP (socket.smtp)</a>
+<a href="smtp.html">SMTP</a>
 <blockquote>
-<a href="smtp.html#mail">open</a>,
 <a href="smtp.html#message">message</a>,
 <a href="smtp.html#send">send</a>.
 </blockquote>
@@ -152,26 +136,20 @@
 <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="socket.html">The socket namespace (socket)</a>
+<a href="socket.html">Socket</a>
 <blockquote>
-<a href="tcp.html#bind">bind</a>,
-<a href="tcp.html#connect">connect</a>,
-<a href="socket.html#debug">debug</a>,
+<a href="socket.html#debug">DEBUG</a>,
 <a href="dns.html#dns">dns</a>,
-<a href="ftp.html#ftp">ftp</a>,
-<a href="http.html#http">http</a>,
 <a href="socket.html#protect">protect</a>,
 <a href="socket.html#select">select</a>,
 <a href="socket.html#sink">sink</a>,
 <a href="socket.html#source">source</a>,
 <a href="socket.html#sleep">sleep</a>,
-<a href="smtp.html#smtp">smtp</a>,
 <a href="socket.html#time">time</a>,
 <a href="tcp.html#tcp">tcp</a>,
 <a href="socket.html#try">try</a>,
 <a href="udp.html#udp">udp</a>,
-<a href="url.html#url">url</a>,
-<a href="socket.html#version">version</a>.
+<a href="socket.html#version">VERSION</a>.
 </blockquote>
 </blockquote>
 </table>
@@ -179,7 +157,7 @@
 <!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="tcp.html">TCP (socket.tcp)</a>
+<a href="tcp.html">TCP (in socket)</a>
 <blockquote>
 <a href="tcp.html#accept">accept</a>,
 <a href="tcp.html#bind">bind</a>,
@@ -198,7 +176,7 @@
 <!-- udp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="udp.html">UDP (socket.udp)</a>
+<a href="udp.html">UDP (in socket)</a>
 <blockquote>
 <a href="udp.html#close">close</a>,
 <a href="udp.html#getpeername">getpeername</a>,
@@ -210,23 +188,22 @@
 <a href="udp.html#setpeername">setpeername</a>,
 <a href="udp.html#setsockname">setsockname</a>,
 <a href="udp.html#setoption">setoption</a>,
-<a href="udp.html#settimeout">settimeout</a>,
-<a href="udp.html#settimeout">shutdown</a>.
+<a href="udp.html#settimeout">settimeout</a>.
 </blockquote>
 </blockquote>
 
 <!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="url.html">URL (socket.url) </a>
+<a href="url.html">URL</a>
 <blockquote>
 <a href="url.html#absolute">absolute</a>,
 <a href="url.html#build">build</a>,
 <a href="url.html#build_path">build_path</a>,
-<a href="url.html#quote">quote</a>,
+<a href="url.html#escape">escape</a>,
 <a href="url.html#parse">parse</a>,
 <a href="url.html#parse_path">parse_path</a>,
-<a href="url.html#quote">unquote</a>.
+<a href="url.html#unescape">unescape</a>.
 </blockquote>
 </blockquote>
 
diff --git a/doc/smtp.html b/doc/smtp.html
index 0862de0..b0ae634 100644
--- a/doc/smtp.html
+++ b/doc/smtp.html
@@ -35,15 +35,22 @@
 
 <h2 id=smtp>SMTP</h2> 
 
-<p>
-The  <tt>smtp.lua</tt> module  provides functionality  to  send  e-mail
+<p> The  <tt>smtp.lua</tt> module  provides functionality to send e-mail
 messages. The implementation conforms to the Simple Mail Transfer Protocol,
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
-The other RFC of interest in this implementation is 
-<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
+Another RFC of interest is <a
+href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
 which governs the Internet Message Format.
+Multipart messages (those that contain attatchments) are part
+of the MIME standard, but described mainly
+in <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2046.txt">RFC
+2046</a>
 
-</p>
+<p> In the description below, good understanding of <a
+href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
+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>
 MIME headers are represented as a Lua table in the form:
@@ -78,29 +85,56 @@ Note: MIME headers are independent of order. Therefore, there is no problem
 in representing them in a Lua table. 
 </p>
 
-<!-- mail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p>
+The following constants can be set to control the default behaviour of
+the SMTP module: 
+</p>
 
-<p class=name id=mail> 
-socket.smtp.<b>mail{</b><br>
+<ul>
+<li> <tt>DOMAIN</tt>: domain used to greet the server;
+<li> <tt>PORT</tt>: default port used for the connection;
+<li> <tt>SERVER</tt>: default server used for the connection;
+<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;
+<li> <tt>ZONE</tt>: default time zone.
+</ul>
+
+<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=send> 
+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;body = <i>string</i>,<br>
-&nbsp;&nbsp;headers = <i>headers-table</i>,<br>
-&nbsp;&nbsp;server = <i>string</i><br>
+&nbsp;&nbsp;source = <i>LTN12 source</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>
 
 <p class=description>
-Sends a message to a recipient list.
+Sends a message to a recipient list. Since sending messages is not as
+simple as downloading an URL from a FTP or HTTP server, this function 
+doesn't have a simple interface. However, see the 
+<a href=#message><tt>message</tt></a> source factory for 
+a very powerful way to define the message contents.
 </p>
 
 <p class=parameters>
-<tt>Rcpt</tt> is a Lua table with one entry for each recipient, or a string
+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 sender is given by the e-mail address <tt>from</tt>. 
-The message is composed by the optional MIME Headers <tt>headers</tt> 
-and text <tt>body</tt>. The message is  sent using  the server  
-<tt>server</tt>. 
+The contents of the message are given by a LTN12 <tt>source</tt>. Several
+arguments are optional:
+<ul>
+<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";
+<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
+source to the server. Defaults to the LTN12 <tt>pump.step</tt> function.
+</ul>
 </p>
 
 <p class=return> 
@@ -109,6 +143,13 @@ If  successful, the function returns 1. Otherwise, the function returns
 </p>
 
 <p class=note>
+Note: SMTP servers are can be very picky with the format of e-mail
+addresses. To be safe, use only addresses of the form
+"<tt>&lt;fulano@tecgraf.puc-rio.br&gt;</tt>" in the <tt>from</tt> and
+<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail
+addresses can take whatever form you like.  </p>
+
+<p class=note>
 Big note: There is a good deal of misconception with the use of the
 destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
 and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
@@ -117,11 +158,12 @@ exact opposite of what you expect.
 </p>
 
 <p class=note>
-Only recipients specified in the recipient list will receive a copy of the
+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 are
-considered as part of the message. The list of recipients is <em>not</em>
-part of the message.  
+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 
+<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>
 
 <p class=note>
@@ -143,9 +185,9 @@ Copy") contains addresses of recipients of the message whose addresses are not t
 </ul> 
 
 <p class=note>
-The LuaSocket <tt>mail</tt> function does not interpret the headers you 
-pass to, but it gives you full control over what is sent and to whom 
-it is sent:
+The LuaSocket <tt>send</tt> function does not care or interpret the 
+headers you send, but it gives you full control over what is sent and 
+to whom it is sent:
 </p>
 <ul>
 <li> If someone is to receive the message, the e-mail address <em>has</em>
@@ -171,36 +213,147 @@ and
 </p>
 
 <pre class=example>
+-- load the smtp support
+local smtp = require("smtp")
+
 -- Connects to server "localhost" and sends a message to users
 -- "fulano@tecgraf.puc-rio.br",  "beltrano@tecgraf.puc-rio.br", 
 -- and "sicrano@tecgraf.puc-rio.br".
 -- Note that "fulano" is the primary recipient, "beltrano" receives a
 -- carbon copy and neither of them knows that "sicrano" received a blind
 -- carbon copy of the message.
-headers = {
-  to = "fulano@tecgraf.puc-rio.br",
-  cc = "beltrano@tecgraf.puc-rio.br",
-  subject = "LuaSocket test message"
-}
-
-from = "luasocket@tecgraf.puc-rio.br"
+from = "&lt;luasocket@tecgraf.puc-rio.br&gt;"
 
 rcpt = {
-  "fulano@tecgraf.puc-rio.br",
-  "beltrano@tecgraf.puc-rio.br",
-  "sicrano@tecgraf.puc-rio.br"
+  "&lt;fulano@tecgraf.puc-rio.br&gt;",
+  "&lt;beltrano@tecgraf.puc-rio.br&gt;",
+  "&lt;sicrano@tecgraf.puc-rio.br&gt;"
 }
 
-body = "This is a test message. Please ignore."
-
-server = "localhost"
+mesgt = {
+  headers = {
+    to = "Fulano da Silva &lt;fulano@tecgraf.puc-rio.br&gt;",
+    cc = '"Beltrano F. Nunes" &lt;beltrano@tecgraf.puc-rio.br&gt;',
+    subject = "My first message"
+  }
+  body = "I hope this works. If it does, I can send you another 1000 copies."
+}
 
-r, e = socket.smtp.mail{
+r, e = smtp.send{
   from = from,
   rcpt = rcpt, 
-  headers = headers, 
-  body = body, 
-  server = server
+  source = smtp.message(mesgt)
+}
+</pre>
+
+<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=message> 
+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). 
+</p>
+
+<p class=parameters>
+The only parameter of the function is a table describing the message.
+<tt>Mesgt</tt> has the following form (notice the recursive structure):
+</p>
+
+<blockquote>
+<table summary="Mesgt table structure">
+<tr><td><tt>
+mesgt = {<br>
+&nbsp;&nbsp;headers = <i>header-table</i>,<br>
+&nbsp;&nbsp;body = <i>LTN12 source</i> or <i>string</i> or 
+<i>multipart-mesgt</i><br>
+}<br>
+&nbsp;<br>
+multipart-mesgt = {<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>
+}<br>
+</tt></td></tr>
+</table>
+</blockquote>
+
+<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.
+</p>
+
+<p class=return> 
+The function returns an LTN12 source that produces the message contents as
+defined by <tt>mesgt</tt>.  Hopefuly, the following example will make
+things clear. When in doubt, refer to the appropriate RFC as listed in the
+introduction.  </p>
+
+<pre class=example>
+-- load the smtp support and its friends
+local smtp = require("smtp")
+local mime = require("mime")
+local ltn12 = require("ltn12")
+
+-- creates a source to send a message with two parts. The first part is 
+-- plain text, the second part is a PNG image, encoded as base64.
+source = smtp.message{
+  headers = {
+     -- Remember that headers are *ignored* by smtp.send. 
+     from = "Sicrano de Oliveira &lt;sicrano@tecgraf.puc-rio.br&gt;",
+     to = "Fulano da Silva &lt;fulano@tecgraf.puc-rio.br&gt;",
+     subject = "Here is a message with attachments"
+  },
+  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.",
+    -- first part: no headers means plain text, us-ascii.
+    -- The mime.eol low-level filter normalizes end-of-line markers.
+    [1] = { 
+      body = mime.eol(0, [[
+        Lines in a message body should always end with CRLF. 
+        The smtp module will *NOT* perform translation. It will
+        perform necessary stuffing or '.' characters, though.
+      ]])
+    },
+    -- second part: headers describe content to be a png image, 
+    -- sent under the base64 transfer content encoding.
+    -- notice that nothing happens until the message is actually sent. 
+    -- small chunks are loaded into memory right before transmission and 
+    -- translation happens on the fly.
+    [2] = { 
+      headers = {
+        ["content-type"] = 'image/png; name="image.png"',
+        ["content-disposition"] = 'attachment; filename="image.png"',
+        ["content-description"] = 'a beautiful image',
+        ["content-transfer-encoding"] = "BASE64"
+      },
+      body = ltn12.source.chain(
+        ltn12.source.file(io.open("image.png", "rb")),
+        ltn12.filter.chain(
+          mime.encode("base64"),
+          mime.wrap()
+        )
+      )
+    },
+    epilogue = "This might also show up, but after the attachments"
+  }
+}
+
+-- finally send it
+r, e = smtp.send{
+    from = "&lt;sicrano@tecgraf.puc-rio.br&gt;",
+    rcpt = "&lt;fulano@tecgraf.puc-rio.br&gt;",
+    source = source,
 }
 </pre>
 
diff --git a/doc/socket.html b/doc/socket.html
index bde882b..eccc676 100644
--- a/doc/socket.html
+++ b/doc/socket.html
@@ -36,16 +36,13 @@
 <h2 id=socket>The socket namespace</h2> 
 
 <p>
-The <tt>socket</tt> namespace contains the namespace tables for all
-LuaSocket modules as well as function that didn't belong in any specific 
-module, functions that are so commonly used that deserve a shortcut and a
-few constants.
+The <tt>socket</tt> namespace contains the core functionality of LuaSocket. 
 </p>
 
 <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=debug> 
-socket.<b>debug</b>
+socket.<b>DEBUG</b>
 </p>
 
 <p class=description>
@@ -57,7 +54,7 @@ with debug support.
 <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=protect> 
-socket.<b>protect(</b>function<b>)</b>
+socket.<b>protect(</b>func<b>)</b>
 </p>
 
 <p class=description>
@@ -65,12 +62,12 @@ Converts a function that throws exceptions into a safe function.
 </p>
 
 <p class=parameters>
-<tt>Function</tt> is a function that calls 
+<tt>Funct</tt> is a function that calls 
 <a href=#try><tt>try</tt></a> to throw exceptions. 
 </p>
 
 <p class=return>
-The function an equivalent function that instead of throwing exceptoins,
+Returns an equivalent function that instead of throwing exceptions,
 returns <tt><b>nil</b></tt> followed by an error message. 
 </p>
 
@@ -103,16 +100,16 @@ simplify the test if a specific socket has changed status.
 </p>
 
 <p class=note>
-<b>Important Note</b>: a known bug in WinSock causes <tt>select</tt> to fail 
+<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail 
 on non-blocking TCP sockets. The function may return a socket as
 writable even though the socket is <em>not</em> ready for sending.
 </p>
 
 <p class=note>
-<b>Important note</b>: calling select with a server socket in the receive
+<b>Another important note</b>: calling select with a server socket in the receive
 parameter before a call to accept does <em>not</em> guarantee
 <a href=tcp.html#accept><tt>accept</tt></a> will return immediately. 
-Use the <a href=tcp.html#timeout><tt>timeout</tt></a> 
+Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a> 
 method or <tt>accept</tt> might block forever.  
 </p>
 
@@ -131,7 +128,7 @@ socket.<b>sink(</b>mode, socket<b>)</b>
 
 <p class=description>
 Creates an 
-<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN012</a>
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
 sink from a stream socket object. 
 </p>
 
@@ -163,7 +160,7 @@ socket.<b>source(</b>mode, socket [, length]<b>)</b>
 
 <p class=description>
 Creates an 
-<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN012</a>
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
 source from a stream socket object. 
 </p>
 
@@ -217,7 +214,7 @@ c = socket.try(socket.connect("localhost", 80))
 <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=version> 
-socket.<b>version</b>
+socket.<b>VERSION</b>
 </p>
 
 <p class=description>
diff --git a/doc/tcp.html b/doc/tcp.html
index 34d6c6e..7a49660 100644
--- a/doc/tcp.html
+++ b/doc/tcp.html
@@ -241,18 +241,16 @@ method returns <b><tt>nil</tt></b> followed by an error message.
 <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=receive>
-client:<b>receive(</b>[pattern<sub>1</sub>, pattern<sub>2</sub>,
-... pattern<sub>N</sub>]<b>)</b>
+client:<b>receive(</b>[pattern]<b>)</b>
 </p>
 
 <p class=description>
 Reads data from a client object, according to the specified <em>read
-patterns</em>.  Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. 
+pattern</em>.  Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. 
 </p>
 
 <p class=parameters>
-The parameters <tt>pattern</tt><sub>1</sub>, <tt>pattern</tt><sub>2</sub>, ...
-<tt>pattern</tt><sub>N</sub> can be any of the following: 
+<tt>Pattern</tt> can be any of the following: 
 </p>
 
 <ul>
@@ -267,16 +265,21 @@ of bytes from the socket.
 </ul>
 
 <p class=return>
-The method  returns one value for  each pattern, followed by  a single
-error  code that  can be  <b><tt>nil</tt></b> in  case of  success, the  string
-'<tt>closed</tt>'  in   case  the  connection  was   closed  before  the
-transmission  was completed  or  the string  '<tt>timeout</tt>' in  case
-there was a timeout during  the operation. 
+If successful, the method returns the received pattern. In case of error,
+the method returns <tt><b>nil</b></tt> followed by an error message which
+can be the string '<tt>closed</tt>'  in   case  the  connection  was
+closed  before  the transmission  was completed  or  the string
+'<tt>timeout</tt>' in  case there was a timeout during  the operation.
+Also, after the error message, the function returns the partial result of
+the transmission.
 </p>
 
 <p class=note>
-Note: In case of error, the method always return everything it managed
-to download before the error condition was met.
+<b>Important note</b>: This function was changed <em>severely</em>. It used
+to support multiple patterns (but I have never seen this feature used) and
+partial results used to be returned in the same way as successful results.
+This last feature violated the idea that all functions should return
+<tt><b>nil</b></tt> on error.  Thus the change.  
 </p>
 
 <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -428,7 +431,7 @@ client:<b>shutdown(</b>mode<b>)</b><br>
 </p>
 
 <p class=description>
-Shuts down part of a full duplex connection. 
+Shuts down part of a full-duplex connection. 
 </p>
 
 <p class=parameters>
diff --git a/doc/udp.html b/doc/udp.html
index 9f5cf8f..5ae0a89 100644
--- a/doc/udp.html
+++ b/doc/udp.html
@@ -29,6 +29,11 @@
 <hr>
 </div>
 
+
+<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h2 id=udp>UDP</h2> 
+
 <!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class="name" id="socket.udp">
diff --git a/doc/url.html b/doc/url.html
index f3a7cb7..cd699a2 100644
--- a/doc/url.html
+++ b/doc/url.html
@@ -59,7 +59,7 @@ An URL is defined by the following grammar:
 <!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=absolute>
-socket.url.<b>absolute(</b>base, relative<b>)</b>
+url.<b>absolute(</b>base, relative<b>)</b>
 </p>
 
 <p class=description>
@@ -79,7 +79,7 @@ The function returns a string with the absolute URL.
 Note: The rules that
 govern the composition are fairly complex, and are described in detail in
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC 2396</a>.
-The example bellow should give an idea of what are the rules.
+The example bellow should give an idea of what the rules are.
 </p>
 
 <pre class=example>
@@ -114,7 +114,7 @@ g;x?y#s  =  http://a/b/c/g;x?y#s
 <!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=build>
-socket.url.<b>build(</b>parsed_url<b>)</b>
+url.<b>build(</b>parsed_url<b>)</b>
 </p>
 
 <p class=description>
@@ -135,7 +135,7 @@ The function returns a string with the built URL.
 <!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=build_path>
-socket.url.<b>build_path(</b>segments, unsafe<b>)</b>
+url.<b>build_path(</b>segments, unsafe<b>)</b>
 </p>
 
 <p class=description>
@@ -157,10 +157,39 @@ The  function  returns   a string with the
 built <tt>&lt;path&gt;</tt> component. 
 </p>
 
+<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="escape">
+url.<b>escape(</b>content<b>)</b>
+</p>
+
+<p class=description>
+Applies the URL escaping content coding to a string
+Each byte is encoded as a percent character followed
+by the two byte hexadecimal representation of its integer 
+value.
+</p>
+
+<p class=parameters>
+<tt>Content</tt> is the string to be encoded.
+</p>
+
+<p class=result>
+The function returns the encoded string.
+</p>
+
+<pre class=example>
+-- load url module
+url = require("url")
+
+code = url.escape("/#?;")
+-- code = "%2f%23%3f%3b"
+</pre>
+
 <!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=parse>
-socket.url.<b>parse(</b>url, default<b>)</b>
+url.<b>parse(</b>url, default<b>)</b>
 </p>
 
 <p class=description>
@@ -196,7 +225,10 @@ parsed_url = {<br>
 </tt></blockquote>
 
 <pre class=example>
-parsed_url = socket.url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there")
+-- load url module
+url = require("url")
+
+parsed_url = url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there")
 -- parsed_url = {
 --   scheme = "http",
 --   authority = "www.puc-rio.br",
@@ -206,7 +238,7 @@ parsed_url = socket.url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there"
 --   host = "www.puc-rio.br",
 -- }
 
-parsed_url = socket.url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
+parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
 -- parsed_url = {
 --   scheme = "ftp",
 --   authority = "root:passwd@unsafe.org",
@@ -222,7 +254,7 @@ parsed_url = socket.url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i
 <!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=parse_path>
-socket.url.<b>parse_path(</b>path<b>)</b>
+url.<b>parse_path(</b>path<b>)</b>
 </p>
 
 <p class=description>
@@ -241,36 +273,10 @@ returning a list with all the parsed segments, the function unescapes all
 of them. 
 </p>
 
-<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-
-<p class=name id="escape">
-socket.url.<b>escape(</b>content<b>)</b>
-</p>
-
-<p class=description>
-Applies the URL escaping content coding to a string
-Each byte is encoded as a percent character followed
-by the two byte hexadecimal representation of its integer 
-value.
-</p>
-
-<p class=parameters>
-<tt>Content</tt> is the string to be encoded.
-</p>
-
-<p class=result>
-The function returns the encoded string.
-</p>
-
-<pre class=example>
-code = socket.url.escape("/#?;")
--- code = "%2f%23%3f%3b"
-</pre>
-
 <!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id="unescape">
-socket.url.<b>unescape(</b>content<b>)</b>
+url.<b>unescape(</b>content<b>)</b>
 </p>
 
 <p class=description>