Salvage the README and move parts into the guide

1 files changed, 42 insertions, 1 deletions

diff --git a/guide/ws_handlers.md b/guide/ws_handlers.md
index fc5d953..226ada0 100644
--- a/guide/ws_handlers.md
+++ b/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.
+```