doc: nng_url converted to mdbook.

5 files changed, 8 insertions, 258 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 7187446b..a6541b52 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -253,16 +253,16 @@ to observe program behaviors and as an aid in troubleshooting.
 |xref:nng_stats_get.3.adoc[nng_stats_get()]|get statistics
 |===
 
-=== URL Object
+// === URL Object
 
-Common functionality is supplied for parsing and handling
-universal resource locators (URLS).
+// Common functionality is supplied for parsing and handling
+// universal resource locators (URLS).
 
-|===
-|xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure
-|xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure
-|xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string
-|===
+// |===
+// |xref:nng_url_clone.3.adoc[nng_url_clone()]|clone URL structure
+// |xref:nng_url_free.3.adoc[nng_url_free()]|free URL structure
+// |xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string
+// |===
 
 === Logging Support
 
diff --git a/docs/man/nng_url.5.adoc b/docs/man/nng_url.5.adoc
deleted file mode 100644
index 2e01b9de..00000000
--- a/docs/man/nng_url.5.adoc
+++ /dev/null
@@ -1,71 +0,0 @@
-= nng_url(5)
-//
-// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
-//
-// 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 - Universal Resource Locator object
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_url {
-    char *u_rawurl;
-    char *u_scheme;
-    char *u_userinfo;
-    char *u_host;
-    char *u_hostname;
-    char *u_port;
-    char *u_path;
-    char *u_query;
-    char *u_fragment;
-    char *u_requri;
-} nng_url;
-----
-
-== DESCRIPTION
-
-(((URL)))(((address, socket)))
-An `nng_url` is a structure used for
-representing URLs.
-These structures are created by parsing string formatted URLs with
-xref:nng_url_parse.3.adoc[`nng_url_parse()`].
-
-Applications may access individual fields, but must not free or
-alter them, as the underlying memory is managed by the library.
-
-The fields are as follows:
-
-[horizontal]
-`u_rawurl`:: The unparsed URL string.  This will never be `NULL`.
-`u_scheme`:: The URL scheme, such as "http" or "inproc". Always lower case. This will never be `NULL`.
-`u_userinfo`:: This username and password if supplied in the URL string.  Will be `NULL` when not present.
-`u_host`:: The full host part of the URL, including the port if present (separated by a colon.)
-`u_hostname`:: The name of the host, and may be the empty string in some cases.
-`u_port`:: The port.  May be empty if irrelevant or not specified.
-`u_path`:: The path, typically used with HTTP or WebSockets.  Will be empty string if not specified.
-`u_query`:: The query info (typically following `?` in the URL.)  Will be `NULL` if not present.
-`u_fragment`:: This is used for specifying an anchor, the part after `#` in a URL.  Will be `NULL` if not present.
-`u_requri`:: The full Request-URI  (path[?query][#fragment]). Will be the empty string if not specified.
-
-NOTE: Other fields may also be present, but only those documented here are safe for application use.
-
-TIP: More information about Universal Resource Locators can be found in
-https://tools.ietf.org/html/rfc3986[RFC 3986].
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_url_clone.3.adoc[nng_url_clone(3)],
-xref:nng_url_free.3.adoc[nng_url_free(3)],
-xref:nng_url_parse.3.adoc[nng_url_parse(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_url_clone.3.adoc b/docs/man/nng_url_clone.3.adoc
deleted file mode 100644
index 0e6ef15f..00000000
--- a/docs/man/nng_url_clone.3.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-= nng_url_clone(3)
-//
-// Copyright 2020 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_clone - clone URL structure
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_url_clone(nng_url **dup, nng_url *orig);
-----
-
-== DESCRIPTION
-
-The `nng_url_clone()` makes a clone of the original URL structure _orig_, and
-saves the result in the location pointed by _dup_.
-This clone includes fully duplicating each of the member fields.
-
-The new
-xref:nng_url.5.adoc[`nng_url`] structure can be disposed of
-using
-xref:nng_url_free.3.adoc[`nng_url_free()`] when it is no longer needed.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists to duplicate a message.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_url_free.3.adoc[nng_url_free(3)],
-xref:nng_url_parse.3.adoc[nng_url_parse(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_url.5.adoc[nng_url(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_url_free.3.adoc b/docs/man/nng_url_free.3.adoc
deleted file mode 100644
index 27ff871e..00000000
--- a/docs/man/nng_url_free.3.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-= nng_url_free(3)
-//
-// Copyright 2020 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_free - free a URL structure
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_url_free(nng_url *url);
-----
-
-== DESCRIPTION
-
-The `nng_url_free()` function deallocates the _url_ entirely, including
-any of its members.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_url_clone.3.adoc[nng_url_clone(3)],
-xref:nng_url_parse.3.adoc[nng_url_parse(3)],
-xref:nng_url.5.adoc[nng_url(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_url_parse.3.adoc b/docs/man/nng_url_parse.3.adoc
deleted file mode 100644
index 15d8137d..00000000
--- a/docs/man/nng_url_parse.3.adoc
+++ /dev/null
@@ -1,83 +0,0 @@
-= nng_url_parse(3)
-//
-// Copyright 2020 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
-an
-xref:nng_url.5.adoc[`nng_url`] structure containing the results.
-A pointer to the resulting structure is stored in _urlp_.
-
-The structure may disposed of when no longer needed by calling
-xref:nng_url_free.3.adoc[`nng_url_free()`].
-
-=== 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
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message.
-`NNG_EINVAL`:: An invalid URL was supplied.
-
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_url_clone.3.adoc[nng_url_clone(3)],
-xref:nng_url_free.3.adoc[nng_url_free(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_url.5.adoc[nng_url(5)],
-xref:nng.7.adoc[nng(7)]