Markup fixes, ensuring links are colored properly.

It turns out that when creating cross references, we need to
make any text styling (generally literal characters) outside of
the link, to avoid having the styling override the link color.
(We prefer to have links colored for ease of use.)

While here a few other markup, and actual content, errors were fixed.

docs/man/libnng.3.adoc

@@ -124,7 +124,7 @@ mode may need to access the header of messages.
 === Asynchronous Operations
 
 Most applications will interact with _nng_ synchronously; that is that
-functions such as <<nng_send.3#,`nng_send()`>> will block the calling
+functions such as `<<nng_send.3#,nng_send()>>` will block the calling
 thread until the operation has completed.
 
 NOTE: Synchronous operations which send messages may return before the
@@ -136,9 +136,9 @@ Asynchronous operations behave differently.  These operations are
 initiated by the calling thread, but control returns immediately to
 the calling thread.  When the operation is subsequently completed (regardless
 of whether this was successful or not), then a user supplied function
-("callback") is executed.
+("`callback`") is executed.
 
-A context structure, an <<nng_aio.5#,`nng_aio`>>, is allocated and
+A context structure, an `<<nng_aio.5#,nng_aio>>`, is allocated and
 associated with each asynchronous operation.
 Only a single asynchronous operation may be associated with an
 `nng_aio` at any time.

docs/man/nn_bind.3compat.adoc

@@ -28,7 +28,7 @@ The `nn_bind()` function arranges for the socket _sock_ to
 accept connections at the address specified by _url_.
 An "`endpoint identifier`" for this socket's association with the _url_ is
 returned to the caller on success.
-This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to
+This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>` to
 "`unbind`" the socket from the address at _url_.
 
 NOTE: This function is provided for API

docs/man/nn_connect.3compat.adoc

@@ -28,7 +28,7 @@ The `nn_connect()` function arranges for the socket _sock_ to
 inititate connection to a peer at the address specified by _url_.
 An "`endpoint identifier`" for this socket's association with the _url_ is
 returned to the caller on success.
-This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>`` to
+This ID can be used with `<<nn_shutdown.3compat#,nn_shutdown()>>` to
 "`unbind`" the socket from the address at _url_.
 
 NOTE: This function is provided for API

docs/man/nn_freemsg.3compat.adoc

@@ -25,7 +25,7 @@ int nn_freemsg(void *msg);
 == DESCRIPTION
 
 The `nn_freemsg()` deallocates a message previously allocated with
-`<<nn_allocmsg.3compat#,nn_allocmsg()>>`` or similar functions.
+`<<nn_allocmsg.3compat#,nn_allocmsg()>>` or similar functions.
 
 NOTE: This function is provided for API
 <<nng_compat.3compat#,compatibility>> with legacy _libnanomsg_.

docs/man/nn_poll.3compat.adoc

@@ -67,7 +67,7 @@ If the _timeout_ is -1, then the function waits forever, or until one of the
 requested events occurs.
 
 WARNING: This function is only suitable for use with sockets obtained with the
-`<<nn_socket.3compat#,nn_socket()>>`` function, and is not compatible
+`<<nn_socket.3compat#,nn_socket()>>` function, and is not compatible
 with file descriptors obtained via any other means.
 This includes file descriptors obtained using the `NN_SNDFD` or `NN_RCVFD`
 options with `<<nn_getsockopt.3compat#,nn_getsockopt()>>`

docs/man/nn_send.3compat.adoc

@@ -38,7 +38,7 @@ is a pointer to the pointer, an extra level of pointer indirection.
 The message must have been previously allocated by
 `<<nn_allocmsg.3compat#,nn_allocmsg()>>` or
 `<<nn_recvmsg.3compat#,nn_recvmsg()>>`, using the same `NN_MSG` size.
-In this case, the "`ownership``" of the message shall remain with
+In this case, the "`ownership`" of the message shall remain with
 the caller, unless the function returns 0, indicating that the
 function has taken responsibility for delivering or disposing of the
 message.

docs/man/nng.7.adoc

@@ -92,7 +92,7 @@ guarantees by performing their own retry and validation schemes.)
 Each socket can have zero, one, or many "endpoints", which are either
 _listeners_ or _dialers_.
 (A given socket may freely choose whether it uses listeners, dialers, or both.)
-These "endpoints" provide access to underlying transports, such as TCP, etc.
+These "`endpoints`" provide access to underlying transports, such as TCP, etc.
 
 Each endpoint is associated with a URL, which is a service address.
 For dialers, this will be the service address that will be contacted, whereas
@@ -130,13 +130,13 @@ to and from the socket with no extra semantic handling.
 This is possible using "`raw`" mode sockets.
 
 Raw mode sockets are generally constructed with a different function,
-such as <<nng_req_open.3#,`nng_req0_open_raw()`>>.
+such as `<<nng_req_open.3#,nng_req0_open_raw()>>`.
 Using these sockets, the application can simply send and receive messages,
 and is responsible for supplying any additional socket semantics.
 Typically this means that the application will need to inspect message
 headers on incoming messages, and supply them on outgoing messages.
 
-TIP: The <<nng_device.3#,`nng_device()`>> function only works with raw mode
+TIP: The `<<nng_device.3#,nng_device()>>` function only works with raw mode
 sockets, but as it only forwards the messages, no additional application
 processing is needed.
 

docs/man/nng_aio.5.adoc

@@ -37,15 +37,15 @@ This callback will be executed exactly once.
 
 The asynchronous I/O framework in _nng_ also supports cancellation of
 operations that are already in progress
-(see <<nng_aio_cancel.3#,`nng_aio_cancel()`>>), as well setting a maximum
+(see `<<nng_aio_cancel.3#,nng_aio_cancel()>>`), as well setting a maximum
 timeout for them to complete within
-(see <<nng_aio_set_timeout.3#,`nng_aio_set_timeout()`>>).
+(see `<<nng_aio_set_timeout.3#,nng_aio_set_timeout()>>`).
 
 It is also possible to initiate an asynchronous operation, and wait for it to
-complete using <<nng_aio_wait.3#,`nng_aio_wait()`>>.
+complete using `<<nng_aio_wait.3#,nng_aio_wait()>>`.
 
-These structures are created using the <<nng_aio_alloc.3#,`nng_aio_alloc()`>>,
-and destroyed using <<nng_aio_free.3#,`nng_aio_free()`>>.
+These structures are created using the `<<nng_aio_alloc.3#,nng_aio_alloc()>>`,
+and destroyed using `<<nng_aio_free.3#,nng_aio_free()>>`.
 
 == SEE ALSO
 

docs/man/nng_aio_abort.3.adoc

@@ -28,7 +28,7 @@ The `nng_aio_abort()` function aborts an operation previously started
 with the handle _aio_.
 If the operation is aborted, then the callback
 for the handle will be called, and the function
-<<nng_aio_result.3#,`nng_aio_result()`>> will return the error _err_.
+`<<nng_aio_result.3#,nng_aio_result()>>` will return the error _err_.
 
 This function does not wait for the operation to be fully aborted, but
 returns immediately.

docs/man/nng_aio_alloc.3.adoc

@@ -34,22 +34,22 @@ NOTE: The callback _callb_ must not perform any blocking operations, and
 must complete it's execution quickly.  If _callb_ does block, this can
 lead ultimately to an apparent "hang" or deadlock in the application.
 
-Asynchronous I/O operations all take an <<nng_aio.5#,`nng_aio`>>
+Asynchronous I/O operations all take an `<<nng_aio.5#,nng_aio>>`
 handle such as allocated by this function.
 Such operations are usually started by a function that returns immediately.
 The operation is then run asynchronously, and completes sometime later.
 When that operation is complete, the callback supplied here is called,
 and that callback is able to determine the result of the operation using
-<<nng_aio_result.3#,`nng_aio_result()`>>,
-<<nng_aio_count.3#,`nng_aio_count()`>>,
-and <<nng_aio_get_output.3#,`nng_aio_get_output()`>>.
+`<<nng_aio_result.3#,nng_aio_result()>>`,
+`<<nng_aio_count.3#,nng_aio_count()>>`,
+and `<<nng_aio_get_output.3#,nng_aio_get_output()>>`.
 
 It is possible to wait synchronously for an otherwise asynchronous operation
-by using the function <<nng_aio_wait.3#,`nng_aio_wait()`>>.
+by using the function `<<nng_aio_wait.3#,nng_aio_wait()>>`.
 In that case, it is permissible for _callb_ and _arg_ to both be `NULL`.
 Note that if these are `NULL`, then it will not be possible to determine when the
 operation is complete except by calling the aforementioned
-<<nng_aio_wait.3#,`nng_aio_wait()`>>.
+`<<nng_aio_wait.3#,nng_aio_wait()>>`.
 
 == RETURN VALUES
 

docs/man/nng_aio_cancel.3.adoc

@@ -16,19 +16,19 @@ nng_aio_cancel - cancel asynchronous I/O operation
 == SYNOPSIS
 
 [source, c]
------------
+----
 #include <nng/nng.h>
 
 void nng_aio_cancel(nng_aio *aio);
------------
+----
 
 == DESCRIPTION
 
 The `nng_aio_cancel()` function aborts an operation previously started
 with the handle _aio_.
 If the operation is aborted, then the callback
 for the handle will be called, and the function
-<<nng_aio_result.3#,`nng_aio_result()`>> will return the error `NNG_ECANCELED`.
+`<<nng_aio_result.3#,nng_aio_result()>>` will return the error `NNG_ECANCELED`.
 
 This function does not wait for the operation to be fully aborted, but
 returns immediately.
@@ -38,7 +38,7 @@ finished, or no operation has been started yet), then this function
 has no effect.
 
 NOTE: This function is the same as calling
-<<nng_aio_abort.3#,`nng_aio_abort()`>> with the error `NNG_ECANCELED`.
+`<<nng_aio_abort.3#,nng_aio_abort()>>` with the error `NNG_ECANCELED`.
 
 == RETURN VALUES
 

docs/man/nng_aio_count.3.adoc

@@ -33,13 +33,13 @@ transfer user data (they may transfer protocol data though) -- in this case
 this function will generally return zero.
 
 This function is most useful when used with operations that make use of
-of a scatter/gather vector (set by <<nng_aio_set_iov.3#,`nng_aio_set_iov()`>>).
+of a scatter/gather vector (set by `<<nng_aio_set_iov.3#,nng_aio_set_iov()>>`).
 
 NOTE: The return value from this function is undefined if the operation
 has not completed yet.
 Either call this from the handle's completion callback,
 or after waiting for the operation to complete with
-<<nng_aio_wait.3#,`nng_aio_wait()`>>.
+`<<nng_aio_wait.3#,nng_aio_wait()>>`.
 
 == RETURN VALUES
 

docs/man/nng_aio_finish.3.adoc

@@ -27,7 +27,7 @@ void nng_aio_finish(nng_aio *aio, int err);
 The `nng_aio_finish()` function marks operation associated with _aio_ as
 complete, with the status _err_.
 This will be the result returned by
-<<nng_aio_result.3#,`nng_aio_result()`>>.
+`<<nng_aio_result.3#,nng_aio_result()>>`.
 
 This function causes the callback associated with the _aio_ to called.
 

docs/man/nng_aio_free.3.adoc

@@ -28,7 +28,7 @@ The `nng_aio_free()` function frees an allocated asynchronous I/O handle.
 If any operation is in progress, the operation is canceled, and the
 caller is blocked until the operation is completely canceled, to ensure
 that it is safe to deallocate the handle and any associated resources.
-(This is done by implicitly calling <<nng_aio_stop.3#,`nng_aio_stop()`>>.)
+(This is done by implicitly calling `<<nng_aio_stop.3#,nng_aio_stop()>>`.)
 
 == RETURN VALUES
 

docs/man/nng_aio_get_input.3.adoc

@@ -26,7 +26,7 @@ void *nng_aio_get_input(nng_aio *aio, unsigned int index);
 
 The `nng_aio_get_input()` function returns the value of the input parameter
 previously set at _index_ on _aio_ with the
-<<nng_aio_set_input.3#,`nng_aio_set_input()`>> function.
+`<<nng_aio_set_input.3#,nng_aio_set_input()>>` function.
 
 The valid values of _index_ range from zero (0) to three (3), as no operation
 currently defined can accept more than four parameters.

docs/man/nng_aio_get_msg.3.adoc

@@ -26,10 +26,10 @@ nng_msg *nng_aio_get_msg(nng_aio *aio);
 
 The `nng_aio_get_msg()` function gets any message stored in _aio_ as
 either a result of a successful receive
-(see <<nng_recv_aio.3#,`nng_recv_aio()`>>)
-or that was previously stored with <<nng_aio_set_msg.3#,`nng_aio_set_msg()`>>.
+(see `<<nng_recv_aio.3#,nng_recv_aio()>>`)
+or that was previously stored with `<<nng_aio_set_msg.3#,nng_aio_set_msg()>>`.
 
-IMPORTANT: The `nng_aio` must not have an operation in progress.
+IMPORTANT: The `<<nng_aio.5#,nng_aio>>` must not have an operation in progress.
 
 == RETURN VALUES
 

docs/man/nng_aio_result.3.adoc

@@ -33,7 +33,7 @@ NOTE: The return value from this function is undefined if the operation
 has not completed yet.
 Either call this from the handle's completion
 callback, or after waiting for the operation to complete with
-<<nng_aio_wait.3#,`nng_aio_wait()`>>.
+`<<nng_aio_wait.3#,nng_aio_wait()>>`.
 
 == RETURN VALUES
 

docs/man/nng_aio_set_input.3.adoc

@@ -42,7 +42,7 @@ IMPORTANT: It is an error to call this function while the _aio_ is currently
 in use by an active asynchronous operation.
 
 An input parameter set with this function may be retrieved later with
-the <<nng_aio_get_input.3#,`nng_aio_get_input()`>> function.
+the `<<nng_aio_get_input.3#,nng_aio_get_input()>>` function.
 
 == RETURN VALUES
 

docs/man/nng_aio_set_iov.3.adoc

@@ -27,7 +27,7 @@ int nng_aio_set_iov(nng_aio *aio, unsigned int niov, nng_iov *iov);
 The `nng_aio_set_iov()` function sets a ((scatter/gather)) vector _iov_ on the
 handle _aio_. 
 
-The _iov_ is a pointer to an array of _niov_ <<nng_iov.5#,`nng_iov`>>
+The _iov_ is a pointer to an array of _niov_ `<<nng_iov.5#,nng_iov>>`
 structures, which have the following definition:
 
 [source, c]

docs/man/nng_aio_set_msg.3.adoc

@@ -25,9 +25,9 @@ void nng_aio_set_msg(nng_aio *aio, nng_msg *msg);
 == DESCRIPTION
 
 The `nng_aio_set_msg()` function sets the message that will be used
-for an asynchronous send operation (see <<nng_send_aio.3#,`nng_send_aio()`>>).
+for an asynchronous send operation (see `<<nng_send_aio.3#,nng_send_aio()>>`).
 
-IMPORTANT: The `nng_aio` must not have an operation in progress.
+IMPORTANT: The `<<nng_aio.5#,nng_aio>>` must not have an operation in progress.
 
 == RETURN VALUES
 

docs/man/nng_aio_set_output.3.adoc

@@ -39,7 +39,7 @@ NOTE:  Note that attempts to set results with an _index_ greater than
 three (3) will be ignored.
 
 An output result set with this function may be retrieved later with
-the <<nng_aio_get_output.3#,`nng_aio_get_output()`>> function.
+the `<<nng_aio_get_output.3#,nng_aio_get_output()>>` function.
 
 == RETURN VALUES
 

docs/man/nng_aio_stop.3.adoc

@@ -41,7 +41,7 @@ completing its callback function.
 
 TIP: When multiple asynchronous I/O handles are in use and need to be
 shut down, it is safest to stop all of them, before deallocating any of
-this with <<nng_aio_free.3#,`nng_aio_free()`>>, particularly if the callbacks
+this with `<<nng_aio_free.3#,nng_aio_free()>>`, particularly if the callbacks
 might attempt to reschedule additional operations.
 
 == RETURN VALUES

docs/man/nng_alloc.3.adoc

@@ -29,9 +29,9 @@ at least _size_ bytes.
 The memory will be 64-bit aligned. 
 
 The returned memory can be used to hold message buffers, in which
-case it can be directly passed to <<nng_send.3#,`nng_send()`>> using
+case it can be directly passed to `<<nng_send.3#,nng_send()>>` using
 the flag `NNG_FLAG_ALLOC`.  Alternatively, it can be freed when no
-longer needed using <<nng_free.3#,`nng_free()`>>.
+longer needed using `<<nng_free.3#,nng_free()>>`.
 
 IMPORTANT: Do not use the system `free()` function to release this memory.
 On some platforms this may work, but it is not guaranteed and may lead

docs/man/nng_bus.7.adoc

@@ -49,7 +49,7 @@ the more likely that message loss is to occur.
 
 === Socket Operations
 
-The <<nng_bus_open.3#,`nng_bus0_open()`>> functions create a bus socket.
+The `<<nng_bus_open.3#,nng_bus0_open()>>` functions create a bus socket.
 This socket may be used to send and receive messages.
 Sending messages will attempt to deliver to each directly connected peer.
 

docs/man/nng_close.3.adoc

@@ -27,7 +27,7 @@ int nng_close(nng_socket s);
 The `nng_close()` function closes the supplied socket, _s_.
 Messages that have been submitted for sending may be flushed or delivered,
 depending upon the transport and the setting of the
-<<nng_options.5#NNG_OPT_LINGER,`NNG_OPT_LINGER`>> option.
+`<<nng_options.5#NNG_OPT_LINGER,NNG_OPT_LINGER>>` option.
 
 Further attempts to use the socket after this call returns will result
 in `NNG_ECLOSED`.

docs/man/nng_compat.3compat.adoc

@@ -80,7 +80,7 @@ ifdef::backend-pdf[]
 // Add links for the following as they are written.
 [.hdlist,width=90%, grid=rows,cols="1,2", align="center"]
 |===
-|`<<nn_socket.3compat#,nn_socket()`>>|create socket
+|`<<nn_socket.3compat#,nn_socket()>>`|create socket
 |`<<nn_getsockopt.3compat#,nn_getsockopt()>>`|get socket option
 |`<<nn_setsockopt.3compat#,nn_setsockopt()>>`|set socket option
 |`<<nn_bind.3compat#,nn_bind()>>`|accept connections from remote peers

docs/man/nng_ctx.5.adoc

@@ -75,8 +75,8 @@ applications, and should be used in lieu of
 
 WARNING: 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
+`<<nng_options.5#NNG_OPT_RECVFD,NNG_OPT_RECVFD>>` or
+`<<nng_options.5#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.
@@ -134,8 +134,8 @@ 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
 created and any transports set up as well with functions such as
-<<nng_dial.3#,`nng_dial()`>>
-or <<nng_listen.3#,`nng_listen()`>>.
+`<<nng_dial.3#,nng_dial()>>`
+or `<<nng_listen.3#,nng_listen()>>`.
 
 [source,c]
 ----

docs/man/nng_ctx_close.3.adoc

@@ -27,15 +27,15 @@ int nng_ctx_close(nng_ctx ctx);
 The `nng_ctx_close()` function closes the context _ctx_.
 Messages that have been submitted for sending may be flushed or delivered,
 depending upon the transport and the setting of the
-<<nng_options.5#NNG_OPT_LINGER,`NNG_OPT_LINGER`>> option.
+`<<nng_options.5#NNG_OPT_LINGER,NNG_OPT_LINGER>>` option.
 
 Further attempts to use the context after this call returns will result
 in `NNG_ECLOSED`.
 Threads waiting for operations on the context when this
 call is executed may also return with an `NNG_ECLOSED` result.
 
 NOTE: Closing the socket associated with _ctx_
-(using <<nng_close.3#,`nng_close()`>>) also closes this context.
+(using `<<nng_close.3#,nng_close()>>`) also closes this context.
 
 == RETURN VALUES
 

docs/man/nng_ctx_getopt.3.adoc

@@ -93,9 +93,9 @@ typically for buffer sizes, message maximum sizes, and similar options.
 
 ==== `nng_ctx_getopt_string()`
 This function is used to retrieve a string into _strp_.
-This string is created from the source using <<nng_strdup.3#,`nng_strdup()`>>
+This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>`
 and consequently must be freed by the caller using
-<<nng_strfree.3#,`nng_strfree()`>> when it is no longer needed.
+`<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed.
 
 ==== `nng_ctx_getopt_uint64()`
 This function is used to retrieve a 64-bit unsigned value into the value

docs/man/nng_ctx_id.3.adoc

@@ -29,10 +29,10 @@ if it is valid.
 Otherwise it returns `-1`.
 
 NOTE: A context is considered valid if it was ever opened with
-<<nng_ctx_open.3#,`nng_ctx_open`>> function.
+`<<nng_ctx_open.3#,nng_ctx_open()>>` function.
 Contexts that are allocated on the stack or statically should be
 initialized with the macro
-<<nng_ctx.5#NNG_CTX_INITIALIZER,`NNG_CTX_INITIALIZER`>> to ensure that
+`<<nng_ctx.5#NNG_CTX_INITIALIZER,NNG_CTX_INITIALIZER>>` to ensure that
 they cannot be confused with a valid context before they are opened.
 
 == RETURN VALUES