Salvage the README and move parts into the guide

guide/loop_handlers.md

@@ -12,6 +12,10 @@ a response.
 They are most useful when performing long-polling operations or
 when using server-sent events.
 
+While the same can be accomplished using plain HTTP handlers,
+it is recommended to use loop handlers because they are well-tested
+and allow using built-in features like hibernation and timeouts.
+
 Callbacks
 ---------
 
@@ -21,3 +25,30 @@ Usage
 -----
 
 @todo Explain how to use them.
+
+The following handler waits for a message `{reply, Body}` before
+sending a response. If this message doesn't arrive within 60
+seconds, it gives up and a `204 No Content` will be replied.
+It also hibernates the process to save memory while waiting for
+this message.
+
+``` erlang
+-module(my_loop_handler).
+-behaviour(cowboy_loop_handler).
+
+-export([init/3]).
+-export([info/3]).
+-export([terminate/2]).
+
+init({tcp, http}, Req, Opts) ->
+	{loop, Req, undefined_state, 60000, hibernate}.
+
+info({reply, Body}, Req, State) ->
+	{ok, Req2} = cowboy_req:reply(200, [], Body, Req),
+	{ok, Req2, State};
+info(Message, Req, State) ->
+	{loop, Req, State, hibernate}.
+
+terminate(Req, State) ->
+	ok.
+```

guide/ws_handlers.md

@@ -4,12 +4,18 @@ Websocket handlers
 Purpose
 -------
 
-Websockets are an extension to HTTP to emulate plain TCP connections
+Websocket is an extension to HTTP to emulate plain TCP connections
 between the user's browser and the server. Requests that are upgraded
 are then handled by websocket handlers.
 
 Both sides of the socket can send data at any time asynchronously.
 
+Websocket is an IETF standard. Cowboy supports the standard and all
+the drafts that were previously implemented by browsers. Websocket
+is implemented by most browsers today, although for backward
+compatibility reasons a solution like [Bullet](https://github.com/extend/bullet)
+might be preferred.
+
 Callbacks
 ---------
 
@@ -19,3 +25,38 @@ Usage
 -----
 
 @todo Explain how to use them.
+
+The following handler sends a message every second. It also echoes
+back what it receives.
+
+``` erlang
+-module(my_ws_handler).
+-behaviour(cowboy_websocket_handler).
+
+-export([init/3]).
+-export([websocket_init/3]).
+-export([websocket_handle/3]).
+-export([websocket_info/3]).
+-export([websocket_terminate/3]).
+
+init({tcp, http}, Req, Opts) ->
+    {upgrade, protocol, cowboy_websocket}.
+
+websocket_init(TransportName, Req, _Opts) ->
+    erlang:start_timer(1000, self(), <<"Hello!">>),
+    {ok, Req, undefined_state}.
+
+websocket_handle({text, Msg}, Req, State) ->
+    {reply, {text, << "That's what she said! ", Msg/binary >>}, Req, State};
+websocket_handle(_Data, Req, State) ->
+    {ok, Req, State}.
+
+websocket_info({timeout, _Ref, Msg}, Req, State) ->
+    erlang:start_timer(1000, self(), <<"How' you doin'?">>),
+    {reply, {text, Msg}, Req, State};
+websocket_info(_Info, Req, State) ->
+    {ok, Req, State}.
+
+websocket_terminate(_Reason, _Req, _State) ->
+    ok.
+```