Documentation updates for 2.1

- Clarify ZMQ_LINGER, zmq_close (), zmq_term () relationship
- New socket options
- Clarify thread safety of sockets and migration between threads
- Other minor and spelling fixes

Signed-off-by: Martin Lucina <mato@kotelna.sk>

11 files changed, 186 insertions, 99 deletions

diff --git a/doc/zmq.txt b/doc/zmq.txt
index 06658c9..0c29a74 100644
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@@ -44,9 +44,15 @@ Terminate 0MQ context::
 Thread safety
 ^^^^^^^^^^^^^
 A 0MQ 'context' is thread safe and may be shared among as many application
-threads as necessary, without any additional locking required on the part of the
-caller.  Each 0MQ socket belonging to a particular 'context' may only be used
-by *the thread that created it* using _zmq_socket()_.
+threads as necessary, without any additional locking required on the part of
+the caller.
+
+Individual 0MQ 'sockets' are _not_ thread safe except in the case where full
+memory barriers are issued when migrating a socket from one thread to another.
+In practice this means applications can create a socket in one thread with
+_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread
+initialization, for example via a structure passed as an argument to
+_pthread_create()_.
 
 
 Multiple contexts
diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt
index 1200fb7..fe3bde5 100644
--- a/doc/zmq_close.txt
+++ b/doc/zmq_close.txt
@@ -16,10 +16,14 @@ DESCRIPTION
 -----------
 The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
 argument. Any outstanding messages physically received from the network but not
-yet received by the application with _zmq_recv()_ shall also be dropped. As for
-the messages sent with _zmq_send()_ but not yet passed to the network, 0MQ
-will try to send them in the background after _zmq_close()_ returns. Time spent
-attempting can be set using _ZMQ_LINGER_ socket option.
+yet received by the application with _zmq_recv()_ shall be discarded. The
+behaviour for discarding messages sent by the application with _zmq_send()_ but
+not yet physically transferred to the network depends on the value of the
+_ZMQ_LINGER_ socket option for the specified 'socket'.
+
+NOTE: The default setting of _ZMQ_LINGER_ does not discard unsent messages;
+this behaviour may cause the application to block when calling _zmq_term()_.
+For details refer to linkzmq:zmq_setsockopt[3] and linkzmq:zmq_term[3].
 
 
 RETURN VALUE
diff --git a/doc/zmq_errno.txt b/doc/zmq_errno.txt
index 61939a5..6bee0f1 100644
--- a/doc/zmq_errno.txt
+++ b/doc/zmq_errno.txt
@@ -20,7 +20,7 @@ the calling thread.
 The _zmq_errno()_ function is provided to assist users on non-POSIX systems who
 are experiencing issues with retrieving the correct value of 'errno' directly.
 Specifically, users on Win32 systems whose application is using a different C
-runtime library from the C runtime library in use by 0MQ will need to use
+run-time library from the C run-time library in use by 0MQ will need to use
 _zmq_errno()_ for correct operation.
 
 IMPORTANT: Users not experiencing issues with retrieving the correct value of
diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt
index 40a99b1..7f73e1c 100644
--- a/doc/zmq_getsockopt.txt
+++ b/doc/zmq_getsockopt.txt
@@ -26,8 +26,8 @@ value stored in the buffer.
 The following options can be retrieved with the _zmq_getsockopt()_ function:
 
 
-ZMQ_TYPE: Retrieve socket type.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_TYPE: Retrieve socket type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_TYPE' option shall retrieve the socket type for the specified
 'socket'.  The socket type is specified at socket creation time and
 cannot be modified afterwards.
@@ -167,13 +167,13 @@ Default value:: 10
 Applicable socket types:: all, when using multicast transports
 
 
-ZMQ_MCAST_LOOP: Control multicast loopback
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_MCAST_LOOP: Control multicast loop-back
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_MCAST_LOOP' option controls whether data sent via multicast
-transports can also be received by the sending host via loopback.  A value of
-zero indicates that the loopback functionality is disabled, while the default
-value of 1 indicates that the loopback functionality is enabled.  Leaving
-multicast loopback enabled when it is not required can have a negative impact
+transports can also be received by the sending host via loop-back.  A value of
+zero indicates that the loop-back functionality is disabled, while the default
+value of 1 indicates that the loop-back functionality is enabled.  Leaving
+multicast loop-back enabled when it is not required can have a negative impact
 on performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production
 environments.
 
@@ -214,53 +214,80 @@ Applicable socket types:: all
 
 ZMQ_LINGER: Retrieve linger period for socket shutdown
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_LINGER' option shall retrieve the period for pending outbound
-messages to linger in memory after closing the socket. Value of -1 means
-infinite. Pending messages will be kept until they are fully transferred to
-the peer. Value of 0 means that all the pending messages are dropped immediately
-when socket is closed. Positive value means number of milliseconds to keep
-trying to send the pending messages before discarding them.
+The 'ZMQ_LINGER' option shall retrieve the linger period for the specified
+'socket'.  The linger period determines how long pending messages which have
+yet to be sent to a peer shall linger in memory after a socket is closed with
+linkzmq:zmq_close[3], and further affects the termination of the socket's
+context with linkzmq:zmq_term[3]. The following outlines the different
+behaviours:
+
+* The default value of '-1' specifies an infinite linger period. Pending
+  messages shall not be discarded after a call to _zmq_close()_; attempting to
+  terminate the socket's context with _zmq_term()_ shall block until all
+  pending messages have been sent to a peer.
+
+* The value of '0' specifies no linger period. Pending messages shall be
+  discarded immediately when the socket is closed with _zmq_close()_.
+
+* Positive values specify an upper bound for the linger period in milliseconds.
+  Pending messages shall not be discarded after a call to _zmq_close()_;
+  attempting to terminate the socket's context with _zmq_term()_ shall block
+  until either all pending messages have been sent to a peer, or the linger
+  period expires, after which any pending messages shall be discarded.
 
 [horizontal]
 Option value type:: int
 Option value unit:: milliseconds
-Default value:: -1
+Default value:: -1 (infinite)
 Applicable socket types:: all
 
-ZMQ_RECONNECT_IVL: Retrieve reconnect period for connection-based transports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_RECONNECT_IVL' option shall retrieve the period indicating how long it
-takes for a disconnected underlying connection to attempt to reconnect.
+ZMQ_RECONNECT_IVL: Retrieve reconnection interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RECONNECT_IVL' option shall retrieve the reconnection interval for the
+specified 'socket'.  The reconnection interval is the maximum period 0MQ shall
+wait between attempts to reconnect disconnected peers when using
+connection-oriented transports.
+
+NOTE: The reconnection interval may be randomized by 0MQ to prevent
+reconnection storms in topologies with a large number of peers per socket.
 
 [horizontal]
 Option value type:: int
 Option value unit:: milliseconds
 Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports
 
 
-ZMQ_BACKLOG: Retrieve maximum length of the queue of pending connections
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_BACKLOG' option shall retrieve maximum size of the
-pending connection backlog for connection-based transports. For details
-refer to your operating system documentation for the 'listen' function.
+ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_BACKLOG' option shall retrieve the maximum length of the queue of
+outstanding peer connections for the specified 'socket'; this only applies to
+connection-oriented transports. For details refer to your operating system
+documentation for the 'listen' function.
 
 [horizontal]
 Option value type:: int
 Option value unit:: connections
 Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports
 
 
 ZMQ_FD: Retrieve file descriptor associated with the socket
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_FD' option shall retrieve file descriptor associated with the 0MQ
-socket. The descriptor can be used to integrate 0MQ socket into an existing
-event loop. It should never be used for anything else than polling -- such as
-reading or writing. The descriptor signals edge-triggered IN event when
-something has happened within the 0MQ socket. It does not necessarily mean that
-the messages can be read or written. Check ZMQ_EVENTS option to find out whether
-the 0MQ socket is readable or writeable.
+The 'ZMQ_FD' option shall retrieve the file descriptor associated with the
+specified 'socket'. The returned file descriptor can be used to integrate the
+socket into an existing event loop; the 0MQ library shall signal any pending
+events on the socket in an _edge-triggered_ fashion by making the file
+descriptor become ready for reading.
+
+NOTE: The ability to read from the returned file descriptor does not
+necessarily indicate that messages are available to be read from, or can be
+written to, the underlying socket; applications must retrieve the actual event
+state with a subsequent retrieval of the 'ZMQ_EVENTS' option.
+
+CAUTION: The returned file descriptor is intended for use with a 'poll' or
+similar system call only. Applications must never attempt to read or write data
+to it directly.
 
 [horizontal]
 Option value type:: int on POSIX systems, SOCKET on Windows
@@ -269,11 +296,24 @@ Default value:: N/A
 Applicable socket types:: all
 
 
-ZMQ_EVENTS: Check whether socket is readable and/or writeable
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_EVENTS' option shall retrieve event flags for the specified socket.
-If a message can be read from the socket ZMQ_POLLIN flag is set. If message can
-be written to the socket ZMQ_POLLOUT flag is set.
+ZMQ_EVENTS: Retrieve socket event state
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_EVENTS' option shall retrieve the event state for the specified
+'socket'.  The returned value is a bit mask constructed by OR'ing a combination
+of the following event flags:
+
+*ZMQ_POLLIN*::
+Indicates that at least one message may be received from the specified socket
+without blocking.
+
+*ZMQ_POLLOUT*::
+Indicates that at least one message may be sent to the specified socket without
+blocking.
+
+The combination of a file descriptor returned by the 'ZMQ_FD' option being
+ready for reading but no actual events returned by a subsequent retrieval of
+the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case
+and restart their polling operation/event loop.
 
 [horizontal]
 Option value type:: uint32_t
diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt
index 4017db2..d9bce5a 100644
--- a/doc/zmq_pgm.txt
+++ b/doc/zmq_pgm.txt
@@ -24,7 +24,7 @@ The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
 'ZMQ_SUB' socket types.
 
 Further, PGM sockets are rate limited by default and incur a performance
-penalty when used over a loopback interface. For details, refer to the
+penalty when used over a loop-back interface. For details, refer to the
 'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in
 linkzmq:zmq_setsockopt[3].
 
@@ -69,7 +69,7 @@ representation.
 
 WIRE FORMAT
 -----------
-Consecutive PGM datagrams are interpreted by 0MQ as a single continous stream
+Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream
 of data where 0MQ messages are not necessarily aligned with PGM datagram
 boundaries and a single 0MQ message may span several PGM datagrams. This stream
 of data consists of 0MQ messages encapsulated in 'frames' as described in
@@ -130,7 +130,7 @@ EXAMPLE
 .Connecting a socket
 ----
 /* Connecting to the multicast address 239.192.1.1, port 5555, */
-/* using the first ethernet network interface on Linux */
+/* using the first Ethernet network interface on Linux */
 /* and the Encapsulated PGM protocol */
 rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
 assert (rc == 0);
diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt
index f709c07..e8e001c 100644
--- a/doc/zmq_poll.txt
+++ b/doc/zmq_poll.txt
@@ -40,17 +40,17 @@ NOTE: All 0MQ sockets passed to the _zmq_poll()_ function must share the
 same 0MQ 'context' and must belong to the thread calling _zmq_poll()_.
 
 For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
-member, and then indicate any requested events that have occured by setting the
+member, and then indicate any requested events that have occurred by setting the
 bit corresponding to the event condition in the 'revents' member.
 
-If none of the requested events have occured on any *zmq_pollitem_t* item,
+If none of the requested events have occurred on any *zmq_pollitem_t* item,
 _zmq_poll()_ shall wait 'timeout' microseconds for an event to occur on
 any of the requested items. If the value of 'timeout' is `0`, _zmq_poll()_
 shall return immediately. If the value of 'timeout' is `-1`, _zmq_poll()_ shall
-block indefinitely until a requested event has occured on at least one
+block indefinitely until a requested event has occurred on at least one
 *zmq_pollitem_t*.
 
-The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed
+The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed
 by OR'ing a combination of the following event flags:
 
 *ZMQ_POLLIN*::
@@ -93,7 +93,8 @@ associated 0MQ 'context' was terminated.
 *EFAULT*::
 The provided 'items' was not valid (NULL).
 *EINTR*::
-The poll was interrupted by delivery of a signal before any event was available.
+The operation was interrupted by delivery of a signal before any events were
+available.
 
 
 EXAMPLE
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index af92929..86b01e4 100644
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@@ -171,13 +171,13 @@ Default value:: 10
 Applicable socket types:: all, when using multicast transports
 
 
-ZMQ_MCAST_LOOP: Control multicast loopback
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ZMQ_MCAST_LOOP: Control multicast loop-back
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_MCAST_LOOP' option shall control whether data sent via multicast
 transports using the specified 'socket' can also be received by the sending
-host via loopback. A value of zero disables the loopback functionality, while
-the default value of 1 enables the loopback functionality. Leaving multicast
-loopback enabled when it is not required can have a negative impact on
+host via loop-back. A value of zero disables the loop-back functionality, while
+the default value of 1 enables the loop-back functionality. Leaving multicast
+loop-back enabled when it is not required can have a negative impact on
 performance. Where possible, disable 'ZMQ_MCAST_LOOP' in production
 environments.
 
@@ -218,44 +218,63 @@ Applicable socket types:: all
 
 ZMQ_LINGER: Set linger period for socket shutdown
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_LINGER' option shall be set to specify period for pending outbound
-messages to linger in memory after closing the socket. Value of -1 means
-infinite. Pending messages will be kept until they are fully transferred to
-the peer. Value of 0 means that all the pending messages are dropped immediately
-when socket is closed. Positive value means number of milliseconds to keep
-trying to send the pending messages before discarding them.
+The 'ZMQ_LINGER' option shall set the linger period for the specified 'socket'.
+The linger period determines how long pending messages which have yet to be
+sent to a peer shall linger in memory after a socket is closed with
+linkzmq:zmq_close[3], and further affects the termination of the socket's
+context with linkzmq:zmq_term[3]. The following outlines the different
+behaviours:
+
+* The default value of '-1' specifies an infinite linger period. Pending
+  messages shall not be discarded after a call to _zmq_close()_; attempting to
+  terminate the socket's context with _zmq_term()_ shall block until all
+  pending messages have been sent to a peer.
+
+* The value of '0' specifies no linger period. Pending messages shall be
+  discarded immediately when the socket is closed with _zmq_close()_.
+
+* Positive values specify an upper bound for the linger period in milliseconds.
+  Pending messages shall not be discarded after a call to _zmq_close()_;
+  attempting to terminate the socket's context with _zmq_term()_ shall block
+  until either all pending messages have been sent to a peer, or the linger
+  period expires, after which any pending messages shall be discarded.
 
 [horizontal]
 Option value type:: int
 Option value unit:: milliseconds
-Default value:: -1
+Default value:: -1 (infinite)
 Applicable socket types:: all
 
 
-ZMQ_RECONNECT_IVL: Set reconnect period for connection-based transports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_RECONNECT_IVL' option shall be set to specify how long it takes for a
-disconnected underlying connection to attempt to reconnect. The interval
-can be randomized to some extent by 0MQ to prevent reconnection storms.
+ZMQ_RECONNECT_IVL: Set reconnection interval
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_RECONNECT_IVL' option shall set the reconnection interval for the
+specified 'socket'.  The reconnection interval is the maximum period 0MQ shall
+wait between attempts to reconnect disconnected peers when using
+connection-oriented transports.
+
+NOTE: The reconnection interval may be randomized by 0MQ to prevent
+reconnection storms in topologies with a large number of peers per socket.
 
 [horizontal]
 Option value type:: int
 Option value unit:: milliseconds
 Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports
 
 
-ZMQ_BACKLOG: Set maximum length of the queue of pending connections
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The 'ZMQ_BACKLOG' option shall be set to specify maximum size of the
-pending connection backlog for connection-based transports. For details
-refer to your operating system documentation for the 'listen' function.
+ZMQ_BACKLOG: Set maximum length of the queue of outstanding connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_BACKLOG' option shall set the maximum length of the queue of
+outstanding peer connections for the specified 'socket'; this only applies to
+connection-oriented transports. For details refer to your operating system
+documentation for the 'listen' function.
 
 [horizontal]
 Option value type:: int
 Option value unit:: connections
 Default value:: 100
-Applicable socket types:: all
+Applicable socket types:: all, only for connection-oriented transports.
 
 
 RETURN VALUE
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index 2156af2..6bcb133 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -35,7 +35,7 @@ sockets transfer streams of bytes or discrete datagrams, 0MQ sockets transfer
 discrete _messages_.
 
 0MQ sockets being _asynchronous_ means that the timings of the physical
-connection setup and teardown, reconnect and effective delivery are transparent
+connection setup and tear down, reconnect and effective delivery are transparent
 to the user and organized by 0MQ itself. Further, messages may be _queued_ in
 the event that a peer is unavailable to receive them.
 
@@ -46,6 +46,18 @@ relationships. With the exception of 'ZMQ_PAIR', 0MQ sockets may be connected
 incoming connections *from multiple endpoints* bound to the socket using
 _zmq_bind()_, thus allowing many-to-many relationships.
 
+.Thread safety
+A 0MQ 'context' is thread safe and may be shared among as many application
+threads as necessary, without any additional locking required on the part of
+the caller.
+
+Individual 0MQ 'sockets' are _not_ thread safe except in the case where full
+memory barriers are issued when migrating a socket from one thread to another.
+In practice this means applications can create a socket in one thread with
+_zmq_socket()_ and then pass it to a _newly created_ thread as part of thread
+initialization, for example via a structure passed as an argument to
+_pthread_create()_.
+
 .Socket types
 The following sections present the socket types defined by 0MQ, grouped by the
 general _messaging pattern_ which is built from related socket types.
@@ -100,7 +112,7 @@ Compatible peer sockets:: 'ZMQ_REQ'
 Direction:: Bidirectional
 Send/receive pattern:: Receive, Send, Receive, Send, ...
 Incoming routing strategy:: Fair-queued
-Outgoing routing stratagy:: Last peer
+Outgoing routing strategy:: Last peer
 ZMQ_HWM option action:: Drop
 
 
@@ -166,13 +178,13 @@ ZMQ_HWM option action:: Drop
 Publish-subscribe pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 The publish-subscribe pattern is used for one-to-many distribution of data from
-a single _publisher_ to multiple _subscribers_ in a fanout fashion.
+a single _publisher_ to multiple _subscribers_ in a fan out fashion.
 
 
 ZMQ_PUB
 ^^^^^^^
 A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
-Messages sent are distributed in a fanout fashion to all connected peers.
+Messages sent are distributed in a fan out fashion to all connected peers.
 The linkzmq:zmq_recv[3] function is not implemented for this socket type.
 
 When a 'ZMQ_PUB' socket enters an exceptional state due to having reached the
@@ -186,7 +198,7 @@ Compatible peer sockets:: 'ZMQ_SUB'
 Direction:: Unidirectional
 Send/receive pattern:: Send only
 Incoming routing strategy:: N/A
-Outgoing routing strategy:: Fanout
+Outgoing routing strategy:: Fan out
 ZMQ_HWM option action:: Drop
 
 
@@ -301,8 +313,6 @@ ERRORS
 ------
 *EINVAL*::
 The requested socket 'type' is invalid.
-*EMTHREAD*::
-The maximum number of sockets within this 'context' has been exceeded.
 *EFAULT*::
 The provided 'context' was not valid (NULL).
 
diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt
index 29fa181..84ec6c8 100644
--- a/doc/zmq_tcp.txt
+++ b/doc/zmq_tcp.txt
@@ -30,7 +30,7 @@ colon and the TCP port number to use.
 
 An 'interface' may be specified by either of the following:
 
-* The wildcard `*`, meaning all available interfaces.
+* The wild-card `*`, meaning all available interfaces.
 * The primary IPv4 address assigned to the interface, in its numeric
   representation.
 * The interface name as defined by the operating system.
@@ -127,10 +127,10 @@ EXAMPLES
 /* TCP port 5555 on all available interfaces */
 rc = zmq_bind(socket, "tcp://*:5555");
 assert (rc == 0);
-/* TCP port 5555 on the local loopback interface on all platforms */
+/* TCP port 5555 on the local loop-back interface on all platforms */
 rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
 assert (rc == 0);
-/* TCP port 5555 on the first ethernet network interface on Linux */
+/* TCP port 5555 on the first Ethernet network interface on Linux */
 rc = zmq_bind(socket, "tcp://eth0:5555");
 assert (rc == 0);
 ----
diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt
index 6c69b82..2edc765 100644
--- a/doc/zmq_term.txt
+++ b/doc/zmq_term.txt
@@ -14,20 +14,27 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-The _zmq_term()_ function terminates the 0MQ context 'context'.
+The _zmq_term()_ function shall terminate the 0MQ context 'context'.
 
-It does so in following steps:
+Context termination is performed in the following steps:
 
-* It causes any blocking operations currently in progress on sockets open within
-  'context' to exit immediately with an error code of ETERM.
+1. Any blocking operations currently in progress on sockets open within
+   'context' shall return immediately with an error code of ETERM.  With the
+   exception of _zmq_close()_, any further operations on sockets open within
+   'context' shall fail with an error code of ETERM.
 
-* With the exception of _zmq_close()_, any further operations on sockets open
-  within 'context' shall fail with an error code of ETERM.
+2. After interrupting all blocking calls, _zmq_term()_ shall _block_ until the
+   following conditions are satisfied:
++
+   * All sockets open within 'context' have been closed with _zmq_close()_.
 
-* After iterrupting all blocking calls, _zmq_term()_ blocks until all sockets
-  open within the context are closed using _zmq_close()_ and either all the
-  pending outbound messages are pushed to the network or ZMQ_LINGER period
-  expires for individual sockets.
+   * For each socket within 'context', all messages sent by the application
+     with _zmq_send()_ have either been physically transferred to a network
+     peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
+     option has expired.
+
+For further details regarding socket linger behaviour refer to the _ZMQ_LINGER_
+option in linkzmq:zmq_setsockopt[3].
 
 
 RETURN VALUE
diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt
index 0ad3a55..58b7977 100644
--- a/doc/zmq_version.txt
+++ b/doc/zmq_version.txt
@@ -15,7 +15,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 The _zmq_version()_ function shall fill in the integer variables pointed to by
-the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel
+the 'major', 'minor' and 'patch' arguments with the major, minor and patch level
 components of the 0MQ library version.
 
 This functionality is intended for applications or language bindings