nng_msg docs converted to mdbook

We're moving to fewer man pages, with related functions grouped
together in the same man page, and this continues the trend.

8 files changed, 6 insertions, 392 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index e6a0da4b..e13ddf0b 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -98,19 +98,19 @@ user-payload and the header carries protocol specific header information.
 Most applications will only interact with the body.
 
 |===
-|xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message
+// |xref:nng_msg_alloc.3.adoc[nng_msg_alloc()]|allocate a message
 |xref:nng_msg_append.3.adoc[nng_msg_append()]|append to message body
 |xref:nng_msg_body.3.adoc[nng_msg_body()]|return message body
-|xref:nng_msg_capacity.3.adoc[nng_msg_capacity()]|return capacity allocated for message body
+// |xref:nng_msg_capacity.3.adoc[nng_msg_capacity()]|return capacity allocated for message body
 |xref:nng_msg_chop.3.adoc[nng_msg_chop()]|remove data from end of message body
 |xref:nng_msg_clear.3.adoc[nng_msg_clear()]|clear message body
-|xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message
-|xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message
+// |xref:nng_msg_dup.3.adoc[nng_msg_dup()]|duplicate a message
+// |xref:nng_msg_free.3.adoc[nng_msg_free()]|free a message
 |xref:nng_msg_get_pipe.3.adoc[nng_msg_get_pipe()]|get pipe for message
 |xref:nng_msg_insert.3.adoc[nng_msg_insert()]|prepend to message body
 |xref:nng_msg_len.3.adoc[nng_msg_len()]|return the message body length
-|xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message
-|xref:nng_msg_reserve.3.adoc[nng_msg_reserve()]|reserve storage for message body
+// |xref:nng_msg_realloc.3.adoc[nng_msg_realloc()]|reallocate a message
+// |xref:nng_msg_reserve.3.adoc[nng_msg_reserve()]|reserve storage for message body
 |xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe()]|set pipe for message
 |xref:nng_msg_trim.3.adoc[nng_msg_trim()]|remove data from start of message body
 |xref:nng_recvmsg.3.adoc[nng_recvmsg()]|receive a message
diff --git a/docs/man/nng_msg.5.adoc b/docs/man/nng_msg.5.adoc
deleted file mode 100644
index 5044cf18..00000000
--- a/docs/man/nng_msg.5.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-= nng_msg(5)
-//
-// Copyright 2019 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_msg - message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-typedef struct nng_msg nng_msg;
-----
-
-== DESCRIPTION
-
-An `nng_msg` represents a single ((message)) sent between Scalability Protocols
-peers.
-Messages internally have a ((body)), containing the application supplied
-payload, and a ((header)), containing protocol specific routing and similar
-related information.
-
-TIP: Using message-oriented functions is a good way to reduce the likelihood
-of data copies and improve application performance.
-
-Messages are allocated using the xref:nng_msg_alloc.3.adoc[`nng_msg_alloc()`]
-function, and are deallocated using the xref:nng_msg_free.3.adoc[`nng_msg_free()`]
-function.
-
-In addition there are other functions used to access message contents,
-including adding data to either the beginning or end of the message,
-automatic data conversion, and removing data from the beginning or end.
-These functions are designed to try to avoid copying message contents
-by making use of scratch areas at the beginning and end of the message.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
-xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
-xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_msg_body.3.adoc[nng_msg_body(3)],
-xref:nng_msg_dup.3.adoc[nng_msg_dup(3)],
-xref:nng_msg_free.3.adoc[nng_msg_free(3)],
-xref:nng_msg_header.3.adoc[nng_msg_header(3)],
-xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)],
-xref:nng_msg_len.3.adoc[nng_msg_len(3)],
-xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)],
-xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)],
-xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)],
-xref:nng_recvmsg.3.adoc[nng_recvmsg(3)],
-xref:nng_sendmsg.3.adoc[nng_sendmsg(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_alloc.3.adoc b/docs/man/nng_msg_alloc.3.adoc
deleted file mode 100644
index 2754b67e..00000000
--- a/docs/man/nng_msg_alloc.3.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= nng_msg_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_msg_alloc - allocate a message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_msg_alloc(nng_msg **msgp, size_t size);
-----
-
-== DESCRIPTION
-
-The `nng_msg_alloc()` function allocates a new message with body length _size_
-and stores the result in __msgp__.
-Messages allocated with this function contain a body and optionally a header.
-They are used with receive and transmit functions.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_free.3.adoc[nng_msg_free(3)],
-xref:nng_msg_body.3.adoc[nng_msg_body(3)],
-xref:nng_msg_dup.3.adoc[nng_msg_dup(3)],
-xref:nng_msg_header.3.adoc[nng_msg_header(3)],
-xref:nng_msg_header_len.3.adoc[nng_msg_header_len(3)],
-xref:nng_msg_len.3.adoc[nng_msg_len(3)],
-xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)],
-xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)],
-xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_capacity.3.adoc b/docs/man/nng_msg_capacity.3.adoc
deleted file mode 100644
index ffc7f5d3..00000000
--- a/docs/man/nng_msg_capacity.3.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-= nng_msg_capacity(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_msg_capacity - return message body length
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-size_t nng_msg_capacity(nng_msg *msg);
-----
-
-== DESCRIPTION
-
-The `nng_msg_capacity()` returns the storage allocated for the body of message _msg_.
-The capacity includes the current contents of the message and free space after it.
-The message body may grow to capacity without performing any further allocations.
-
-== RETURN VALUES
-
-Allocated capacity for message body.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)],
-xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_msg_body.3.adoc[nng_msg_body(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_dup.3.adoc b/docs/man/nng_msg_dup.3.adoc
deleted file mode 100644
index b985d5bb..00000000
--- a/docs/man/nng_msg_dup.3.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-= nng_msg_dup(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_msg_dup - duplicate a message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_msg_dup(nng_msg **dup, nng_msg_t *orig);
-----
-
-== DESCRIPTION
-
-The `nng_msg_dup()` makes a duplicate of the original message _orig_, and
-saves the result in the location pointed by _dup_.
-The actual message body and header content is copied,
-but the duplicate may contain a
-different amount of unused space than the original message.
-
-== 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_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_msg_free.3.adoc[nng_msg_free(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_free.3.adoc b/docs/man/nng_msg_free.3.adoc
deleted file mode 100644
index 1ee045c0..00000000
--- a/docs/man/nng_msg_free.3.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= nng_msg_free(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_msg_free - free a message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_msg_free(nng_msg *msg);
-----
-
-== DESCRIPTION
-
-The `nng_msg_free()` function deallocates the message _msg_ entirely.
-
-== RETURN VALUES
-
-None.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_msg_realloc.3.adoc[nng_msg_realloc(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_realloc.3.adoc b/docs/man/nng_msg_realloc.3.adoc
deleted file mode 100644
index bf407289..00000000
--- a/docs/man/nng_msg_realloc.3.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-= nng_msg_realloc(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_msg_realloc - reallocate a message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_msg_realloc(nng_msg *msg, size_t size);
-----
-
-== DESCRIPTION
-
-The `nng_msg_realloc()` function re-allocates a message so that it has
-a body of length _size_.
-This message attempts to avoid extra allocations,
-and will reuse the existing memory when possible.
-
-TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data.
-When appending many small pieces of data to a message using xref:nng_msg_append.3.adoc[`nng_msg_append()`],
-allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`]
-to create sufficient space.
-In any case, reallocating or appending to a message is guaranteed to succeed if the resulting
-body length is less than xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. 
-
-NOTE: Pointers to message body and header content obtained prior to this
-function must not be in use, as the underlying memory used for the message
-may have changed, particularly if the message size is increasing.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)],
-xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_msg_append.3.adoc[nng_msg_append(3)],
-xref:nng_msg_body.3.adoc[nng_msg_body(3)],
-xref:nng_msg_chop.3.adoc[nng_msg_chop(3)],
-xref:nng_msg_free.3.adoc[nng_msg_free(3)],
-xref:nng_msg_insert.3.adoc[nng_msg_insert(3)],
-xref:nng_msg_len.3.adoc[nng_msg_len(3)],
-xref:nng_msg_trim.3.adoc[nng_msg_trim(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_msg_reserve.3.adoc b/docs/man/nng_msg_reserve.3.adoc
deleted file mode 100644
index 254c1e94..00000000
--- a/docs/man/nng_msg_reserve.3.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-= nng_msg_reserve(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_msg_reserve - reserve storage for a message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_msg_reserve(nng_msg *msg, size_t capacity);
-----
-
-== DESCRIPTION
-
-The `nng_msg_reserve()` function ensures a message has allocated enough storage 
-to accommodate a body of the given length.
-This message attempts to avoid extra allocations,
-and will reuse the existing memory when possible.
-
-TIP: Using this message before xref:nng_msg_append.3.adoc[`nng_msg_append()`]
-will prevent additional memory allocations until the message's length exceeds
-the alotted capacity.
-
-NOTE: Pointers to message body and header content obtained prior to this
-function must not be in use, as the underlying memory used for the message
-may have changed, particularly if the message capacity is increasing.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient free memory exists to reallocate a message.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_capacity.3.adoc[nng_msg_capacity(3)],
-xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_msg_append.3.adoc[nng_msg_append(3)],
-xref:nng_msg_body.3.adoc[nng_msg_body(3)],
-xref:nng_msg_chop.3.adoc[nng_msg_chop(3)],
-xref:nng_msg_free.3.adoc[nng_msg_free(3)],
-xref:nng_msg_insert.3.adoc[nng_msg_insert(3)],
-xref:nng_msg_len.3.adoc[nng_msg_len(3)],
-xref:nng_msg_trim.3.adoc[nng_msg_trim(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng.7.adoc[nng(7)]