Simplify example instructions and fix broken examples

Also convert to AsciiDoc while we're at it.

examples/chunked_hello_world/README.md → 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
-```
+----

examples/compress_response/README.md → 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.
-```
+----

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!

examples/cookie/README.md

@@ -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!

examples/echo_get/README.md → 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
-```
+----

examples/echo_post/README.md → 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
-```
+----

examples/error_hook/README.md → 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.
-```
+----

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

examples/eventsource/README.md

@@ -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).

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!
+----

examples/hello_world/README.md

@@ -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!
-```

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.

examples/markdown_middleware/README.md

@@ -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.

examples/rest_basic_auth/README.md → 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!
-```
+----

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}

examples/rest_hello_world/README.md → 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
 
-```
+----

examples/rest_pastebin/README.md → 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

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

examples/rest_stream_response/README.md → 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
 
-```
+----

examples/ssl_hello_world/README.md → 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!
-```
+----

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!
+----

examples/static_world/README.md

@@ -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!
-```

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.

examples/upload/README.md

@@ -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.

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.

examples/web_server/README.md

@@ -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.

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

examples/websocket/README.md

@@ -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).