Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.

doc/src/guide/handlers.ezdoc

@@ -1,99 +0,0 @@
-::: Handlers
-
-Handlers are Erlang modules that handle HTTP requests.
-
-:: Plain HTTP handlers
-
-The most basic handler in Cowboy implements the mandatory
-`init/2` callback, manipulates the request, optionally
-sends a response and then returns.
-
-This callback receives the ^"Req object^req and the options
-defined during the ^"router configuration^routing^.
-
-A handler that does nothing would look like this:
-
-``` erlang
-init(Req, _Opts) ->
-    {ok, Req, #state{}}.
-```
-
-Despite sending no reply, a `204 No Content` reply will be
-sent to the client, as Cowboy makes sure that a reply is
-sent for every request.
-
-We need to use the Req object for sending a reply.
-
-``` erlang
-init(Req, _Opts) ->
-    Req2 = cowboy_req:reply(200, [
-        {<<"content-type">>, <<"text/plain">>}
-    ], <<"Hello World!">>, Req),
-    {ok, Req2, #state{}}.
-```
-
-As you can see we return a 3-tuple. `ok` means that the
-handler ran successfully. The Req object is returned as
-it may have been modified as is the case here: replying
-returns a modified Req object that you need to return
-back to Cowboy for proper operations.
-
-The last value of the tuple is a state that will be used
-in every subsequent callbacks to this handler. Plain HTTP
-handlers only have one additional callback, the optional
-`terminate/3`.
-
-:: Other handlers
-
-The `init/2` callback can also be used to inform Cowboy
-that this is a different kind of handler and that Cowboy
-should switch to it. To do this you simply need to return
-the module name of the handler type you want to switch to.
-
-Cowboy comes with three handler types you can switch to:
-^"cowboy_rest^rest_handlers^, ^"cowboy_websocket^ws_handlers^
-and ^"cowboy_loop^loop_handlers^. In addition to those you
-can define your own handler types.
-
-Switching is simple. Instead of returning `ok`, you simply
-return the name of the handler type you want to use. The
-following snippet switches to a Websocket handler:
-
-``` erlang
-init(Req, _Opts) ->
-	{cowboy_websocket, Req, #state{}}.
-```
-
-You can also switch to your own custom handler type:
-
-``` erlang
-init(Req, _Opts) ->
-	{my_handler_type, Req, #state{}}.
-```
-
-How to implement a custom handler type is described in the
-^"Sub protocols^sub_protocols chapter.
-
-:: Cleaning up
-
-All handlers coming with Cowboy allow the use of the optional
-`terminate/3` callback.
-
-``` erlang
-terminate(_Reason, Req, State) ->
-    ok.
-```
-
-This callback is strictly reserved for any required cleanup.
-You cannot send a response from this function. There is no
-other return value.
-
-If you used the process dictionary, timers, monitors or may
-be receiving messages, then you can use this function to clean
-them up, as Cowboy might reuse the process for the next
-keep-alive request.
-
-Note that while this function may be called in a Websocket
-handler, it is generally not useful to do any clean up as
-the process terminates immediately after calling this callback
-when using Websocket.