Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.

1 files changed, 0 insertions, 269 deletions

diff --git a/doc/src/guide/req.ezdoc b/doc/src/guide/req.ezdoc
deleted file mode 100644
index add6166..0000000
--- a/doc/src/guide/req.ezdoc
+++ /dev/null
@@ -1,269 +0,0 @@
-::: The Req object
-
-The Req object is this variable that you will use to obtain
-information about a request, read the body of the request
-and send a response.
-
-:: A special variable
-
-While we call it an "object", it is not an object in the
-OOP sense of the term. In fact it is completely opaque
-to you and the only way you can perform operations using
-it is by calling the functions from the `cowboy_req`
-module.
-
-Almost all the calls to the `cowboy_req` module will
-return an updated request object. Just like you would
-keep the updated `State` variable in a gen_server,
-you MUST keep the updated `Req` variable in a Cowboy
-handler. Cowboy will use this object to know whether
-a response has been sent when the handler has finished
-executing.
-
-The Req object allows accessing both immutable and
-mutable state. This means that calling some of the
-functions twice will not produce the same result.
-For example, when streaming the request body, the
-function will return the body by chunks, one at a
-time, until there is none left.
-
-:: Overview of the cowboy_req interface
-
-With the exception of functions manipulating the request
-body, all functions return a single value. Depending on
-the function this can be the requested value (method,
-host, path, ...), a boolean (has_body, has_resp_header...)
-a new Req object (set_resp_body, set_resp_header...), or
-simply the atom `ok` (chunk, continue, ...).
-
-The request body reading functions may return `{Result, Req}`
-or `{Result, Value, Req}`. The functions in this category
-are `body/{1,2}`, `body_qs/{1,2}`, `part/{1,2}`, `part_body/{1,2}`.
-
-This chapter covers the access functions mainly. Cookies,
-request body and response functions are covered in their
-own chapters.
-
-:: Request
-
-When a client performs a request, it first sends a few required
-values. They are sent differently depending on the protocol
-being used, but the intent is the same. They indicate to the
-server the type of action it wants to do and how to locate
-the resource to perform it on.
-
-The method identifies the action. Standard methods include
-GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names
-are case sensitive.
-
-``` erlang
-Method = cowboy_req:method(Req).
-```
-
-The host, port and path parts of the URL identify the resource
-being accessed. The host and port information may not be
-available if the client uses HTTP/1.0.
-
-``` erlang
-Host = cowboy_req:host(Req),
-Port = cowboy_req:port(Req),
-Path = cowboy_req:path(Req).
-```
-
-The version used by the client can of course also be obtained.
-
-``` erlang
-Version = cowboy_req:version(Req).
-```
-
-Do note however that clients claiming to implement one version
-of the protocol does not mean they implement it fully, or even
-properly.
-
-:: Bindings
-
-After routing the request, bindings are available. Bindings
-are these parts of the host or path that you chose to extract
-when defining the routes of your application.
-
-You can fetch a single binding. The value will be `undefined`
-if the binding doesn't exist.
-
-``` erlang
-Binding = cowboy_req:binding(my_binding, Req).
-```
-
-If you need a different value when the binding doesn't exist,
-you can change the default.
-
-``` erlang
-Binding = cowboy_req:binding(my_binding, Req, 42).
-```
-
-You can also obtain all bindings in one call. They will be
-returned as a list of key/value tuples.
-
-``` erlang
-AllBindings = cowboy_req:bindings(Req).
-```
-
-If you used `...` at the beginning of the route's pattern
-for the host, you can retrieve the matched part of the host.
-The value will be `undefined` otherwise.
-
-``` erlang
-HostInfo = cowboy_req:host_info(Req).
-```
-
-Similarly, if you used `...` at the end of the route's
-pattern for the path, you can retrieve the matched part,
-or get `undefined` otherwise.
-
-``` erlang
-PathInfo = cowboy_req:path_info(Req).
-```
-
-:: Query string
-
-The raw query string can be obtained directly.
-
-``` erlang
-Qs = cowboy_req:qs(Req).
-```
-
-You can parse the query string and then use standard library
-functions to access individual values.
-
-``` erlang
-QsVals = cowboy_req:parse_qs(Req),
-{_, Lang} = lists:keyfind(<<"lang">>, 1, QsVals).
-```
-
-You can match the query string into a map.
-
-``` erlang
-#{id := ID, lang := Lang} = cowboy_req:match_qs([id, lang], Req).
-```
-
-You can use constraints to validate the values while matching
-them. The following snippet will crash if the `id` value is
-not an integer number or if the `lang` value is empty. Additionally
-the `id` value will be converted to an integer term, saving
-you a conversion step.
-
-``` erlang
-QsMap = cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).
-```
-
-Note that in the case of duplicate query string keys, the map
-value will become a list of the different values.
-
-Read more about ^constraints^.
-
-A default value can be provided. The default will be used
-if the `lang` key is not found. It will not be used if
-the key is found but has an empty value.
-
-``` erlang
-#{lang := Lang} = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).
-```
-
-If no default is provided and the value is missing, the
-query string is deemed invalid and the process will crash.
-
-:: Request URL
-
-You can reconstruct the full URL of the resource.
-
-``` erlang
-URL = cowboy_req:url(Req).
-```
-
-You can also obtain only the base of the URL, excluding the
-path and query string.
-
-``` erlang
-BaseURL = cowboy_req:host_url(Req).
-```
-
-:: Headers
-
-Cowboy allows you to obtain the header values as string,
-or parsed into a more meaningful representation.
-
-This will get the string value of a header.
-
-``` erlang
-HeaderVal = cowboy_req:header(<<"content-type">>, Req).
-```
-
-You can of course set a default in case the header is missing.
-
-``` erlang
-HeaderVal
-    = cowboy_req:header(<<"content-type">>, Req, <<"text/plain">>).
-```
-
-And also obtain all headers.
-
-``` erlang
-AllHeaders = cowboy_req:headers(Req).
-```
-
-To parse the previous header, simply call `parse_header/{2,3}`
-where you would call `header/{2,3}` otherwise.
-
-``` erlang
-ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req).
-```
-
-Cowboy will crash if it doesn't know how to parse the given
-header, or if the value is invalid.
-
-You can of course define a default value. Note that the default
-value you specify here is the parsed value you'd like to get
-by default.
-
-``` erlang
-ParsedVal = cowboy_req:parse_header(<<"content-type">>, Req,
-	{<<"text">>, <<"plain">>, []}).
-```
-
-The list of known headers and default values is defined in the
-manual.
-
-:: Meta
-
-Cowboy will sometimes associate some meta information with
-the request. Built-in meta values are listed in the manual
-for their respective modules.
-
-This will get a meta value. The returned value will be `undefined`
-if it isn't defined.
-
-``` erlang
-MetaVal = cowboy_req:meta(websocket_version, Req).
-```
-
-You can change the default value if needed.
-
-``` erlang
-MetaVal = cowboy_req:meta(websocket_version, Req, 13).
-```
-
-You can also define your own meta values. The name must be
-an `atom()`.
-
-``` erlang
-Req2 = cowboy_req:set_meta(the_answer, 42, Req).
-```
-
-:: Peer
-
-You can obtain the peer address and port number. This is
-not necessarily the actual IP and port of the client, but
-rather the one of the machine that connected to the server.
-
-``` erlang
-{IP, Port} = cowboy_req:peer(Req).
-```