5 files changed, 94 insertions, 69 deletions
diff --git a/doc/zmq.txt b/doc/zmq.txt
index 003570a..fa15e43 100644
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@@ -90,8 +90,8 @@ Standard sockets present a _synchronous_ interface to either connection-mode
 reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams
 (SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
 asynchronous _message queue_, with the exact queueing semantics depending on
-the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the
-_messaging patterns_ provided.
+the socket type in use. See linkzmq:zmq_socket[3] for the socket types
+provided.
 
 0MQ sockets being _asynchronous_ means that the timings of the physical
 connection setup and teardown, reconnect and effective delivery are organized
diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt
index 983ce93..c76d05a 100644
--- a/doc/zmq_bind.txt
+++ b/doc/zmq_bind.txt
@@ -4,34 +4,36 @@ zmq_bind(3)
 
 NAME
 ----
-zmq_bind - assign a local address to a socket
+zmq_bind - accept connections on a socket
 
 
 SYNOPSIS
 --------
-*int zmq_bind (void '*socket', const char '*address');*
+*int zmq_bind (void '*socket', const char '*endpoint');*
 
 
 DESCRIPTION
 -----------
-The _zmq_bind()_ function shall assign a local address specified by the
-'address' argument to the socket referenced by the 'socket' argument.
+The _zmq_bind()_ function shall create an endpoint for accepting connections
+and bind it to the socket referenced by the 'socket' argument.
 
-The 'address' argument is a string consisting of two parts as follows:
-'transport'://'endpoint'. The 'transport' part specifies the underlying
-transport protocol to use. The meaning of the 'endpoint' part is specific to
+The 'endpoint' argument is a string consisting of two parts as follows:
+'transport'`://`'address'. The 'transport' part specifies the underlying
+transport protocol to use. The meaning of the 'address' part is specific to
 the underlying transport protocol selected.
 
 The following transports are defined:
 
+'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
+'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
 'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
-'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
-'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
 
-A single socket may have an arbitrary number of local addresses assigned to it
-using _zmq_bind()_, while also being connected to an arbitrary number of peer
-addresses using _zmq_connect()_.
+With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to
+multiple endpoints using _zmq_connect()_, while simultaneously accepting
+incoming connections from multiple endpoints bound to the socket using
+_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact
+semantics involved when connecting or binding a socket to multiple endpoints.
 
 
 RETURN VALUE
@@ -63,7 +65,7 @@ EXAMPLE
 /* Create a ZMQ_PUB socket */
 void *socket = zmq_socket (context, ZMQ_PUB);
 assert (socket);
-/* Bind it to a in-process transport with the endpoint 'my_publisher' */
+/* Bind it to a in-process transport with the address 'my_publisher' */
 int rc = zmq_bind (socket, "inproc://my_publisher");
 assert (rc == 0);
 /* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt
index d31b87b..2bc8e4f 100644
--- a/doc/zmq_connect.txt
+++ b/doc/zmq_connect.txt
@@ -4,34 +4,36 @@ zmq_connect(3)
 
 NAME
 ----
-zmq_connect - connect a socket to a peer address
+zmq_connect - connect a socket
 
 
 SYNOPSIS
 --------
-*int zmq_connect (void '*socket', const char '*address');*
+*int zmq_connect (void '*socket', const char '*endpoint');*
 
 
 DESCRIPTION
 -----------
 The _zmq_connect()_ function shall connect the socket referenced by the
-'socket' argument to a peer address specified by the 'address' argument.
+'socket' argument to the endpoint specified by the 'endpoint' argument.
 
-The 'address' argument is a string consisting of two parts as follows:
-'transport'`://`'endpoint'. The 'transport' part specifies the underlying
-transport protocol to use. The meaning of the 'endpoint' part is specific to
+The 'endpoint' argument is a string consisting of two parts as follows:
+'transport'`://`'address'. The 'transport' part specifies the underlying
+transport protocol to use. The meaning of the 'address' part is specific to
 the underlying transport protocol selected.
 
 The following transports are defined:
 
+'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
+'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
 'pgm', 'epgm':: reliable multicast transport using PGM, see linkzmq:zmq_pgm[7]
-'ipc':: local inter-process communication transport, see linkzmq:zmq_ipc[7]
-'inproc':: local in-process (inter-thread) communication transport, see linkzmq:zmq_inproc[7]
 
-A single socket may be connected to an arbitrary number of peer addresses using
-_zmq_connect()_, while also having an arbitrary number of local addresses
-assigned to it using _zmq_bind()_.
+With the exception of 'ZMQ_PAIR' sockets, a single socket may be connected to
+multiple endpoints using _zmq_connect()_, while simultaneously accepting
+incoming connections from multiple endpoints bound to the socket using
+_zmq_bind()_. Refer to linkzmq:zmq_socket[3] for a description of the exact
+semantics involved when connecting or binding a socket to multiple endpoints.
 
 NOTE: The connection will not be performed immediately but as needed by 0MQ.
 Thus a successful invocation of _zmq_connect()_ does not indicate that a
@@ -61,7 +63,7 @@ EXAMPLE
 /* Create a ZMQ_SUB socket */
 void *socket = zmq_socket (context, ZMQ_SUB);
 assert (socket);
-/* Connect it to an in-process transport with the endpoint 'my_publisher' */
+/* Connect it to an in-process transport with the address 'my_publisher' */
 int rc = zmq_connect (socket, "inproc://my_publisher");
 assert (rc == 0);
 /* Connect it to the host server001, port 5555 using a TCP transport */
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index 8845a10..3bc1081 100644
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@@ -61,13 +61,13 @@ The 'ZMQ_AFFINITY' option shall set the I/O thread affinity for connections
 created by subsequent _zmq_connect()_ or _zmq_bind()_ calls on the specified
 'socket'.
 
-sockets. Affinity determines which threads from the 0MQ I/O thread pool
-associated with the socket's _context_ shall handle newly created connections.
-A value of zero specifies no affinity, meaning that work shall be distributed
-fairly among all 0MQ I/O threads in the thread pool. For non-zero values, the
-lowest bit corresponds to thread 1, second lowest bit to thread 2 and so on.
-For example, a value of 3 specifies that subsequent connections on 'socket'
-shall be handled exclusively by I/O threads 1 and 2.
+Affinity determines which threads from the 0MQ I/O thread pool associated with
+the socket's _context_ shall handle newly created connections.  A value of zero
+specifies no affinity, meaning that work shall be distributed fairly among all
+0MQ I/O threads in the thread pool. For non-zero values, the lowest bit
+corresponds to thread 1, second lowest bit to thread 2 and so on.  For example,
+a value of 3 specifies that subsequent connections on 'socket' shall be handled
+exclusively by I/O threads 1 and 2.
 
 See also linkzmq:zmq_init[3] for details on allocating the number of I/O
 threads for a specific _context_.
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index e01921c..ebae5e1 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -19,7 +19,31 @@ The 'zmq_socket()' function shall create a 0MQ socket within the specified
 argument specifies the socket type, which determines the semantics of
 communication over the socket.
 
-The following _messaging patterns_ are defined:
+The following sections present the socket types defined by 0MQ, grouped by the
+general _messaging pattern_ built from related socket types.
+
+
+Request-reply pattern
+~~~~~~~~~~~~~~~~~~~~~
+The request-reply pattern is used for sending requests from a _client_ to a
+_service_, and receiving subsequent replies to each request sent.
+
+Socket type:: 'ZMQ_REQ'
+Compatible peer sockets:: 'ZMQ_REP'
+
+A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
+receive replies from a _service_. This socket type allows only an alternating
+sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
+request sent is load-balanced among all connected _services_.
+
+Socket type:: 'ZMQ_REP'
+Compatible peer sockets:: 'ZMQ_REQ'
+
+A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
+send replies to a _client_.  This socket type allows only an alternating
+sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
+reply is routed to the _client_ that issued the last received request.
+
 
 Publish-subscribe pattern
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -43,49 +67,46 @@ which messages to subscribe to. The _zmq_send()_ function is not implemented
 for this socket type.
 
 
-Request-reply pattern
-~~~~~~~~~~~~~~~~~~~~~
-The request-reply pattern is used for sending requests from a _client_ to a
-_service_, and receiving subsequent replies to each request sent.
-
-Socket type:: 'ZMQ_REQ'
-Compatible peer sockets:: 'ZMQ_REP'
+Pipeline pattern
+~~~~~~~~~~~~~~~~
+The pipeline pattern is used for distributing data to _nodes_ arranged in
+a pipeline. Data always flows *down* the pipeline, and each stage of the
+pipeline is connected to at least one _node_. When a pipeline stage is
+connected to multiple _nodes_ data is processed by all connected _nodes_ in
+parallel.
 
-A socket of type 'ZMQ_REQ' is used by a _client_ to send requests to and
-receive replies from a _service_. This socket type allows only an alternating
-sequence of _zmq_send(request)_ and subsequent _zmq_recv(reply)_ calls. Each
-request sent is load-balanced among all connected _services_.
+Socket type:: 'ZMQ_DOWNSTREAM'
+Compatible peer sockets:: 'ZMQ_UPSTREAM'
 
-Socket type:: 'ZMQ_REP'
-Compatible peer sockets:: 'ZMQ_REQ'
+A socket of type 'ZMQ_DOWNSTREAM' is used by a pipeline _node_ to send messages
+to downstream pipeline _nodes_. Messages are load-balanced to all connected
+downstream _nodes_. The _zmq_recv()_ function is not implemented for this
+socket type.
 
-A socket of type 'ZMQ_REP' is used by a _service_ to receive requests from and
-send replies to a _client_.  This socket type allows only an alternating
-sequence of _zmq_recv(request)_ and subsequent _zmq_send(reply)_ calls. Each
-reply is routed to the _client_ that issued the last received request.
+Socket type:: 'ZMQ_UPSTREAM'
+Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
 
+A socket of type 'ZMQ_UPSTREAM' is used by a pipeline _node_ to receive
+messages from upstream pipeline _nodes_. Messages are fair-queued from among
+all connected upstream _nodes_. The _zmq_send()_ function is not implemented
+for this socket type.
 
-Parallelized pipeline pattern
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The parallelized pipeline pattern is used for distributing work between
-_components_ of a pipeline. Work travels down the pipeline and at each stage
-can be processed by any number of _components_ in parallel.
 
-Socket type:: 'ZMQ_UPSTREAM'
-Compatible peer sockets:: 'ZMQ_DOWNSTREAM'
+Exclusive pair pattern
+~~~~~~~~~~~~~~~~~~~~~~
+The exclusive pair pattern is used for communicating exclusively between two
+peers.
 
-A socket of type 'ZMQ_UPSTREAM' is used by a _component_ of a pipeline to
-receive messages from upstream stages of the pipeline. Messages are fair-queued
-from among all connected upstream _components_. The _zmq_send()_ function is
-not implemented for this socket type.
+Socket type:: 'ZMQ_PAIR'
+Compatible peer sockets:: 'ZMQ_PAIR'
 
-Socket type:: 'ZMQ_DOWNSTREAM'
-Compatible peer sockets:: 'ZMQ_UPSTREAM'
+A socket of type 'ZMQ_PAIR' can only be connected to a single peer at any one
+time.  No message routing or filtering is performed on messages sent over a
+'ZMQ_PAIR' socket.
 
-A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to
-send messages to downstream stages of the pipeline. Messages are load-balanced
-to all connected downstream _components_. The _zmq_recv()_ function is not
-implemented for this socket type.
+NOTE: 'ZMQ_PAIR' sockets are experimental, and are currently missing several
+features such as auto-reconnection. Developers should consider other patterns
+in preference to the exclusive pair pattern.
 
 
 RETURN VALUE