nng_recv* added

11 files changed, 315 insertions, 363 deletions

diff --git a/docs/man/nng_recv.3.adoc b/docs/man/nng_recv.3.adoc
deleted file mode 100644
index ef1f2756..00000000
--- a/docs/man/nng_recv.3.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-= nng_recv(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_recv - recv data
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);
-----
-
-== DESCRIPTION
-
-The `nng_recv()` receives a message.
-
-The _flags_ is a bit mask that may contain any of the following values:
-
-`NNG_FLAG_NONBLOCK`::
-  The function returns immediately, even if no message is available.
-  Without this flag, the function will wait until a message is received
-  by the socket _s_, or any configured timer expires.
-
-`NNG_FLAG_ALLOC`::
-  If this flag is present, then a ((zero-copy)) mode is used.
-  In this case the caller must set the value of _data_ to the location
-  of another pointer (of type `void *`), and the _sizep_ pointer must be set
-  to a location to receive the size of the message body.
-  The function will then allocate a message buffer
-  (as if by xref:nng_alloc.3.adoc[`nng_alloc()`]), fill it with
-  the message body, and store it at the address referenced by _data_, and update
-  the size referenced by _sizep_.
-  The caller is responsible for disposing of the received buffer either by
-  the xref:nng_free.3.adoc[`nng_free()`] function or passing the message (also
-  with the `NNG_FLAG_ALLOC` flag) in a call to xref:nng_send.3.adoc[`nng_send()`].
-
-If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the
-caller must set _data_ to a buffer to receive the message body content,
-and must store the size of that buffer at the location pointed to by _sizep_.
-When the function returns, if it is successful, the size at _sizep_ will be
-updated with the actual message body length copied into _data_.
-
-NOTE: The semantics of what receiving a message means vary from protocol to
-protocol, so examination of the protocol documentation is encouraged.
-(For example, with a xref:nng_req.7.adoc[_req_] socket a message may only be received
-after a request has been sent, and a xref:nng_sub.7.adoc[_sub_] socket
-may only receive messages corresponding to topics to which it has subscribed.)
-Furthermore, some protocols may not support receiving data at all, such as
-xref:nng_pub.7.adoc[_pub_].
-
-TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby
-increasing performance, particularly if the buffer is reused to send
-a response using the same flag.
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
-`NNG_ECLOSED`:: The socket _s_ is not open.
-`NNG_EINVAL`:: An invalid set of _flags_ was specified.
-`NNG_EMSGSIZE`:: The received message did not fit in the size provided.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving.
-`NNG_ESTATE`:: The socket _s_ cannot receive data in this state.
-`NNG_ETIMEDOUT`:: The operation timed out.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_alloc.3.adoc[nng_alloc(3)],
-xref:nng_free.3.adoc[nng_free(3)],
-xref:nng_recvmsg.3.adoc[nng_recvmsg(3)],
-xref:nng_send.3.adoc[nng_send(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_recv_aio.3.adoc b/docs/man/nng_recv_aio.3.adoc
deleted file mode 100644
index 4c970489..00000000
--- a/docs/man/nng_recv_aio.3.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-= nng_recv_aio(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_recv_aio - receive message asynchronously
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-void nng_recv_aio(nng_socket s, nng_aio *aio);
-----
-
-== DESCRIPTION
-
-The `nng_recv_aio()` receives a xref:nng_msg.5.adoc[message] using the
-xref:nng_socket.5.adoc[socket] _s_ asynchronously.
-
-When a message is successfully received by the socket, it is
-stored in the _aio_ by an internal call equivalent to
-xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`], then the completion
-callback on the _aio_ is executed.
-In this case, xref:nng_aio_result.3.adoc[`nng_aio_result()`] will
-return zero.
-The callback function is responsible for retrieving the message
-and disposing of it appropriately.
-
-IMPORTANT: Failing to accept and dispose of messages in this
-case can lead to memory leaks.
-
-If for some reason the asynchronous receive cannot be completed
-successfully (including by being canceled or timing out), then
-the callback will still be executed,
-but xref:nng_aio_result.3.adoc[`nng_aio_result()`] will be non-zero.
-
-NOTE: The semantics of what receiving a message means varies from protocol to
-protocol, so examination of the protocol documentation is encouraged.
-(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that
-any peers who have a suitable subscription will be able to receive it using
-xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.)
-Furthermore, some protocols may not support receiving (such as
-xref:nng_pub.7.adoc[_pub_]) or may require other conditions.
-(For example, xref:nng_req.7.adoc[_req_] sockets cannot normally receive data, which
-are replies to requests, until they have first sent a request.)
-
-== RETURN VALUES
-
-None.  (The operation completes asynchronously.)
-
-== ERRORS
-
-[horizontal]
-`NNG_ECANCELED`:: The operation was aborted.
-`NNG_ECLOSED`:: The socket _s_ is not open.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving.
-`NNG_ESTATE`:: The socket _s_ cannot receive data in this state.
-`NNG_ETIMEDOUT`:: The receive timeout expired.
-
-== 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_strerror.3.adoc[nng_strerror(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_recvmsg.3.adoc b/docs/man/nng_recvmsg.3.adoc
deleted file mode 100644
index c502d650..00000000
--- a/docs/man/nng_recvmsg.3.adoc
+++ /dev/null
@@ -1,71 +0,0 @@
-= nng_recvmsg(3)
-//
-// Copyright 2021 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_recvmsg - receive a message
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags);
-----
-
-== DESCRIPTION
-
-The `nng_recvmsg()` receives a message on socket _s_, storing the
-received message at the location pointed to by _msgp_.
-
-TIP: Using this function gives access to the message structure, and thus may
-offer more functionality than the simpler xref:nng_recv.3.adoc[`nng_recv()`] function.
-
-The _flags_ may contain the following value:
-
-`NNG_FLAG_NONBLOCK`::
-  The function returns immediately, even if no message is available.
-  Without this flag, the function will wait until a message is received
-  by the socket _s_, or any configured timer expires.
-
-NOTE: The semantics of what receiving a message means vary from protocol to
-protocol, so examination of the protocol documentation is encouraged.
-(For example, with an xref:nng_req.7.adoc[_req_] socket a message may only be received
-after a request has been sent, and an xref:nng_sub.7.adoc[_sub_] socket
-may only receive messages corresponding to topics to which it has subscribed.)
-Furthermore, some protocols may not support receiving data at all, such as
-xref:nng_pub.7.adoc[_pub_].
-
-== RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-== ERRORS
-
-[horizontal]
-`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
-`NNG_ECLOSED`:: The socket _s_ is not open.
-`NNG_EINVAL`:: An invalid set of _flags_ was specified.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving.
-`NNG_ESTATE`:: The socket _s_ cannot receive data in this state.
-`NNG_ETIMEDOUT`:: The operation timed out.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_free.3.adoc[nng_msg_free(3)],
-xref:nng_recv.3.adoc[nng_recv(3)],
-xref:nng_sendmsg.3.adoc[nng_sendmsg(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index 40a02f7d..1a911e37 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -61,6 +61,9 @@
     - [nng_pull_open](sock/nng_pull_open.md)
     - [nng_push_open](sock/nng_push_open.md)
     - [nng_respondent_open](sock/nng_respondent_open.md)
+    - [nng_recv](sock/nng_recv.md)
+    - [nng_recv_aio](sock/nng_recv_aio.md)
+    - [nng_recvmsg](sock/nng_recvmsg.md)
     - [nng_rep_open](sock/nng_rep_open.md)
     - [nng_req_open](sock/nng_req_open.md)
     - [nng_sub_open](sock/nng_sub_open.md)
diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md
index cb5c74f1..98a3d153 100644
--- a/docs/reference/src/refs.md
+++ b/docs/reference/src/refs.md
@@ -54,6 +54,12 @@
 [nng_surveyor_open]: ../sock/nng_surveyor_open.md
 [nng_close]: ../sock/nng_close.md
 [nng_device]: ../sock/nng_device.md
+[nng_recv]: ../sock/nng_recv.md
+[nng_recv_aio]: ../sock/nng_recv_aio.md
+[nng_recvmsg]: ../sock/nng_recvmsg.md
+[nng_send]: ../sock/nng_send.md
+[nng_send_aio]: ../sock/nng_send_aio.md
+[nng_sendmsg]: ../sock/nng_sendmsg.md
 
 <!-- Messages -->
 
diff --git a/docs/reference/src/sock/nng_recv.md b/docs/reference/src/sock/nng_recv.md
new file mode 100644
index 00000000..178661f7
--- /dev/null
+++ b/docs/reference/src/sock/nng_recv.md
@@ -0,0 +1,83 @@
+# nng_recv
+
+## NAME
+
+nng_recv --- recv data
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_recv(nng_socket s, void *data, size_t *sizep, int flags);
+```
+
+## DESCRIPTION
+
+The `nng_recv()` receives a message from the [socket][socket] _s_,
+obtaining its body content.
+
+The _flags_ is a bit mask that may contain any of the following values:
+
+- `NNG_FLAG_NONBLOCK`:\
+  The function returns immediately, even if no message is available.
+  Without this flag, the function will wait until a message is received
+  by the socket _s_, or any configured timer expires.
+
+- `NNG_FLAG_ALLOC`:\
+  If this flag is present, then a {{i:zero-copy}} mode is used.
+  In this case the caller must set the value of _data_ to the location
+  of another pointer (of type `void *`), and the _sizep_ pointer must be set
+  to a location to receive the size of the message body.
+  The function will then allocate a message buffer
+  (as if by [`nng_alloc()`][nng_alloc]), fill it with
+  the message body, and store it at the address referenced by _data_, and update
+  the size referenced by _sizep_.
+  The caller is responsible for disposing of the received buffer either by
+  the [`nng_free()`][nng_free] function or passing the message (also
+  with the {{i:`NNG_FLAG_ALLOC`}} flag) in a call to [`nng_send()`][nng_send].
+
+If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the
+caller must set _data_ to a buffer to receive the message body content,
+and must store the size of that buffer at the location pointed to by _sizep_.
+When the function returns, if it is successful, the size at _sizep_ will be
+updated with the actual message body length copied into _data_.
+
+> [!NOTE]
+> The semantics of what receiving a message means vary from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> (For example, with a [_REQ_][req] socket a message may only be received
+> after a request has been sent, and a [_SUB_][sub] socket
+> may only receive messages corresponding to topics to which it has subscribed.)
+> Furthermore, some protocols may not support receiving data at all, such as
+> [_PUB_][pub].
+
+> [!TIP]
+> The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby
+> increasing performance, particularly if the buffer is reused to send
+> a response using the same flag. However, the [`nng_recvmsg()`][nng_recvmsg] function is even better in this regard, and should be preferred over this
+> function when possible.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+- `NNG_ECLOSED`: The socket _s_ is not open.
+- `NNG_EINVAL`: An invalid set of _flags_ was specified.
+- `NNG_EMSGSIZE`: The received message did not fit in the size provided.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
+- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
+- `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc],
+[nng_free][nng_free],
+[nng_recvmsg][nng_recvmsg],
+[nng_send][nng_send]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_recv_aio.md b/docs/reference/src/sock/nng_recv_aio.md
new file mode 100644
index 00000000..257ec691
--- /dev/null
+++ b/docs/reference/src/sock/nng_recv_aio.md
@@ -0,0 +1,65 @@
+# nng_recv_aio
+
+## NAME
+
+nng_recv_aio --- receive message asynchronously
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+void nng_recv_aio(nng_socket s, nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_recv_aio()` function receives a [message][msg] using the
+[socket][socket] _s_ asynchronously.
+
+When a message is successfully received by the socket, it is
+stored in the _aio_ by an internal call equivalent to
+[`nng_aio_set_msg()`][nng_aio_set_msg], then the completion
+callback on the _aio_ is executed.
+In this case, [`nng_aio_result()`][nng_aio_result] will
+return zero.
+The callback function is responsible for retrieving the message
+and disposing of it appropriately.
+
+> [!IMPORTANT]
+> Failing to dispose of successfully received messages
+> will leak the memory associated with it.
+
+If for some reason the asynchronous receive cannot be completed
+successfully (including by being canceled or timing out), then
+the callback will still be executed,
+but `nng_aio_result()` will be non-zero.
+
+> [!NOTE]
+> The semantics of what receiving a message means varies from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> For example, with [_PUB_][pub] socket the data is broadcast, so that
+> only peers who have a suitable subscription will be able to receive it.
+> Furthermore, some protocols may not support receiving (such as
+> _PUB_) or may require other conditions.
+> (For example, [_REQ_][req] sockets cannot normally receive data
+> until they have first sent a request.)
+
+## ERRORS
+
+- `NNG_ECANCELED`: The operation was aborted.
+- `NNG_ECLOSED`: The socket _s_ is not open.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
+- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
+- `NNG_ETIMEDOUT`: The receive timeout expired.
+
+## SEE ALSO
+
+[Messages][msg],
+[Sockets][socket],
+[Asynchronous I/O][aio],
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_msg_alloc][nng_msg_alloc]
+
+{{#include ../refs.md}}
diff --git a/docs/reference/src/sock/nng_recvmsg.md b/docs/reference/src/sock/nng_recvmsg.md
new file mode 100644
index 00000000..3d3912c0
--- /dev/null
+++ b/docs/reference/src/sock/nng_recvmsg.md
@@ -0,0 +1,68 @@
+# nng_recvmsg
+
+## NAME
+
+nng_recvmsg --- receive a message
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags);
+```
+
+## DESCRIPTION
+
+The `nng_recvmsg()` receives a [message][msg] on [socket][socket] _s_, storing the
+received message at the location pointed to by _msgp_.
+
+This function gives access to the message structure, and thus may
+offer more functionality than the simpler [`nng_recv()`][nng_recv] function.[^1] [^2]
+
+[^1]: It is also more efficient.
+[^2]: An asynchronous form of this function is available as [`nng_recv_aio()`][nng_recv_aio].
+
+The _flags_ may contain the following value:
+
+- {{i:`NNG_FLAG_NONBLOCK`}}: \
+  The function returns immediately, even if no message is available.
+  Without this flag, the function will wait until a message is received
+  by the socket _s_, or any configured timer expires.
+
+After successfully receiving a message, the caller is responsible for
+disposing of it when it is no longer needed.
+
+> [!IMPORTANT]
+> Failing to dispose of the message will leak the memory associated with it.
+
+> [!NOTE]
+> The semantics of what receiving a message means vary from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> (For example, with a [_REQ_][req] socket a message may only be received
+> after a request has been sent).
+> Furthermore, some protocols do not support receiving data at all.
+
+## RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+## ERRORS
+
+- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+- `NNG_ECLOSED`: The socket _s_ is not open.
+- `NNG_EINVAL`: An invalid set of _flags_ was specified.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving.
+- `NNG_ESTATE`: The socket _s_ cannot receive data in this state.
+- `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[Messages][msg],
+[Sockets][socket],
+[nng_msg_free][nng_msg_free],
+[nng_recv][nng_recv],
+[nng_sendmsg][nng_sendmsg]
+
+{{#include ../refs.md}}
diff --git a/docs/man/nng_send.3.adoc b/docs/reference/src/sock/nng_send.3.adoc
index 7037f547..4932712a 100644
--- a/docs/man/nng_send.3.adoc
+++ b/docs/reference/src/sock/nng_send.3.adoc
@@ -1,28 +1,18 @@
-= nng_send(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.
-//
+# nng_send
 
-== NAME
+## NAME
 
-nng_send - send data
+nng_send --- send data
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```
 #include <nng/nng.h>
 
 int nng_send(nng_socket s, void *data, size_t size, int flags);
-----
+```
 
-== DESCRIPTION
+## DESCRIPTION
 
 The `nng_send()` function sends a message containing the _data_ of
 length _size_ using the xref:nng_socket.5.adoc[socket] _s_.
@@ -72,29 +62,29 @@ Using an incorrect size results
 in unspecified behavior, which may include heap corruption, program crashes,
 or trans-dimensional mutation of the program's author.
 
-== RETURN VALUES
+## RETURN VALUES
 
 This function returns 0 on success, and non-zero otherwise.
 
-== ERRORS
-
-[horizontal]
-`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
-`NNG_ECLOSED`:: The socket _s_ is not open.
-`NNG_EINVAL`:: An invalid set of _flags_ was specified.
-`NNG_EMSGSIZE`:: The value of _size_ is too large.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending.
-`NNG_ESTATE`:: The socket _s_ cannot send data in this state.
-`NNG_ETIMEDOUT`:: The operation timed out.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_alloc.3.adoc[nng_alloc(3)],
-xref:nng_free.3.adoc[nng_free(3)],
-xref:nng_recv.3.adoc[nng_recv(3)],
-xref:nng_sendmsg.3.adoc[nng_sendmsg(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng.7.adoc[nng(7)]
+## ERRORS
+
+* `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+* `NNG_ECLOSED`: The socket _s_ is not open.
+* `NNG_EINVAL`: An invalid set of _flags_ was specified.
+* `NNG_EMSGSIZE`: The value of _size_ is too large.
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending.
+* `NNG_ESTATE`: The socket _s_ cannot send data in this state.
+* `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[nng_alloc][nng_alloc],
+[nng_free][nng_free],
+[nng_recv][nng_recv],
+[nng_sendmsg][nng_sendmsg],
+[nng_strerror][nng_strerror],
+[nng_socket][nng_socket],
+[nng][nng]
+
+{{#include ../refs.md}}
diff --git a/docs/man/nng_send_aio.3.adoc b/docs/reference/src/sock/nng_send_aio.3.adoc
index e8fc2005..4597619c 100644
--- a/docs/man/nng_send_aio.3.adoc
+++ b/docs/reference/src/sock/nng_send_aio.3.adoc
@@ -1,28 +1,18 @@
-= nng_send_aio(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.
-//
+# nng_send_aio
 
-== NAME
+## NAME
 
-nng_send_aio - send message asynchronously
+nng_send_aio --- send message asynchronously
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```
 #include <nng/nng.h>
 
 void nng_send_aio(nng_socket s, nng_aio *aio);
-----
+```
 
-== DESCRIPTION
+## DESCRIPTION
 
 The `nng_send_aio()` sends a xref:nng_msg.5.adoc[message] using the
 xref:nng_socket.5.adoc[socket] _s_ asynchronously.
@@ -63,29 +53,29 @@ xref:nng_sub.7.adoc[_sub_]) or may require other conditions.
 (For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which
 are responses to requests, until they have first received a request.)
 
-== RETURN VALUES
+## RETURN VALUES
 
 None.  (The operation completes asynchronously.)
 
-== ERRORS
-
-[horizontal]
-`NNG_ECANCELED`:: The operation was aborted.
-`NNG_ECLOSED`:: The socket _s_ is not open.
-`NNG_EMSGSIZE`:: The message is too large.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending.
-`NNG_ESTATE`:: The socket _s_ cannot send data in this state.
-`NNG_ETIMEDOUT`:: The send timeout expired.
-
-== 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_strerror.3.adoc[nng_strerror(3)],
-xref:nng_aio.5.adoc[nng_aio(5)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng.7.adoc[nng(7)]
+## ERRORS
+
+* `NNG_ECANCELED`: The operation was aborted.
+* `NNG_ECLOSED`: The socket _s_ is not open.
+* `NNG_EMSGSIZE`: The message is too large.
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending.
+* `NNG_ESTATE`: The socket _s_ cannot send data in this state.
+* `NNG_ETIMEDOUT`: The send timeout expired.
+
+## SEE ALSO
+
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_msg_alloc][nng_msg_alloc],
+[nng_strerror][nng_strerror],
+[nng_aio][nng_aio],
+[nng_msg][nng_msg],
+[nng_socket][nng_socket],
+[nng][nng]
+
+{{#include ../refs.md}}
diff --git a/docs/man/nng_sendmsg.3.adoc b/docs/reference/src/sock/nng_sendmsg.3.adoc
index 5b7a73ee..004ae78d 100644
--- a/docs/man/nng_sendmsg.3.adoc
+++ b/docs/reference/src/sock/nng_sendmsg.3.adoc
@@ -1,28 +1,18 @@
-= nng_sendmsg(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.
-//
+# nng_sendmsg
 
-== NAME
+## NAME
 
-nng_sendmsg - send message
+nng_sendmsg --- send message
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```
 #include <nng/nng.h>
 
 int nng_sendmsg(nng_socket s, nng_msg *msg, int flags);
-----
+```
 
-== DESCRIPTION
+## DESCRIPTION
 
 The `nng_sendmsg()` sends message _msg_ using the socket _s_.
 
@@ -66,29 +56,29 @@ Furthermore, there is no guarantee that the message has actually been delivered.
 Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`,
 such as with xref:nng_pub.7.adoc[_pub_] sockets, which are best-effort delivery only.
 
-== RETURN VALUES
+## RETURN VALUES
 
 This function returns 0 on success, and non-zero otherwise.
 
-== ERRORS
-
-[horizontal]
-`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
-`NNG_ECLOSED`:: The socket _s_ is not open.
-`NNG_EINVAL`:: An invalid set of _flags_ was specified.
-`NNG_EMSGSIZE`:: The value of _size_ is too large.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending.
-`NNG_ESTATE`:: The socket _s_ cannot send data in this state.
-`NNG_ETIMEDOUT`:: The operation timed out.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
-xref:nng_recvmsg.3.adoc[nng_recvmsg(3)],
-xref:nng_send.3.adoc[nng_send(3)],
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng_msg.5.adoc[nng_msg(5)],
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng.7.adoc[nng(7)]
+## ERRORS
+
+* `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified.
+* `NNG_ECLOSED`: The socket _s_ is not open.
+* `NNG_EINVAL`: An invalid set of _flags_ was specified.
+* `NNG_EMSGSIZE`: The value of _size_ is too large.
+* `NNG_ENOMEM`: Insufficient memory is available.
+* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending.
+* `NNG_ESTATE`: The socket _s_ cannot send data in this state.
+* `NNG_ETIMEDOUT`: The operation timed out.
+
+## SEE ALSO
+
+[nng_msg_alloc][nng_msg_alloc],
+[nng_recvmsg][nng_recvmsg],
+[nng_send][nng_send],
+[nng_strerror][nng_strerror],
+[nng_msg][nng_msg],
+[nng_socket][nng_socket],
+[nng][nng]
+
+{{#include ../refs.md}}