Provide installable man pages

make docs: generate Markdown and man pages in doc/
make install-docs: install man pages to be usable directly

Docs are generated from the ezdoc files in doc/src/.

1 files changed, 135 insertions, 0 deletions

diff --git a/doc/src/guide/rest_handlers.ezdoc b/doc/src/guide/rest_handlers.ezdoc
new file mode 100644
index 0000000..ee3e5aa
--- /dev/null
+++ b/doc/src/guide/rest_handlers.ezdoc
@@ -0,0 +1,135 @@
+::: REST handlers
+
+REST is implemented in Cowboy as a protocol upgrade. Once upgraded,
+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 requests.
+
+:: Initialization
+
+First, the `init/3` callback is called. This callback is common
+to all handlers. To use REST for the current request, this function
+must return an `upgrade` tuple.
+
+``` erlang
+init({tcp, http}, Req, Opts) ->
+    {upgrade, protocol, cowboy_rest}.
+```
+
+Cowboy will then switch to the REST protocol and start executing
+the state machine, starting from `rest_init/2` if it's defined,
+and ending with `rest_terminate/2` also if 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.
+
+When the request starts being processed, Cowboy will call the
+`rest_init/2` function if it is defined, with the Req object
+and the handler options as arguments. This function must return
+`{ok, Req, State}` where `State` is the handler's state that all
+subsequent callbacks will receive.
+
+At the end of every request, the special callback `rest_terminate/2`
+will be called if it is defined. It cannot be used to send a reply,
+and must always return `ok`.
+
+All other callbacks are resource callbacks. They all take two
+arguments, the Req object and the State, and return a three-element
+tuple of the form `{Value, Req, State}`.
+
+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.
+
+All callbacks can also return `{halt, Req, State}` to stop execution
+of the request, at which point `rest_terminate/2` will be called.
+
+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.
+
+||	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_content_type		`true`
+|	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.
+
+||	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.
+
+||	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