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, 0 insertions, 560 deletions

diff --git a/manual/cowboy_rest.md b/manual/cowboy_rest.md
deleted file mode 100644
index a2abf3a..0000000
--- a/manual/cowboy_rest.md
+++ /dev/null
@@ -1,560 +0,0 @@
-cowboy_rest
-===========
-
-The `cowboy_rest` module implements REST semantics on top of
-the HTTP protocol.
-
-This module cannot be described as a behaviour due to most of
-the callbacks it defines being optional. It has the same
-semantics as a behaviour otherwise.
-
-The only mandatory callback is `init/3`, needed to perform
-the protocol upgrade.
-
-Types
------
-
-None.
-
-Meta values
------------
-
-### charset
-
-> Type: binary()
->
-> Negotiated charset.
->
-> This value may not be defined if no charset was negotiated.
-
-### language
-
-> Type: binary()
->
-> Negotiated language.
->
-> This value may not be defined if no language was negotiated.
-
-### media_type
-
-> Type: {binary(), binary(), '*' | [{binary(), binary()}]}
->
-> Negotiated media-type.
->
-> The media-type is the content-type, excluding the charset.
->
-> This value is always defined after the call to
-> `content_types_provided/2`.
-
-Callbacks
----------
-
-### init({TransportName, ProtocolName}, Req, Opts)
-	-> {upgrade, protocol, cowboy_rest}
-	| {upgrade, protocol, cowboy_rest, Req, Opts}
-
-> Types:
->  *  TransportName = tcp | ssl | atom()
->  *  ProtocolName = http | atom()
->  *  Req = cowboy_req:req()
->  *  Opts = any()
->
-> Upgrade the protocol to `cowboy_rest`.
->
-> This is the only mandatory callback.
-
-### rest_init(Req, Opts) -> {ok, Req, State}
-
-> Types:
->  *  Req = cowboy_req:req()
->  *  Opts = any()
->  *  State = any()
->
-> Initialize the state for this request.
-
-### rest_terminate(Req, State) -> ok
-
-> Types:
->  *  Req = cowboy_req:req()
->  *  State = any()
->
-> Perform any necessary cleanup of the state.
->
-> This callback should release any resource currently in use,
-> clear any active timer and reset the process to its original
-> state, as it might be reused for future requests sent on the
-> same connection.
-
-### Callback(Req, State) -> {Value, Req, State} | {halt, Req, State}
-
-> Types:
->  *  Callback - one of the REST callbacks described below
->  *  Req = cowboy_req:req()
->  *  State = any()
->  *  Value - see the REST callbacks description below
->
-> Please see the REST callbacks description below for details
-> on the `Value` type, the default value if the callback is
-> not defined, and more general information on when the
-> callback is called and what its intended use is.
->
-> The `halt` tuple can be returned to stop REST processing.
-> It is up to the resource code to send a reply before that,
-> otherwise a `204 No Content` will be sent.
-
-REST callbacks description
---------------------------
-
-### allowed_methods
-
->  *  Methods: all
->  *  Value type: [binary()]
->  *  Default value: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
->
-> Return the list of allowed methods.
->
-> Methods are case sensitive. Standard methods are always uppercase.
-
-### allow_missing_post
-
->  *  Methods: POST
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether POST is allowed when the resource doesn't exist.
->
-> Returning `true` here means that a new resource will be
-> created. The URL to the created resource should also be
-> returned from the `AcceptResource` callback.
-
-### charsets_provided
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: [binary()]
->  *  Skip to the next step if undefined
->
-> Return the list of charsets the resource provides.
->
-> The list must be ordered in order of preference.
->
-> If the accept-charset header was not sent, the first charset
-> in the list will be selected. Otherwise Cowboy will select
-> the most appropriate charset from the list.
->
-> The chosen charset will be set in the `Req` object as the meta
-> value `charset`.
->
-> While charsets are case insensitive, this callback is expected
-> to return them as lowercase binary.
-
-### content_types_accepted
-
->  *  Methods: POST, PUT, PATCH
->  *  No default
->
-> Types:
->  *  Value = [{binary() | {Type, SubType, Params}, AcceptResource}]
->  *  Type = SubType = binary()
->  *  Params = '*' | [{binary(), binary()}]
->  *  AcceptResource = atom()
->
-> Return the list of content-types the resource accepts.
->
-> The list must be ordered in order of preference.
->
-> Each content-type can be given either as a binary string or as
-> a tuple containing the type, subtype and parameters.
->
-> Cowboy will select the most appropriate content-type from the list.
-> If any parameter is acceptable, then the tuple form should be used
-> with parameters set to `'*'`. If the parameters value is set to `[]`
-> only content-type values with no parameters will be accepted. All
-> parameter values are treated in a case sensitive manner except the
-> `charset` parameter, if present, which is case insensitive.
->
-> This function will be called for POST, PUT and PATCH requests.
-> It is entirely possible to define different callbacks for different
-> methods if the handling of the request differs. Simply verify
-> what the method is with `cowboy_req:method/1` and return a
-> different list for each methods.
->
-> The `AcceptResource` value is the name of the callback that will
-> be called if the content-type matches. It is defined as follow.
->
->  *  Value type: true | {true, URL} | false
->  *  No default
->
-> Process the request body.
->
-> This function should create or update the resource with the
-> information contained in the request body. This information
-> may be full or partial depending on the request method.
->
-> If the request body was processed successfully, `true` or
-> `{true, URL}` may be returned. If an URL is provided, the
-> response will redirect the client to the location of the
-> resource.
->
-> If a response body must be sent, the appropriate media-type, charset
-> and language can be retrieved using the `cowboy_req:meta/{2,3}`
-> functions. The respective keys are `media_type`, `charset`
-> and `language`. The body can be set using `cowboy_req:set_resp_body/2`.
-
-### content_types_provided
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
->
-> Types:
->  *  Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
->  *  Type = SubType = binary()
->  *  Params = '*' | [{binary(), binary()}]
->  *  ProvideResource = atom()
->
-> Return the list of content-types the resource provides.
->
-> The list must be ordered in order of preference.
->
-> Each content-type can be given either as a binary string or as
-> a tuple containing the type, subtype and parameters.
->
-> Cowboy will select the most appropriate content-type from the list.
-> If any parameter is acceptable, then the tuple form should be used
-> with parameters set to `'*'`. If the parameters value is set to `[]`
-> only content-type values with no parameters will be accepted. All
-> parameter values are treated in a case sensitive manner except the
-> `charset` parameter, if present, which is case insensitive.
->
-> The `ProvideResource` value is the name of the callback that will
-> be called if the content-type matches. It will only be called when
-> a representation of the resource needs to be returned. It is defined
-> as follow.
->
->  *  Methods: GET, HEAD
->  *  Value type: iodata() | {stream, Fun} | {stream, Len, Fun} | {chunked, ChunkedFun}
->  *  No default
->
-> Return the response body.
->
-> The response body may be provided directly or through a fun.
-> If a fun tuple is returned, the appropriate `set_resp_body_fun`
-> function will be called. Please refer to the documentation for
-> these functions for more information about the types.
->
-> The call to this callback happens a good time after the call to
-> `content_types_provided/2`, when it is time to start rendering
-> the response body.
-
-### delete_completed
-
->  *  Methods: DELETE
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether the delete action has been completed.
->
-> This function should return `false` if there is no guarantee
-> that the resource gets deleted immediately from the system,
-> including from any internal cache.
->
-> When this function returns `false`, a `202 Accepted`
-> response will be sent instead of a `200 OK` or `204 No Content`.
-
-### delete_resource
-
->  *  Methods: DELETE
->  *  Value type: boolean()
->  *  Default value: false
->
-> Delete the resource.
->
-> The value returned indicates if the action was successful,
-> regardless of whether the resource is immediately deleted
-> from the system.
-
-### expires
-
->  *  Methods: GET, HEAD
->  *  Value type: calendar:datetime() | binary() | undefined
->  *  Default value: undefined
->
-> Return the date of expiration of the resource.
->
-> This date will be sent as the value of the expires header.
-
-### forbidden
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: false
->
-> Return whether access to the resource is forbidden.
->
-> A `403 Forbidden` response will be sent if this
-> function returns `true`. This status code means that
-> access is forbidden regardless of authentication,
-> and that the request shouldn't be repeated.
-
-### generate_etag
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: binary() | {weak | strong, binary()}
->  *  Default value: undefined
->
-> Return the entity tag of the resource.
->
-> This value will be sent as the value of the etag header.
->
-> If a binary is returned, then the value will be parsed
-> to the tuple form automatically. The value must be in
-> the same format as the etag header, including quotes.
-
-### is_authorized
-
->  *  Methods: all
->  *  Value type: true | {false, AuthHeader}
->  *  Default value: true
->
-> Return whether the user is authorized to perform the action.
->
-> This function should be used to perform any necessary
-> authentication of the user before attempting to perform
-> any action on the resource.
->
-> If the authentication fails, the value returned will be sent
-> as the value for the www-authenticate header in the
-> `401 Unauthorized` response.
-
-### is_conflict
-
->  *  Methods: PUT
->  *  Value type: boolean()
->  *  Default value: false
->
-> Return whether the put action results in a conflict.
->
-> A `409 Conflict` response will be sent if this function
-> returns `true`.
-
-### known_content_type
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether the content-type is known.
->
-> This function determines if the server understands the
-> content-type, regardless of its use by the resource.
-
-### known_methods
-
->  *  Methods: all
->  *  Value type: [binary()]
->  *  Default value: [<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
->
-> Return the list of known methods.
->
-> The full list of methods known by the server should be
-> returned, regardless of their use in the resource.
->
-> The default value lists the methods Cowboy knows and
-> implement in `cowboy_rest`.
->
-> Methods are case sensitive. Standard methods are always uppercase.
-
-### languages_provided
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: [binary()]
->  *  Skip to the next step if undefined
->
-> Return the list of languages the resource provides.
->
-> The list must be ordered in order of preference.
->
-> If the accept-language header was not sent, the first language
-> in the list will be selected. Otherwise Cowboy will select
-> the most appropriate language from the list.
->
-> The chosen language will be set in the `Req` object as the meta
-> value `language`.
->
-> While languages are case insensitive, this callback is expected
-> to return them as lowercase binary.
-
-### last_modified
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: calendar:datetime()
->  *  Default value: undefined
->
-> Return the date of last modification of the resource.
->
-> This date will be used to test against the if-modified-since
-> and if-unmodified-since headers, and sent as the last-modified
-> header in the response of GET and HEAD requests.
-
-### malformed_request
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: false
->
-> Return whether the request is malformed.
->
-> Cowboy has already performed all the necessary checks
-> by the time this function is called, so few resources
-> are expected to implement it.
->
-> The check is to be done on the request itself, not on
-> the request body, which is processed later.
-
-### moved_permanently
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: {true, URL} | false
->  *  Default value: false
->
-> Return whether the resource was permanently moved.
->
-> If it was, its new URL is also returned and sent in the
-> location header in the response.
-
-### moved_temporarily
-
->  *  Methods: GET, HEAD, POST, PATCH, DELETE
->  *  Value type: {true, URL} | false
->  *  Default value: false
->
-> Return whether the resource was temporarily moved.
->
-> If it was, its new URL is also returned and sent in the
-> location header in the response.
-
-### multiple_choices
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: boolean()
->  *  Default value: false
->
-> Return whether there are multiple representations of the resource.
->
-> This function should be used to inform the client if there
-> are different representations of the resource, for example
-> different content-type. If this function returns `true`,
-> the response body should include information about these
-> different representations using `cowboy_req:set_resp_body/2`.
-> The content-type of the response should be the one previously
-> negociated and that can be obtained by calling
-> `cowboy_req:meta(media_type, Req)`.
-
-### options
-
->  *  Methods: OPTIONS
->  *  Value type: ok
->  *  Default value: ok
->
-> Handle a request for information.
->
-> The response should inform the client the communication
-> options available for this resource.
->
-> By default, Cowboy will send a `200 OK` response with the
-> allow header set.
-
-### previously_existed
-
->  *  Methods: GET, HEAD, POST, PATCH, DELETE
->  *  Value type: boolean()
->  *  Default value: false
->
-> Return whether the resource existed previously.
-
-### resource_exists
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether the resource exists.
->
-> If it exists, conditional headers will be tested before
-> attempting to perform the action. Otherwise, Cowboy will
-> check if the resource previously existed first.
-
-### service_available
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether the service is available.
->
-> This function can be used to test that all relevant backend
-> systems are up and able to handle requests.
->
-> A `503 Service Unavailable` response will be sent if this
-> function returns `false`.
-
-### uri_too_long
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: false
->
-> Return whether the requested URI is too long.
->
-> Cowboy has already performed all the necessary checks
-> by the time this function is called, so few resources
-> are expected to implement it.
->
-> A `414 Request-URI Too Long` response will be sent if this
-> function returns `true`.
-
-### valid_content_headers
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether the content-* headers are valid.
->
-> This also applies to the transfer-encoding header. This
-> function must return `false` for any unknown content-*
-> headers, or if the headers can't be understood. The
-> function `cowboy_req:parse_header/2` can be used to
-> quickly check the headers can be parsed.
->
-> A `501 Not Implemented` response will be sent if this
-> function returns `false`.
-
-### valid_entity_length
-
->  *  Methods: all
->  *  Value type: boolean()
->  *  Default value: true
->
-> Return whether the request body length is within acceptable boundaries.
->
-> A `413 Request Entity Too Large` response will be sent if this
-> function returns `false`.
-
-### variances
-
->  *  Methods: GET, HEAD, POST, PUT, PATCH, DELETE
->  *  Value type: [binary()]
->  *  Default value: []
->
-> Return the list of headers that affect the representation of the resource.
->
-> These request headers return the same resource but with different
-> parameters, like another language or a different content-type.
->
-> Cowboy will automatically add the accept, accept-language and
-> accept-charset headers to the list if the respective functions
-> were defined in the resource.
->
-> This operation is performed right before the `resource_exists/2`
-> callback. All responses past that point will contain the vary
-> header which holds this list.