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, 104 insertions, 0 deletions

diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc
new file mode 100644
index 00000000..80780884
--- /dev/null
+++ b/docs/man/nng_device.3.adoc
@@ -0,0 +1,104 @@
+= nng_device(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_sendmsg - send message
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+int nng_device(nng_socket s1, nng_socket s2);
+----
+
+== DESCRIPTION
+
+The `nng_device()` function forwards messages received from one
+<<nng_socket.5#,socket>> _s1_ to another socket _s2_, and vice versa.
+
+This function is used to create forwarders, which can be used to create
+complex network topologies to provide for improved ((horizontal scalability)),
+reliability, and isolation.
+
+The `nng_device()` function does not return until one of the sockets
+is closed.
+
+=== Reflectors
+
+One of the sockets may be passed the special value `-1` (cast to an,
+<<nng_socket.5#,`nng_socket`>> of course).
+If this is the case, then the other socket must be valid, and must be
+a protocol that is bidirectional and can peer with itself (such as
+<<nng_pair.7#,_pair_>> or
+<<nng_bus.7#,_bus_>>.)
+In this case the device acts as a ((reflector)) or loop-back device,
+where messages received from the valid socket are merely returned
+back 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 <<nng_pub.7#,_pub_>> socket, then _s2_ must 
+be a <<nng_sub.7#,_sub_>> socket.
+Or, if _s1_ is a <<nng_bus.7#,_bus_>> socket, then _s2_ must also
+be a _bus_ socket.
+
+=== Operation
+
+This `nng_device()` function puts each socket into raw mode
+(see <<nng_options.5#NNG_OPT_RAW,`NNG_OPT_RAW`>>), and then moves messages
+between them.
+When a protocol has a ((backtrace)) style header, routing information is
+added as the message crosses the forwarder, allowing replies to be
+returned to requestors, and responses to be routed back to surveyors.
+
+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 <<nng_options.5#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 determintal
+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 requestor, if reliable delivery is needed.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== 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
+
+<<nng_options.5#,nng_options(5)>>,
+<<nng_socket.5#,nng_socket(5)>>,
+<<nng.7#,nng(7)>>