fixes #286 nng_pair0_open (and all others) need man page

fixes #279 consider restructuring man sections

This represents a rather significant rework, and major editing
effort, for the entire set of manual pages.

All of the pages now have a section number in their filename;
this assists in some other tooling, particularly ebook generation
as every link needs to be programmatically modified when combined
into an ebook.

Section 5 is introduced, and populated with pages for the main
types, and all options are now documented.

Numerous errors have been corrected, including rewriting certain
portions such as the header section of the surveyor protocol.

Much work has been done to facilitate index generation, although
certainly more work remains here.

Every internal link within these pages now resolves; there are no
more dead links.  (This is required to generate Kindle format books.)

1 files changed, 0 insertions, 94 deletions

diff --git a/docs/man/nng_url_parse.adoc b/docs/man/nng_url_parse.adoc
deleted file mode 100644
index c42d5c1c..00000000
--- a/docs/man/nng_url_parse.adoc
+++ /dev/null
@@ -1,94 +0,0 @@
-= nng_url_parse(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_url_parse - create URL structure from a string
-
-== SYNOPSIS
-
-[source, c]
------------
-#include <nng/nng.h>
-
-int nng_url_parse(nng_url **urlp, const char *str);
------------
-
-== DESCRIPTION
-
-The `nng_url_parse()` function parses the string _str_ containing an
-https://tools.ietf.org/html/rfc3986[RFC 3986] compliant URL, and creates
-a structure containing the results.  A pointer to the resulting structure
-is stored in _urlp_.
-
-The `nng_url` structure has at least the following members:
-
-[source, c]
-----
-struct nng_url {
-    char *u_scheme;   // Scheme, such as "http"; always lower case.
-    char *u_rawurl;   // Unparsed URL, with minimal canonicalization.
-    char *u_userinfo; // Userinfo component, or NULL.
-    char *u_host;     // Full host, including port if present.
-    char *u_hostname; // Hostname only (or address), or empy string.
-    char *u_port;     // Port number, may be default or empty string.
-    char *u_path;     // Path if present, empty string otherwise.
-    char *u_query;    // Query info if present, NULL otherwise.
-    char *u_fragment; // Fragment if present, NULL otherwise.
-    char *u_requri;   // Request-URI (path[?query][#fragment])
-};
-----
-
-=== URL Canonicalization
-
-The `nng_url_parse()` function also canonicalizes the results, as
-follows:
-
-  1. The URL is parsed into the various components.
-  2. The `u_scheme`, `u_hostname`, `u_host`, and `u_port` members are
-     converted to lower case.
-  3. Percent-encoded values for
-     https://tools.ietf.org/html/rfc3986#section-2.3[unreserved characters]
-     converted to their unencoded forms.
-  4. Additionally URL percent-encoded values for characters in the path
-     and with numeric values larger than 127 (i.e. not ASCII) are decoded.
-  5. The resulting `u_path` is checked for invalid UTF-8 sequences, consisting
-     of surrogate pairs, illegal byte sequences, or overlong encodings.
-     If this check fails, then the entire URL is considered invalid, and
-     the function returns `NNG_EINVAL`.
-  6. Path segments consisting of `.` and `..` are resolved as per
-     https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3].
-  7. Further, empty path segments are removed, meaning that duplicate
-     slash (`/`) separators are removed from the path.
-  8. If a port was not specified, but the scheme defines a default
-     port, then `u_port` will be filled in with the value of the default port.
-
-TIP: Only the `u_userinfo`, `u_query`, and `u_fragment` members will ever be
-     `NULL`.  The other members will be filled in with either default values
-     or the empty string if they cannot be determined from _str_.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-
-== ERRORS
-
-`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message.
-`NNG_EINVAL`:: An invalid URL was supplied.
-
-
-== SEE ALSO
-
-<<nng_url_clone#,nng_url_clone(3)>>,
-<<nng_url_free#,nng_url_free(3)>>,
-<<nng_strerror#,nng_strerror(3)>>,
-<<nng#,nng(7)>>