converted nng_device

4 files changed, 115 insertions, 122 deletions

diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc
deleted file mode 100644
index 7151239f..00000000
--- a/docs/man/nng_device.3.adoc
+++ /dev/null
@@ -1,122 +0,0 @@
-= nng_device(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_device - message forwarding device
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-
-int nng_device(nng_socket s1, nng_socket s2);
-
-void nng_device_aio(nng_aio *aio, nng_socket s1, nng_socket s2);
-----
-
-== DESCRIPTION
-
-The `nng_device()` and `nng_device_aio()` functions forward messages received from one
-xref:nng_socket.5.adoc[socket] _s1_ to another socket _s2_, and vice versa.
-
-These functions are used to create forwarders, which can be used to create
-complex network topologies to provide for improved ((horizontal scalability)),
-reliability, and isolation.
-
-Only xref:nng_options.5.adoc#NNG_OPT_RAW[raw] mode sockets may be used with this
-function.
-These can be created using `_raw` forms of the various socket constructors,
-such as xref:nng_req_open.3.adoc[`nng_req0_open_raw()`].
-
-The `nng_device()` function does not return until one of the sockets
-is closed.
-The `nng_device_aio()` function returns immediately, and operates completely in
-the background.
-
-=== Reflectors
-
-One of the sockets passed may be an unopened socket initialized with
-the `NNG_SOCKET_INITIALIZER` special value.
-If this is the case, then the other socket must be valid, and must use
-a protocol that is bidirectional and can peer with itself (such as
-xref:nng_pair.7.adoc[_pair_] or
-xref:nng_bus.7.adoc[_bus_].)
-In this case the device acts as a ((reflector)) or loop-back device,
-where messages received from the valid socket are merely returned
-to the sender.
-
-=== Forwarders
-
-When both sockets are valid, then the result is a ((forwarder)) or proxy.
-In this case sockets _s1_ and _s2_ must be compatible with each other,
-which is to say that they should represent the opposite halves of a two
-protocol pattern, or both be the same protocol for a single protocol
-pattern.
-For example, if _s1_ is a xref:nng_pub.7.adoc[_pub_] socket, then _s2_ must
-be a xref:nng_sub.7.adoc[_sub_] socket.
-Or, if _s1_ is a xref:nng_bus.7.adoc[_bus_] socket, then _s2_ must also
-be a _bus_ socket.
-
-=== Operation
-
-The `nng_device()` function moves messages between the provided sockets.
-
-When a protocol has a ((backtrace)) style header, routing information
-is present in the header of received messages, and is copied to the
-header of the output bound message.
-The underlying raw mode protocols supply the necessary header
-adjustments to add or remove routing headers as needed.
-This allows replies to be
-returned to requesters, and responses to be routed back to surveyors.
-
-The caller of these functions is required to close the sockets when the
-device is stopped.
-
-Additionally, some protocols have a maximum ((time-to-live)) to protect
-against forwarding loops and especially amplification loops.
-In these cases, the default limit (usually 8), ensures that messages will
-self-terminate when they have passed through too many forwarders,
-protecting the network from unlimited message amplification that can arise
-through misconfiguration.
-This is controlled via the xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]
-option.
-
-IMPORTANT: Not all protocols have support for guarding against forwarding loops,
-and even for those that do, forwarding loops can be extremely detrimental
-to network performance.
-
-NOTE: Devices (forwarders and reflectors) act in best-effort delivery mode only.
-If a message is received from one socket that cannot be accepted by the
-other (due to backpressure or other issues), then the message is discarded.
-
-TIP: Use the request/reply pattern, which includes automatic retries by
-the requester, if reliable delivery is needed.
-
-== RETURN VALUES
-
-This function continues running, and only returns an appropriate error when
-one occurs, or if one of the sockets is closed.
-
-== ERRORS
-
-[horizontal]
-`NNG_ECLOSED`:: At least one of the sockets is not open.
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_EINVAL`:: The sockets are not compatible, or are both invalid.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_options.5.adoc[nng_options(5)],
-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 fe9913f2..2315b515 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -53,6 +53,7 @@
 
     - [nng_bus_open](sock/nng_bus_open.md)
     - [nng_close](sock/nng_close.md)
+    - [nng_device](sock/nng_device.md)
     - [nng_pub_open](sock/nng_pub_open.md)
 
   - [Contexts](ctx/index.md)
diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md
index 44dd69a3..97bea94a 100644
--- a/docs/reference/src/refs.md
+++ b/docs/reference/src/refs.md
@@ -48,6 +48,7 @@
 [nng_surveyor_open]: ../sock/nng_surveyor_open.md
 [nng_sub_open]: ../sock/nng_sub_open.md
 [nng_close]: ../sock/nng_close.md
+[nng_device]: ../sock/nng_device.md
 
 <!-- Messages -->
 
diff --git a/docs/reference/src/sock/nng_device.md b/docs/reference/src/sock/nng_device.md
new file mode 100644
index 00000000..1c59314a
--- /dev/null
+++ b/docs/reference/src/sock/nng_device.md
@@ -0,0 +1,113 @@
+# nng_device
+
+## NAME
+
+nng_device - message forwarding device
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+int nng_device(nng_socket s1, nng_socket s2);
+
+void nng_device_aio(nng_aio *aio, nng_socket s1, nng_socket s2);
+```
+
+### DESCRIPTION
+
+The `nng_device()` and `nng_device_aio()` functions forward messages received from one
+[socket][socket] _s1_ to another socket _s2_, and vice versa.
+
+These functions are used to create forwarders, which can be used to create
+complex network topologies to provide for improved {{i:horizontal scalability}},
+reliability, and isolation.
+
+Only [raw mode][raw] sockets may be used with this
+function.
+These can be created using `_raw` forms of the various socket constructors,
+such as [`nng_req0_open_raw()`][nng_req_open].
+
+The `nng_device()` function does not return until one of the sockets
+is closed.
+The `nng_device_aio()` function returns immediately, and operates completely in
+the background.
+
+### Reflectors
+
+One of the sockets passed may be an unopened socket initialized with
+the {{i:`NNG_SOCKET_INITIALIZER`}} special value.
+If this is the case, then the other socket must be valid, and must use
+a protocol that is bidirectional and can peer with itself
+(such as [_PAIR_][pair] or [_BUS_][bus]).
+In this case the device acts as a {{i:reflector}} or {{i:loop-back}} device,
+where messages received from the valid socket are merely returned
+to the sender.
+
+## Forwarders
+
+When both sockets are valid, then the result is a {{i:forwarder}} or proxy.
+In this case sockets _s1_ and _s2_ must be compatible with each other,
+which is to say that they should represent the opposite halves of a two
+protocol pattern, or both be the same protocol for a single protocol
+pattern.
+For example, if _s1_ is a [_PUB_][pub] socket, then _s2_ must
+be a [_SUB_][sub] socket.
+Or, if _s1_ is a [_BUS_][bus] socket, then _s2_ must also
+be a _BUS_ socket.
+
+### Operation
+
+The `nng_device()` function moves messages between the provided sockets.
+
+When a protocol has a {{i:backtrace}} style header, routing information
+is present in the header of received messages, and is copied to the
+header of the output bound message.
+The underlying raw mode protocols supply the necessary header
+adjustments to add or remove routing headers as needed.
+This allows replies to be
+returned to requesters, and responses to be routed back to surveyors.
+
+The caller of these functions is required to close the sockets when the
+device is stopped.
+
+Additionally, some protocols have a maximum {{i:time-to-live}} to protect
+against forwarding loops and especially amplification loops.
+In these cases, the default limit (usually 8), ensures that messages will
+self-terminate when they have passed through too many forwarders,
+protecting the network from unlimited message amplification that can arise
+through misconfiguration.
+This is controlled via the [`NNG_OPT_MAXTTL`][NNG_OPT_MAXTTL] option.
+
+> [!NOTE]
+> Not all protocols have support for guarding against forwarding loops,
+> and even for those that do, forwarding loops can be extremely detrimental
+> to network performance.
+
+> [!NOTE]
+> Devices (forwarders and reflectors) act in {{i:best-effort}} delivery
+> mode only.
+> If a message is received from one socket that cannot be accepted by the
+> other (due to {{i:back-pressure}} or other issues), then the message is discarded.
+
+> [!TIP]
+> Use the request/reply pattern, which includes automatic retries by
+> the requester, if reliable delivery is needed.
+
+## RETURN VALUES
+
+This function continues running, and only returns an appropriate error when
+one occurs, or if one of the sockets is closed.
+
+## ERRORS
+
+- `NNG_ECLOSED`: At least one of the sockets is not open.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_EINVAL`: The sockets are not compatible, or are both invalid.
+
+## SEE ALSO
+
+[Sockets][socket],
+[Raw mode][raw]
+
+{{#include ../refs.md}}