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

diff --git a/docs/man/nngcat.1.adoc b/docs/man/nngcat.1.adoc
new file mode 100644
index 00000000..4bbaf002
--- /dev/null
+++ b/docs/man/nngcat.1.adoc
@@ -0,0 +1,306 @@
+= nngcat(1)
+//
+// 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
+
+nngcat - command line access to Scalabity Protocols
+
+== SYNOPSIS
+
+*nngcat* --help
+
+*nngcat* --version
+
+*nngcat* [_OPTION_]... 
+
+== DESCRIPTION
+
+The ((_nngcat_)) utility provides command line access to the Scalability
+Protocols, making it possible to write shell scripts that interact
+with other peers in a Scalability Protocols topology, by both sending and
+receiving messages.
+
+== OPTIONS
+
+The possible values for _OPTION_ are described below.
+
+TIP: The _nngcat_ utility accepts shortened versions of these options, as long
+as the supplied option is unambiguous.
+For example `--comp` can be used in lieu
+of `--compat`, but `--re` may not be used for anything because it could mean
+any of `--req`, `--rep`, or `--respondent`.
+
+When using the long form of an option (names prefixed with with `--`), if the
+option takes a value then the value may be supplied by appending the option
+with an equals sign and the value (e.g. `--subscribe=times`), by appending
+the option with a colon and the value (e.g. `--subscribe:tribune`) or by
+providing the data as the next program argument (e.g. `--subscribe herald`).
+
+When using short form options (a single letter prefixed with a `-`),
+if the option takes a value it may either be immediately appended to
+the value (e.g. `-L5678`) or provided as the next program argument
+(e.g. `-L 5678`).
+
+POSIX style option clustering of single letter options is not supported;
+each option must be presented as a separate argument to the program.
+
+=== Generic Options
+*-h, --help*::
+  Get usage help.
+*-V, --version*::
+  Print the version and exit.
+*-v, --verbose*::
+  Select verbose operation.
+*-q, --silent*::
+  Select silent operation.
+*--compat*::
+  Compatible mode. (((compatible mode)))
+  This cause _nngcat_ to behave more like the legacy
+  _nanocat_ application.
+  In this mode connections are made asynchronously,
+  and the *--pair* option selects version 0 of
+  the <<nng_pair.7#,_pair_>> protocol instead of version 1.
+*--subscribe*=_TOPIC_::
+  Subscribe to _TOPIC_.  This option can only be used with the
+  <<nng_sub.7#,_sub_>> protocol.
+  The _TOPIC_ is checked against the first bytes
+  of messages received, and messages are discarded if they do not match.
+  This may be specified multiple times to subscribe to multiple topics.
+  If not specified at all, then a default subscription to everything is assumed.
+
+=== Protocol Selection Options
+NOTE: At least one protocol must be selected.
+
+*--bus, --bus0*::
+  Select the <<nng_bus.7#,_bus_>> version 0 protocol.
+  This protocol can send and receive messages to and from other _bus_ version 0
+  peers.
+
+*--req, --req0*::
+  Select the <<nng_req.7#,_req_>> version 0 protocol.
+  This protocol sends messages to <<nng_rep.7#,_rep_>> version 0
+  peers and receives replies from them.
+
+*--rep, --rep0*::
+  Select the <<nng_rep.7#,_rep_>> version 0 protocol.
+  This protocol receives messages from <<nng_req.7#,_req_>> version 0 peers
+  and can send replies to them.
+
+*--pub, --pub0*::
+  Select the <<nng_pub.7#,_pub_>> version 0 protocol.
+  This protocol sends messages to <<nng_sub.7#,_sub_>> version peers.
+
+*--sub, --sub0*::
+  Select the <<nng_sub.7#,_sub_>> version 0 protocol.
+  This protocol receives messages from <<nng_pub.7#,_pub_>> version
+  0 peers, and filters them based on subscriptions set with *--subscribe*.
+  
+*--push, --push0*::
+  Select the <<nng_push.7#,_push_>> version 0 protocol.
+  This protocol sends messages to <<nng_pull.7#,_pull_>> version 0 peers.
+  A given message is normally only delivered to a single peer.
+
+*--pull, --pull0*::
+  Select the <<nng_pull.7#,_pull_>> version 0 protocol.
+  This protocol receives
+  messages from <<nng_push.7#,_push_>> version 0 peers.
+
+*--pair0*::
+  Select the <<nng_pair.7#,_pair_>> veresion 0 protocol.
+  This protocol can send and receive messages with one connected _pair_
+  version 0 peer.
+
+*--pair1*::
+  Select the <<nng_pair.7#,_pair_>> version 1 protocol.
+  This protocol can send and receive messages with one connected _pair_
+  version 1 peer.
+  It is not supported in *--compat* mode.
+  (Polyamorous mode is not supported 
+  in _nngcat_, although peers may be using polyamorous mode.)
+
+*--pair*::
+  Acts as an alias for *--pair1*, unless *--compat* mode is selected, in
+  which case it acts as an alias for *--pair0*.
+
+*--surveyor, --surveyor0*::
+  Select the <<nng_surveyor.7#,_surveyor_>> version 0 protocol.
+  This protocol sends a survey request to <<nng_respondent.7#,_respondent_>>
+  version 0 peers, and then receives replies from them.
+
+*--respondent, --respondent0*::
+  Select the <<nng_respondent.7#,_respondent_>> version 0 protocol.
+  This protocol receives survey requests from <nng_surveyor.7#,_surveyor_>>
+  version 0 peers, and can send a reply to them.
+
+=== Peer Selection Options
+NOTE: At least one peer address must be selected.
+
+TIP: While legacy _nanocat_ only supported one peer, _nng_ can support
+more than one peer on a given connection.
+
+*--connect, --dial*=_URL_::
+  Connect to the peer at the address specified by _URL_.
+
+*--bind, --listen*=_URL_::
+  Bind to, and accept connections from peers, at the address specified by _URL_.
+
+*-x, --connect-ipc*=_PATH_::
+  Connect to the IPC path specified by _PATH_.  This is the same as 
+  *--connect*=ipc://_PATH_.
+
+*-X, --bind-ipc*=_PATH_::
+  Bind to the IPC path specified by _PATH_.  This is the same as 
+  *--bind*=ipc://_PATH_.
+
+*-l, --connect-local*=_PORT_::
+  Connect to `localhost` at the TCP port specified by _PORT_.  This is the same
+  as *--connect*=tcp://127.0.0.1:__PORT__.
+
+*-L, --bind-local*=_PORT_::
+  Bind to the TCP port specified by _PORT_.  This is the same as 
+  *--bind*=tcp://127.0.0.1:__PORT__.
+
+=== Receive Options
+
+Data messages received can be formatted in different ways.  These
+options can only be specified when using a protocol that receives messages.
+
+*--format*=_FORMAT_::
+  Format data as indicated.  The _FORMAT_ can be any of: +
+  `no`:::
+    No output at all.
+  `raw`:::
+    Raw output, every byte received is sent to standard output.
+  `ascii`:::
+    ((ASCII)) safe, printable ASCII is emitted verbatim, with other bytes
+    substituted with `.` (period).
+  `quoted`:::
+    Messages are printed as ((quoted)) strings, using C language conventions.
+  `hex`:::
+    (((hex))) Messages are printed as quoted strings, with every byte appearing
+    as an escaped hexadecimal value, such as `\x2E`.
+  `msgpack`:::
+    (((msgpack)))
+    (((MessagePack)))
+    Messages are emitted as https://msgpack.org[MessagePack] "bin format"
+    (byte arrays).
+
+*-A, --ascii*::
+  The same as specifying *--format*=`ascii`.
+
+*-Q, --quoted*::
+  The same as specifying *--format*=`quoted`.
+
+*--hex*::
+  The same as specifying *--format*=`hex`.
+
+*--msgpack*::
+  The same as specifying *--format*=`msgpack`.
+
+*--raw*::
+  The same as specifying *--format*=`raw`.
+
+*--receive-timeout*=_SEC_::
+  Give up receiving messages after _SEC_ seconds pass without any received
+  messages.
+
+=== Transmit Options
+
+Protocols that support sending data can use these options to select the data. 
+
+*-D, --data*=_DATA_::
+  Use _DATA_ for the body of outgoing messages.
+
+*-F, --file*=_FILE_::
+  Use _FILE_ for the body of outgoing messages.
+
+*-i, --interval*=_SEC_::
+  For protocols that send unsolicited data (as opposed to those that
+  send data only in response to received messages), this will resend the
+  outgoing message at repeating intervals of _SEC_ seconds.
+
+*-d, --delay*=_SEC_::
+  Wait _SEC_ seconds before sending the first outgoing message.
+  This is useful to let connections establish before sending data, thereby
+  avoiding message loss.
+
+*--send-timeout*=_SEC_::
+  Give up trying to send a message after _SEC_ seconds.
+
+=== TLS Options
+
+These options are only present if TLS is configured; they are ignored
+when using addresses that are not secured with TLS.
+
+*-k, --insecure*::
+  Skip peer validation.
+
+*-E, --cert*=_FILE_::
+  Load own certificate from _FILE_.
+
+*--key*=_FILE_::
+  Load own key from _FILE_.
+  Should be used in conjuction with *--cert*.
+  If not specified, and *--cert* is specified, then a single file containing both 
+  the private key and the associated certificate is assumed.
+
+*--cacert*=_FILE_::
+  Load CA certificates from _FILE_.
+  These CAs ("Certificate Authorities") are
+  used as trust roots when validating certificates presented by peers.
+
+=== ZeroTier Options
+
+These options are only present if ZeroTier is configured; they are ignored
+otherwise.
+
+*--zt-home*=_DIRECTORY_::
+  Directory for persistent ZeroTier node (key material, etc.)
+  This directory must already exist.
+  Only one program may use a ZeroTier node at a time;
+  file locking is used to prevent this.
+
+== EXAMPLES
+
+.Echo service using request/reply.
+[source,sh]
+----
+$ addr="tcp://127.0.0.1:4567"
+$ nngcat --rep --listen=${addr} --data="42" --quoted &
+$ nngcat --req --dial=${addr} --data="what is the answer?" --quoted
+"what is the answer?"
+"42"
+----
+
+.Send a chime every hour (3600 seconds).
+[source,sh]
+----
+$ addr=ipc:///grandpa_clock
+$ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
+$ nngcat --sub --dial=${addr} --quoted &
+"cuckoo"
+----
+
+== SEE ALSO
+
+<<libnng.3#,libnng(3)>>,
+<<nng.7#,nng(7)>>,
+<<nng_bus.7#,nng_bus(7)>>,
+<<nng_pair.7#,nng_pair(7)>>,
+<<nng_pub.7#,nng_pub(7)>>,
+<<nng_pull.7#,nng_pull(7)>>,
+<<nng_push.7#,nng_push(7)>>,
+<<nng_sub.7#,nng_sub(7)>>,
+<<nng_rep.7#,nng_rep(7)>>,
+<<nng_req.7#,nng_req(7)>>,
+<<nng_respondent.7#,nng_respondent(7)>>,
+<<nng_surveyor.7#,nng_surveyor(7)>>
+