anchor.diff:  [[ws_handlers]]
  -== Handling Websocket connections
  -
  -A special handler is required for handling Websocket connections.
  -Websocket handlers allow you to initialize the connection,
  -handle incoming frames from the socket, handle incoming Erlang
  -messages and then clean up on termination.
  -
  -Websocket handlers essentially act as a bridge between the client
  -and the Erlang system. They will typically do little more than
  -socket communication and decoding/encoding of frames.
  -
  -=== Initialization
  -
  -First, the `init/2` callback is called. This callback is common
  -to all handlers. To establish a Websocket connection, this function
  -must return a `ws` tuple.
  +== Websocket handlers
  +
  +Websocket handlers provide an interface for upgrading HTTP/1.1
  +connections to Websocket and sending or receiving frames on
  +the Websocket connection.
  +
  +As Websocket connections are established through the HTTP/1.1
  +upgrade mechanism, Websocket handlers need to be able to first
  +receive the HTTP request for the upgrade, before switching to
  +Websocket and taking over the connection. They can then receive
  +or send Websocket frames, handle incoming Erlang messages or
  +close the connection.
  +
  +=== Upgrade
  +
  +The `init/2` callback is called when the request is received.
  +To establish a Websocket connection, you must switch to the
  +`cowboy_websocket` module:
   
   [source,erlang]
   ----
  
positive.code: 	end.
  ----
  
  It is not recommended to wait too long inside the `init/2`
  function. Any extra initialization may be done after returning by
  sending yourself a message before doing anything. Any message sent
  to `self()` from `init/2` is guaranteed to arrive before
  any frames from the client.
  
  It is also very easy to ensure that this message arrives before
  any message from other processes by sending it before registering
  or enabling timers.
  
  // @todo This doesn't even work.
  
  [source,erlang]
  ----
  init(Req, State) ->
  	self() ! post_init,
  	%% Register process here...
  	{cowboy_websocket, Req, State}.
  
  websocket_info(post_init, State) ->
  	%% Perform post_init initialization here...
  	{ok, State}.
  ----
  
  === Handling frames from the client
  
  Cowboy will call `websocket_handle/2` whenever a text, binary,
  ping or pong frame arrives from the client. Note that in the
  case of ping and pong frames, no action is expected as Cowboy
  automatically replies to ping frames.
  
  The handler can decide to send frames to the socket, stop
  or just continue without sending anything.
  
  The following snippet echoes back any text frame received and
  ignores all others.
  
  [source,erlang]
  ----
  
negative.code: 	{ok, State}.
  ----
  
  Note that ping and pong frames require no action from the
  handler as Cowboy will automatically reply to ping frames.
  They are provided for informative purposes only.
  
  === Receiving Erlang messages
  
  Cowboy will call `websocket_info/2` whenever an Erlang message
  arrives.
  
  The handler can handle or ignore the messages. It can also
  send frames to the client or stop the connection.
  
  The following snippet forwards log messages to the client
  and ignores all others:
  
  [source,erlang]
  ----
  