Documentation rewrite

2025-03-20 02:17:55 +00:00 · 2010-03-09 18:47:31 +01:00 · 2010-03-09 18:47:31 +01:00 · 1aee86408d
commit 1aee86408d
parent d790940fd0
34 changed files with 1286 additions and 962 deletions
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@ -4,8 +4,8 @@ MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_flush.3 zmq_init.3 \
    zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \
    zmq_poll.3 zmq_recv.3 zmq_send.3 zmq_setsockopt.3 zmq_socket.3 \
    zmq_strerror.3 zmq_term.3 zmq_version.3
-MAN7 = zmq.7 zmq_tcp.7 zmq_udp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
+MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \
-    zmq_cpp.7 zmq_java.7
+    zmq_cpp.7
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
 MAN_TXT = $(MAN1:%.1=%.txt)
--- a/doc/asciidoc.conf
+++ b/doc/asciidoc.conf
@ -1,3 +1,6 @@
 [paradef-default]
 literal-style=template="literalparagraph"
 [macros]
 (?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
@ -32,3 +35,8 @@ template::[header-declarations]
 </refnamediv>
 endif::backend-docbook[]
 endif::doctype-manpage[]
 [replacements]
 ifdef::backend-xhtml11[]
 0MQ=ØMQ
 endif::backend-xhtml11[]
--- a/doc/zmq.txt
+++ b/doc/zmq.txt
@ -9,59 +9,69 @@ zmq - 0MQ lightweight messaging kernel
 SYNOPSIS
 --------
-0MQ is an extension of POSIX sockets. It is a library that augments standard
+*#include <zmq.h>*
 networking sockets by special capabilities that you can otherwise get only
 by using specialised "messaging middleware" products, such as automated
 handling of connections and disconnections, delivery of a message to multiple
 destinations, load balancing messages, sophisticated message filtering etc.
-0MQ is designed to be extremely fast. Expected end-to-end latencies for
+*cc* ['flags'] 'files' *-lzmq* ['libraries']
 messages passed over a LAN are in tens of microseconds. Expected
 throughputs are to be measured in millions of messages per second.
 0MQ is designed to be very thin. It requires no more than couple of
 pages in resident memory and is thus well suited for any environment ranging
 from small embedded devices, routers and cell phones to enterprise-scale
 data centers.
 0MQ runs on a wide range of operating systems and supports variety of processor
 microarchitectures.
 0MQ is accessible from a large set of programming languages.
 0MQ is fully open sourced LGPL-licensed software.
-CONTEXT
+DESCRIPTION
-------
+-----------
-Each 0MQ socket lives within a specific context. Creating and destroying
+The 0MQ lightweight messaging kernel is a library which extends the standard
-context is a counterpart of library initialisation/deinitialisation as used
+socket interfaces with features traditionally provided by specialised
-elsewhere. Ability to create multiple contexts saves the day when an application
+_messaging middleware_ products. 0MQ sockets provide an abstraction of
-happens to link (indirectly and involuntarily) with several instances of 0MQ.
+asynchronous  _message queues_, multiple _messaging patterns_, message
 filtering (_subscriptions_), seamless access to multiple _transport protocols_
 and more.
 This documentation presents an overview of 0MQ concepts, describes how 0MQ
 abstracts standard sockets and provides a reference manual for the functions
 provided by the 0MQ library.
 Context
 ~~~~~~~
 Before using any 0MQ library functions the caller must initialise a 0MQ
 'context' using _zmq_init()_. The following functions are provided to handle
 initialisation and termination of a 'context':
 Initialise 0MQ context::
    linkzmq:zmq_init[3]
-Uninitialise 0MQ context::
+Terminate 0MQ context::
    linkzmq:zmq_term[3]
-MESSAGES
+Thread safety
--------
+^^^^^^^^^^^^^
-Message is a discrete unit of data passed between applications or components
+A 0MQ 'context' is thread safe and may be shared among as many application
-of the same application. 0MQ message has no internal structure, it is an opaque
+threads as the application has requested using the _app_threads_ parameter to
-BLOB. When writing data to or reading data from the message, you are free to
+_zmq_init()_, without any additional locking required on the part of the
-use any of the many serialisation libraries available. Alternatively, you can
+caller.  Each 0MQ socket belonging to a particular 'context' may only be used
-use your own serialisation code. The latter option is especially useful when
+by *the thread that created it* using _zmq_socket()_.
-migrating legacy applications to 0MQ - there's no need to break existing
+
-message formats.
+
 Multiple contexts
 ^^^^^^^^^^^^^^^^^
 Multiple 'contexts' may coexist within a single application. Thus, an
 application can use 0MQ directly and at the same time make use of any number of
 additional libraries or components which themselves make use of 0MQ as long as
 the above guidelines regarding thread safety are adhered to.
 Messages
 ~~~~~~~~
 A 0MQ message is a discrete unit of data passed between applications or
 components of the same application. 0MQ messages have no internal structure and
 from the point of view of 0MQ itself they are considered to be opaque BLOBs.
 The following functions are provided to work with messages:
 Initialise a message::
    linkzmq:zmq_msg_init[3]
-    linkzmq:zmq_msg_size[3]
+    linkzmq:zmq_msg_init_size[3]
-    linkzmq:zmq_msg_data[3]
+    linkzmq:zmq_msg_init_data[3]
-Uninitialise a message::
+Release a message::
    linkzmq:zmq_msg_close[3]
 Access message content::
@ -73,10 +83,21 @@ Message manipulation::
    linkzmq:zmq_msg_move[3]
-SOCKETS
+Sockets
-------
+~~~~~~~
-0MQ sockets are very similar to POSIX sockets. See following manual pages to
+Standard sockets present a _synchronous_ interface to either connection-mode
-understand them in depth.
+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.
 0MQ sockets being _asynchronous_ means that the timings of the physical
 connection setup and teardown, reconnect and effective delivery are organized
 by 0MQ itself, and that messages may be _queued_ in the event that a peer is
 unavailable to receive them.
 The following functions are provided to work with sockets:
 Creating a socket::
    linkzmq:zmq_socket[3]
@ -91,82 +112,108 @@ Establishing a message flow::
    linkzmq:zmq_bind[3]
    linkzmq:zmq_connect[3]
-Sending & receiving messages::
+Sending and receiving messages::
    linkzmq:zmq_send[3]
    linkzmq:zmq_flush[3]
    linkzmq:zmq_recv[3]
-MULTIPLEXING
+Input/output multiplexing
------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
-0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
+0MQ provides a mechanism for applications to multiplex input/output events over
-in an asynchronous manner.
+a set containing both 0MQ sockets and standard sockets. This mechanism mirrors
 the standard _poll()_ system call, and is described in detail in
 linkzmq:zmq_poll[3].
-Poll for I/O events::
+
-    linkzmq:zmq_poll[3]
+Transports
 ~~~~~~~~~~
 A 0MQ socket can use multiple different underlying transport mechanisms.
 Each transport mechanism is suited to a particular purpose and has its own
 advantages and drawbacks.
 The following transport mechanisms are provided:
 Unicast transport using TCP::
    linkzmq:zmq_tcp[7]
 Reliable multicast transport using PGM::
    linkzmq:zmq_pgm[7]
 Local inter-process communication transport::
    linkzmq:zmq_ipc[7]
 Local in-process (inter-thread) communication transport::
    linkzmq:zmq_inproc[7]
 Devices
 ~~~~~~~
 Apart from the 0MQ library the 0MQ distribution includes 'devices' which are
 building blocks intended to serve as intermediate nodes in complex messaging
 topologies.
 The following devices are provided:
 Forwarder device for request-response messaging::
    linkzmq:zmq_queue[1]
 Forwarder device for publish-subscribe messaging::
    linkzmq:zmq_forwarder[1]
 Streamer device for parallelized pipeline messaging::
    linkzmq:zmq_streamer[1]
 ERROR HANDLING
 --------------
-0MQ defines couple of non-POSIX error codes. Use following functions to handle
+The 0MQ library functions handle errors using the standard conventions found on
-them neatly.
+POSIX systems. Generally, this means that upon failure a 0MQ library function
 shall return either a NULL value (if returning a pointer) or a negative value
 (if returning an integer), and the actual error code shall be stored in the
 'errno' variable.
-Convert error code into human readable string::
+A _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
-    linkzmq:zmq_strerror[3]
+into error message strings. For further details refer to
 linkzmq:zmq_strerror[3].
-TRANSPORTS
+LANGUAGE BINDINGS
----------
+-----------------
-0MQ allows for using different underlying transport mechanisms (even multiple
+The 0MQ library provides interfaces suitable for calling from programs in any
-at once). Each transport mechanism has its own advantages and drawbacks. For
+language; this documentation documents those interfaces as they would be used
-detailed description of individual mechanisms check following manual pages:
+by C programmers. The intent is that programmers using 0MQ from other languages
-
+shall refer to this documentation alongside any documentation provided by the
-TCP/IP transport::
+vendor of their language binding.
    linkzmq:zmq_tcp[7]
 UDP reliable multicast transport::
    linkzmq:zmq_udp[7]
 PGM reliable multicast transport::
    linkzmq:zmq_pgm[7]
 Inter-process transport::
    linkzmq:zmq_ipc[7]
 In-process (inter-thread) transport::
    linkzmq:zmq_inproc[7]
-DEVICES
+C++ language binding
 ~~~~~~~~~~~~~~~~~~~~
 The 0MQ distribution includes a $$C++$$ language binding, which is documented
 separately in linkzmq:zmq_cpp[7].
 Other language bindings
 ~~~~~~~~~~~~~~~~~~~~~~~
 Other language bindings (Python, Ruby, Java and more) are provided by members
 of the 0MQ community and pointers can be found on the 0MQ website.
 AUTHORS
 -------
-Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-executables - devices - to serve as middle nodes in complex messaging
+Martin Lucina <mato@kotelna.sk>.
 topologies. For detailed description of individual devices check following
 manual pages:
 Forwarder device for PUB/SUB messaging::
    linkzmq:zmq_forwarder[1]
 Streamer device for UPSTREAM/DOWNSTREAM messaging::
    linkzmq:zmq_streamer[1]
 Forwarder device for REQ/REP messaging::
    linkzmq:zmq_queue[1]
-LANGUAGES
+RESOURCES
 ---------
-0MQ manual pages provide info on C API. To find out how the your
+Main web site: <http://www.zeromq.org/>
 favourite language API maps to C API and thus how to find relevant manual pages,
 see following articles:
-$$C++$$::
+Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
    linkzmq:zmq_cpp[7]
 Java::
    linkzmq:zmq_java[7]
-AUTHOR
+COPYING
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+Free use of this software is granted under the terms of the GNU Lesser General
 Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
 included with the 0MQ distribution.
--- a/doc/zmq_bind.txt
+++ b/doc/zmq_bind.txt
@ -4,53 +4,66 @@ zmq_bind(3)
 NAME
 ----
-zmq_bind - binds the socket to the specified address
+zmq_bind - assign a local address to a socket
 SYNOPSIS
 --------
-'int zmq_bind (void *s, const char *addr);'
+*int zmq_bind (void '*socket', const char '*address');*
 DESCRIPTION
 -----------
-The function binds socket 's' to a particular transport. Actual semantics of the
+The _zmq_bind()_ function shall assign a local address specified by the
-command depend on the underlying transport mechanism, however, in cases where
+'address' argument to the socket referenced by the 'socket' argument.
 peers connect in an asymmetric manner, 'zmq_bind' should be called first,
 'zmq_connect' afterwards. Actual formats of 'addr' parameter are defined by
 individual transports. For a list of supported transports have a look at
 linkzmq:zmq[7] manual page.
-Note that single socket can be bound (and connected) to
+The 'address' argument is a string consisting of two parts as follows:
-arbitrary number of peers using different transport mechanisms.
+'transport'://'endpoint'. The 'transport' part specifies the underlying
 transport protocol to use. The meaning of the 'endpoint' part is specific to
 the underlying transport protocol selected.
 The following transports are defined:
 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
 'pgm', 'udp':: 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()_.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_bind()_ function shall return zero if successful. Otherwise it shall
-sets 'errno' to the appropriate value.
+return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *EPROTONOSUPPORT*::
-unsupported protocol.
+The requested 'transport' protocol is not supported.
 *ENOCOMPATPROTO*::
-protocol is not compatible with the socket type.
+The requested 'transport' protocol is not compatible with the socket type.
 *EADDRINUSE*::
-the given address is already in use.
+The given 'address' is already in use.
 *EADDRNOTAVAIL*::
-a nonexistent interface was requested or the requested address was not local.
+A nonexistent interface was requested or the requested 'address' was not local.
 EXAMPLE
 -------
 .Binding a publisher socket to an in-process and a TCP transport
 ----
-void *s = zmq_socket (context, ZMQ_PUB);
+/* Create a ZMQ_PUB socket */
-assert (s);
+void *socket = zmq_socket (context, ZMQ_PUB);
-int rc = zmq_bind (s, "inproc://my_publisher");
+assert (socket);
 /* Bind it to a in-process transport with the endpoint 'my_publisher' */
 int rc = zmq_bind (socket, "inproc://my_publisher");
 assert (rc == 0);
-rc = zmq_bind (s, "tcp://eth0:5555");
+/* Bind it to a TCP transport on port 5555 of the 'eth0' interface */
 rc = zmq_bind (socket, "tcp://eth0:5555");
 assert (rc == 0);
 ----
@ -62,6 +75,7 @@ linkzmq:zmq_socket[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_close.txt
+++ b/doc/zmq_close.txt
@ -4,28 +4,29 @@ zmq_close(3)
 NAME
 ----
-zmq_close - destroys 0MQ socket
+zmq_close - close 0MQ socket
 SYNOPSIS
 --------
-'int zmq_close (void *s);'
+*int zmq_close (void '*socket');*
 DESCRIPTION
 -----------
-Destroys 0MQ socket (one created using
+The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
-'zmq_socket' function). All sockets have to be properly closed before the
+argument. All active connections on the socket shall be terminated and
-application terminates, otherwise memory leaks will occur. Note that any
+resources associated with the socket shall be released. Any outstanding
-outbound messages that haven't been psuhed to the network yet and any inbound
+messages sent with _zmq_send()_ but not yet physically sent to the network
-messages that haven't been received by the application yet will be dropped on
+shall be dropped. Likewise, any outstanding messages physically received from
-the socket shutdown.
+the network but not yet received by the application with _zmq_recv()_ shall
 also be dropped.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_close()_ function shall return zero if successful. Otherwise it shall
-sets 'errno' to the appropriate value.
+return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -33,20 +34,14 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 int rc = zmq_close (s);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_socket[3]
 linkzmq:zmq_term[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_connect.txt
+++ b/doc/zmq_connect.txt
@ -4,49 +4,66 @@ zmq_connect(3)
 NAME
 ----
-zmq_connect - connect the socket to the specified peer
+zmq_connect - connect a socket to a peer address
 SYNOPSIS
 --------
-'int zmq_connect (void *s, const char *addr);'
+*int zmq_connect (void '*socket', const char '*address');*
 DESCRIPTION
 -----------
-The function connect socket 's' to the peer identified by 'addr'.  Actual
+The _zmq_connect()_ function shall connect the socket referenced by the
-semantics of the  command depend on the underlying transport mechanism,
+'socket' argument to a peer address specified by the 'address' argument.
 however, in cases where peers connect in an asymmetric manner, 'zmq_bind'
 should be called first, 'zmq_connect' afterwards. Formats of the 'addr'
 parameter are defined by individual transports. For a list of supported
 transports have a look at linkzmq:zmq[7] manual page.
-Note that single socket can be connected (and bound) to
+The 'address' argument is a string consisting of two parts as follows:
-arbitrary number of peers using different transport mechanisms.
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
 transport protocol to use. The meaning of the 'endpoint' part is specific to
 the underlying transport protocol selected.
 The following transports are defined:
 'tcp':: unicast transport using TCP, see linkzmq:zmq_tcp[7]
 'pgm', 'udp':: 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()_.
 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
 physical connection was or can actually be established.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_connect()_ function shall return zero if successful. Otherwise it
-sets 'errno' to the appropriate value.
+shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *EPROTONOSUPPORT*::
-unsupported protocol.
+The requested 'transport' protocol is not supported.
 *ENOCOMPATPROTO*::
-protocol is not compatible with the socket type.
+The requested 'transport' protocol is not compatible with the socket type.
 EXAMPLE
 -------
 .Connecting a subscriber socket to an in-process and a TCP transport
 ----
-void *s = zmq_socket (context, ZMQ_SUB);
+/* Create a ZMQ_SUB socket */
-assert (s);
+void *socket = zmq_socket (context, ZMQ_SUB);
-int rc = zmq_connect (s, "inproc://my_publisher");
+assert (socket);
 /* Connect it to an in-process transport with the endpoint 'my_publisher' */
 int rc = zmq_connect (socket, "inproc://my_publisher");
 assert (rc == 0);
-rc = zmq_connect (s, "tcp://server001:5555");
+/* Connect it to the host server001, port 5555 using a TCP transport */
 rc = zmq_connect (socket, "tcp://server001:5555");
 assert (rc == 0);
 ----
@ -58,6 +75,7 @@ linkzmq:zmq_socket[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_epgm.txt
+++ b/doc/zmq_epgm.txt
@ -0,0 +1 @@
 zmq_pgm.txt
--- a/doc/zmq_flush.txt
+++ b/doc/zmq_flush.txt
@ -4,56 +4,52 @@ zmq_flush(3)
 NAME
 ----
-zmq_flush - flushes pre-sent messages to the socket
+zmq_flush - flush messages queued on a socket
 SYNOPSIS
 --------
-'int zmq_flush (void *s);'
+*int zmq_flush (void '*socket');*
 DESCRIPTION
 -----------
-Flushes all the pre-sent messages - i.e. those that have been sent with
+The _zmq_flush()_ function shall flush messages previously queued on the socket
-ZMQ_NOFLUSH flag - to the socket. This functionality improves performance in
+referenced by the 'socket' argument. The _zmq_flush()_ function only affects
-cases where several messages are sent during a single business operation.
+messages that have been queued on the _message queue_ associated with 'socket'
-It should not be used as a transaction - ACID properties are not guaranteed.
+using the 'ZMQ_NOFLUSH' flag to the _zmq_send()_ function. If no such messages
-Note that calling 'zmq_send' without ZMQ_NOFLUSH flag automatically flushes all
+exist, the function has no effect.
-previously pre-sent messages.
+
 CAUTION: A successful invocation of _zmq_flush()_ does not indicate that the
 flushed messages have been transmitted to the network, or even that such a
 transmission has been initiated by 0MQ. This function exists merely as a way
 for the application programmer to supply a hint to the 0MQ infrastructure that
 the queued messages *may* be flushed as a single batch.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_flush()_ function shall return zero if successful. Otherwise it shall
-sets 'errno' to the appropriate value.
+return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *ENOTSUP*::
-function isn't supported by particular socket type.
+The _zmq_flush()_ operation is not supported by this socket type.
 *EFSM*::
-function cannot be called at the moment, because socket is not in the
+The _zmq_flush()_ operation cannot be performed on this socket at the moment
-approprite state.
+due to the socket not being in the appropriate state.
 EXAMPLE
 -------
 ----
 rc = zmq_send (s, &msg1, ZMQ_NOFLUSH);
 assert (rc == 0);
 rc = zmq_send (s, &msg2, ZMQ_NOFLUSH);
 assert (rc == 0);
 rc = zmq_flush (s);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_send[3]
 linkzmq:zmq_socket[3]
 linkzmq:zmq[7]
 AUTHOR
 ------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_forwarder.txt
+++ b/doc/zmq_forwarder.txt
@ -4,29 +4,30 @@ zmq_forwarder(1)
 NAME
 ----
-zmq_forwarder - forwards the stream of PUB/SUB messages
+zmq_forwarder - forwarding device for publish-subscribe messaging
 SYNOPSIS
 --------
-*
+To be written.
 DESCRIPTION
 -----------
-*
+To be written.
 OPTIONS
 -------
-*
+To be written.
 SEE ALSO
 --------
-*
+linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_init.txt
+++ b/doc/zmq_init.txt
@ -4,58 +4,56 @@ zmq_init(3)
 NAME
 ----
-zmq_init - initialises 0MQ context
+zmq_init - initialise 0MQ context
 SYNOPSIS
 --------
-'void *zmq_init (int app_threads, int io_threads, int flags);'
+*void *zmq_init (int 'app_threads', int 'io_threads', int 'flags');*
 DESCRIPTION
 -----------
-Initialises 0MQ context. 'app_threads' specifies maximal number of application
+The _zmq_init()_ function initialises a 0MQ 'context' with 'app_threads'
-threads that can own open sockets at the same time. At least one application
+application threads and 'io_threads' I/O threads.
-thread should be defined. 'io_threads' specifies the size of thread pool to
+
-handle I/O operations. The value shouldn't be negative. Zero can be used in
+The 'app_threads' argument specifies the maximum number of application threads
-case only in-process messaging is going to be used, i.e. there will be no I/O
+that will be using 0MQ sockets in this 'context'. As a guide, set this to the
-traffic.
+number of threads in your application.
 The 'io_threads' argument specifies the size of the 0MQ thread pool to handle
 I/O operations. If your application is using 'inproc' messaging exclusively you
 may set this to zero, otherwise set it to at least one.
 The 'flags' argument is a combination of the flags defined below:
 *ZMQ_POLL*::
-    flag specifying that the sockets within this context should be pollable
+Specifies that sockets within this 'context' should support multiplexing using
-    (see linkzmq:zmq_poll[3]). Pollable sockets may add a little latency to the
+_zmq_poll()_. Enabling this functionality may add a small amount of latency to
-    message transfer when compared to non-pollable sockets.
+message transfers compared to leaving it disabled.
 RETURN VALUE
 ------------
-Function returns context handle is successful. Otherwise it returns NULL and
+The _zmq_init()_ function shall return an opaque handle to the initialised
-sets errno to one of the values below.
+'context' if successful. Otherwise it shall return NULL and set 'errno' to one
 of the values defined below.
 ERRORS
 ------
 *EINVAL*::
-    there's less than one application thread allocated, or number of I/O
+The number of 'app_threads' requested is less than one, or the number of
-    threads is negative.
+'io_threads' requested is negative.
 EXAMPLE
 -------
 ----
 void *ctx = zmq_init (1, 1, ZMQ_POLL);
 assert (ctx);
 ----
 SEE ALSO
 --------
 linkzmq:zmq[7]
 linkzmq:zmq_term[3]
 linkzmq:zmq_socket[3]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_inproc.txt
+++ b/doc/zmq_inproc.txt
@ -4,47 +4,86 @@ zmq_inproc(7)
 NAME
 ----
-zmq_inproc - 0MQ transport to pass messages between threads
+zmq_inproc - 0MQ local in-process (inter-thread) communication transport
 SYNOPSIS
 --------
-In-process transport is optimised for passing messages between threads in the
+The in-process transport passes messages via memory directly between threads
-same process.
+sharing a single 0MQ 'context'.
-Messages are passed directly from one application thread to
+NOTE: No I/O threads are involved in passing messages using the 'inproc'
-another application thread. There are no intervening I/O threads involved.
+transport. Therefore, if you are using a 0MQ 'context' for in-process messaging
-Thus, if you are using 0MQ for in-process messaging only, you can initialise
+only you can initialise the 'context' with zero I/O threads. See
-the library (linkzmq:zmq_init[3]) with zero I/O worker threads.
+linkzmq:zmq_init[3] for details.
-CONNECTION STRING
+ADDRESSING
-----------------
+----------
-Connection string for inproc transport is "inproc://" followed by an arbitrary
+A 0MQ address string consists of two parts as follows:
-string. There are no restrictions on the string format:
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
 transport protocol to use, and for the in-process transport shall be set to
 `inproc`.  The meaning of the 'endpoint' part for the in-process transport is
 defined below.
----
+
-    inproc://my_endpoint
+Assigning a local address to a socket
-    inproc://feeds/opra/cboe
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-    inproc://feeds.opra.nasdaq
+When assigning a local address to a 'socket' using _zmq_bind()_ with the
-    inproc://!&W#($)_@_123*((^^^
+'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
----
+identifying the 'name' to create. The 'name' must be unique within the 0MQ
 'context' associated with the 'socket' and may be up to 256 characters in
 length.  No other restrictions are placed on the format of the 'name'.
 Connecting a socket
 ~~~~~~~~~~~~~~~~~~~
 When connecting a 'socket' to a peer address using _zmq_connect()_ with the
 'inproc' transport, the 'endpoint' shall be interpreted as an arbitrary string
 identifying the 'name' to connect to.  The 'name' must have been previously
 created by assigning it to at least one 'socket' within the same 0MQ 'context'
 as the 'socket' being connected.
 WIRE FORMAT
 -----------
-In-process transport transfers messages via memory thus there is no need for a
+Not applicable.
-wire format specification.
+
 EXAMPLES
 --------
 .Assigning a local address to a socket
 ----
 /* Assign the in-process name "#1" */
 rc = zmq_bind(socket, "inproc://#1");
 assert (rc == 0);
 /* Assign the in-process name "my-endpoint" */
 rc = zmq_bind(socket, "inproc://my-endpoint");
 assert (rc == 0);
 ----
 .Connecting a socket
 ----
 /* Connect to the in-process name "#1" */
 rc = zmq_connect(socket, "inproc://#1");
 assert (rc == 0);
 /* Connect to the in-process name "my-endpoint" */
 rc = zmq_connect(socket, "inproc://my-endpoint");
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_bind[3]
 linkzmq:zmq_connect[3]
 linkzmq:zmq_ipc[7]
 linkzmq:zmq_tcp[7]
 linkzmq:zmq_udp[7]
 linkzmq:zmq_pgm[7]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_ipc.txt
+++ b/doc/zmq_ipc.txt
@ -4,41 +4,77 @@ zmq_ipc(7)
 NAME
 ----
-zmq_ipc - 0MQ transport to pass messages between processes
+zmq_ipc - 0MQ local inter-process communication transport
 SYNOPSIS
 --------
-Inter-process transport is optimised for passing messages between processes on
+The inter-process transport passes messages between local processes using a
-the same physical machine.
+system-dependent IPC mechanism.
 NOTE: The inter-process transport is currently only implemented on operating
 systems that provide UNIX domain sockets.
-CONNECTION STRING
+ADDRESSING
-----------------
+----------
-Connection string for inter-process transport is "ipc://" followed by a file
+A 0MQ address string consists of two parts as follows:
-name. The file will be used as placeholder for a message endpoint. (UNIX domain
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
-sockets associate a file with the listening socket in a similar way.)
+transport protocol to use, and for the inter-process transport shall be set to
 `ipc`.  The meaning of the 'endpoint' part for the inter-process transport is
 defined below.
----
+
-    ipc:///tmp/my_ipc_endpoint
+Assigning a local address to a socket
-    ipc:///tmp/prices.ipc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----
+When assigning a local address to a 'socket' using _zmq_bind()_ with the 'ipc'
 transport, the 'endpoint' shall be interpreted as an arbitrary string
 identifying the 'pathname' to create. The 'pathname' must be unique within the
 operating system namespace used by the 'ipc' implementation, and must fulfill
 any restrictions placed by the operating system on the format and length of a
 'pathname'.
 Connecting a socket
 ~~~~~~~~~~~~~~~~~~~
 When connecting a 'socket' to a peer address using _zmq_connect()_ with the
 'ipc' transport, the 'endpoint' shall be interpreted as an arbitrary string
 identifying the 'pathname' to connect to.  The 'pathname' must have been
 previously created within the operating system namespace by assigning it to a
 'socket' with _zmq_bind()_.
 WIRE FORMAT
 -----------
-IPC transport doesn't transfer messages across the network thus there is no need
+Not applicable.
 for a wire format specification.
 EXAMPLES
 --------
 .Assigning a local address to a socket
 ----
 /* Assign the pathname "/tmp/feeds/0" */
 rc = zmq_bind(socket, "ipc:///tmp/feeds/0");
 assert (rc == 0);
 ----
 .Connecting a socket
 ----
 /* Connect to the pathname "/tmp/feeds/0" */
 rc = zmq_connect(socket, "ipc:///tmp/feeds/0");
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_bind[3]
 linkzmq:zmq_connect[3]
 linkzmq:zmq_inproc[7]
 linkzmq:zmq_tcp[7]
 linkzmq:zmq_udp[7]
 linkzmq:zmq_pgm[7]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_java.txt
+++ b/doc/zmq_java.txt
@ -1,27 +0,0 @@
 zmq_java(7)
 ===========
 NAME
 ----
 zmq_java - interface between 0MQ and Java applications
 SYNOPSIS
 --------
 *
 DESCRIPTION
 -----------
 *
 SEE ALSO
 --------
 *
 AUTHOR
 ------
 Martin Sustrik <sustrik at 250bpm dot com>
--- a/doc/zmq_msg_close.txt
+++ b/doc/zmq_msg_close.txt
@ -4,25 +4,33 @@ zmq_msg_close(3)
 NAME
 ----
-zmq_msg_close - destroys 0MQ message
+zmq_msg_close - release 0MQ message
 SYNOPSIS
 --------
-'int zmq_msg_close (zmq_msg_t *msg);'
+*int zmq_msg_close (zmq_msg_t '*msg');*
 DESCRIPTION
 -----------
-Deallocates message 'msg' including any associated buffers (unless the buffer
+The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any
-is shared with another message). Not calling this function can result in
+resources associated with the message object referenced by 'msg' are no longer
-memory leaks.
+required and may be released. Actual release of resources associated with the
 message object shall be postponed by 0MQ until all users of the message or
 underlying data buffer have indicated it is no longer required.
 Applications should ensure that _zmq_msg_close()_ is called once a message is
 no longer required, otherwise memory leaks may occur.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and sets
+The _zmq_msg_close()_ function shall return zero if successful. Otherwise
-'errno' to the appropriate value.
+it shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -30,24 +38,17 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 zmq_msg_t msg;
 rc = zmq_msg_init_size (&msg, 1000000);
 assert (rc = 0);
 rc = zmq_msg_close (&msg);
 assert (rc = 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_data[3]
 linkzmq:zmq_msg_size[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_copy.txt
+++ b/doc/zmq_msg_copy.txt
@ -4,30 +4,35 @@ zmq_msg_copy(3)
 NAME
 ----
-zmq_msg_copy - copies content of a message to another message
+zmq_msg_copy - copy content of a message to another message
 SYNOPSIS
 --------
-'int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src);'
+*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*
 DESCRIPTION
 -----------
-Copy the 'src' message to 'dest'.  The original content of
+The _zmq_msg_copy()_ function shall copy the message object referenced by 'src'
-'dest' is orderly deallocated.
+to the message object referenced by 'dest'. The original content of 'dest', if
 any, shall be released.
-CAUTION: The implementation may choose not to physically copy the data, rather
+CAUTION: The implementation may choose not to physically copy the message
-to share the buffer between two messages. Thus avoid modifying message data
+content, rather to share the underlying buffer between 'src' and 'dest'. Avoid
-after the message was copied. Doing so can modify multiple message instances.
+modifying message content after a message has been copied with
-If what you need is actual hard copy, allocate new message using
+_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need
-'zmq_msg_size' and copy the data using 'memcpy'.
+is an actual hard copy, allocate a new message using _zmq_msg_init_size()_ and
 copy the message content using _memcpy()_.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it
-sets 'errno' to the appropriate value.
+shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -35,17 +40,6 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 zmq_msg_t dest;
 rc = zmq_msg_init (&dest);
 assert (rc == 0);
 rc = zmq_msg_copy (&dest, &src);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_move[3]
@ -53,8 +47,10 @@ linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_data.txt
+++ b/doc/zmq_msg_data.txt
@ -4,23 +4,27 @@ zmq_msg_data(3)
 NAME
 ----
-zmq_msg_data - retrieves pointer to the message content
+zmq_msg_data - retrieve pointer to message content
 SYNOPSIS
 --------
-'void *zmq_msg_data (zmq_msg_t *msg);'
+*void *zmq_msg_data (zmq_msg_t '*msg');*
 DESCRIPTION
 -----------
-Returns pointer to message data. Always use this function to access the data,
+The _zmq_msg_data()_ function shall return a pointer to the message content of
-never use 'zmq_msg_t' members directly.
+the message object referenced by 'msg'.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-Pointer to the message data.
+Upon successful completion, _zmq_msg_data()_ shall return a pointer to the
 message content.
 ERRORS
@ -28,23 +32,17 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 zmq_msg_t msg;
 rc = zmq_msg_init_size (&msg, 100);
 memset (zmq_msg_data (&msg), 0, 100);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_size[3]
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_init.txt
+++ b/doc/zmq_msg_init.txt
@ -4,24 +4,28 @@ zmq_msg_init(3)
 NAME
 ----
-zmq_msg_init - initialises empty 0MQ message
+zmq_msg_init - initialise empty 0MQ message
 SYNOPSIS
 --------
-'int zmq_msg_init (zmq_msg_t *msg);'
+*int zmq_msg_init (zmq_msg_t '*msg');*
 DESCRIPTION
 -----------
-Initialises 0MQ message zero bytes long. The function is most useful
+The _zmq_msg_init()_ function shall initialise the message object referenced by
-to initialise a 'zmq_msg_t' structure before receiving a message.
+'msg' to represent an empty message.  This function is most useful when called
 before receiving a message with _zmq_recv()_.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_msg_init()_ function shall return zero if successful. Otherwise it
-sets 'errno' to the appropriate value.
+shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -31,24 +35,27 @@ No errors are defined.
 EXAMPLE
 -------
 .Receiving a message from a socket
 ----
 zmq_msg_t msg;
 rc = zmq_msg_init (&msg);
 assert (rc == 0);
-rc = zmq_recv (s, &msg, 0);
+rc = zmq_recv (socket, &msg, 0);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq_msg_data[3]
 linkzmq:zmq_msg_size[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_init_data.txt
+++ b/doc/zmq_msg_init_data.txt
@ -4,30 +4,35 @@ zmq_msg_init_data(3)
 NAME
 ----
-zmq_msg_init_data - initialises 0MQ message from the given data
+zmq_msg_init_data - initialise 0MQ message from a supplied buffer
 SYNOPSIS
 --------
-'typedef void (zmq_free_fn) (void *data, void *hint);'
+*typedef void (zmq_free_fn) (void '*data', void '*hint');*
-'int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn, void *hint);'
+
 *int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*
 DESCRIPTION
 -----------
-Initialise a message from a supplied buffer. Message isn't copied,
+The _zmq_msg_init_data()_ function shall initialise the message object
-instead 0MQ infrastructure takes ownership of the buffer located at address
+referenced by 'msg' to represent the content referenced by the buffer located
-'data', 'size' bytes long.  Deallocation function ('ffn') will be called once
+at address 'data', 'size' bytes long. No copy of 'data' shall be performed and
-the data are not needed anymore. When using a static constant buffer, 'ffn' may
+0MQ shall take ownership of the supplied buffer.
-be NULL to prevent subsequent deallocation. If needed, additional 'hint' can be
+
-passed to the initialisation function. It's an opaque pointer that will be
+If provided, the deallocation function 'ffn' shall be called once the data
-later on passed to 'ffn' as a second argument.
+buffer is no longer required by 0MQ, with the 'data' and 'hint' arguments
 supplied to _zmq_msg_init_data()_.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
-sets 'errno' to the appropriate value.
+it shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -37,10 +42,14 @@ No errors are defined.
 EXAMPLE
 -------
 .Initialising a message from a supplied buffer
 ----
-void my_free (void *data, void *hint) {free (data);}
+void my_free (void *data, void *hint) 
 {
    free (data);
 }
-        ...
+    /*  ...  */
 void *data = malloc (6);
 assert (data);
@ -48,20 +57,20 @@ memcpy (data, "ABCDEF", 6);
 zmq_msg_t msg;
 rc = zmq_msg_init_data (&msg, data, 6, my_free, NULL);
 assert (rc == 0);
 rc = zmq_send (s, &msg, 0);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq_msg_data[3]
 linkzmq:zmq_msg_size[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_init_size.txt
+++ b/doc/zmq_msg_init_size.txt
@ -4,58 +4,51 @@ zmq_msg_init_size(3)
 NAME
 ----
-zmq_msg_init_size - initialises 0MQ message of a specified size
+zmq_msg_init_size - initialise 0MQ message of a specified size
 SYNOPSIS
 --------
-'int zmq_msg_init_size (zmq_msg_t *msg, size_t size);'
+*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
 DESCRIPTION
 -----------
-Initialises 0MQ message 'size' bytes long. The implementation chooses whether
+The _zmq_msg_init_size()_ function shall allocate any resources required to
-it is more efficient to store message content on the stack (small messages) or
+store a message 'size' bytes long and initialise the message object referenced
-on the heap (large messages).  Therefore, never access message data directly
+by 'msg' to represent the newly allocated message.
-via 'zmq_msg_t' members, rather use 'zmq_msg_data' and 'zmq_msg_size' functions
+
-to get message data and size.  Note that the message data are not nullified to
+The implementation shall choose whether to store message content on the stack
-avoid the associated performance impact. Thus you should expect your message to
+(small messages) or on the heap (large messages). For performance reasons
-contain bogus data after this call.
+_zmq_msg_init_size()_ shall not clear the message data.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise
-sets 'errno' to the appropriate value.
+it shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *ENOMEM*::
-memory to hold the message cannot be allocated.
+Insufficient storage space is available.
 EXAMPLE
 -------
 ----
 zmq_msg_t msg;
 rc = zmq_msg_init_size (&msg, 6);
 assert (rc == 0);
 memcpy (zmq_msg_data (&msg), "ABCDEF", 6);
 rc = zmq_send (s, &msg, 0);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq_msg_data[3]
 linkzmq:zmq_msg_size[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_move.txt
+++ b/doc/zmq_msg_move.txt
@ -4,25 +4,30 @@ zmq_msg_move(3)
 NAME
 ----
-zmq_msg_move - moves content of a message to another message
+zmq_msg_move - move content of a message to another message
 SYNOPSIS
 --------
-int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src);
+*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
 DESCRIPTION
 -----------
-Move the content of the message from 'src' to 'dest'.  The content isn't
+The _zmq_msg_move()_ function shall move the content of the message object
-copied, just moved.  'src' becomes an empty message after the call. Original
+referenced by 'src' to the message object referenced by 'dest'. No actual
-content of 'dest' message is deallocated.
+copying of message content is performed, 'dest' is simply updated to reference
 the new content. 'src' becomes an empty message after calling _zmq_msg_move()_.
 The original content of 'dest', if any, shall be released.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_msg_move()_ function shall return zero if successful. Otherwise it
-sets 'errno' to the appropriate value.
+shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -30,17 +35,6 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 zmq_msg_t dest;
 rc = zmq_msg_init (&dest);
 assert (rc == 0);
 rc = zmq_msg_move (&dest, &src);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_copy[3]
@ -48,8 +42,10 @@ linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_msg_size.txt
+++ b/doc/zmq_msg_size.txt
@ -4,23 +4,27 @@ zmq_msg_size(3)
 NAME
 ----
-zmq_msg_size - retrieves size of the message content
+zmq_msg_size - retrieve message content size in bytes
 SYNOPSIS
 --------
-'size_t zmq_msg_size (zmq_msg_t *msg);'
+*size_t zmq_msg_size (zmq_msg_t '*msg');*
 DESCRIPTION
 -----------
-Returns size of the message data. Always use this function to get the size,
+The _zmq_msg_size()_ function shall return the size in bytes of the content of
-never use 'zmq_msg_t' members directly.
+the message object referenced by 'msg'.
 CAUTION: Never access 'zmq_msg_t' members directly, instead always use the
 _zmq_msg_ family of functions.
 RETURN VALUE
 ------------
-Size of the message data (bytes).
+Upon successful completion, _zmq_msg_data()_ shall return the size of the
 message content in bytes.
 ERRORS
@ -28,26 +32,17 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 zmq_msg_t msg;
 rc = zmq_msg_init (&msg);
 assert (rc == 0);
 rc = zmq_recv (s, &msg, 0);
 assert (rc == 0);
 size_t msg_size = zmq_msg_size (&msg);
 ----
 SEE ALSO
 --------
 linkzmq:zmq_msg_data[3]
 linkzmq:zmq_msg_init[3]
 linkzmq:zmq_msg_init_size[3]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_close[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_pgm.txt
+++ b/doc/zmq_pgm.txt
@ -4,103 +4,125 @@ zmq_pgm(7)
 NAME
 ----
-zmq_pgm - 0MQ PGM reliable multicast transport
+zmq_pgm - 0MQ reliable multicast transport using PGM
 SYNOPSIS
 --------
-PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows
+PGM (Pragmatic General Multicast) is a protocol for reliable multicast
-you to deliver messages to multiple destinations sending the data over
+transport of data over IP networks.
 the network once only. It makes sense to use PGM transport if the data,
 delivered to each destination separately, would seriously load or even overload
 the network.
 PGM sending is rate limited rather than controlled by receivers. Thus, to get
 optimal performance you should set ZMQ_RATE and ZMQ_RECOVERY_IVL socket options
 prior to using PGM transport. Also note that passing multicast packets via
 loopback interface has negative effect on the overall performance of the system.
 Thus, if not needed, you should turn multicast loopback off using ZMQ_MCAST_LOOP
 socket option.
 PGM transport can be used only with ZMQ_PUB and ZMQ_SUB sockets.
 CAUTION: PGM protocol runs directly on top of IP protocol and thus needs to
 open raw IP socket. On some operating systems this operation requires special
 privileges. On Linux, for example, you would need to either run your application
 as root or set adequate capabilities for your executable. Alternative approach
 is to use UDP transport, linkzmq:zmq_udp[7], that stacks PGM on top of UDP and
 thus needs no special privileges.
-CONNECTION STRING
+DESCRIPTION
-----------------
+-----------
-Connection string for PGM transport is "pgm://" followed by an IP address
+0MQ implements two variants of PGM, the standard protocol where PGM datagrams
-of the NIC to use, semicolon, IP address of the multicast group, colon and
+are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
-port number. IP address of the NIC can be either its numeric representation
+transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside
-or the name of the NIC as reported by operating system. IP address of the
+UDP datagrams (the 'epgm' transport).
 multicast group should be specified in the numeric representation. For example:
----
+The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
-    pgm://eth0;224.0.0.1:5555
+'ZMQ_SUB' socket types.
    pgm://lo;230.0.0.0:6666
    pgm://192.168.0.111;224.0.0.1:5555
 ----
-NOTE: NIC names are not standardised by POSIX. They tend to be rather arbitrary
+Further, PGM sockets are rate limited by default and incur a performance
-and platform dependent. Say, "eth0" on Linux would correspond to "en0" on OSX
+penalty when used over a loopback interface. For details, refer to the
-and "e1000g" on Solaris. On Windows platform, as there are no short NIC names
+'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in
-available, you have to use numeric IP addresses instead.
+linkzmq:zmq_setsockopt[3].
 CAUTION: The 'pgm' transport implementation requires access to raw IP sockets.
 Additional privileges may be required on some operating systems for this
 operation. Applications not requiring direct interoperability with other PGM
 implementations are encouraged to use the 'epgm' transport instead which does
 not require any special privileges.
 ADDRESSING
 ----------
 A 0MQ address string consists of two parts as follows:
 'transport'`://`'endpoint'. The 'transport' part specifies the underlying
 transport protocol to use. For the standard PGM protocol, 'transport' shall be
 set to `pgm`. For the "Encapsulated PGM" protocol 'transport' shall be set to
 `epgm`. The meaning of the 'endpoint' part for both the 'pgm' and 'epgm'
 transport is defined below.
 Connecting a socket
 ~~~~~~~~~~~~~~~~~~~
 When connecting a socket to a peer address using _zmq_connect()_ with the 'pgm'
 or 'epgm' transport, the 'endpoint' shall be interpreted as an 'interface'
 followed by a semicolon, followed by a 'multicast address', followed by a colon
 and a port number.
 An 'interface' may be specified by either of the following:
 * The interface name as defined by the operating system.
 * The primary IPv4 address assigned to the interface, in it's numeric
  representation.
 NOTE: Interface names are not standardised in any way and should be assumed to
 be arbitrary and platform dependent. On Win32 platforms no short interface
 names exist, thus only the primary IPv4 address may be used to specify an
 'interface'.
 A 'multicast address' is specified by an IPv4 multicast address in it's numeric
 representation.
 WIRE FORMAT
 -----------
-Consecutive PGM packets are interpreted as a single continuous stream of data.
+Consecutive PGM datagrams are interpreted by 0MQ as a single continous stream
-The data is then split into messages using the wire format described in
+of data where 0MQ messages are not necessarily aligned with PGM datagram
-linkzmq:zmq_tcp[7]. Thus, messages are not aligned with packet boundaries and
+boundaries and a single 0MQ message may span several PGM datagrams. This stream
-each message can start at an arbitrary position within the packet and span
+of data consists of 0MQ messages encapsulated in 'frames' as described in
-several packets.
+linkzmq:zmq_tcp[7].
-Given this wire format, it would be impossible for late joining consumers to
+In order for late joining consumers to be able to identify message boundaries,
-identify message boundaries. To solve this problem, each PGM packet payload
+each PGM datagram payload starts with a 16-bit unsigned integer in network byte
-starts with 16-bit unsigned integer in network byte order which specifies the
+order specifying either the offset of the first message 'frame' in the datagram
-offset of the first message in the packet. If there's no beginning of a message
+or containing the value 0xFFFF if the datagram contains solely an intermediate
-in the packet (it's a packet transferring inner part of a larger message)
+part of a larger message.
 the value of the initial integer is 0xFFFF.
-Each packet thus looks like this:
+A single PGM datagram as used by 0MQ can thus be defined by the following ABNF
 grammar:
 ....
 datagram               = message / intermediate
 message                = (frame-offset *data 1*frame)    <1>
 intermediate           = (escape 1*data)
 frame-offset           = 2OCTET
 escape                 = %xFF %xFF
 data                   = 1*OCTET
 ....
 <1> 'frame' as defined in linkzmq:zmq_tcp[7].
 EXAMPLE
 -------
 .Connecting a socket
 ----
-+-----------+------------+------------------+--------
+/* Connecting to the multicast address 239.192.1.1, port 5555, */
-| IP header | PGM header | offset (16 bits) | data .....
+/* 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);
-Following example shows how messages are arranged in subsequent packets:
+/* Connecting to the multicast address 239.192.1.1, port 5555, */
-
+/* using the network interface with the address 192.168.1.1 */
----
+/* and the standard PGM protocol */
-+---------------+--------+-----------+-----------------------------+
+rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
-| PGM/IPheaders | 0x0000 |   message 1   |   message 2 (part 1)    |
+assert (rc == 0);
 +---------------+--------+-----------+-----------------------------+
 +---------------+--------+-----------------------------------------+
 | PGM/IPheaders | 0xFFFF |           message 2 (part 2)            |
 +---------------+--------+-----------------------------------------+
 +---------------+--------+--------------------------+-----------+
 | PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
 +---------------+--------+--------------------------+-----------+
 ----
 SEE ALSO
 --------
-linkzmq:zmq_udp[7]
+linkzmq:zmq_connect[3]
 linkzmq:zmq_setsockopt[3]
 linkzmq:zmq_tcp[7]
 linkzmq:zmq_ipc[7]
 linkzmq:zmq_inproc[7]
-linkzmq:zmq_setsockopt[3]
+linkzmq:zmq[7]
-
+AUTHORS
-AUTHOR
+-------
------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Sustrik <sustrik at 250bpm dot com>
+Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_poll.txt
+++ b/doc/zmq_poll.txt
@ -4,83 +4,127 @@ zmq_poll(3)
 NAME
 ----
-zmq_poll - polls for events on a set of 0MQ and POSIX sockets
+zmq_poll - input/output multiplexing
 SYNOPSIS
 --------
-'int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);'
+
 *int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
 DESCRIPTION
 -----------
-Waits for the events specified by 'items' parameter. Number of items in the
+The _zmq_poll()_ function provides a mechanism for applications to multiplex
-array is determined by 'nitems' argument. Each item in the array looks like
+input/output events in a level-triggered fashion over a set of sockets. Each
-this:
+member of the array pointed to by the 'items' argument is a *zmq_pollitem_t*
 structure. The 'nitems' argument specifies the number of items in the 'items'
 array. The *zmq_pollitem_t* structure is defined as follows:
----
+["literal", subs="quotes"]
 typedef struct
 {
-    void *socket;
+    void '*socket';
-    int fd;
+    int 'fd';
-    short events;
+    short 'events';
-    short revents;
+    short 'revents';
 } zmq_pollitem_t;
 ----
-0MQ socket to poll on is specified by 'socket'.  In case you want to poll on
+For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
-standard POSIX socket, set 'socket' to NULL and fill the POSIX file descriptor
+socket referenced by 'socket' *or* the standard socket specified by the file
-to 'fd'.  'events' specifies which events to wait for. It's a combination of
+descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
-the values below.  Once the call exits, 'revents' will be filled with events
+'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
-that have actually occured on the socket. The field will contain a combination
+'socket' shall take precedence and the value of 'fd' shall be ignored.
-of the values below.
+
 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
 bit corresponding to the event condition in the 'revents' member.
 If none of the requested events have occured on any *zmq_pollitem_t* item,
 _zmq_poll()_ shall wait up to '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 wait
 indefinitely for requested events to occur.
 The 'events' and 'revents' members of *zmq_pollitem_t* are bitmasks constructed
 by OR'ing a combination of the following event flags:
 *ZMQ_POLLIN*::
-poll for incoming messages.
+For 0MQ sockets, at least one message may be dequeued from the underlying
-*ZMQ_POLLOUT*::
+_message queue_ associated with 'socket' without blocking. For standard sockets
-wait while message can be set socket. Poll will return if a message of at least
+this is equivalent to the 'POLLIN' flag of the _poll()_ system call and
-one byte can be written to the socket. However, there is no guarantee that
+generally means that at least one byte of data may be read from 'fd' without
-arbitrarily large message can be sent.
+blocking.
-'timeout' argument specifies an upper limit on the time for which 'zmq_poll'
+*ZMQ_POLLOUT*::
-will block, in microseconds. Specifying a negative value in timeout means an
+For 0MQ sockets, at least one message may be queued on the underlying
-infinite timeout.
+_message queue_ associated with 'socket' without blocking. For standard sockets
 this is equivalent to the 'POLLOUT' flag of the _poll()_ system call and
 generally means that at least one byte of data may be written to 'fd'
 without blocking.
 *ZMQ_POLLERR*::
 For standard sockets, this flag is passed through _zmq_poll()_ to the
 underlying _poll()_ system call and generally means that some sort of error
 condition is present on the socket specified by 'fd'. For 0MQ sockets this flag
 has no effect if set in 'events', and shall never be returned in 'revents' by
 _zmq_poll()_.
 NOTE: The _zmq_poll()_ function may be implemented or emulated using operating
 system interfaces other than _poll()_, and as such may be subject to the limits
 of those interfaces in ways not defined in this documentation.
 RETURN VALUE
 ------------
-Function returns number of items signaled, 0 in the case of timeout or -1
+Upon successful completion, the _zmq_poll()_ function shall return the number
-in the case of error.
+of *zmq_pollitem_t* structures with events signaled in 'revents' or 0 if the
 'timeout' period has expired and no events have been signaled. Upon failure,
 _zmq_poll()_ shall return -1 and set 'errno' to one of the values defined
 below.
 ERRORS
 ------
 *EFAULT*::
-there's a 0MQ socket in the pollset belonging to a different application thread.
+At least one of the members of the 'items' array refers to a 'socket' belonging
 to a different application thread.
 *ENOTSUP*::
-0MQ context was initialised without ZMQ_POLL flag. I/O multiplexing is disabled.
+At least one of the members of the 'items' array refers to a 'socket' whose
 associated 0MQ 'context' was initialised without the 'ZMQ_POLL' flag.
 EXAMPLE
 -------
 .Polling idenfinitely for input events on both a 0MQ socket and a standard socket.
 ----
 zmq_pollitem_t items [2];
-items [0].socket = s;
+/* First item refers to 0MQ socket 'socket' */
-items [0].events = ZMQ_POLLIN;
+items[0].socket = socket;
-items [1].socket = NULL;
+items[0].events = ZMQ_POLLIN;
-items [1].fd = my_fd;
+/* Second item refers to standard socket 'fd' */
-items [1].events = ZMQ_POLLIN;
+items[1].socket = NULL;
-
+items[1].fd = fd;
-int rc = zmq_poll (items, 2);
+items[1].events = ZMQ_POLLIN;
-assert (rc != -1);
+/* Poll for events indefinitely */
 int rc = zmq_poll (items, 2, -1);
 assert (rc >= 0);
 /* Returned events will be stored in items[].revents */
 ----
 SEE ALSO
 --------
 linkzmq:zmq_socket[3]
 linkzmq:zmq_send[3]
 linkzmq:zmq_recv[3]
 linkzmq:zmq[7]
 Your operating system documentation for the _poll()_ system call.
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_queue.txt
+++ b/doc/zmq_queue.txt
@ -4,29 +4,30 @@ zmq_queue(1)
 NAME
 ----
-zmq_queue - forwards REQ/REP messages
+zmq_queue - forwarding device for request-reply messaging
 SYNOPSIS
 --------
-*
+To be written.
 DESCRIPTION
 -----------
-*
+To be written.
 OPTIONS
 -------
-*
+To be written.
 SEE ALSO
 --------
-*
+linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_recv.txt
+++ b/doc/zmq_recv.txt
@ -4,51 +4,60 @@ zmq_recv(3)
 NAME
 ----
-zmq_recv - retrieves a message from the socket
+zmq_recv - receive a message from a socket
 SYNOPSIS
 --------
-'int zmq_recv (void *s, zmq_msg_t *msg, int flags);'
+*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');*
 DESCRIPTION
 -----------
-Receive a message from the socket 's', store it in
+The _zmq_recv()_ function shall dequeue a message from the underlying _message
-'msg' .  Any content previously in 'msg' will be properly deallocated.  'flags'
+queue_ associated with the socket referenced by the 'socket' argument and store
-argument can be combination of the flags described below.
+it in the message referenced by the 'msg' argument. Any content previously
 stored in 'msg' shall be properly deallocated. If there are no messages
 available to be dequeued from the underlying _message queue_ associated with
 'socket' the _zmq_recv()_ function shall block until the request can be
 satisfied. The 'flags' argument is a combination of the flags defined below:
 *ZMQ_NOBLOCK*::
-The flag specifies that the operation should be performed in
+Specifies that the operation should be performed in non-blocking mode. If there
-non-blocking mode. I.e. if it cannot be processed immediately,
+are no messages available to be dequeued from the underlying _message queue_
-error should be returned with 'errno' set to EAGAIN.
+associated with 'socket', the _zmq_recv()_ function shall fail with 'errno' set
 to EAGAIN.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_recv()_ function shall return zero if successful. Otherwise it shall
-sets 'errno' to the appropriate value.
+return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *EAGAIN*::
-it's a non-blocking receive and there's no message available at the moment.
+Non-blocking mode was requested and no messages are available at the moment.
 *ENOTSUP*::
-function isn't supported by particular socket type.
+The _zmq_recv()_ operation is not supported by this socket type.
 *EFSM*::
-function cannot be called at the moment, because socket is not in the
+The _zmq_recv()_ operation cannot be performed on this socket at the moment due
-appropriate state. This error may occur with sockets that switch between
+to the socket not being in the appropriate state.  This error may occur with
-several states (e.g. ZMQ_REQ).
+socket types that switch between several states, such as ZMQ_REP.  See the
 _messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
 EXAMPLE
 -------
 .Receiving a message from a socket
 ----
 /* Create an empty 0MQ message */
 zmq_msg_t msg;
 int rc = zmq_msg_init (&msg);
 assert (rc == 0);
-rc = zmq_recv (s, &msg, 0);
+/* Block until a message is available to be dequeued from socket */
 rc = zmq_recv (socket, &msg, 0);
 assert (rc == 0);
 ----
@ -56,11 +65,11 @@ assert (rc == 0);
 SEE ALSO
 --------
 linkzmq:zmq_send[3]
-linkzmq:zmq_msg_init[3]
+linkzmq:zmq_socket[7]
-linkzmq:zmq_msg_data[3]
+linkzmq:zmq[7]
 linkzmq:zmq_msg_size[3]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_send.txt
+++ b/doc/zmq_send.txt
@ -4,59 +4,69 @@ zmq_send(3)
 NAME
 ----
-zmq_send - sends a message
+zmq_send - send a message on a socket
 SYNOPSIS
 --------
-'int zmq_send (void *s, zmq_msg_t *msg, int flags);'
+*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');*
 DESCRIPTION
 -----------
-Send the message 'msg' to the socket 's'.  'flags' argument can be combination
+The _zmq_send()_ function shall queue the message referenced by the 'msg'
-the flags described below.
+argument to be sent to the socket referenced by the 'socket' argument.  The
 'flags' argument is a combination of the flags defined below:
 *ZMQ_NOBLOCK*::
-The flag specifies that the operation should be performed in non-blocking mode.
+Specifies that the operation should be performed in non-blocking mode. If the
-I.e. if it cannot be processed immediately, error should be returned with
+message cannot be queued on the underlying _message queue_ associated with
-'errno' set to EAGAIN.
+'socket', the _zmq_send()_ function shall fail with 'errno' set to EAGAIN.
 *ZMQ_NOFLUSH*::
-The flag specifies that 'zmq_send' should not flush the message downstream
+Specifies that the _zmq_send()_ function should not flush the underlying
-immediately. Instead, it should batch ZMQ_NOFLUSH messages and send them
+_message queue_ associated with 'socket' to the network automatically.
-downstream only once 'zmq_flush' is invoked. This is an optimisation for cases
+Instead, it should batch all messages queued with the 'ZMQ_NOFLUSH' flag and
-where several messages are sent in a single business transaction. However, the
+only flush the _message queue_ once either a message without the 'ZMQ_NOFLUSH'
-effect is measurable only in extremely high-perf scenarios (million messages a
+flag is queued, or manually on invocation of the _zmq_flush()_ function.
-second or so).  If that's not your case, use standard flushing send instead.
+
 NOTE: A successful invocation of _zmq_send()_ does not indicate that the
 message has been transmitted to the network, only that it has been queued on
 the _message queue_ associated with the socket and 0MQ has assumed
 responsibility for the message.
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_send()_ function shall return zero if successful. Otherwise it shall
-sets 'errno' to the appropriate value.
+return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *EAGAIN*::
-it's a non-blocking send and message cannot be sent at the moment.
+Non-blocking mode was requested and the message cannot be queued at the moment.
 *ENOTSUP*::
-function isn't supported by particular socket type.
+The _zmq_send()_ operation is not supported by this socket type.
 *EFSM*::
-function cannot be called at the moment, because socket is not in the
+The _zmq_send()_ operation cannot be performed on this socket at the moment due
-appropriate state. This error may occur with sockets that switch between
+to the socket not being in the appropriate state.  This error may occur with
-several states (e.g. ZMQ_REQ).
+socket types that switch between several states, such as ZMQ_REP.  See the
 _messaging patterns_ section of linkzmq:zmq_socket[3] for more information.
 EXAMPLE
 -------
 .Filling in a message and sending it to a socket
 ----
 /* Create a new message, allocating 6 bytes for message content */
 zmq_msg_t msg;
 int rc = zmq_msg_init_size (&msg, 6);
 assert (rc == 0);
 /* Fill in message content with 'AAAAAA' */
 memset (zmq_msg_data (&msg), 'A', 6);
-rc = zmq_send (s, &msg, 0);
+/* Send the message to the socket */
 rc = zmq_send (socket, &msg, 0);
 assert (rc == 0);
 ----
@ -65,13 +75,11 @@ SEE ALSO
 --------
 linkzmq:zmq_flush[3]
 linkzmq:zmq_recv[3]
-linkzmq:zmq_msg_init[3]
+linkzmq:zmq_socket[7]
-linkzmq:zmq_msg_init_size[3]
+linkzmq:zmq[7]
 linkzmq:zmq_msg_init_data[3]
 linkzmq:zmq_msg_data[3]
 linkzmq:zmq_msg_size[3]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_setsockopt.txt
+++ b/doc/zmq_setsockopt.txt
@ -5,144 +5,255 @@ zmq_setsockopt(3)
 NAME
 ----
-zmq_setsockopt - sets a specified option on a 0MQ socket
+zmq_setsockopt - set 0MQ socket options
 SYNOPSIS
 --------
-'int zmq_setsockopt (void *s, int option, const void *optval, size_t optvallen);'
+*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
 DESCRIPTION
 -----------
-Sets an option on the socket. 'option' argument specifies the option from the
+The _zmq_setsockopt()_ function shall set the option specified by the
-list below. 'optval' is a pointer to the value to set, 'optvallen' is the size
+'option_name' argument to the value pointed to by the 'option_value' argument
-of the value in bytes.
+for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
 argument is the size of the option value in bytes.
-*ZMQ_HWM*::
+The following options are defined:
 High watermark for the message pipes associated with the socket. The water
 mark cannot be exceeded. If the messages don't fit into the pipe emergency
 mechanisms of the particular socket type are used (block, drop etc.) If HWM
 is set to zero, there are no limits for the content of the pipe.
 +
 Type: int64_t  Unit: messages  Default: 0
 *ZMQ_LWM*::
 Low watermark makes sense only if high watermark is defined (i.e. is non-zero).
 When the emergency state is reached when messages overflow the pipe, the
 emergency lasts at most till the size of the pipe decreases to low watermark.
 Normal state is resumed at that point.
 +
 Type: int64_t  Unit: messages  Default: 0
-*ZMQ_SWAP*::
+ZMQ_HWM: Set high water mark
-Swap allows the pipe to exceed high watermark. However, the data are written
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-to the disk rather than held in the memory. Until high watermark is
+The 'ZMQ_HWM' option shall set the high water mark for the _message queue_
-exceeded there is no disk activity involved though. The value of the option
+associated with the socket.  The high water mark is a hard limit on the number
-defines maximal size of the swap file.
+of outstanding messages in the queue; if this limit has been reached the socket
-+
+shall enter an "emergency" state and depending on the socket type, 0MQ shall
-Type: int64_t  Unit: bytes  Default: 0
+take appropriate action such as blocking or dropping new messages entering the
 queue.
-*ZMQ_AFFINITY*::
+The default 'ZMQ_HWM' value of zero means "no limit".
 Affinity defines which threads in the thread pool will be used to handle
 newly created sockets. This way you can dedicate some of the threads (CPUs)
 to a specific work. Value of 0 means no affinity. Work is distributed
 fairly among the threads in the thread pool. For non-zero values, the lowest
 bit corresponds to the thread 1, second lowest bit to the thread 2 etc.
 Thus, value of 3 means that from now on newly created sockets will handle
 I/O activity exclusively using threads no. 1 and 2.
 +
 Type: int64_t  Unit: N/A (bitmap)  Default: 0
-*ZMQ_IDENTITY*::
+Option value type:: int64_t
-Identity of the socket. Identity is important when restarting applications.
+Option value unit:: messages
-If the socket has no identity, each run of the application is completely
+Default value:: 0
-separated from other runs. However, with identity application reconnects to
+Applicable socket types:: all
 existing infrastructure left by the previous run. Thus it may receive
 messages that were sent in the meantime, it shares pipe limits with the
 previous run etc. Identity should be at least one byte and at most 255 bytes
 long. Identities starting with binary zero are reserver for use by 0MQ
 infrastructure.
 +
 Type: BLOB  Unit: N/A  Default: NULL
 *ZMQ_SUBSCRIBE*::
 Applicable only to ZMQ_SUB socket type. It establishes new message filter.
 When ZMQ_SUB socket is created all the incoming messages are filtered out.
 This option allows you to subscribe for all messages (""), or messages 
 beginning with specific prefix (e.g. "animals.mammals.dogs."). Multiple
 filters can be attached to a single 'sub' socket. In that case message passes
 if it matches at least one of the filters.
 +
 Type: BLOB  Unit: N/A  Default: N/A
-*ZMQ_UNSUBSCRIBE*::
+ZMQ_LWM: Set low water mark
-Applicable only to ZMQ_SUB socket type. Removes existing message filter.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The filter specified must match the string passed to ZMQ_SUBSCRIBE options
+The 'ZMQ_LWM' option shall set the low water mark for the _message queue_
-exactly. If there were several instances of the same filter created,
+associated with the socket.  This option only makes sense when used in
-this options removes only one of them, leaving the rest in place
+conjunction with the 'ZMQ_HWM' option. A socket which has reached it's high
-and functional.
+water mark remains in the "emergency" state until the number of outstanding
-+
+messages in it's associated message queue falls below the low water mark, at
-Type: BLOB  Unit: N/A  Default: N/A
+which point normal message processing is resumed.
-*ZMQ_RATE*::
+Option value type:: int64_t
-This option applies only to sending side of multicast transports (pgm & udp).
+Option value unit:: messages
-It specifies maximal outgoing data rate that an individual sender socket
+Default value:: 0
-can send.
+Applicable socket types:: all
 +
 Type: uint64_t  Unit: kilobits/second  Default: 100
 *ZMQ_RECOVERY_IVL*::
 This option applies only to multicast transports (pgm & udp). It specifies
 how long can the receiver socket survive when the sender is inaccessible.
 Keep in mind that large recovery intervals at high data rates result in
 very large recovery buffers, meaning that you can easily overload your box
 by setting say 1 minute recovery interval at 1Gb/s rate (requires
 7GB in-memory buffer).
 +
 Type: uint64_t Unit: seconds Default: 10 
-*ZMQ_MCAST_LOOP*::
+ZMQ_SWAP: Set disk offload size
-This option applies only to multicast transports (pgm & udp). Value of 1
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-means that the mutlicast packets can be received on the box they were sent
+The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the _message
-from. Setting the value to 0 disables the loopback functionality which
+queue_ associated with the socket. A socket which has 'ZMQ_SWAP' set to a
-can have negative impact on the performance. If possible, disable
+non-zero value may exceed it's high water mark; in this case outstanding
-the loopback in production environments.
+messages shall be offloaded to storage on disk rather than held in memory.
 +
 Type: uint64_t Unit: N/A (boolean value) Default: 1
-*ZMQ_SNDBUF*::
+The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
 Sets the underlying kernel transmit buffer size to the specified size. See
 'SO_SNDBUF' POSIX socket option. Value of zero means leaving the OS default
 unchanged.
 +
 Type: uint64_t Unit: bytes Default: 0
-*ZMQ_RCVBUF*::
+Option value type:: int64_t
-Sets the underlying kernel receive buffer size to the specified size. See
+Option value unit:: bytes
-'SO_RCVBUF' POSIX socket option. Value of zero means leaving the OS default
+Default value:: 0
-unchanged.
+Applicable socket types:: all
-+
+
-Type: uint64_t Unit: bytes Default: 0
+
 ZMQ_AFFINITY: Set I/O thread affinity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 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.
 See also linkzmq:zmq_init[3] for details on allocating the number of I/O
 threads for a specific _context_.
 Option value type:: int64_t
 Option value unit:: N/A (bitmap)
 Default value:: 0
 Applicable socket types:: N/A
 ZMQ_IDENTITY: Set socket identity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_IDENTITY' option shall set the identity of the socket. Socket identity
 determines if existing 0MQ infastructure (_message queues_, _forwarding
 devices_) shall be identified with a specific application and persist across
 multiple runs of the application.
 If the socket has no identity, each run of an application is completely
 separate from other runs. However, with identity set the socket shall re-use
 any existing 0MQ infrastructure configured by the previous run(s). Thus the
 application may receive messages that were sent in the meantime, _message
 queue_ limits shall be shared with previous run(s) and so on.
 Identity should be at least one byte and at most 255 bytes long. Identities
 starting with binary zero are reserved for use by 0MQ infrastructure.
 Option value type:: BLOB
 Option value unit:: N/A
 Default value:: NULL
 Applicable socket types:: all
 ZMQ_SUBSCRIBE: Establish message filter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_SUBSCRIBE' option shall establish a new message filter on a 'ZMQ_SUB'
 socket. Newly created 'ZMQ_SUB' sockets shall filter out all incoming messages,
 therefore you should call this option to establish an initial message filter.
 An empty 'option_value' of length zero shall subscribe to all incoming
 messages. A non-empty 'option_value' shall subscribe to all messages beginning
 with the specified prefix. Mutiple filters may be attached to a single
 'ZMQ_SUB' socket, in which case a message shall be accepted if it matches at
 least one filter.
 Option value type:: BLOB
 Option value unit:: N/A
 Default value:: N/A
 Applicable socket types:: ZMQ_SUB
 ZMQ_UNSUBSCRIBE: Remove message filter
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_UNSUBSCRIBE' option shall remove an existing message filter on a
 'ZMQ_SUB' socket. The filter specified must match an existing filter previously
 established with the 'ZMQ_SUBSCRIBE' option. If the socket has several
 instances of the same filter attached the 'ZMQ_UNSUBSCRIBE' option shall remove
 only one instance, leaving the rest in place and functional.
 Option value type:: BLOB
 Option value unit:: N/A
 Default value:: N/A
 Applicable socket types:: ZMQ_SUB
 ZMQ_RATE: Set multicast data rate
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_RATE' option shall set the maximum send or receive data rate for
 multicast transports such as linkzmq:zmq_pgm[7] and linkzmq:zmq_udp[7] using
 the specified 'socket'.
 Option value type:: uint64_t
 Option value unit:: kilobits per second
 Default value:: 100
 Applicable socket types:: all, when using multicast transports
 ZMQ_RECOVERY_IVL: Set multicast recovery interval
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_RECOVERY_IVL' option shall set the recovery interval for multicast
 transports such as linkzmq:zmq_pgm[7] and linkzmq:zmq_udp[7] using the
 specified 'socket'. The recovery interval determines the maximum time in
 seconds that a receiver can be absent from a multicast group before
 unrecoverable data loss will occur.
 CAUTION: Excersize care when setting large recovery intervals as the data
 needed for recovery will be held in memory. For example, a 1 minute recovery
 interval at a data rate of 1Gbps requires a 7GB in-memory buffer.
 Option value type:: uint64_t
 Option value unit:: seconds
 Default value:: 10
 Applicable socket types:: all, when using multicast transports
 ZMQ_MCAST_LOOP: Control multicast loopback
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_MCAST_LOOP' option shall control whether data sent via multicast
 transports 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 performance. Where possible, disable
 'ZMQ_MCAST_LOOP' in production environments.
 Option value type:: uint64_t
 Option value unit:: boolean
 Default value:: 1
 Applicable socket types:: all, when using multicast transports
 ZMQ_SNDBUF: Set kernel transmit buffer size
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_SNDBUF' option shall set the underlying kernel transmit buffer size
 for the socket to the specified size in bytes.  A value of zero means leave the
 OS default unchanged. For details please refer to your operating system
 documentation for the 'SO_SNDBUF' socket option.
 Option value type:: uint64_t
 Option value unit:: bytes
 Default value:: 0
 Applicable socket types:: all
 ZMQ_RCVBUF: Set kernel receive buffer size
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_RCVBUF' option shall set the underlying kernel receive buffer size for
 the socket to the specified size in bytes.  A value of zero means leave the OS
 default unchanged. For details refer to your operating system documentation for
 the 'SO_RCVBUF' socket option.
 Option value type:: uint64_t
 Option value unit:: bytes
 Default value:: 0
 Applicable socket types:: all
 RETURN VALUE
 ------------
-In case of success the function returns zero. Otherwise it returns -1 and
+The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it
-sets 'errno' to the appropriate value.
+shall return -1 and set 'errno' to one of the values defined below.
 ERRORS
 ------
 *EINVAL*::
-unknown option, a value with incorrect length or invalid value.
+The requested option _option_name_ is unknown, or the requested _option_len_ or
 _option_value_ is invalid.
 EXAMPLE
 -------
 .Subscribing to messages on a 'ZMQ_SUB' socket
 ----
-int rc = zmq_setsockopt (s, ZMQ_SUBSCRIBE, "", 0);
+/* Subscribe to all messages */
 rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "", 0);
 assert (rc == 0);
 /* Subscribe to messages prefixed with "ANIMALS.CATS" */
 rc = zmq_setsockopt (socket, ZMQ_SUBSCRIBE, "ANIMALS.CATS", 12);
 ----
 .Setting I/O thread affinity
 ----
 /* Incoming connections on TCP port 5555 shall be handled by I/O thread 1 */
 rc = zmq_setsockopt (socket, ZMQ_AFFINITY, 1, sizeof (int64_t));
 assert (rc);
 rc = zmq_bind (socket, "tcp://lo:5555");
 assert (rc);
 /* Incoming connections on TCP port 5556 shall be handled by I/O thread 2 */
 rc = zmq_setsockopt (socket, ZMQ_AFFINITY, 2, sizeof (int64_t));
 assert (rc);
 rc = zmq_bind (socket, "tcp://lo:5555");
 assert (rc);
 ----
@ -152,6 +263,7 @@ linkzmq:zmq_socket[3]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@ -4,110 +4,117 @@ zmq_socket(3)
 NAME
 ----
-zmq_socket - creates 0MQ socket
+zmq_socket - create 0MQ socket
 SYNOPSIS
 --------
-'void *zmq_socket (void *context, int type);'
+*void *zmq_socket (void '*context', int 'type');*
 DESCRIPTION
 -----------
-Open a socket within the specified 'context'. To create a context, use
+The 'zmq_socket()' function shall create a 0MQ socket within the specified
-'zmq_init' function. 'type' argument can be one of the values defined below.
+'context' and return an opaque handle to the newly created socket. The 'type'
-Note that each socket is owned by exactly one thread (the one that it was
+argument specifies the _messaging pattern_, which determines the semantics of
-created from) and should not be used from any other thread.
+communication over the socket.
-*ZMQ_P2P*::
+The following _messaging patterns_ are defined:
 Socket to communicate with a single peer. Allows for only a single connect
 or a single bind. There's no message routing or message filtering involved.
 +
 Compatible peer sockets: ZMQ_P2P.
 *ZMQ_PUB*::
 Socket to distribute data. Recv function is not implemented for this socket
 type. Messages are distributed in fanout fashion to all the peers.
 +
 Compatible peer sockets: ZMQ_SUB.
-*ZMQ_SUB*::
+Peer to peer pattern
-Socket to subscribe for data. Send function is not implemented for this socket
+~~~~~~~~~~~~~~~~~~~~
-type. Initially, socket is subscribed for no messages. Use ZMQ_SUBSCRIBE option
+The simplest messaging pattern, used for communicating between two peers.
 to specify which messages to subscribe for.
 +
 Compatible peer sockets: ZMQ_PUB.
-*ZMQ_REQ*::
+Socket type:: 'ZMQ_P2P'
-Socket to send requests and receive replies. Requests are load-balanced among
+Compatible peer sockets:: 'ZMQ_P2P'
 all the peers. This socket type allows only an alternated sequence of send's
 and recv's.
 +
 Compatible peer sockets: ZMQ_REP, ZMQ_XREP.
-*ZMQ_REP*::
+A socket of type 'ZMQ_P2P' can only be connected to a single peer at any one
-Socket to receive requests and send replies. This socket type allows only an
+time.  No message routing or filtering is performed on messages sent over a
-alternated sequence of recv's and send's. Each send is routed to the peer that
+'ZMQ_P2P' socket.
 issued the last received request.
 +
 Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ.
 *ZMQ_XREQ*::
 Special socket type to be used in request/reply middleboxes such as
 linkzmq:zmq_queue[7]. Requests forwarded using this socket type should be
 tagged by a proper prefix identifying the original requester. Replies received
 by this socket are tagged with a proper prefix that can be use to route the
 reply back to the original requester.
 +
 Compatible peer sockets: ZMQ_REP, ZMQ_XREP.
-*ZMQ_XREP*::
+Publish-subscribe pattern
-Special socket type to be used in request/reply middleboxes such as
+~~~~~~~~~~~~~~~~~~~~~~~~~
-linkzmq:zmq_queue[7]. Requests received using this socket are already properly
+The publish-subscribe pattern is used for one-to-many distribution of data from
-tagged with prefix identifying the original requester. When sending a reply via
+a single _publisher_ to multiple _subscribers_ in a fanout fashion.
 XREP socket the message should be tagged with a prefix from a corresponding
 request.
 +
 Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ.
-*ZMQ_UPSTREAM*::
+Socket type:: 'ZMQ_PUB'
-Socket to receive messages from up the stream. Messages are fair-queued from
+Compatible peer sockets:: 'ZMQ_SUB'
 among all the connected peers. Send function is not implemented for this socket
 type.
 +
 Compatible peer sockets: ZMQ_DOWNSTREAM.
-*ZMQ_DOWNSTREAM*::
+A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
-Socket to send messages down stream. Messages are load-balanced among all the
+Messages sent are distributed in a fanout fashion to all connected peers.
-connected peers. Recv function is not implemented for this socket type.
+The _zmq_recv()_ function is not implemented for this socket type.
-+
+
-Compatible peer sockets: ZMQ_UPSTREAM.
+Socket type:: 'ZMQ_SUB'
 Compatible peer sockets:: 'ZMQ_PUB'
 A socket of type 'ZMQ_SUB' is used by a _subscriber_ to subscribe to data
 distributed by a _publisher_. Initially a 'ZMQ_SUB' socket is not subscribed to
 any messages, use the 'ZMQ_SUBSCRIBE' option of _zmq_setsockopt()_ to specify
 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'
 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.
 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'
 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_DOWNSTREAM'
 Compatible peer sockets:: 'ZMQ_UPSTREAM'
 A socket of type 'ZMQ_DOWNSTREAM' is used by a _component_ of a pipeline to
 send messages to downstream stages of the pipeline. The _zmq_recv()_ function
 is not implemented for this socket type.
 RETURN VALUE
 ------------
-Function returns socket handle is successful. Otherwise it returns NULL and
+The _zmq_socket()_ function shall return an opaque handle to the newly created
-sets errno to one of the values below.
+socket if successful. Otherwise, it shall return NULL and set 'errno' to one of
 the values defined below.
 ERRORS
 ------
 *EINVAL*::
-    invalid socket type.
+The requested socket 'type' is invalid.
 *EMTHREAD*::
-    the number of application threads allowed to own 0MQ sockets was exceeded.
+The number of application threads using sockets within this 'context' has been
-    See 'app_threads' parameter to 'zmq_init' function.
+exceeded. See the 'app_threads' parameter of the _zmq_init()_ function.
 EXAMPLE
 -------
 ----
 void *s = zmq_socket (context, ZMQ_PUB);
 assert (s);
 int rc = zmq_bind (s, "tcp://192.168.0.1:5555");
 assert (rc == 0);
 ----
 SEE ALSO
@ -121,6 +128,7 @@ linkzmq:zmq_flush[3]
 linkzmq:zmq_recv[3]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_streamer.txt
+++ b/doc/zmq_streamer.txt
@ -4,29 +4,30 @@ zmq_streamer(1)
 NAME
 ----
-zmq_streamer - forwards the stream of UPSTREAM/DOWNSTREAM messages
+zmq_streamer - streamer device for parallelized pipeline messaging
 SYNOPSIS
 --------
-*
+To be written.
 DESCRIPTION
 -----------
-*
+To be written.
 OPTIONS
 -------
-*
+To be written.
 SEE ALSO
 --------
-*
+linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_strerror.txt
+++ b/doc/zmq_strerror.txt
@ -4,24 +4,27 @@ zmq_strerror(3)
 NAME
 ----
-zmq_strerror - returns string describing the error number
+zmq_strerror - get 0MQ error message string
 SYNOPSIS
 --------
-'const char *zmq_strerror (int errnum);'
+*const char *zmq_strerror (int 'errnum');*
 DESCRIPTION
 -----------
-As 0MQ defines few additional (non-POSIX) error codes, standard
+The _zmq_strerror()_ function shall return a pointer to an error message string
-'strerror' isn't capable of translating those errors into human readable
+corresponding to the error number specified by the 'errnum' argument. As 0MQ
-strings. Instead, 'zmq_strerror' should be used.
+defines additional error numbers over and above those defined by the operating
 system, applications should use _zmq_strerror()_ in preference to the standard
 _strerror()_ function.
 RETURN VALUE
 ------------
-Returns string describing the error number.
+The _zmq_strerror()_ function shall return a pointer to an error message
 string.
 ERRORS
@ -31,10 +34,11 @@ No errors are defined.
 EXAMPLE
 -------
 .Displaying an error message when a 0MQ context cannot be initialised
 ----
 void *ctx = zmq_init (1, 1, 0);
 if (!ctx) {
-    printf ("error occured during zmq_init: %s\\n", zmq_strerror (errno));
+    printf ("Error occurred during zmq_init(): %s\n", zmq_strerror (errno));
    abort ();
 }
 ----
@ -45,6 +49,7 @@ SEE ALSO
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_tcp.txt
+++ b/doc/zmq_tcp.txt
@ -4,55 +4,72 @@ zmq_tcp(7)
 NAME
 ----
-zmq_tcp - 0MQ unicast TCP transport over the network
+zmq_tcp - 0MQ unicast transport using TCP
 SYNOPSIS
 --------
-TCP is an ubiquitous unicast transport. When connecting distributed
+TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
-applications, you will mostly use TCP transport.
+applications over a network with 0MQ, using the TCP transport will likely be
 your first choice.
-CONNECTION STRING
+ADDRESSING
-----------------
+----------
-Connection string for TCP transport is "tcp://" followed by an IP address,
+A 0MQ address string consists of two parts as follows:
-colon and port number. IP address can be either its numeric representation,
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
-a NIC name or a hostname (resolved by DNS):
+transport protocol to use, and for the TCP transport shall be set to `tcp`.
 The meaning of the 'endpoint' part for the TCP transport is defined below.
 ----
    tcp://192.168.0.111:5555
    tcp://myserver001:80
    tcp://lo:32768
 ----
-Note that NIC names are not standardised by POSIX. They tend to be rather
+Assigning a local address to a socket
-arbitrary and platform dependent. Say, "eth0" on Linux would correspond to "en0"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-on OSX and "e1000g" on Solaris. On Windows platform, as there are no short NIC
+When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
-names available, you have to use numeric IP addresses instead.
+transport, the 'endpoint' shall be interpreted as an 'interface' followed by a
 colon and the TCP port number to use.
 An 'interface' may be specified by either of the following:
 * The interface name as defined by the operating system.
 * The primary IPv4 address assigned to the interface, in it's numeric representation.
 * The wildcard `*`, meaning that the interface address is unspecified.
 NOTE: Interface names are not standardised in any way and should be assumed to
 be arbitrary and platform dependent. On Win32 platforms no short interface
 names exist, thus only the primary IPv4 address may be used to specify an
 'interface'.
 Connecting a socket
 ~~~~~~~~~~~~~~~~~~~
 When connecting a socket to a peer address using _zmq_connect()_ with the 'tcp'
 transport, the 'endpoint' shall be interpreted as a 'peer address' followed by
 a colon and the TCP port number to use.
 A 'peer address' may be specified by either of the following:
 * The DNS name of the peer.
 * The IPv4 address of the peer, in it's numeric representation.
 WIRE FORMAT
 -----------
-A message consists of a message length followed by message data.
+0MQ messages are transmitted over TCP in frames consisting of the message
-Size of message data MUST correspond to the message length.
+length followed by the message data.  The size of the message data MUST
 correspond to the message length. A single 'frame' can be defined by the
 following ABNF grammar:
-For messages of 0 to 254 octets, the length is represented by single octet. 
+....
-
+    frame           = (message-length message-data)
-For messages of 255 or more octets the length is represented by a single octet
+    message-length  = OCTET / (escape 8OCTET)
 %xFF followed by a 64-bit unsigned integer length in network byte order.
 The protocol can be defined by this BNF grammar:
 ----
    frame   = length data
    length  = OCTET | escape 8*OCTET
    escape          = %xFF
-    data    = *OCTET
+    message-data    = *OCTET
----
+....
 Binary layout of a message (up to 254 bytes long):
----
+For messages of 0 to 254 octets in length, the message length is represented by
 a single octet:
 ....
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@ -60,11 +77,13 @@ Binary layout of a message (up to 254 bytes long):
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Message body ...
 +-+-+-+-+-+-+- ...
----
+....
-Binary layout of a larger message:
+For messages of 255 or more octets in length, the message length is represented
 by a single octet with the value `255` followed by the message length
 represented as a 64-bit unsigned integer in network byte order:
----
+....
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@ -76,18 +95,46 @@ Binary layout of a larger message:
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |  Message body ...
 +-+-+-+-+-+-+-+ ...
 ....
 EXAMPLES
 --------
 .Assigning a local address to a socket
 ----
 /* TCP port 5555 on the local loopback 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 */
 rc = zmq_bind(socket, "tcp://eth0:5555");
 assert (rc == 0);
 /* TCP port 5555 with an unspecified interface */
 rc = zmq_bind(socket, "tcp://*:5555");
 assert (rc == 0);
 ----
 .Connecting a socket
 ----
 /* Connecting using an IP address */
 rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
 assert (rc == 0);
 /* Connecting using a DNS name */
 rc = zmq_connect(socket, "tcp://server1:5555");
 assert (rc == 0);
 ----
 SEE ALSO
 --------
-linkzmq:zmq_udp[7]
+linkzmq:zmq_bind[3]
 linkzmq:zmq_connect[3]
 linkzmq:zmq_pgm[7]
 linkzmq:zmq_ipc[7]
 linkzmq:zmq_inproc[7]
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
-
+Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_term.txt
+++ b/doc/zmq_term.txt
@ -4,25 +4,27 @@ zmq_term(3)
 NAME
 ----
-zmq_term - terminates 0MQ context
+zmq_term - terminate 0MQ context
 SYNOPSIS
 --------
-'int zmq_term (void *context);'
+*int zmq_term (void '*context');*
 DESCRIPTION
 -----------
-Destroys 0MQ context. However, if there are still any sockets open within
+The _zmq_term()_ function terminates the 0MQ context 'context'.
-the context, 'zmq_term' succeeds but shutdown of the context is delayed till
+
-the last socket is closed.
+If there are still sockets open within 'context' at the time _zmq_term()_ is
 called the call will succeed but the actual shutdown of 'context' will be
 delayed until the last socket within it is closed.
 RETURN VALUE
 ------------
-Function returns zero is successful. Otherwise it returns -1 and sets errno to
+The _zmq_term()_ function shall return zero if successful. Otherwise it shall
-one of the values below.
+return -1 and set 'errno' to one of the values defined below.
 ERRORS
@ -30,20 +32,13 @@ ERRORS
 No errors are defined.
 EXAMPLE
 -------
 ----
 int rc = zmq_term (context);
 assert (rc == 0);
 ----
 SEE ALSO
 --------
 linkzmq:zmq[7]
 linkzmq:zmq_init[3]
 linkzmq:zmq_close[3]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.
--- a/doc/zmq_udp.txt
+++ b/doc/zmq_udp.txt
@ -1,56 +0,0 @@
 zmq_udp(7)
 ==========
 NAME
 ----
 zmq_udp - 0MQ reliable multicast transport using UDP
 SYNOPSIS
 --------
 UDP transport is exactly the same as PGM transport except that PGM packets
 are encapsulated in UDP packets. Rationale for this transport is that user-space
 implementation of PGM requires right to create raw sockets (PGM is located
 directly on top of IP layer in the networking stack), which is often not
 available. UDP encapsulation solves this problem, however, it adds some overhead
 related to creating and transferring UDP packet headers.
 CONNECTION STRING
 -----------------
 Connection string for UDP transport is "udp://" followed by an IP address
 of the NIC to use, semicolon, IP address of the multicast group, colon and
 port number. IP address of the NIC can be either its numeric representation
 or the name of the NIC as reported by operating system. IP address of the
 multicast group should be specified in the numeric representation. For example:
 ----
    udp://eth0;224.0.0.1:5555
    udp://lo;230.0.0.0:6666
    udp://192.168.0.111;224.0.0.1:5555
 ----
 NOTE: NIC names are not standardised by POSIX. They tend to be rather
 arbitrary and platform dependent. Say, "eth0" on Linux would correspond to "en0"
 on OSX and "e1000g" on Solaris. On Windows platform, as there are no short NIC
 names available, you have to use numeric IP addresses instead.
 WIRE FORMAT
 -----------
 Same as with PGM transport except for UDP packet headers.
 SEE ALSO
 --------
 linkzmq:zmq_pgm[7]
 linkzmq:zmq_tcp[7]
 linkzmq:zmq_ipc[7]
 linkzmq:zmq_inproc[7]
 AUTHOR
 ------
 Martin Sustrik <sustrik at 250bpm dot com>
--- a/doc/zmq_version.txt
+++ b/doc/zmq_version.txt
@ -4,19 +4,24 @@ zmq_version(3)
 NAME
 ----
-zmq_version - reports 0MQ version
+zmq_version - report 0MQ library version
 SYNOPSIS
 --------
-'void zmq_version (int *major, int *minor, int *patch);'
+*void zmq_version (int '*major', int '*minor', int '*patch');*
 DESCRIPTION
 -----------
-Returns current version of 0MQ. The functionality is useful for applications
+The _zmq_version()_ function shall fill in the integer variables pointed to by
-linking with 0MQ dynamically to make sure the right version of 0MQ is installed
+the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel
-on the system.
+components of the 0MQ library version.
 This functionality is intended for applications or language bindings
 dynamically linking to the 0MQ library that wish to determine the actual
 version of the 0MQ library they are using.
 RETURN VALUE
 ------------
@ -30,6 +35,7 @@ No errors are defined.
 EXAMPLE
 -------
 .Printing out the version of the 0MQ library
 ----
 int major, minor, patch;
 zmq_version (&major, &minor, &patch);
@ -41,6 +47,7 @@ SEE ALSO
 --------
 linkzmq:zmq[7]
-AUTHOR
+AUTHORS
------
+-------
-Martin Sustrik <sustrik at 250bpm dot com>
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
 Martin Lucina <mato@kotelna.sk>.