Simplify example instructions and fix broken examples

Also convert to AsciiDoc while we're at it.

28 files changed, 246 insertions, 388 deletions

diff --git a/examples/chunked_hello_world/README.md b/examples/chunked_hello_world/README.asciidoc
index c568e3b..4b4225d 100644
--- a/examples/chunked_hello_world/README.md
+++ b/examples/chunked_hello_world/README.asciidoc
@@ -1,27 +1,19 @@
-Chunked hello world example
-===========================
+= Chunked hello world example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/chunked_hello_world_example/bin/chunked_hello_world_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080),
+Then point your browser to http://localhost:8080
 or use `curl` to see the chunks arriving one at a time every second.
 
-Example output
---------------
+== Example output
 
-``` bash
+[source,bash]
+----
 $ time curl -i http://localhost:8080
 HTTP/1.1 200 OK
 transfer-encoding: chunked
@@ -33,4 +25,4 @@ Hello
 World
 Chunked!
 curl -i http://localhost:8080  0.01s user 0.00s system 0% cpu 2.015 total
-```
+----
diff --git a/examples/compress_response/README.md b/examples/compress_response/README.asciidoc
index ecffcad..1e6d2ed 100644
--- a/examples/compress_response/README.md
+++ b/examples/compress_response/README.asciidoc
@@ -1,28 +1,20 @@
-Compressed response example
-===========================
+= Compressed response example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080
 
-``` bash
-$ ./_rel/compress_response_example/bin/compress_response_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-Example output
---------------
+== Example output
 
 Without compression:
 
-``` bash
+[source,bash]
+----
 $ curl -i http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -42,11 +34,12 @@ have established the ability to work at virtually identical tasks and obtained
 considerable respect for their achievements. There are also cattle handlers
 in many other parts of the world, particularly South America and Australia,
 who perform work similar to the cowboy in their respective nations.
-```
+----
 
 With compression:
 
-```
+[source,bash]
+----
 $ curl -i --compressed http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -67,4 +60,4 @@ have established the ability to work at virtually identical tasks and obtained
 considerable respect for their achievements. There are also cattle handlers
 in many other parts of the world, particularly South America and Australia,
 who perform work similar to the cowboy in their respective nations.
-```
+----
diff --git a/examples/cookie/README.asciidoc b/examples/cookie/README.asciidoc
new file mode 100644
index 0000000..20294f5
--- /dev/null
+++ b/examples/cookie/README.asciidoc
@@ -0,0 +1,13 @@
+= Cookie example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080
+
+This example allows you to use any path to show that the cookies
+are defined site-wide. Try it!
diff --git a/examples/cookie/README.md b/examples/cookie/README.md
deleted file mode 100644
index 61ddaae..0000000
--- a/examples/cookie/README.md
+++ /dev/null
@@ -1,20 +0,0 @@
-Cookie example
-==============
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/cookie_example/bin/cookie_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-This example allows you to use any path to show that the cookies
-are defined site-wide. Try it!
diff --git a/examples/echo_get/README.md b/examples/echo_get/README.asciidoc
index 737d04d..d002d61 100644
--- a/examples/echo_get/README.md
+++ b/examples/echo_get/README.asciidoc
@@ -1,29 +1,21 @@
-GET parameter echo example
-==========================
+= GET parameter echo example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080/?echo=hello
 
-``` bash
-$ ./_rel/echo_get_example/bin/echo_get_example console
-```
-
-Then point your browser at
-[http://localhost:8080/?echo=hello](http://localhost:8080/?echo=hello).
 You can replace the `echo` parameter with another to check
 that the handler is echoing it back properly.
 
-Example output
---------------
+== Example output
 
-``` bash
+[source,bash]
+----
 $ curl -i "http://localhost:8080/?echo=saymyname"
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -33,4 +25,4 @@ content-length: 9
 content-type: text/plain; charset=utf-8
 
 saymyname
-```
+----
diff --git a/examples/echo_post/README.md b/examples/echo_post/README.asciidoc
index cc89fd6..144e216 100644
--- a/examples/echo_post/README.md
+++ b/examples/echo_post/README.asciidoc
@@ -1,29 +1,21 @@
-POST parameter echo example
-===========================
+= POST parameter echo example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/echo_post_example/bin/echo_post_example console
-```
+[source,bash]
+$ make run
 
 As this example echoes a POST parameter, it is a little more
 complex to test. Some browsers feature tools that allow you
 to perform one such request, or you can use the command line
 tool `curl` as we will demonstrate.
 
-Example output
---------------
+== Example output
 
-``` bash
+[source,bash]
+----
 $ curl -i -d echo=echomeplz http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -33,4 +25,4 @@ content-length: 9
 content-type: text/plain; charset=utf-8
 
 echomeplz
-```
+----
diff --git a/examples/error_hook/README.md b/examples/error_hook/README.asciidoc
index cd0da97..6f61cb7 100644
--- a/examples/error_hook/README.md
+++ b/examples/error_hook/README.asciidoc
@@ -1,28 +1,20 @@
-Error hook example
-==================
+= Error hook example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080
 
-``` bash
-$ ./_rel/error_hook_example/bin/error_hook_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-Example output
---------------
+== Example output
 
 Not found:
 
-``` bash
+[source,bash]
+----
 $ curl -i http://localhost:8080
 HTTP/1.1 404 Not Found
 connection: keep-alive
@@ -31,11 +23,12 @@ date: Wed, 27 Feb 2013 23:32:55 GMT
 content-length: 56
 
 404 Not Found: "/" is not the path you are looking for.
-```
+----
 
 Bad request:
 
-``` bash
+[source,bash]
+----
 $ telnet localhost 8080
 Trying ::1...
 Connection failed: Connection refused
@@ -51,4 +44,4 @@ content-length: 15
 
 HTTP Error 400
 Connection closed by foreign host.
-```
+----
diff --git a/examples/eventsource/README.asciidoc b/examples/eventsource/README.asciidoc
new file mode 100644
index 0000000..9461b77
--- /dev/null
+++ b/examples/eventsource/README.asciidoc
@@ -0,0 +1,10 @@
+= EventSource example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080
diff --git a/examples/eventsource/README.md b/examples/eventsource/README.md
deleted file mode 100644
index b6b611c..0000000
--- a/examples/eventsource/README.md
+++ /dev/null
@@ -1,19 +0,0 @@
-EventSource example
-===================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/eventsource_example/bin/eventsource_example console
-```
-
-Then point your EventSource capable browser at
-[http://localhost:8080](http://localhost:8080).
diff --git a/examples/hello_world/README.asciidoc b/examples/hello_world/README.asciidoc
new file mode 100644
index 0000000..66a6bd6
--- /dev/null
+++ b/examples/hello_world/README.asciidoc
@@ -0,0 +1,25 @@
+= Hello world example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080
+
+== Example output
+
+[source,bash]
+----
+$ curl -i http://localhost:8080
+HTTP/1.1 200 OK
+connection: keep-alive
+server: Cowboy
+date: Fri, 28 Sep 2012 04:10:25 GMT
+content-length: 12
+content-type: text/plain
+
+Hello world!
+----
diff --git a/examples/hello_world/README.md b/examples/hello_world/README.md
deleted file mode 100644
index 1e5be0e..0000000
--- a/examples/hello_world/README.md
+++ /dev/null
@@ -1,33 +0,0 @@
-Hello world example
-===================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/hello_world_example/bin/hello_world_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-Example output
---------------
-
-``` bash
-$ curl -i http://localhost:8080
-HTTP/1.1 200 OK
-connection: keep-alive
-server: Cowboy
-date: Fri, 28 Sep 2012 04:10:25 GMT
-content-length: 12
-content-type: text/plain
-
-Hello world!
-```
diff --git a/examples/markdown_middleware/README.asciidoc b/examples/markdown_middleware/README.asciidoc
new file mode 100644
index 0000000..3881bfb
--- /dev/null
+++ b/examples/markdown_middleware/README.asciidoc
@@ -0,0 +1,15 @@
+= Middleware example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080/video.html
+
+Cowboy will serve all the files you put in the `priv` directory.
+If you request a `.html` file that has a corresponding `.md` file
+that has been modified more recently than the `.html` file, the
+Markdown file will be converted to HTML and served by Cowboy.
diff --git a/examples/markdown_middleware/README.md b/examples/markdown_middleware/README.md
deleted file mode 100644
index cc890fc..0000000
--- a/examples/markdown_middleware/README.md
+++ /dev/null
@@ -1,24 +0,0 @@
-Middleware example
-==================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/markdown_middleware_example/bin/markdown_middleware_example console
-```
-
-Then point your browser at
-[http://localhost:8080/video.html](http://localhost:8080/video.html).
-
-Cowboy will serve all the files you put in the `priv` directory.
-If you request a `.html` file that has a corresponding `.md` file
-that has been modified more recently than the `.html` file, the
-Markdown file will be converted to HTML and served by Cowboy.
diff --git a/examples/rest_basic_auth/README.md b/examples/rest_basic_auth/README.asciidoc
index 236ce2f..04609b3 100644
--- a/examples/rest_basic_auth/README.md
+++ b/examples/rest_basic_auth/README.asciidoc
@@ -1,28 +1,20 @@
-Basic authorization example using REST
-======================================
+= Basic authorization example using REST
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080
 
-``` bash
-$ ./_rel/rest_basic_auth_example/bin/rest_basic_auth_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-Example output
---------------
+== Example output
 
 Request with no authentication:
 
-``` bash
+[source,bash]
+----
 $ curl -i http://localhost:8080
 HTTP/1.1 401 Unauthorized
 connection: keep-alive
@@ -30,11 +22,12 @@ server: Cowboy
 date: Sun, 20 Jan 2013 14:10:27 GMT
 content-length: 0
 www-authenticate: Basic realm="cowboy"
-```
+----
 
 Request with authentication:
 
-``` bash
+[source,bash]
+----
 $ curl -i -u "Alladin:open sesame" http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -44,4 +37,4 @@ content-length: 16
 content-type: text/plain
 
 Hello, Alladin!
-```
+----
diff --git a/examples/rest_basic_auth/src/toppage_handler.erl b/examples/rest_basic_auth/src/toppage_handler.erl
index 18a8cae..2e8250f 100644
--- a/examples/rest_basic_auth/src/toppage_handler.erl
+++ b/examples/rest_basic_auth/src/toppage_handler.erl
@@ -13,7 +13,7 @@ init(Req, Opts) ->
 
 is_authorized(Req, State) ->
 	case cowboy_req:parse_header(<<"authorization">>, Req) of
-		{<<"basic">>, {User = <<"Alladin">>, <<"open sesame">>}} ->
+		{basic, User = <<"Alladin">>, <<"open sesame">>} ->
 			{true, Req, User};
 		_ ->
 			{{false, <<"Basic realm=\"cowboy\"">>}, Req, State}
diff --git a/examples/rest_hello_world/README.md b/examples/rest_hello_world/README.asciidoc
index c7e124c..5eb94e8 100644
--- a/examples/rest_hello_world/README.md
+++ b/examples/rest_hello_world/README.asciidoc
@@ -1,28 +1,20 @@
-REST hello world example
-========================
+= REST hello world example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080
 
-``` bash
-$ ./_rel/rest_hello_world_example/bin/rest_hello_world_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-Example output
---------------
+== Example output
 
 Request HTML:
 
-``` bash
+[source,bash]
+----
 $ curl -i http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -41,11 +33,12 @@ vary: Accept
   <p>REST Hello World as HTML!</p>
 </body>
 </html>
-```
+----
 
 Request JSON:
 
-``` bash
+[source,bash]
+----
 $ curl -i -H "Accept: application/json" http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -56,11 +49,12 @@ content-type: application/json
 vary: Accept
 
 {"rest": "Hello World!"}
-```
+----
 
 Request plain text:
 
-``` bash
+[source,bash]
+----
 $ curl -i -H "Accept: text/plain" http://localhost:8080
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -71,11 +65,12 @@ content-type: text/plain
 vary: Accept
 
 REST Hello World as text!
-```
+----
 
 Request a non acceptable content-type:
 
-``` bash
+[source,bash]
+----
 $ curl -i -H "Accept: text/css" http://localhost:8080
 HTTP/1.1 406 Not Acceptable
 connection: keep-alive
@@ -83,4 +78,4 @@ server: Cowboy
 date: Fri, 28 Sep 2012 04:18:51 GMT
 content-length: 0
 
-```
+----
diff --git a/examples/rest_pastebin/README.md b/examples/rest_pastebin/README.asciidoc
index a3941f1..d0cabc1 100644
--- a/examples/rest_pastebin/README.md
+++ b/examples/rest_pastebin/README.asciidoc
@@ -1,59 +1,46 @@
-REST pastebin example
-=====================
+= REST pastebin example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080
 
-``` bash
-$ ./_rel/rest_pastebin_example/bin/rest_pastebin_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-Usage
------
+== Usage
 
 To upload something to the paste application, you can use `curl`:
 
-``` bash
+[source,bash]
 $ <command> | curl -i --data-urlencode paste@- localhost:8080
-```
 
 Or, to upload the file `my_file`:
 
-``` bash
+[source,bash]
 curl -i --data-urlencode paste@my_file localhost:8080
-```
 
 The URL of your data will be in the location header. Alternately, you can visit
 http://localhost:8080 with your favorite web browser and submit your paste via
 the form.
 
 Code that has been pasted can be highlighted with ?lang=<language> option if
-you have [highlight](http://www.andre-simon.de/doku/highlight/en/highlight.html)
+you have http://www.andre-simon.de/doku/highlight/en/highlight.html[highlight]
 installed (although `pygments` or any other should work just fine).
 
 This will show the contents of the HTML file:
 
-``` bash
+[source,bash]
 curl -i --data-urlencode paste@priv/index.html localhost:8080
 curl <url from location header>
-```
 
 If your terminal supports color sequences and `highlight` is installed,
 the following command will show the same contents but with HTML syntax
 highlighting.
 
-``` bash
+[source,bash]
 curl <url from location header>?lang=html
-```
 
 If you open the same URL in your web browser and your web browser tells
 Cowboy that it prefers HTML files, you will see the file highlighted
diff --git a/examples/rest_pastebin/src/toppage_handler.erl b/examples/rest_pastebin/src/toppage_handler.erl
index 57b9315..324fa4a 100644
--- a/examples/rest_pastebin/src/toppage_handler.erl
+++ b/examples/rest_pastebin/src/toppage_handler.erl
@@ -16,7 +16,7 @@
 -export([paste_text/2]).
 
 init(Req, Opts) ->
-	random:seed(now()),
+	random:seed(os:timestamp()),
 	{cowboy_rest, Req, Opts}.
 
 allowed_methods(Req, State) ->
@@ -57,13 +57,13 @@ create_paste(Req, State) ->
 paste_html(Req, index) ->
 	{read_file("index.html"), Req, index};
 paste_html(Req, Paste) ->
-	#{lang := Lang} = cowboy_req:match_qs([lang], Req),
+	#{lang := Lang} = cowboy_req:match_qs([{lang, [], plain}], Req),
 	{format_html(Paste, Lang), Req, Paste}.
 
 paste_text(Req, index) ->
 	{read_file("index.txt"), Req, index};
 paste_text(Req, Paste) ->
-	#{lang := Lang} = cowboy_req:match_qs([lang], Req),
+	#{lang := Lang} = cowboy_req:match_qs([{lang, [], plain}], Req),
 	{format_text(Paste, Lang), Req, Paste}.
 
 % Private
diff --git a/examples/rest_stream_response/README.md b/examples/rest_stream_response/README.asciidoc
index 3b49451..411c4c4 100644
--- a/examples/rest_stream_response/README.md
+++ b/examples/rest_stream_response/README.asciidoc
@@ -1,35 +1,26 @@
-REST streaming example
-======================
+= REST streaming example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to http://localhost:8080
 
-``` bash
-$ ./_rel/rest_stream_response_example/bin/rest_stream_response_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-About
------
+== About
 
 This example simulates streaming a large amount of data from a data store one
 record at a time in CSV format. It also uses a constraint to ensure that the
 last segment of the route is an integer.
 
-Example output
---------------
+== Example output
 
 Fetch records with the second field with value 1:
 
-``` bash
+[source,bash]
+----
 $ curl -i localhost:8080
 HTTP/1.1 200 OK
 transfer-encoding: identity
@@ -42,11 +33,12 @@ DBUZGQ0C,1,28
 BgoQAxMV,1,6
 DAYEFxER,1,18
 ...
-```
+----
 
 Fetch records with the second field with value 4:
 
-``` bash
+[source,bash]
+----
 $ curl -i localhost:8080/4
 HTTP/1.1 200 OK
 transfer-encoding: identity
@@ -59,11 +51,12 @@ ABcFDxcE,4,42
 DgYQCgEE,4,5
 CA8BBhYD,4,10
 ...
-```
+----
 
 Fail to use a proper integer and get an error:
 
-``` bash
+[source,bash]
+----
 $ curl -i localhost:8080/foo
 HTTP/1.1 404 Not Found
 connection: keep-alive
@@ -71,4 +64,4 @@ server: Cowboy
 date: Sun, 10 Feb 2013 19:36:16 GMT
 content-length: 0
 
-```
+----
diff --git a/examples/ssl_hello_world/README.md b/examples/ssl_hello_world/README.asciidoc
index 1dabbd6..d3fcf77 100644
--- a/examples/ssl_hello_world/README.md
+++ b/examples/ssl_hello_world/README.asciidoc
@@ -1,28 +1,21 @@
-Hello world example
-===================
+= Hello world example
 
 To try this example, you need GNU `make` and `git` in your PATH.
 
-To build the example, run the following command:
+To build and run the example, use the following command:
 
-``` bash
-$ make
-```
+[source,bash]
+$ make run
 
-To start the release in the foreground:
+Then point your browser to https://localhost:8443
 
-``` bash
-$ ./_rel/ssl_hello_world_example/bin/ssl_hello_world_example console
-```
-
-Then point your browser at [https://localhost:8443](https://localhost:8443).
 You will need to temporarily trust the root certificate authority,
 which can also be found in `priv/ssl/cowboy-ca.crt`.
 
-Example output
---------------
+== Example output
 
-``` bash
+[source,bash]
+----
 $ curl --cacert priv/ssl/cowboy-ca.crt -i https://localhost:8443
 HTTP/1.1 200 OK
 connection: keep-alive
@@ -31,4 +24,4 @@ date: Fri, 28 Sep 2012 04:10:25 GMT
 content-length: 12
 
 Hello world!
-```
+----
diff --git a/examples/static_world/README.asciidoc b/examples/static_world/README.asciidoc
new file mode 100644
index 0000000..3f09900
--- /dev/null
+++ b/examples/static_world/README.asciidoc
@@ -0,0 +1,30 @@
+= Static file handler example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+The example will serve all the files found in the 'priv/'
+directory. For example:
+
+* http://localhost:8080/test.txt[Plain text file]
+* http://localhost:8080/video.html[HTML5 video demo]
+
+== Example output
+
+[source,bash]
+----
+$ curl -i http://localhost:8080/test.txt
+HTTP/1.1 200 OK
+connection: keep-alive
+server: Cowboy
+date: Mon, 09 Sep 2013 13:49:50 GMT
+content-length: 52
+content-type: text/plain
+last-modified: Fri, 18 Jan 2013 16:33:31 GMT
+
+If you read this then the static file server works!
+----
diff --git a/examples/static_world/README.md b/examples/static_world/README.md
deleted file mode 100644
index aa72e89..0000000
--- a/examples/static_world/README.md
+++ /dev/null
@@ -1,38 +0,0 @@
-Static file handler example
-===========================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/static_world_example/bin/static_world_example console
-```
-
-The example will serve all the files found in the `priv`
-directory. For example:
-
- *  [Plain text file](http://localhost:8080/test.txt)
- *  [HTML5 video demo](http://localhost:8080/video.html)
-
-Example output
---------------
-
-``` bash
-$ curl -i http://localhost:8080/test.txt
-HTTP/1.1 200 OK
-connection: keep-alive
-server: Cowboy
-date: Mon, 09 Sep 2013 13:49:50 GMT
-content-length: 52
-content-type: text/plain
-last-modified: Fri, 18 Jan 2013 16:33:31 GMT
-
-If you read this then the static file server works!
-```
diff --git a/examples/upload/README.asciidoc b/examples/upload/README.asciidoc
new file mode 100644
index 0000000..96f6ec7
--- /dev/null
+++ b/examples/upload/README.asciidoc
@@ -0,0 +1,12 @@
+= Multipart upload example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080
+
+The uploaded file will be displayed in the shell directly.
diff --git a/examples/upload/README.md b/examples/upload/README.md
deleted file mode 100644
index 0a0d8b4..0000000
--- a/examples/upload/README.md
+++ /dev/null
@@ -1,20 +0,0 @@
-Multipart upload example
-========================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/upload_example/bin/upload_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).
-
-The uploaded file will be displayed in the shell directly.
diff --git a/examples/web_server/README.asciidoc b/examples/web_server/README.asciidoc
new file mode 100644
index 0000000..8f0eb4b
--- /dev/null
+++ b/examples/web_server/README.asciidoc
@@ -0,0 +1,11 @@
+= Directory indexing example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080
+to browse the contents of the `priv` directory.
diff --git a/examples/web_server/README.md b/examples/web_server/README.md
deleted file mode 100644
index b8938dd..0000000
--- a/examples/web_server/README.md
+++ /dev/null
@@ -1,19 +0,0 @@
-Static file handler example
-===========================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/web_server_example/bin/web_server_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080)
-to browse the contents of the `priv` directory.
diff --git a/examples/websocket/README.asciidoc b/examples/websocket/README.asciidoc
new file mode 100644
index 0000000..0b22607
--- /dev/null
+++ b/examples/websocket/README.asciidoc
@@ -0,0 +1,10 @@
+= Websocket example
+
+To try this example, you need GNU `make` and `git` in your PATH.
+
+To build and run the example, use the following command:
+
+[source,bash]
+$ make run
+
+Then point your browser to http://localhost:8080
diff --git a/examples/websocket/README.md b/examples/websocket/README.md
deleted file mode 100644
index bb55c1c..0000000
--- a/examples/websocket/README.md
+++ /dev/null
@@ -1,18 +0,0 @@
-Websocket example
-=================
-
-To try this example, you need GNU `make` and `git` in your PATH.
-
-To build the example, run the following command:
-
-``` bash
-$ make
-```
-
-To start the release in the foreground:
-
-``` bash
-$ ./_rel/websocket_example/bin/websocket_example console
-```
-
-Then point your browser at [http://localhost:8080](http://localhost:8080).