Language cleanups in the documentation.

Mostly this is removal of the smart quotes, which were
over-used, and misused, and could have been mistaken to
be pejorative.  A few other minor nits were fixed while here.

docs/man/libnng.3.adoc

@@ -149,7 +149,7 @@ 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.
+is executed.
 
 A context structure, an xref:nng_aio.5.adoc[`nng_aio`], is allocated and
 associated with each asynchronous operation.

docs/man/man7.desc

@@ -2,7 +2,7 @@ This sections documents various protocols and transports that are
 available in the distribution.
 
 (((protocol)))
-Protocols represent "`patterns`" of communication, such as
+Protocols implement communication patterns, such as
 request/reply, publish/subscribe, and so forth.
 A given xref:nng_socket.5.adoc[socket] is created with exactly one protocol, and that
 protocol defines the key behavior of the socket.

docs/man/nn_bind.3compat.adoc

@@ -1,6 +1,6 @@
 = nn_bind(3compat)
 //
-// Copyright 2018 Staysail Systems, Inc. <[email protected]>
+// Copyright 2020 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -26,10 +26,11 @@ int nn_bind(int sock, const char *url)
 
 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
+An identifier for this socket's association with the _url_ is
 returned to the caller on success.
-This ID can be used with xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to
-"`unbind`" the socket from the address at _url_.
+This identfier can be used with
+xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to
+remove the association later.
 
 NOTE: This function is provided for API
 xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_.

docs/man/nn_connect.3compat.adoc

@@ -26,10 +26,11 @@ int nn_connect(int sock, const char *url)
 
 The `nn_connect()` function arranges for the socket _sock_ to
 initiate connection to a peer at the address specified by _url_.
-An "`endpoint identifier`" for this socket's association with the _url_ is
+An identifier for this socket's association with the _url_ is
 returned to the caller on success.
-This ID can be used with xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to
-"`unbind`" the socket from the address at _url_.
+This identifier can be used with
+xref:nn_shutdown.3compat.adoc[`nn_shutdown()`] to
+remove the association later.
 
 NOTE: This function is provided for API
 xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_.

docs/man/nn_getsockopt.3compat.adoc

@@ -129,7 +129,7 @@ It can be changed to help with identifying different sockets with
 their different application-specific purposes.
 
 `NN_MAXTTL`::
-Maximum "`hops`" through proxies and devices a message may go through.
+Maximum number of times a message may traverse devices or proxies.
 This value, if positive, provides some protection against forwarding loops in
 xref:nng_device.3.adoc[device] chains.
 

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
 xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`] or
 xref:nn_recvmsg.3compat.adoc[`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/nn_setsockopt.3compat.adoc

@@ -123,7 +123,7 @@ It can be changed to help with identifying different sockets with
 their different application-specific purposes.
 
 `NN_MAXTTL`::
-Maximum "`hops`" through proxies and devices a message may go through.
+Maximum number of times a message may traverse devices or proxies.
 This value, if positive, provides some protection against forwarding loops in
 xref:nng_device.3.adoc[device] chains.
 

docs/man/nn_shutdown.3compat.adoc

@@ -1,6 +1,6 @@
 = nn_shutdown(3compat)
 //
-// Copyright 2018 Staysail Systems, Inc. <[email protected]>
+// Copyright 2020 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -24,11 +24,11 @@ int nn_shutdown(int sock, int ep)
 
 == DESCRIPTION
 
-The `nn_shutdown()` shuts down the "`endpoint`"  _ep_ on the socket _sock_.
+The `nn_shutdown()` shuts down the endpoint _ep_, which is either a listener or
+a dialer) on the socket _sock_.
 This will stop the socket from either accepting new connections, or establishing
 old ones.
-Additionally, any established connections associated with _ep_ will be
-closed.
+Additionally, any established connections associated with _ep_ will be closed.
 
 NOTE: This function is provided for API
 xref:nng_compat.3compat.adoc[compatibility] with legacy _libnanomsg_.

docs/man/nn_socket.3compat.adoc

@@ -40,7 +40,7 @@ The address family _af_ can be one of two values:
 
 [horizontal]
 `AF_SP`:: Normal socket.
-`AF_SP_RAW`:: xref:nng.7.adoc#raw_mode["`Raw mode`"] socket.
+`AF_SP_RAW`:: xref:nng.7.adoc#raw_mode[Raw mode] socket.
 
 The protocol indicates the protocol to be used when creating the socket.
 The following protocols are defined:

docs/man/nng.7.adoc

@@ -102,10 +102,10 @@ messages may be dropped or reordered
 (Some protocols, such as xref:nng_req.7.adoc[_req_] may offer stronger
 guarantees by performing their own retry and validation schemes.)
 
-Each socket can have zero, one, or many "endpoints", which are either
+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
@@ -131,7 +131,7 @@ other than in a few specific circumstances.
 ==== Raw Mode
 
 (((cooked mode)))(((raw mode)))
-Most applications will use _nng_ sockets in "`cooked`" mode.
+Most applications will use _nng_ sockets in normal, or _cooked_, mode.
 This mode provides the full semantics of the protocol.
 For example, xref:nng_req.7.adoc[_req_] sockets will automatically
 match a reply to a request, and resend requests periodically if no reply
@@ -140,7 +140,7 @@ was received.
 There are situations, such as with xref:nng_device.3.adoc[proxies],
 where it is desirable to bypass these semantics and simply pass messages
 to and from the socket with no extra semantic handling.
-This is possible using "`raw`" mode sockets.
+This is possible using _raw_ mode sockets.
 
 Raw mode sockets are generally constructed with a different function,
 such as xref:nng_req_open.3.adoc[`nng_req0_open_raw()`].

docs/man/nng_aio.5.adoc

@@ -31,7 +31,7 @@ can only be used with a single operation at a time.
 
 Asynchronous operations are performed without blocking calling application
 threads.
-Instead the application registers a "`callback`" function to be executed
+Instead the application registers a callback function to be executed
 when the operation is complete (whether successfully or not).
 This callback will be executed exactly once.
 

docs/man/nng_aio_finish.3.adoc

@@ -31,9 +31,9 @@ xref:nng_aio_result.3.adoc[`nng_aio_result()`].
 
 This function causes the callback associated with the _aio_ to called.
 
-IMPORTANT: It is mandatory that operation "`providers`" call this function
-*EXACTLY ONCE* when they are finished with the operation.
-After calling this function they *MUST NOT* perform any further accesses
+IMPORTANT: It is mandatory that operation providers call this function
+*exactly once* when they are finished with the operation.
+After calling this function they *must not* perform any further accesses
 to the _aio_.
 
 NOTE: This function is only for I/O providers (those actually performing

docs/man/nng_bus.7.adoc

@@ -64,7 +64,7 @@ The _bus_ protocol has no protocol-specific options.
 
 === Protocol Headers
 
-When using a xref:nng.7.adoc#raw_mode["`raw`"] _bus_ socket, received messages will
+When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will
 contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header.
 If a message containing such a header is sent using a raw _bus_ socket, then,
 the message will be delivered to all connected pipes _except_ the one
@@ -75,7 +75,7 @@ Such configurations are useful in the creation of rebroadcasters, and this
 capability prevents a message from being routed back to its source.
 If no header is present, then a message is sent to all connected pipes.
 
-When using "`cooked`" _bus_ sockets, no message headers are present.
+When using normal (cooked mode) _bus_ sockets, no message headers are present.
 
 == SEE ALSO
 

docs/man/nng_compat.3compat.adoc

@@ -63,7 +63,7 @@ See the <<Caveats>> section below.
 === Compiling
 
 When compiling legacy _nanomsg_ applications, it will generally be
-necessary to change the include search path to add the "`compat`" subdirectory
+necessary to change the include search path to add the `compat` subdirectory
 of the directory where headers were installed.
 For example, if _nng_ is installed in `$prefix`, then header files will
 normally be located in `$prefix/include/nng`.

docs/man/nng_ctx.5.adoc

@@ -24,7 +24,7 @@ typedef struct nng_ctx_s nng_ctx
 
 == DESCRIPTION
 
-An `nng_ctx`(((context))) is a handle to an underlying "`context`" object,
+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
@@ -51,7 +51,7 @@ See the protocol-specific documentation for further details about whether
 contexts are supported, and details about what options are supported for
 contexts.
 
-Protocols that make use of contexts will also have a "`default`" context
+Protocols that make use of contexts will also have a default context
 that is used when the socket global operations are used.
 Operations using the global context will generally not interfere with
 any other contexts, except that certain socket options may affect socket

docs/man/nng_ctx_send.3.adoc

@@ -29,14 +29,14 @@ xref:nng_ctx.5.adoc[context] _ctx_ asynchronously.
 
 The message to send must have previously been set on the _aio_
 using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function.
-The function assumes "`ownership`" of the message.
+The function assumes ownership of the message.
 
 If the message was successfully queued for delivery to the socket,
 then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`]
 will return zero.
 In this case the socket will dispose of the message when it is finished with it.
 
-NOTE: The operation will be "`completed`", and the callback associated
+NOTE: The operation will be completed, and the callback associated
 with the _aio_ executed, as soon as the socket accepts the message
 for sending.
 This does _not_ indicate that the message was actually delivered, as it

docs/man/nng_cv_until.3supp.adoc

@@ -37,7 +37,7 @@ atomically just before returning to the caller.
 (The waiting is done without holding the mutex.)
 
 NOTE: Any condition may be used or checked, but the condition must be
-checked, as it is possible for this function to wake up "`spuriously`".
+checked, as it is possible for this function to wake up spuriously.
 The best way to do this is inside a loop that repeats until the condition
 tests for true.
 

docs/man/nng_cv_wait.3supp.adoc

@@ -36,7 +36,7 @@ atomically just before returning to the caller.
 (The waiting is done without holding the mutex.)
 
 NOTE: Any condition may be used or checked, but the condition must be
-checked, as it is possible for this function to wake up "`spuriously`".
+checked, as it is possible for this function to wake up spuriously.
 The best way to do this is inside a loop that repeats until the condition
 tests for true.
 

docs/man/nng_cv_wake.3supp.adoc

@@ -1,6 +1,6 @@
 = nng_cv_wake(3supp)
 //
-// Copyright 2018 Staysail Systems, Inc. <[email protected]>
+// Copyright 2020 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -36,8 +36,8 @@ NOTE: The caller should already have set the condition that the waiters
 will check, while holding the mutex.
 
 TIP: This function wakes all threads, which is generally safer but can
-lead to a problem known as the "`thundering herd`" when there are many
-waiters, as they are all woken simultaneously.
+lead to a performance problem when there are many waiters, as they are all
+woken simultaneously and may contend for resources.
 See xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] for a solution to this problem.
 
 == RETURN VALUES

docs/man/nng_cv_wake1.3supp.adoc

@@ -36,8 +36,7 @@ _cv_ was allocated.
 NOTE: The caller should already have set the condition that the waiters
 will check, while holding the mutex.
 
-TIP: While this function avoids the "`thundering herd`" problem, the
-caller cannot predict which waiter will be woken, and so the design must
+NOTE: The caller cannot predict which waiter will be woken, and so the design must
 ensure that it is sufficient that _any_ waiter be woken.
 When in doubt, it is safer to use xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`].
 

docs/man/nng_device.3.adoc

@@ -54,7 +54,7 @@ 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,
+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.

docs/man/nng_dial.3.adoc

@@ -39,7 +39,7 @@ When the pipe is closed, the dialer attempts to re-establish the connection.
 Dialers will also periodically retry a connection automatically if an attempt
 to connect asynchronously fails.
 
-TIP: While it is convenient to think of dialers as "`clients`", the relationship
+TIP: While it is convenient to think of dialers as clients, the relationship
 between the listener or dialer is orthogonal to any server or client status
 that might be associated with a given protocol.
 For example, a xref:nng_req.7.adoc[_req_]

docs/man/nng_dialer.5.adoc

@@ -25,7 +25,7 @@ typedef struct nng_dialer_s nng_dialer;
 == DESCRIPTION
 
 (((dialer)))
-An `nng_dialer` is a handle to a "`dialer`" object, which is responsible for
+An `nng_dialer` is a handle to a dialer object, which is responsible for
 creating a single xref:nng_pipe.5.adoc[`nng_pipe`] at a time by
 establishing an outgoing connection.
 
@@ -35,8 +35,8 @@ destroyed.
 
 Dialer objects are created by the
 xref:nng_dialer_create.3.adoc[`nng_dialer_create()`]
-or xref:nng_dial.3.adoc[`nng_dial()`] functions, and are always "`owned`"
-by a single xref:nng_socket.5.adoc[`nng_socket`].
+or xref:nng_dial.3.adoc[`nng_dial()`] functions, and are always associated
+with a single xref:nng_socket.5.adoc[`nng_socket`].
 
 IMPORTANT: The `nng_dialer` structure is always passed by value (both
 for input parameters and return values), and should be treated opaquely.
@@ -56,7 +56,7 @@ challenging communications problems.
 
 Dialer objects may be destroyed by the
 xref:nng_dialer_close.3.adoc[`nng_dialer_close()`] function.
-They are also closed when their "`owning`" socket is closed.
+They are also closed when their associated socket is closed.
 
 [[NNG_DIALER_INITIALIZER]]
 === Initialization

docs/man/nng_dialer_create.3.adoc

@@ -39,7 +39,7 @@ Dialers will also periodically retry a connection automatically if
 an attempt to connect asynchronously
 fails.
 
-TIP: While it is convenient to think of dialers as "`clients`", the relationship
+TIP: While it is convenient to think of dialers as clients, the relationship
 between the listener or dialer is orthogonal to any server or client status
 that might be associated with a given protocol.
 For example, a xref:nng_req.7.adoc[_req_]

docs/man/nng_http_handler_collect_body.3http.adoc

@@ -36,7 +36,7 @@ The collection is enabled if _want_ is true.
 Furthermore, the data that the client may sent is limited by the
 value of _maxsz_.
 If the client attempts to send more data than _maxsz_, then the
-request will be terminated with a 400 "`Bad Request`" status.
+request will be terminated with a 400 `Bad Request` status.
 
 TIP: Limiting the size of incoming request data can provide protection
 against denial of service attacks, as a buffer of the client-supplied

docs/man/nng_http_res_alloc.3http.adoc

@@ -28,8 +28,8 @@ int nng_http_res_alloc(nng_http_res **resp);
 The `nng_http_res_alloc()` function allocates a new HTTP response structure
 and stores a pointer to it in __resp__.
 The response will be initialized
-with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of `"OK`",
-and HTTP protocol version `"HTTP/1.1`".
+with status code 200 (`NNG_HTTP_STATUS_OK`), and a reason phrase of `OK`,
+and HTTP protocol version `HTTP/1.1`.
 
 TIP: When an error response is needed, consider using
 xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`] instead.

docs/man/nng_http_res_get_reason.3http.adoc

@@ -26,7 +26,7 @@ const char *nng_http_res_get_reason(nng_http_res *res);
 == DESCRIPTION
 
 The `nng_http_res_get_reason()` returns a string representing the
-"`reason phrase`" associated with the response _res_.
+reason associated with the response _res_.
 This is a human-readable explanation of the status code that
 would be obtained from
 xref:nng_http_res_get_status.3http.adoc[`nng_http_res_get_status()`].

docs/man/nng_http_res_get_status.3http.adoc

@@ -97,7 +97,7 @@ enum {
 ----
 
 TIP: When displaying status information to users (or logging such information),
-consider also including the "`reason phrase`" obtained with
+consider also including the reason obtained with
 xref:nng_http_res_get_reason.3http.adoc[`nng_http_res_get_reason()`].
 
 == RETURN VALUES

docs/man/nng_http_res_set_reason.3http.adoc

@@ -25,7 +25,7 @@ int nng_http_res_set_reason(nng_http_res *res, const char *reason);
 
 == DESCRIPTION
 
-The `nng_http_res_set_reason()` sets the human readable "`reason phrase`"
+The `nng_http_res_set_reason()` sets the human readable reason
 associated with the response _res_ to _reason_.
 
 If the value of _reason_ is `NULL` (the default), then a default reason

docs/man/nng_http_res_set_status.3http.adoc

@@ -102,7 +102,7 @@ enum {
 Please see the relevant HTTP RFCs for the semantics and correct
 use of these status codes.
 
-TIP: It is a good idea to also set the "`reason phrase`" with
+TIP: It is a good idea to also set the reason message with
 xref:nng_http_res_set_reason.3http.adoc[`nng_http_set_reason()`].
 This will help any humans who may have to diagnose a failure.
 

docs/man/nng_listen.3.adoc

@@ -38,7 +38,7 @@ pipes, which may be open concurrently.
 
 The _flags_ argument is ignored, but reserved for future use.
 
-TIP: While it is convenient to think of listeners as "`servers`", the
+TIP: While it is convenient to think of listeners as servers, the
 relationship between the listener or dialer is orthogonal to any server or
 client status that might be associated with a given protocol.
 For example, a xref:nng_req.7.adoc[_req_]