fixes #938 document limitations between polling fds and contexts

While here, also updated the markup for those man pages to use the
current non-ambiguous cross reference syntax.

2 files changed, 69 insertions, 61 deletions

diff --git a/docs/man/nng_ctx.5.adoc b/docs/man/nng_ctx.5.adoc
index 0ca0b9de..f8a444c6 100644
--- a/docs/man/nng_ctx.5.adoc
+++ b/docs/man/nng_ctx.5.adoc
@@ -1,6 +1,6 @@
 = nng_ctx(5)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2019 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
@@ -28,12 +28,12 @@ An `nng_ctx`(((context))) is a handle to an underlying "`context`" object,
 which keeps the protocol state for some stateful protocols.
 The purpose of a separate context object is to permit applications to
 share a single socket, with its various underlying
-<<nng_dialer.5#,dialers>>,
-<<nng_listener.5#,listeners>>,
-and <<nng_pipe.5#,pipes>>,
+xref:nng_dialer.5.adoc[dialers],
+xref:nng_listener.5.adoc[listeners],
+and xref:nng_pipe.5.adoc[pipes],
 while still benefiting from separate state tracking.
 
-For example, a <<nng_req.7#,_req_>> context will contain the request ID
+For example, a xref:nng_req.7.adoc[_req_] context will contain the request ID
 of any sent request, a timer to retry the request on failure, and so forth.
 A separate context on the same socket can have similar data, but corresponding
 to a completely different request.
@@ -59,24 +59,24 @@ global behavior.
 
 (((concurrent)))(((raw mode)))
 Historically, applications wanting to use a stateful protocol concurrently
-would have to resort to <<nng.7#raw_mode,raw mode>> sockets, which bypasses
+would have to resort to xref:nng.7#raw_mode[raw mode] sockets, which bypasses
 much of the various protocol handling, leaving it to up to the application
 to do so.
 Contexts make it possible to still benefit from advanced protocol handling,
 including timeouts, retries, and matching requests to responses, while doing so
 concurrently.
 
-NOTE: <<nng.7#raw_mode,Raw mode>> sockets do not support contexts, since
+NOTE: xref:nng.7.adoc#raw_mode[Raw mode] sockets do not support contexts, since
 there is generally no state tracked for them, and thus contexts make no sense.
 
 TIP: Contexts are an excellent mechanism to use when building concurrent
 applications, and should be used in lieu of
-<<nng.7#raw_mode,raw mode>> sockets when possible.
+xref:nng.7.adoc#raw_mode[raw mode] sockets when possible.
 
 IMPORTANT: Use of file descriptor polling (with descriptors
 obtained using the
-`<<nng_options.5#NNG_OPT_RECVFD,NNG_OPT_RECVFD>>` or
-`<<nng_options.5#NNG_OPT_SENDFD,NNG_OPT_SENDFD>>` options) while contexts
+xref:nng_options.5.adoc#NNG_OPT_RECVFD[`NNG_OPT_RECVFD`] or
+xref:nng_options.5.adoc#NNG_OPT_SENDFD[`NNG_OPT_SENDFD`] options) while contexts
 are in use on the same socket is not supported, and may lead to unpredictable
 behavior.
 These asynchronous methods should not be mixed on the same socket.
@@ -90,7 +90,7 @@ before it is opened, to prevent confusion with valid open contexts.
 == EXAMPLE
 
 The following program fragment demonstrates the use of contexts to implement
-a concurrent <<nng_rep.7#,_rep_>> service that simply echos messages back
+a concurrent xref:nng_rep.7.adoc[_rep_] service that simply echos messages back
 to the sender.
 
 [source, c]
@@ -132,10 +132,10 @@ echo(void *arg)
 ----
 
 Given the above fragment, the following example shows setting up the
-service.  It assumes that the <<nng_socket.5#,socket>> has already been
+service.  It assumes that the xref:nng_socket.5.adoc[socket] has already been
 created and any transports set up as well with functions such as
-`<<nng_dial.3#,nng_dial()>>`
-or `<<nng_listen.3#,nng_listen()>>`.
+xref:nng_dial.3.adoc[`nng_dial()`]
+or xref:nng_listen.3.adoc[`nng_listen()`].
 
 [source,c]
 ----
@@ -159,16 +159,16 @@ start_echo_service(nng_socket rep_socket)
 == SEE ALSO
 
 [.text-left]
-<<libnng.3#,libnng(3)>>,
-<<nng_ctx_close.3#,nng_ctx_close(3)>>,
-<<nng_ctx_open.3#,nng_ctx_open(3)>>,
-<<nng_ctx_getopt.3#,nng_ctx_getopt(3)>>,
-<<nng_ctx_id.3#,nng_ctx_id(3)>>,
-<<nng_ctx_recv.3#,nng_ctx_recv(3)>>,
-<<nng_ctx_send.3#,nng_ctx_send(3)>>,
-<<nng_ctx_setopt.3#,nng_ctx_setopt(3)>>,
-<<nng_dialer.5#,nng_dialer(5)>>,
-<<nng_listener.5#,nng_listener(5)>>,
-<<nng_socket.5#,nng_socket(5)>>,
-<<nng_options.5#,nng_options(5)>>,
-<<nng.7#,nng(7)>>
+xref:libnng.3.adoc[libnng(3)],
+xref:nng_ctx_close.3.adoc[nng_ctx_close(3)],
+xref:nng_ctx_open.3.adoc[nng_ctx_open(3)],
+xref:nng_ctx_getopt.3.adoc[nng_ctx_getopt(3)],
+xref:nng_ctx_id.3.adoc[nng_ctx_id(3)],
+xref:nng_ctx_recv.3.adoc[nng_ctx_recv(3)],
+xref:nng_ctx_send.3.adoc[nng_ctx_send(3)],
+xref:nng_ctx_setopt.3.adoc[nng_ctx_setopt(3)],
+xref:nng_dialer.5.adoc[nng_dialer(5)],
+xref:nng_listener.5.adoc[nng_listener(5)],
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng_options.5.adoc[nng_options(5)],
+xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc
index dd5f50eb..1bf0b232 100644
--- a/docs/man/nng_options.5.adoc
+++ b/docs/man/nng_options.5.adoc
@@ -46,22 +46,22 @@ nng_options - socket, dialer, listener, and pipe options
 This page documents the various standard options that can be set or
 retrieved on objects in the _nng_ library.
 
-Sockets (<<nng_socket.5#,`nng_socket`>> objects) use the functions
-<<nng_getopt.3#,`nng_getopt()`>>
-and <<nng_setopt.3#,`nng_setopt()`>> to set and retrieve option values.
+Sockets (xref:nng_socket.5.adoc[`nng_socket`] objects) use the functions
+xref:nng_getopt.3.adoc[`nng_getopt()`]
+and xref:nng_setopt.3.adoc[`nng_setopt()`] to set and retrieve option values.
 
-Dialers (<<nng_dialer.5#,`nng_dialer`>> objects) use the functions
-<<nng_dialer_getopt.3#,`nng_dialer_getopt()`>> and
-<<nng_dialer_setopt.3#,`nng_dialer_setopt()`>> to set and retrieve option
+Dialers (xref:nng_dialer.5.adoc[`nng_dialer`] objects) use the functions
+xref:nng_dialer_getopt.3.adoc[`nng_dialer_getopt()`] and
+xref:nng_dialer_setopt.3.adoc[`nng_dialer_setopt()`] to set and retrieve option
 values.
 
-Listeners (<<nng_listener.5#,`nng_listener`>> objects) use the functions
-<<nng_listener_getopt.3#,`nng_listener_getopt()`>>
-and <<nng_listener_setopt.3#,`nng_listener_setopt()`>> to set and
+Listeners (xref:nng_listener.5.adoc[`nng_listener`] objects) use the functions
+xref:nng_listener_getopt.3.adoc[`nng_listener_getopt()`]
+and xref:nng_listener_setopt.3.adoc[`nng_listener_setopt()`] to set and
 retrieve option values.
 
-Pipes (<<nng_pipe.5#,`nng_pipe`>> objects) can only retrieve option values using
-the <<nng_pipe_getopt.3#,`nng_pipe_getopt()`>> function.
+Pipes (xref:nng_pipe.5.adoc[`nng_pipe`] objects) can only retrieve option values using
+the xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function.
 
 Other object types may have additional methods to access these options.
 
@@ -82,7 +82,7 @@ description of the option.
 
 [[NNG_OPT_LOCADDR]]
 ((`NNG_OPT_LOCADDR`))::
-(<<nng_sockaddr.5#,`nng_sockaddr`>>)
+(xref:nng_sockaddr.5.adoc[`nng_sockaddr`])
 This read-only option may be used on listeners, dialers and connected pipes, and
 represents the local address used for communication.
 NOTE: Not all transports support this option, and some transports may support it on
@@ -104,15 +104,15 @@ in "`cooked`" mode.
 +
 Raw mode sockets generally do not have any protocol-specific semantics applied
 to them; instead the application is expected to perform such semantics itself.
-(For example, in "`cooked`" mode a <<nng_rep.7#,_rep_>> socket would
+(For example, in "`cooked`" mode a xref:nng_rep.7.adoc[_rep_] socket would
 automatically copy message headers from a received message to the corresponding
 reply, whereas in "`raw`" mode this is not done.)
-See <<nng.7#raw_mode,Raw Mode>> for more details.
+See xref:nng.7#raw_mode[Raw Mode] for more details.
 
 [[NNG_OPT_RECONNMINT]]
 ((`NNG_OPT_RECONNMINT`))::
 (((reconnect time, minimum)))
-(<<nng_duration.5#,`nng_duration`>>)
+(xref:nng_duration.5.adoc[`nng_duration`])
 This is the minimum amount of time (milliseconds) to wait before attempting
 to establish a connection after a previous attempt has failed.
 This can be set on a socket, but it can also be overridden on an individual
@@ -123,7 +123,7 @@ The option is irrelevant for listeners.
 ((`NNG_OPT_RECONNMAXT`))::
 (((`NNG_OPT_RECONNMAXT`)))
 (((reconnect time, maximum)))
-(<<nng_duration.5#,`nng_duration`>>)
+(xref:nng_duration.5.adoc[`nng_duration`])
 This is the maximum amount of time
 (milliseconds) to wait before attempting to establish a connection after
 a previous attempt has failed.
@@ -167,10 +167,14 @@ be readable.
 IMPORTANT: Applications should never attempt to read or write to the
 returned file descriptor.
 +
+IMPORTANT: This option is incompatible with
+xref:nng_ctx.5.adoc[`nng_ctx`] contexts and should be used on a socket
+where they are in use.
++
 TIP: While this option may help applications integrate into existing polling
 loops, it is more efficient, and often easier, to use the asynchronous I/O
 objects instead.
-See <<nng_aio_alloc.3#,`nng_aio_alloc()`>>.
+See xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`].
 
 [[NNG_OPT_RECVMAXSZ]]
 ((`NNG_OPT_RECVMAXSZ`))::
@@ -192,14 +196,14 @@ NOTE: Some transports may have further message size restrictions.
 ((`NNG_OPT_RECVTIMEO`))::
 (((receive, timeout)))
 (((timeout, receive)))
-(<<nng_duration.5#,`nng_duration`>>)
+(xref:nng_duration.5.adoc[`nng_duration`])
 This is the socket receive timeout in milliseconds.
 When no message is available for receiving at the socket for this period of
 time, receive operations will fail with a return value of `NNG_ETIMEDOUT`.
 
 [[NNG_OPT_REMADDR]]
 ((`NNG_OPT_REMADDR`))::
-(<<nng_sockaddr.5#,`nng_sockaddr`>>)
+(xref:nng_sockaddr.5.adoc[`nng_sockaddr`])
 This read-only option may be used on dialers and connected pipes, and
 represents the address of a remote peer.
 Not all transports support this option.
@@ -215,7 +219,7 @@ transport is ready to accept them for delivery.
 This value must be an integer between 0 and 8192, inclusive.
 +
 NOTE: Not all protocols support buffering sent messages;
-generally multicast protocols like <<nng_pub.7#,_pub_>> will
+generally multicast protocols like xref:nng_pub.7.adoc[_pub_] will
 simply discard messages when they cannot be delivered immediately.
 
 [[NNG_OPT_SENDFD]]
@@ -240,16 +244,20 @@ the descriptor will *not* be readable.
 IMPORTANT: Applications should never attempt to read or write to the
 returned file descriptor; use should be limited to polling system calls only.
 +
+IMPORTANT: This option is incompatible with
+xref:nng_ctx.5.adoc[`nng_ctx`] contexts and should be used on a socket
+where they are in use.
++
 TIP: While this option may help applications integrate into existing polling
 loops, it is more efficient, and often easier, to use the asynchronous I/O
 objects instead.
-See <<nng_aio_alloc.3#,`nng_aio_alloc()`>>.
+See xref:nng_aio_alloc.3.adoc[`nng_aio_alloc()`].
 
 [[NNG_OPT_SENDTIMEO]]
 ((`NNG_OPT_SENDTIMEO`))::
 (((send, timeout)))
 (((timeout, send)))
-(<<nng_duration.5#,`nng_duration`>>)
+(xref:nng_duration.5.adoc[`nng_duration`])
 This is the socket send timeout in milliseconds.
 When a message cannot be queued for delivery by the socket for this period of
 time (such as if send buffers are full), the operation will fail with a
@@ -271,7 +279,7 @@ in the library itself.
 (`int`)
 (((time-to-live)))
 This is the maximum number of "`hops`" a message may traverse across
-a <<nng_device.3#,`nng_device()`>> forwarders.
+a xref:nng_device.3.adoc[`nng_device()`] forwarders.
 The intention here is to prevent ((forwarding loops)) in device chains.
 When this is supported, it can have a value between 1 and 255, inclusive.
 +
@@ -320,14 +328,14 @@ the socket.
 == SEE ALSO
 
 [.text-left]
-<<nng_dialer_getopt.3#,nng_dialer_getopt(3)>>,
-<<nng_dialer_setopt.3#,nng_dialer_setopt(3)>>,
-<<nng_getopt.3#,nng_getopt(3)>>,
-<<nng_listener_getopt.3#,nng_listener_getopt(3)>>,
-<<nng_listener_setopt.3#,nng_listener_setopt(3)>>,
-<<nng_pipe_getopt.3#,nng_pipe_getopt(3)>>,
-<<nng_setopt.3#,nng_setopt(3)>>,
-<<nng_ipc_options.5#,nng_ipc_options(5)>>,
-<<nng_tcp_options.5#,nng_tcp_options(5)>>,
-<<nng_tls_options.5#,nng_tls_options(5)>>,
-<<nng.7#,nng(7)>>
+xref:nng_dialer_getopt.3.adoc[nng_dialer_getopt(3)],
+xref:nng_dialer_setopt.3.adoc[nng_dialer_setopt(3)],
+xref:nng_getopt.3.adoc[nng_getopt(3)],
+xref:nng_listener_getopt.3.adoc[nng_listener_getopt(3)],
+xref:nng_listener_setopt.3.adoc[nng_listener_setopt(3)],
+xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)],
+xref:nng_setopt.3.adoc[nng_setopt(3)],
+xref:nng_ipc_options.5.adoc[nng_ipc_options(5)],
+xref:nng_tcp_options.5.adoc[nng_tcp_options(5)],
+xref:nng_tls_options.5.adoc[nng_tls_options(5)],
+xref:nng.7.adoc[nng(7)]