More man page reorganization.

Man pages need special handling, and we can have other kinds of documentation
like initial starting guides, etc., which would have different processing
applied.  So lets move them off into their own directory.

1 files changed, 139 insertions, 0 deletions

diff --git a/docs/man/nng_http_handler_alloc.adoc b/docs/man/nng_http_handler_alloc.adoc
new file mode 100644
index 00000000..023d0400
--- /dev/null
+++ b/docs/man/nng_http_handler_alloc.adoc
@@ -0,0 +1,139 @@
+= nng_http_handler_alloc(3)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_http_handler_alloc - allocate HTTP server handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+#include <nng/supplemental/http/http.h>
+
+typedef struct nng_http_handler nng_http_handler;
+
+int nng_http_handler_alloc(nng_http_handler **hp, const char *path,
+    void (*func)(nng_aio *);
+int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path,
+    const char *dirname);
+int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path,
+    const char *filename);
+int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path,
+    const void *data, size_t size, const char *content_type);
+-----------
+
+== DESCRIPTION
+
+The `nng_http_handler_alloc()` family of functions allocate a handler
+which will be used to process requests coming into an HTTP server.
+On success, a pointer to the handler is stored at the located pointed to
+by _hp_.
+
+Every handler has a Request-URI to which it refers, which is determined
+by the _path_ argument. Only the path component of the Request URI is
+considered when determining whether the handler should be called.
+
+Additionally each handler has a method it is registered to handle
+(the default is "GET", see
+<<nng_http_handler_set_method#,nng_http_handler_set_method(3)), and
+optionally a 'Host' header it can be matched against (see
+<<nng_http_handler_set_host#,nng_http_handler_set_host(3)).
+
+In some cases, a handler may reference a logical tree rather (directory)
+rather than just a single element.
+(See <<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>).
+
+=== Custom Handler
+
+The generic (first) form of this creates a handler that uses a user-supplied
+function to process HTTP requests.  This function uses the asynchronous I/O
+framework.  The function takes a pointer to an `nng_aio` structure.  That
+structure will be passed with the following input values (retrieved with
+<<nng_aio_get_input#,nng_aio_get_input(3)>>):
+
+   0: ``nng_http_req *`` __request__:: The client's HTTP request.
+   1: ``nng_http_handler *``__handler__:: Pointer to the handler object.
+   2: ``nng_http_conn *``__conn__:: The underlying HTTP connection.
+
+The handler should create an `nng_http_res *` response (such as via
+<<nng_http_res_alloc#,nng_http_res_alloc(3)>> or
+<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>) and store that
+in as the first output (index 0) with
+<<nng_aio_set_output#,nng_aio_set_output(3)>>.
+
+Alternatively, the handler may send the HTTP response (and any associated
+body data) itself using the connection.  In that case the output at index
+0 of the _aio_ should be NULL.
+
+Finally, using the <<nng_aio_finish#,nng_aio_finish(3)>> function, the
+_aio_ should be completed successfully.  If any non-zero status is returned
+back to the caller instead, then a generic 500 response will be created and
+sent, if possible, and the connection will be closed.
+
+=== Directory Handler
+
+The second member of this family, `nng_http_handler_alloc_directory()`, creates
+a handler configured to serve a directory tree.  The _uri_ is taken as
+the root, and files are served from the directory tree rooted at _path_.
+
+When the client Request-URI resolves to a directory in the filesystem,
+the handler looks first for a file named `index.html` or `index.htm`.  If
+one is found, then that file is returned back to the client.   If no such
+index file exists, then an `NNG_HTTP_STATUS_NOT_FOUND` (404) error is
+sent back to the client.
+
+The `Content-Type` will be set automatically based upon the extension
+of the requsted file name.  If a content type cannot be determined from
+the extension, then `application/octet-stream` is used.
+
+=== File Handler
+
+The third member of this family, `nng_http_handler_alloc_file()`, creates
+a handler to serve up a single file; it does not traverse directories
+or search for `index.html` or `index.htm` files. 
+
+The `Content-Type` will be set automatically based upon the extension
+of the requsted file name.  If a content type cannot be determined from
+the extension, then `application/octet-stream` is used.
+
+=== Static Handler
+
+The fourth member of this family, `nng_http_handler_alloc_static()`, creates
+a handler to serve up fixed content located in program data.  The client is
+sent the _data_, with `Content-Length` of _size_ bytes, and `Content-Type` of
+__content_type__.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_EINVAL`:: An invalid _path_ was specified.
+`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message.
+`NNG_ENOTSUP`:: No support for HTTP in the library.
+
+== SEE ALSO
+
+<<nng_aio_finish#,nng_aio_finish(3)>>,
+<<nng_aio_get_input#,nng_aio_get_input(3)>>,
+<<nng_aio_set_output#,nng_aio_set_output(3)>>,
+<<nng_http_handler_free#,nng_http_handler_free(3)>>,
+<<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>,
+<<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>,
+<<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>,
+<<nng_http_res_alloc#,nng_http_res_alloc(3)>>,
+<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>