Convert the documentation to Asciidoc

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

doc/src/guide/rest_handlers.asciidoc

@@ -0,0 +1,133 @@
+[[rest_handlers]]
+== REST handlers
+
+REST is implemented in Cowboy as a sub protocol. The request
+is handled as a state machine with many optional callbacks
+describing the resource and modifying the machine's behavior.
+
+The REST handler is the recommended way to handle HTTP requests.
+
+=== Initialization
+
+First, the `init/2` callback is called. This callback is common
+to all handlers. To use REST for the current request, this function
+must return a `cowboy_rest` tuple.
+
+[source,erlang]
+----
+init(Req, _Opts) ->
+    {cowboy_rest, Req, #state{}}.
+----
+
+Cowboy will then switch to the REST protocol and start executing
+the state machine.
+
+After reaching the end of the flowchart, the `terminate/3` callback
+will be called if it is defined.
+
+=== Methods
+
+The REST component has code for handling the following HTTP methods:
+HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.
+
+Other methods can be accepted, however they have no specific callback
+defined for them at this time.
+
+=== Callbacks
+
+All callbacks are optional. Some may become mandatory depending
+on what other defined callbacks return. The various flowcharts
+in the next chapter should be a useful to determine which callbacks
+you need.
+
+All callbacks take two arguments, the Req object and the State,
+and return a three-element tuple of the form `{Value, Req, State}`.
+
+All callbacks can also return `{stop, Req, State}` to stop execution
+of the request.
+
+The following table summarizes the callbacks and their default values.
+If the callback isn't defined, then the default value will be used.
+Please look at the flowcharts to find out the result of each return
+value.
+
+In the following table, "skip" means the callback is entirely skipped
+if it is undefined, moving directly to the next step. Similarly,
+"none" means there is no default value for this callback.
+
+[cols="<,^",options="header"]
+|===
+| Callback name          | Default value
+| allowed_methods        | `[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]`
+| allow_missing_post     | `true`
+| charsets_provided      | skip
+| content_types_accepted | none
+| content_types_provided | `$$[{{<<"text">>, <<"html">>, '*'}, to_html}]$$`
+| delete_completed       | `true`
+| delete_resource        | `false`
+| expires                | `undefined`
+| forbidden              | `false`
+| generate_etag          | `undefined`
+| is_authorized          | `true`
+| is_conflict            | `false`
+| known_methods          | `[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]`
+| languages_provided     | skip
+| last_modified          | `undefined`
+| malformed_request      | `false`
+| moved_permanently      | `false`
+| moved_temporarily      | `false`
+| multiple_choices       | `false`
+| options                | `ok`
+| previously_existed     | `false`
+| resource_exists        | `true`
+| service_available      | `true`
+| uri_too_long           | `false`
+| valid_content_headers  | `true`
+| valid_entity_length    | `true`
+| variances              | `[]`
+|===
+
+As you can see, Cowboy tries to move on with the request whenever
+possible by using well thought out default values.
+
+In addition to these, there can be any number of user-defined
+callbacks that are specified through `content_types_accepted/2`
+and `content_types_provided/2`. They can take any name, however
+it is recommended to use a separate prefix for the callbacks of
+each function. For example, `from_html` and `to_html` indicate
+in the first case that we're accepting a resource given as HTML,
+and in the second case that we send one as HTML.
+
+=== Meta data
+
+Cowboy will set informative meta values at various points of the
+execution. You can retrieve them using `cowboy_req:meta/{2,3}`.
+The values are defined in the following table.
+
+[cols="<,<",options="header"]
+|===
+| Meta key   | Details
+| media_type | The content-type negotiated for the response entity.
+| language   | The language negotiated for the response entity.
+| charset    | The charset negotiated for the response entity.
+|===
+
+They can be used to send a proper body with the response to a
+request that used a method other than HEAD or GET.
+
+=== Response headers
+
+Cowboy will set response headers automatically over the execution
+of the REST code. They are listed in the following table.
+
+[cols="<,<",options="header"]
+|===
+| Header name      | Details
+| content-language | Language used in the response body
+| content-type     | Media type and charset of the response body
+| etag             | Etag of the resource
+| expires          | Expiration date of the resource
+| last-modified    | Last modification date for the resource
+| location         | Relative or absolute URI to the requested resource
+| vary             | List of headers that may change the representation of the resource
+|===