From 61ca86b05493f82bcbddd76911fee64dc636c885 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 27 Jun 2013 00:02:12 +0200
Subject: Greatly improve the guide introduction

---
 guide/introduction.md | 93 ++++-----------------------------------------------
 1 file changed, 6 insertions(+), 87 deletions(-)

(limited to 'guide/introduction.md')

diff --git a/guide/introduction.md b/guide/introduction.md
index fb338ac..8c936a5 100644
--- a/guide/introduction.md
+++ b/guide/introduction.md
@@ -21,16 +21,12 @@ features both a Function Reference and a User Guide.
 Prerequisites
 -------------
 
-It is assumed the developer already knows Erlang and has basic knowledge
-about the HTTP protocol.
+No Erlang knowledge is required for reading this guide. The reader will
+be introduced to Erlang concepts and redirected to reference material
+whenever necessary.
 
-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.
+Knowledge of the HTTP protocol is recommended but not required, as it
+will be detailed throughout the guide.
 
 Supported platforms
 -------------------
@@ -57,81 +53,4 @@ 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 a group of processes that are used to accept and manage
-connections. The processes used specifically for accepting connections
-are called acceptors. The number of acceptor processes is unrelated to
-the maximum number of connections Cowboy can handle. Please refer to
-the Ranch guide for in-depth information.
-
-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 = cowboy_router:compile([
-    %% {URIHost, list({URIPath, Handler, Opts})}
-    {'_', [{'_', my_handler, []}]}
-]),
-%% Name, NbAcceptors, TransOpts, ProtoOpts
-cowboy:start_http(my_http_listener, 100,
-    [{port, 8080}],
-    [{env, [{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/3. You can find more information
-about the arguments and possible return values of these callbacks in the
-HTTP handlers section of this guide. Following is an example of a simple
-HTTP handler module.
-
-``` erlang
--module(my_handler).
--behaviour(cowboy_http_handler).
-
--export([init/3]).
--export([handle/2]).
--export([terminate/3]).
-
-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(Reason, Req, State) ->
-    ok.
-```
-
-The `Req` variable above is the Req object, which allows the developer
-to obtain information about the request and to perform a reply. Its usage
-is explained in its respective section of the guide.
+The same applies to any other case insensitive value.
-- 
cgit v1.2.3