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>