Add Introduction chapter to the guide

README.md

@@ -6,35 +6,40 @@ Cowboy is a small, fast and modular HTTP server written in Erlang.
 Goals
 -----
 
-Cowboy aims to provide the following advantages:
+Cowboy aims to provide a **complete** HTTP stack in a **small** code base.
+It is optimized for **low latency** and **low memory usage**, in parts
+because it uses **binary strings**.
 
-* **Small** code base.
-* Damn **fast**.
-* **Modular**: transport and protocol handlers are replaceable.
-* **Binary HTTP** for greater speed and lower memory usage.
-* Easy to **embed** inside another application.
-* Selectively **dispatch** requests to handlers, allowing you to send some
-  requests to your embedded code and others to a FastCGI application in
-  PHP or Ruby.
-* No parameterized module. No process dictionary. **Clean** Erlang code.
+Cowboy provides **routing** capabilities, selectively dispatching requests
+to handlers written in Erlang.
 
-The server is currently in early development. Comments and suggestions are
-more than welcome. To contribute, either open bug reports, or fork the project
-and send us pull requests with new or improved functionality. You should
-discuss your plans with us before doing any serious work, though, to avoid
-duplicating efforts.
+Because it uses Ranch for managing connections, Cowboy can easily be
+**embedded** in any other application.
+
+No parameterized module. No process dictionary. **Clean** Erlang code.
 
 Quick start
 -----------
 
-* Add Cowboy as a rebar or agner dependency to your application.
+* Add Cowboy as a rebar dependency to your application.
 * Start Cowboy and add one or more listeners.
 * Write handlers for your application.
-* Check out the `examples/` directory!
 
 Getting Started
 ---------------
 
+* [Read the guide](https://github.com/extend/cowboy/blob/master/guide/toc.md)
+* Look at the examples in the ```examples/``` directory
+* Build API documentation with ```make docs```; open ```doc/index.html```
+
+
+
+Old README
+----------
+
+This and all following sections will be removed as soon as their
+equivalent appear in the Cowboy guide.
+
 Cowboy does nothing by default.
 
 Cowboy uses Ranch for handling connections, and provides convenience

guide/introduction.md

@@ -0,0 +1,114 @@
+Introduction
+============
+
+Purpose
+-------
+
+Cowboy is a small, fast and modular HTTP server written in Erlang.
+
+Cowboy aims to provide a complete HTTP stack, including its derivatives
+SPDY, Websocket and REST. Cowboy currently supports HTTP/1.0, HTTP/1.1,
+Websocket (all implemented drafts + standard) and Webmachine-based REST.
+
+Cowboy is a high quality project. It has a small code base, is very
+efficient (both in latency and memory use) and can easily be embedded
+in another application.
+
+Cowboy is clean Erlang code. It bans the use of parameterized modules
+and the process dictionary. It includes documentation and typespecs
+for all public interfaces.
+
+Prerequisites
+-------------
+
+It is assumed the developer already knows Erlang and has basic knowledge
+about the HTTP protocol.
+
+In order to run the examples available in this user guide, you will need
+Erlang and rebar installed and in your $PATH.
+
+Please see the [rebar repository](https://github.com/basho/rebar) for
+downloading and building instructions. Please look up the environment
+variables documentation of your system for details on how to update the
+$PATH information.
+
+Conventions
+-----------
+
+In the HTTP protocol, the method name is case sensitive. All standard
+method names are uppercase.
+
+Header names are case insensitive. Cowboy converts all the request
+header names to lowercase, and expects your application to provide
+lowercase header names in the response.
+
+Getting started
+---------------
+
+Cowboy does nothing by default.
+
+Cowboy requires the `crypto` and `ranch` applications to be started.
+
+``` erlang
+ok = application:start(crypto).
+ok = application:start(ranch).
+ok = application:start(cowboy).
+```
+
+Cowboy uses Ranch for handling the connections and provides convenience
+functions to start Ranch listeners.
+
+The `cowboy:start_http/4` function starts a listener for HTTP connections
+using the TCP transport. The `cowboy:start_https/4` function starts a
+listener for HTTPS connections using the SSL transport.
+
+Listeners are named. They spawn a given number of acceptors, listen for
+connections using the given transport options and pass along the protocol
+options to the connection processes. The protocol options must include
+the dispatch list for routing requests to handlers.
+
+The dispatch list is explained in greater details in the Routing section
+of the guide.
+
+``` erlang
+Dispatch = [
+    %% {URIHost, list({URIPath, Handler, Opts})}
+    {'_', [{'_', my_handler, []}]}
+],
+%% Name, NbAcceptors, TransOpts, ProtoOpts
+cowboy:start_http(my_http_listener, 100,
+	[{port, 8080}],
+    [{dispatch, Dispatch}]
+).
+```
+
+Cowboy features many kinds of handlers. It has plain HTTP handlers, loop
+handlers, Websocket handlers, REST handlers and static handlers. Their
+usage is documented in the respective sections of the guide.
+
+Most applications use the plain HTTP handler, which has three callback
+functions: init/3, handle/2 and terminate/2. Following is an example of
+a simple handler module.
+
+``` erlang
+-module(my_handler).
+-behaviour(cowboy_http_handler).
+
+-export([init/3]).
+-export([handle/2]).
+-export([terminate/2]).
+
+init({tcp, http}, Req, Opts) ->
+    {ok, Req, undefined_state}.
+
+handle(Req, State) ->
+    {ok, Req2} = cowboy_req:reply(200, [], <<"Hello World!">>, Req),
+    {ok, Req2, State}.
+
+terminate(Req, State) ->
+    ok.
+```
+
+The `Req` variable above is the Req object, which allows the developer
+to obtain informations about the request and to perform a reply. Its usage
+is explained in its respective section of the guide.

guide/toc.md

@@ -0,0 +1,47 @@
+Cowboy User Guide
+=================
+
+ *  [Introduction](introduction.md)
+   *  Purpose
+   *  Prerequisites
+   *  Conventions
+   *  Getting started
+ *  Routing
+   *  Purpose
+   *  Dispatch rule
+   *  Match rules
+   *  Bindings
+ *  Handlers
+   *  Purpose
+   *  Protocol upgrades
+ *  HTTP handlers
+   *  Purpose
+   *  Callbacks
+   *  Usage
+ *  Loop handlers
+   *  Purpose
+   *  Callbacks
+   *  Usage
+ *  Websocket handlers
+   *  Purpose
+   *  Callbacks
+   *  Usage
+ *  REST handlers
+   *  Purpose
+   *  Flow diagram
+   *  Callbacks
+   *  Usage
+ *  Static handlers
+   *  Purpose
+   *  Usage
+ *  Request object
+   *  Purpose
+   *  Request
+   *  Request body
+   *  Reply
+ *  Hooks
+   *  On request
+   *  On response
+ *  Internals
+   *  Architecture
+   *  Efficiency considerations