Introduce nng_options, nng_setopt, nng_getopt manual pages.

This starts a new section 5 for generic topics, and sets up some links
for things like nng_duration and nng_socket types.  There will some day
be an nng_errors(5) page as well.

Some initial work towards indexing terms for these pages is done now too.
(Indexing will mostly be useful when generating book forms of this
documentation.)

1 files changed, 29 insertions, 33 deletions

diff --git a/docs/man/nng_zerotier.adoc b/docs/man/nng_zerotier.adoc
index 06f89566..b77b8b8c 100644
--- a/docs/man/nng_zerotier.adoc
+++ b/docs/man/nng_zerotier.adoc
@@ -24,6 +24,7 @@ int nng_zt_register(void);
 
 == DESCRIPTION
 
+(((ZeroTier)))
 The _nng_zerotier_ transport provides communication support for
 _nng_ applications over a http://www.zerotier.com[ZeroTier] network,
 using a Virtual Layer 2 packet facility.
@@ -31,7 +32,7 @@ using a Virtual Layer 2 packet facility.
 IMPORTANT: This transport is very experimental.  To utilize it at
 present, the library must be built with support, and the
 ZeroTierOne `dev` branch must be included; this will require
-linking against a suitable `libzerotiercore` static library.
+linking against a suitable ((`libzerotiercore`)) static library.
 
 IMPORTANT: The `libzerotiercore` library at present is covered under different
 license terms than the rest of _nng_.  Please be careful to review
@@ -63,6 +64,7 @@ cannot be initialized for any reason.
 
 === URI Format
 
+(((URI, `zt://`)))
 This transport uses URIs using the scheme `zt://`, followed by a node
 number (ten hexadecimal digits) followed by a `.` delimited, and then
 a network address (sixteen hexadecimal digits), followed by a colon (`.`)
@@ -79,6 +81,9 @@ selected port number using the `nng_listener_getopt` function.
 
 === Socket Address
 
+(((address, socket, zerotier)))
+(((`NNG_AF_ZT`)))
+(((`nng_sockaddr_zt`)))
 When using an `nng_sockaddr` structure, the actual structure is of type
 `struct nng_sockaddr_zt`.  This type has the following definition:
 
@@ -116,31 +121,31 @@ It is possible for a single application to join multiple networks
 using the same node, or using separate nodes.
 
 === Network Status
-
+(((status, zerotier network)))
 A ZeroTier node can be in one of the following states, which
 can be obtained with the `NNG_OPT_ZT_NETWORK_STATUS` option:
 
-`NNG_ZT_STATUS_UP`::
+((`NNG_ZT_STATUS_UP`))::
 The ZeroTier network is up.  This is the only state where it is
 possible to communicate with peers, and the only state where
 the network name (`NNG_OPT_ZT_NETWORK_NAME`) is available.
 
-`NNG_ZT_STATUS_CONFIG`::
+((`NNG_ZT_STATUS_CONFIG`))::
 The ZeroTier node is still configuring, network services are not available.
 
-`NNG_ZT_STATUS_DENIED`::
+((`NNG_ZT_STATUS_DENIED`))::
 The node does not have permission to join the ZeroTier network.
 
-`NNG_ZT_STATUS_NOTFOUND`::
+((`NNG_ZT_STATUS_NOTFOUND`))::
 The ZeroTier network is not found.
 
-`NNG_ZT_STATUS_ERROR`::
+((`NNG_ZT_STATUS_ERROR`))::
 Some other ZeroTier error has occurred; the network is not available.
 
-`NNG_ZT_STATUS_OBSOLETE`::
+((`NNG_ZT_STATUS_OBSOLETE`))::
 The node is running obsolete software; the network is not available.
 
-`NNG_ZT_STATUS_UNKNOWN`::
+((`NNG_ZT_STATUS_UNKNOWN`))::
 The network is in an unknown state. This should not happen, as it
 indicates that the ZeroTier software is reporting an unexpected status.
 The network is most likely not available.
@@ -149,8 +154,7 @@ The network is most likely not available.
 
 The following transport options are available:
 
-`NNG_OPT_ZT_HOME`::
-
+((`NNG_OPT_ZT_HOME`))::
   This is a string representing the "home directory", where the transport
   can store (and reuse) persistent state, such as key materials, node
   identity, and federation membership.  This option must be set before the
@@ -163,76 +167,68 @@ dialers, or listeners, then separate nodes will be created.  It
 is perfectly valid for an application to have multiple node identities
 in this fashion.
 
-`NNG_OPT_ZT_NWID`::
-
+((`NNG_OPT_ZT_NWID`))::
   This is a read-only option for listeners, dialers, and pipes, and
   provides a `uint64_t` in native byte order representing the 64-bit ZeroTier
   network number.
 
-`NNG_OPT_ZT_NODE`::
-
+((`NNG_OPT_ZT_NODE`))::
   This is a read-only option for listeners, dialers, and pipes, and
   provides a `uint64_t` in native byte order representing the ZeroTier
   40-bit node address.
 
-`NNG_OPT_ZT_NETWORK_STATUS`::
-
+((`NNG_OPT_ZT_NETWORK_STATUS`))::
+  (((status, zerotier network)))
   This is a read-only integer, representing the ZeroTier network status.
   See <<Network Status>> for an explanation of this option.
 
-`NNG_OPT_ZT_NETWORK_NAME`::
-
+((`NNG_OPT_ZT_NETWORK_NAME`))::
+  (((name, zerotier network)))
   This is a read-only ASCIIZ string containing the name of the network
   as established by the ZeroTier network administrator.
 
-`NNG_OPT_ZT_CONN_TIME`::
-
+((`NNG_OPT_ZT_CONN_TIME`))::
   The time to wait between sending connection attempts.  This is an
   `nng_duration` (msec), and is only used with dialers. The default is 500 msec.
 
-`NNG_OPT_ZT_CONN_TRIES`::
-
+((`NNG_OPT_ZT_CONN_TRIES`))::
   The maximum number (`int`) of attempts to try to establish a connection
   before reporting a timeout, and is only used with dialers.  The default
   is 240, which results in a 2 minute timeout if `NNG_OPT_ZT_CONN_TIME` is at
   it's default of 500.  If the value is set to 0, then the connection
   attempts will keep retrying forever.
 
-`NNG_OPT_ZT_PING_TIME`::
-
+((`NNG_OPT_ZT_PING_TIME`))::
   If no traffic has been received from the ZeroTier peer after this
   period of time, then a "ping" message is sent to check if the peer
   is still alive.  This is an `nng_duration` (msec).
 
-`NNG_OPT_ZT_PING_TRIES`::
-
+((`NNG_OPT_ZT_PING_TRIES`))::
   If this number (`int`) of consecutive "ping" requests are sent to the
   peer with no response (and no other intervening traffic), then the
   peer is assumed to be dead and the connection is closed.  Note that
   if any traffic is received from the peer, then the underlying counter
   is reset to zero.
 
-`NNG_OPT_ZT_MTU`::
-
+((`NNG_OPT_ZT_MTU`))::
   This is a read-only size (`size_t`) representing the ZeroTier virtual
   network MTU; this is the Virtual Layer 2 MTU.  The headers used by
   this transport and the protocols consume some of this for each message
   sent over the network.  (The transport uses 20-bytes of this, and each
   protocol may consume additional space, typically not more than 16-bytes.)
 
-`NNG_OPT_ZT_ORBIT`::
-
+((`NNG_OPT_ZT_ORBIT`))::
   This is a write-only option that takes an array of two `uint64_t` values,
   indicating the ID of a ZeroTier "moon", and the node ID of the root server
   for that moon.  (The ID may be zero if the moon ID is the same as it's
   root server ID, which is conventional.)
 
-`NNG_OPT_ZT_DEORBIT`::
-
+((`NNG_OPT_ZT_DEORBIT`))::
   This write-only option takes a single `uint64_t` indicating the moon
   ID to "deorbit".  If the node is not already orbiting the moon, then
   this has no effect.
     
 == SEE ALSO
 
+[.text-left]
 <<nng#,nng(7)>>