Documentation rewrite

34 files changed, 1297 insertions, 973 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1158243..5a4e3ea 100644
--- 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 \
-    zmq_cpp.7 zmq_java.7
+MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \
+    zmq_cpp.7
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
 
 MAN_TXT = $(MAN1:%.1=%.txt)
diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
index 18273f2..15633a3 100644
--- 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[]
diff --git a/doc/zmq.txt b/doc/zmq.txt
index bc2571b..21722a7 100644
--- 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
-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.
+*#include <zmq.h>*
 
-0MQ is designed to be extremely fast. Expected end-to-end latencies for
-messages passed over a LAN are in tens of microseconds. Expected
-throughputs are to be measured in millions of messages per second.
+*cc* ['flags'] 'files' *-lzmq* ['libraries']
 
-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.
+DESCRIPTION
+-----------
+The 0MQ lightweight messaging kernel is a library which extends the standard
+socket interfaces with features traditionally provided by specialised
+_messaging middleware_ products. 0MQ sockets provide an abstraction of
+asynchronous  _message queues_, multiple _messaging patterns_, message
+filtering (_subscriptions_), seamless access to multiple _transport protocols_
+and more.
 
-0MQ is accessible from a large set of programming languages.
+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.
 
-0MQ is fully open sourced LGPL-licensed software.
 
-
-CONTEXT
--------
-Each 0MQ socket lives within a specific context. Creating and destroying
-context is a counterpart of library initialisation/deinitialisation as used
-elsewhere. Ability to create multiple contexts saves the day when an application
-happens to link (indirectly and involuntarily) with several instances of 0MQ.
+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
---------
-Message is a discrete unit of data passed between applications or components
-of the same application. 0MQ message has no internal structure, it is an opaque
-BLOB. When writing data to or reading data from the message, you are free to
-use any of the many serialisation libraries available. Alternatively, you can
-use your own serialisation code. The latter option is especially useful when
-migrating legacy applications to 0MQ - there's no need to break existing
-message formats.
+Thread safety
+^^^^^^^^^^^^^
+A 0MQ 'context' is thread safe and may be shared among as many application
+threads as the application has requested using the _app_threads_ parameter to
+_zmq_init()_, without any additional locking required on the part of the
+caller.  Each 0MQ socket belonging to a particular 'context' may only be used
+by *the thread that created it* using _zmq_socket()_.
+
+
+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_data[3]
+    linkzmq:zmq_msg_init_size[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
--------
-0MQ sockets are very similar to POSIX sockets. See following manual pages to
-understand them in depth.
+Sockets
+~~~~~~~
+Standard sockets present a _synchronous_ interface to either connection-mode
+reliable byte streams (SOCK_STREAM), or connection-less unreliable datagrams
+(SOCK_DGRAM). In comparison, 0MQ sockets present an abstraction of a
+asynchronous _message queue_, with the exact queueing semantics depending on
+the socket type (_messaging pattern_) in use. See linkzmq:zmq_socket[3] for the
+_messaging patterns_ provided.
+
+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
-------------
-0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
-in an asynchronous manner.
-
-Poll for I/O events::
-    linkzmq:zmq_poll[3]
-
+Input/output multiplexing
+^^^^^^^^^^^^^^^^^^^^^^^^^
+0MQ provides a mechanism for applications to multiplex input/output events over
+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].
 
-ERROR HANDLING
---------------
-0MQ defines couple of non-POSIX error codes. Use following functions to handle
-them neatly.
-
-Convert error code into human readable string::
-    linkzmq:zmq_strerror[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.
 
-TRANSPORTS
-----------
-0MQ allows for using different underlying transport mechanisms (even multiple
-at once). Each transport mechanism has its own advantages and drawbacks. For
-detailed description of individual mechanisms check following manual pages:
+The following transport mechanisms are provided:
 
-TCP/IP transport::
+Unicast transport using TCP::
     linkzmq:zmq_tcp[7]
 
-UDP reliable multicast transport::
-    linkzmq:zmq_udp[7]
-
-PGM reliable multicast transport::
+Reliable multicast transport using PGM::
     linkzmq:zmq_pgm[7]
 
-Inter-process transport::
+Local inter-process communication transport::
     linkzmq:zmq_ipc[7]
 
-In-process (inter-thread) transport::
+Local in-process (inter-thread) communication transport::
     linkzmq:zmq_inproc[7]
 
 
-DEVICES
--------
-Aside of the messaging library (a.k.a. messaging kernel) 0MQ provides pre-built
-executables - devices - to serve as middle nodes in complex messaging
-topologies. For detailed description of individual devices check following
-manual pages:
+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.
 
-Forwarder device for PUB/SUB messaging::
+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 UPSTREAM/DOWNSTREAM messaging::
+Streamer device for parallelized pipeline messaging::
     linkzmq:zmq_streamer[1]
 
-Forwarder device for REQ/REP messaging::
-    linkzmq:zmq_queue[1]
 
+ERROR HANDLING
+--------------
+The 0MQ library functions handle errors using the standard conventions found on
+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.
+
+A _zmq_strerror()_ function is provided to translate 0MQ-specific error codes
+into error message strings. For further details refer to
+linkzmq:zmq_strerror[3].
+
+
+LANGUAGE BINDINGS
+-----------------
+The 0MQ library provides interfaces suitable for calling from programs in any
+language; this documentation documents those interfaces as they would be used
+by C programmers. The intent is that programmers using 0MQ from other languages
+shall refer to this documentation alongside any documentation provided by the
+vendor of their language binding.
 
-LANGUAGES
----------
-0MQ manual pages provide info on C API. To find out how the your
-favourite language API maps to C API and thus how to find relevant manual pages,
-see following articles:
 
-$$C++$$::
-    linkzmq:zmq_cpp[7]
+C++ language binding
+~~~~~~~~~~~~~~~~~~~~
+The 0MQ distribution includes a $$C++$$ language binding, which is documented
+separately in linkzmq:zmq_cpp[7].
 
-Java::
-    linkzmq:zmq_java[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.
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
+
+
+RESOURCES
+---------
+Main web site: <http://www.zeromq.org/>
+
+Report bugs to the 0MQ development mailing list: <zeromq-dev@lists.zeromq.org>
+
+
+COPYING
+-------
+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.
diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt
index 391238a..6d83752 100644
--- 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
-command depend on the underlying transport mechanism, however, in cases where
-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.
+The _zmq_bind()_ function shall assign a local address specified by the
+'address' argument to the socket referenced by the 'socket' argument.
 
-Note that single socket can be bound (and connected) to
-arbitrary number of peers using different transport mechanisms.
+The 'address' argument is a string consisting of two parts as follows:
+'transport'://'endpoint'. The 'transport' part specifies the underlying
+transport protocol to use. The meaning of the 'endpoint' part is specific to
+the 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
-sets 'errno' to the appropriate value.
+The _zmq_bind()_ function shall return zero if successful. Otherwise it 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.
 *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);
-assert (s);
-int rc = zmq_bind (s, "inproc://my_publisher");
+/* Create a ZMQ_PUB socket */
+void *socket = zmq_socket (context, ZMQ_PUB);
+assert (socket);
+/* Bind it to a in-process transport with the endpoint 'my_publisher' */
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt
index 9964d36..55b10f4 100644
--- 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
-'zmq_socket' function). All sockets have to be properly closed before the
-application terminates, otherwise memory leaks will occur. Note that any
-outbound messages that haven't been psuhed to the network yet and any inbound
-messages that haven't been received by the application yet will be dropped on
-the socket shutdown.
+The _zmq_close()_ function shall destroy the socket referenced by the 'socket'
+argument. All active connections on the socket shall be terminated and
+resources associated with the socket shall be released. Any outstanding
+messages sent with _zmq_send()_ but not yet physically sent to the network
+shall be dropped. Likewise, any outstanding messages physically received from
+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
-sets 'errno' to the appropriate value.
+The _zmq_close()_ function shall return zero if successful. Otherwise it shall
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt
index 375873d..e0dd9ca 100644
--- 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
-semantics of the  command depend on the underlying transport mechanism,
-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.
+The _zmq_connect()_ function shall connect the socket referenced by the
+'socket' argument to a peer address specified by the 'address' argument.
 
-Note that single socket can be connected (and bound) to
-arbitrary number of peers using different transport mechanisms.
+The 'address' argument is a string consisting of two parts as follows:
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
+transport protocol to use. The meaning of the 'endpoint' part is specific to
+the 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
-sets 'errno' to the appropriate value.
+The _zmq_connect()_ function shall return zero if successful. Otherwise it
+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);
-assert (s);
-int rc = zmq_connect (s, "inproc://my_publisher");
+/* Create a ZMQ_SUB socket */
+void *socket = zmq_socket (context, ZMQ_SUB);
+assert (socket);
+/* Connect it to an in-process transport with the endpoint 'my_publisher' */
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_epgm.txt b/doc/zmq_epgm.txt
new file mode 120000
index 0000000..4d58b1b
--- /dev/null
+++ b/doc/zmq_epgm.txt
@@ -0,0 +1 @@
+zmq_pgm.txt
\ No newline at end of file
diff --git a/doc/zmq_flush.txt b/doc/zmq_flush.txt
index 3a2cd37..77f4452 100644
--- 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
-ZMQ_NOFLUSH flag - to the socket. This functionality improves performance in
-cases where several messages are sent during a single business operation.
-It should not be used as a transaction - ACID properties are not guaranteed.
-Note that calling 'zmq_send' without ZMQ_NOFLUSH flag automatically flushes all
-previously pre-sent messages.
+The _zmq_flush()_ function shall flush messages previously queued on the socket
+referenced by the 'socket' argument. The _zmq_flush()_ function only affects
+messages that have been queued on the _message queue_ associated with 'socket'
+using the 'ZMQ_NOFLUSH' flag to the _zmq_send()_ function. If no such messages
+exist, the function has no effect.
+
+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
-sets 'errno' to the appropriate value.
+The _zmq_flush()_ function shall return zero if successful. Otherwise it shall
+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
-approprite 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);
-----
+The _zmq_flush()_ operation cannot be performed on this socket at the moment
+due to the socket not being in the appropriate state.
 
 
 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>.
diff --git a/doc/zmq_forwarder.txt b/doc/zmq_forwarder.txt
index 17d938b..b3325f2 100644
--- 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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_init.txt b/doc/zmq_init.txt
index 6683d27..9df3e67 100644
--- 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
-threads that can own open sockets at the same time. At least one application
-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
-case only in-process messaging is going to be used, i.e. there will be no I/O
-traffic.
+The _zmq_init()_ function initialises a 0MQ 'context' with 'app_threads'
+application threads and 'io_threads' I/O threads.
+
+The 'app_threads' argument specifies the maximum number of application threads
+that will be using 0MQ sockets in this 'context'. As a guide, set this to the
+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
-    (see linkzmq:zmq_poll[3]). Pollable sockets may add a little latency to the
-    message transfer when compared to non-pollable sockets.
+Specifies that sockets within this 'context' should support multiplexing using
+_zmq_poll()_. Enabling this functionality may add a small amount of latency to
+message transfers compared to leaving it disabled.
 
 
 RETURN VALUE
 ------------
-Function returns context handle is successful. Otherwise it returns NULL and
-sets errno to one of the values below.
+The _zmq_init()_ function shall return an opaque handle to the initialised
+'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
-    threads is negative.
-
-
-EXAMPLE
--------
-----
-void *ctx = zmq_init (1, 1, ZMQ_POLL);
-assert (ctx);
-----
+The number of 'app_threads' requested is less than one, or the number of
+'io_threads' requested is negative.
 
 
 SEE ALSO
 --------
+linkzmq:zmq[7]
 linkzmq:zmq_term[3]
-linkzmq:zmq_socket[3]
 
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_inproc.txt b/doc/zmq_inproc.txt
index 7861201..2805f71 100644
--- 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
-same process.
+The in-process transport passes messages via memory directly between threads
+sharing a single 0MQ 'context'.
 
-Messages are passed directly from one application thread to
-another application thread. There are no intervening I/O threads involved.
-Thus, if you are using 0MQ for in-process messaging only, you can initialise
-the library (linkzmq:zmq_init[3]) with zero I/O worker threads.
+NOTE: No I/O threads are involved in passing messages using the 'inproc'
+transport. Therefore, if you are using a 0MQ 'context' for in-process messaging
+only you can initialise the 'context' with zero I/O threads. See
+linkzmq:zmq_init[3] for details.
 
 
-CONNECTION STRING
------------------
-Connection string for inproc transport is "inproc://" followed by an arbitrary
-string. There are no restrictions on the string format:
+ADDRESSING
+----------
+A 0MQ address string consists of two parts as follows:
+'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.
+
+
+Assigning a local address to a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When assigning a local address to a 'socket' using _zmq_bind()_ with the
+'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'.
 
-----
-    inproc://my_endpoint
-    inproc://feeds/opra/cboe
-    inproc://feeds.opra.nasdaq
-    inproc://!&W#($)_@_123*((^^^
-----
+
+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
-wire format specification.
+Not applicable.
+
+
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_ipc.txt b/doc/zmq_ipc.txt
index acce97a..81f6747 100644
--- 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 same physical machine.
+The inter-process transport passes messages between local processes using a
+system-dependent IPC mechanism.
 
+NOTE: The inter-process transport is currently only implemented on operating
+systems that provide UNIX domain sockets.
 
-CONNECTION STRING
------------------
-Connection string for inter-process transport is "ipc://" followed by a file
-name. The file will be used as placeholder for a message endpoint. (UNIX domain
-sockets associate a file with the listening socket in a similar way.)
 
-----
-    ipc:///tmp/my_ipc_endpoint
-    ipc:///tmp/prices.ipc
-----
+ADDRESSING
+----------
+A 0MQ address string consists of two parts as follows:
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
+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.
+
+
+Assigning a local address to a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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
-for a wire format specification.
+Not applicable.
+
 
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_java.txt b/doc/zmq_java.txt
deleted file mode 100644
index c49e589..0000000
--- a/doc/zmq_java.txt
+++ /dev/null
@@ -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>
diff --git a/doc/zmq_msg_close.txt b/doc/zmq_msg_close.txt
index 1b043a2..dcc42ff 100644
--- 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
-is shared with another message). Not calling this function can result in
-memory leaks.
+The _zmq_msg_close()_ function shall inform the 0MQ infrastructure that any
+resources associated with the message object referenced by 'msg' are no longer
+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
-'errno' to the appropriate value.
+The _zmq_msg_close()_ function shall return zero if successful. Otherwise
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_copy.txt b/doc/zmq_msg_copy.txt
index b31897a..78337ea 100644
--- 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
-'dest' is orderly deallocated.
+The _zmq_msg_copy()_ function shall copy the message object referenced by 'src'
+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
-to share the buffer between two messages. Thus avoid modifying message data
-after the message was copied. Doing so can modify multiple message instances.
-If what you need is actual hard copy, allocate new message using
-'zmq_msg_size' and copy the data using 'memcpy'.
+CAUTION: The implementation may choose not to physically copy the message
+content, rather to share the underlying buffer between 'src' and 'dest'. Avoid
+modifying message content after a message has been copied with
+_zmq_msg_copy()_, doing so can result in undefined behaviour. If what you need
+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
-sets 'errno' to the appropriate value.
+The _zmq_msg_copy()_ function shall return zero if successful. Otherwise it
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_data.txt b/doc/zmq_msg_data.txt
index 45a99b1..dbf6612 100644
--- 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,
-never use 'zmq_msg_t' members directly.
+The _zmq_msg_data()_ function shall return a pointer to the message content of
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_init.txt b/doc/zmq_msg_init.txt
index b080c18..904dc08 100644
--- 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
-to initialise a 'zmq_msg_t' structure before receiving a message.
+The _zmq_msg_init()_ function shall initialise the message object referenced by
+'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
-sets 'errno' to the appropriate value.
+The _zmq_msg_init()_ function shall return zero if successful. Otherwise it
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_init_data.txt b/doc/zmq_msg_init_data.txt
index 1ae6ce2..5adfeee 100644
--- 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);'
-'int zmq_msg_init_data (zmq_msg_t *msg, void *data, size_t size, zmq_free_fn *ffn, 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');*
 
 
 DESCRIPTION
 -----------
-Initialise a message from a supplied buffer. Message isn't copied,
-instead 0MQ infrastructure takes ownership of the buffer located at address
-'data', 'size' bytes long.  Deallocation function ('ffn') will be called once
-the data are not needed anymore. When using a static constant buffer, 'ffn' may
-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
-later on passed to 'ffn' as a second argument.
+The _zmq_msg_init_data()_ function shall initialise the message object
+referenced by 'msg' to represent the content referenced by the buffer located
+at address 'data', 'size' bytes long. No copy of 'data' shall be performed and
+0MQ shall take ownership of the supplied buffer.
+
+If provided, the deallocation function 'ffn' shall be called once the data
+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
-sets 'errno' to the appropriate value.
+The _zmq_msg_init_data()_ function shall return zero if successful. Otherwise
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_init_size.txt b/doc/zmq_msg_init_size.txt
index 9f09ade..1217eb2 100644
--- 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
-it is more efficient to store message content on the stack (small messages) or
-on the heap (large messages).  Therefore, never access message data directly
-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
-avoid the associated performance impact. Thus you should expect your message to
-contain bogus data after this call.
+The _zmq_msg_init_size()_ function shall allocate any resources required to
+store a message 'size' bytes long and initialise the message object referenced
+by 'msg' to represent the newly allocated message.
+
+The implementation shall choose whether to store message content on the stack
+(small messages) or on the heap (large messages). For performance reasons
+_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
-sets 'errno' to the appropriate value.
+The _zmq_msg_init_size()_ function shall return zero if successful. Otherwise
+it shall return -1 and set 'errno' to one of the values defined below.
 
 
 ERRORS
 ------
 *ENOMEM*::
-memory to hold the message cannot be allocated.
-
-
-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);
-----
+Insufficient storage space is available.
 
 
 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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_move.txt b/doc/zmq_msg_move.txt
index d8ce667..e8bde8a 100644
--- 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
-copied, just moved.  'src' becomes an empty message after the call. Original
-content of 'dest' message is deallocated.
+The _zmq_msg_move()_ function shall move the content of the message object
+referenced by 'src' to the message object referenced by 'dest'. No actual
+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
-sets 'errno' to the appropriate value.
+The _zmq_msg_move()_ function shall return zero if successful. Otherwise it
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_msg_size.txt b/doc/zmq_msg_size.txt
index 6d24243..05abfa6 100644
--- 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,
-never use 'zmq_msg_t' members directly.
+The _zmq_msg_size()_ function shall return the size in bytes of the content of
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_pgm.txt b/doc/zmq_pgm.txt
index d0e2622..c92824e 100644
--- 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
-you to deliver messages to multiple destinations sending the data over
-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
------------------
-Connection string for PGM transport is "pgm://" 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:
+PGM (Pragmatic General Multicast) is a protocol for reliable multicast
+transport of data over IP networks.
 
-----
-    pgm://eth0;224.0.0.1:5555
-    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
-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.
+DESCRIPTION
+-----------
+0MQ implements two variants of PGM, the standard protocol where PGM datagrams
+are layered directly on top of IP datagrams as defined by RFC 3208 (the 'pgm'
+transport) and "Encapsulated PGM" where PGM datagrams are encapsulated inside
+UDP datagrams (the 'epgm' transport).
 
+The 'pgm' and 'epgm' transports can only be used with the 'ZMQ_PUB' and
+'ZMQ_SUB' socket types.
 
-WIRE FORMAT
------------
-Consecutive PGM packets are interpreted as a single continuous stream of data.
-The data is then split into messages using the wire format described in
-linkzmq:zmq_tcp[7]. Thus, messages are not aligned with packet boundaries and
-each message can start at an arbitrary position within the packet and span
-several packets.
+Further, PGM sockets are rate limited by default and incur a performance
+penalty when used over a loopback interface. For details, refer to the
+'ZMQ_RATE', 'ZMQ_RECOVERY_IVL' and 'ZMQ_MCAST_LOOP' options documented in
+linkzmq:zmq_setsockopt[3].
 
-Given this wire format, it would be impossible for late joining consumers to
-identify message boundaries. To solve this problem, each PGM packet payload
-starts with 16-bit unsigned integer in network byte order which specifies the
-offset of the first message in the packet. If there's no beginning of a message
-in the packet (it's a packet transferring inner part of a larger message)
-the value of the initial integer is 0xFFFF.
+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.
 
-Each packet thus looks like this:
 
-----
-+-----------+------------+------------------+--------
-| IP header | PGM header | offset (16 bits) | data .....
-+-----------+------------+------------------+--------
-----
+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.
 
-Following example shows how messages are arranged in subsequent packets:
 
-----
-+---------------+--------+-----------+-----------------------------+
-| PGM/IPheaders | 0x0000 |   message 1   |   message 2 (part 1)    |
-+---------------+--------+-----------+-----------------------------+
+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:
 
-+---------------+--------+-----------------------------------------+
-| PGM/IPheaders | 0xFFFF |           message 2 (part 2)            |
-+---------------+--------+-----------------------------------------+
+* The interface name as defined by the operating system.
+* The primary IPv4 address assigned to the interface, in it's numeric
+  representation.
 
-+---------------+--------+--------------------------+-----------+
-| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
-+---------------+--------+--------------------------+-----------+
+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 datagrams are interpreted by 0MQ as a single continous stream
+of data where 0MQ messages are not necessarily aligned with PGM datagram
+boundaries and a single 0MQ message may span several PGM datagrams. This stream
+of data consists of 0MQ messages encapsulated in 'frames' as described in
+linkzmq:zmq_tcp[7].
+
+In order for late joining consumers to be able to identify message boundaries,
+each PGM datagram payload starts with a 16-bit unsigned integer in network byte
+order specifying either the offset of the first message 'frame' in the datagram
+or containing the value 0xFFFF if the datagram contains solely an intermediate
+part of a larger message.
+
+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, */
+/* 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);
+/* 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");
+assert (rc == 0);
 ----
 
 
 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]
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_poll.txt b/doc/zmq_poll.txt
index 9969d0f..b654041 100644
--- 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
-array is determined by 'nitems' argument. Each item in the array looks like
-this:
+The _zmq_poll()_ function provides a mechanism for applications to multiplex
+input/output events in a level-triggered fashion over a set of sockets. Each
+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;
-    int fd;
-    short events;
-    short revents;
+    void '*socket';
+    int 'fd';
+    short 'events';
+    short 'revents';
 } zmq_pollitem_t;
-----
 
-0MQ socket to poll on is specified by 'socket'.  In case you want to poll on
-standard POSIX socket, set 'socket' to NULL and fill the POSIX file descriptor
-to 'fd'.  'events' specifies which events to wait for. It's a combination of
-the values below.  Once the call exits, 'revents' will be filled with events
-that have actually occured on the socket. The field will contain a combination
-of the values below.
+For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
+socket referenced by 'socket' *or* the standard socket specified by the file
+descriptor 'fd', for the event(s) specified in 'events'. If both 'socket' and
+'fd' are set in a single *zmq_pollitem_t*, the 0MQ socket referenced by
+'socket' shall take precedence and the value of 'fd' shall be ignored.
+
+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
+_message queue_ associated with 'socket' without blocking. For standard sockets
+this is equivalent to the 'POLLIN' flag of the _poll()_ system call and
+generally means that at least one byte of data may be read from 'fd' without
+blocking.
+
 *ZMQ_POLLOUT*::
-wait while message can be set socket. Poll will return if a message of at least
-one byte can be written to the socket. However, there is no guarantee that
-arbitrarily large message can be sent.
+For 0MQ sockets, at least one message may be queued on the underlying
+_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()_.
 
-'timeout' argument specifies an upper limit on the time for which 'zmq_poll'
-will block, in microseconds. Specifying a negative value in timeout means an
-infinite timeout.
+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
-in the case of error.
+Upon successful completion, the _zmq_poll()_ function shall return the number
+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;
-items [0].events = ZMQ_POLLIN;
-items [1].socket = NULL;
-items [1].fd = my_fd;
-items [1].events = ZMQ_POLLIN;
-
-int rc = zmq_poll (items, 2);
-assert (rc != -1);
+/* First item refers to 0MQ socket 'socket' */
+items[0].socket = socket;
+items[0].events = ZMQ_POLLIN;
+/* Second item refers to standard socket 'fd' */
+items[1].socket = NULL;
+items[1].fd = fd;
+items[1].events = ZMQ_POLLIN;
+/* 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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_queue.txt b/doc/zmq_queue.txt
index 7f31ff9..a3f84f2 100644
--- 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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_recv.txt b/doc/zmq_recv.txt
index 0365d23..dbdf45f 100644
--- 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
-'msg' .  Any content previously in 'msg' will be properly deallocated.  'flags'
-argument can be combination of the flags described below.
+The _zmq_recv()_ function shall dequeue a message from the underlying _message
+queue_ associated with the socket referenced by the 'socket' argument and store
+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
-non-blocking mode. I.e. if it cannot be processed immediately,
-error should be returned with 'errno' set to EAGAIN.
+Specifies that the operation should be performed in non-blocking mode. If there
+are no messages available to be dequeued from the underlying _message queue_
+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
-sets 'errno' to the appropriate value.
+The _zmq_recv()_ function shall return zero if successful. Otherwise it shall
+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
-appropriate state. This error may occur with sockets that switch between
-several states (e.g. ZMQ_REQ).
+The _zmq_recv()_ operation cannot be performed on this socket at the moment due
+to the socket not being in the appropriate state.  This error may occur with
+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_msg_data[3]
-linkzmq:zmq_msg_size[3]
+linkzmq:zmq_socket[7]
+linkzmq:zmq[7]
 
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_send.txt b/doc/zmq_send.txt
index f6a35c5..d2ae318 100644
--- 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 flags described below.
+The _zmq_send()_ function shall queue the message referenced by the 'msg'
+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.
-I.e. if it cannot be processed immediately, error should be returned with
-'errno' set to EAGAIN.
+Specifies that the operation should be performed in non-blocking mode. If the
+message cannot be queued on the underlying _message queue_ associated with
+'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
-immediately. Instead, it should batch ZMQ_NOFLUSH messages and send them
-downstream only once 'zmq_flush' is invoked. This is an optimisation for cases
-where several messages are sent in a single business transaction. However, the
-effect is measurable only in extremely high-perf scenarios (million messages a
-second or so).  If that's not your case, use standard flushing send instead.
+Specifies that the _zmq_send()_ function should not flush the underlying
+_message queue_ associated with 'socket' to the network automatically.
+Instead, it should batch all messages queued with the 'ZMQ_NOFLUSH' flag and
+only flush the _message queue_ once either a message without the 'ZMQ_NOFLUSH'
+flag is queued, or manually on invocation of the _zmq_flush()_ function.
+
+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
-sets 'errno' to the appropriate value.
+The _zmq_send()_ function shall return zero if successful. Otherwise it shall
+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
-appropriate state. This error may occur with sockets that switch between
-several states (e.g. ZMQ_REQ).
+The _zmq_send()_ operation cannot be performed on this socket at the moment due
+to the socket not being in the appropriate state.  This error may occur with
+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_msg_init_size[3]
-linkzmq:zmq_msg_init_data[3]
-linkzmq:zmq_msg_data[3]
-linkzmq:zmq_msg_size[3]
+linkzmq:zmq_socket[7]
+linkzmq:zmq[7]
 
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt
index 629bffc..f230111 100644
--- 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
-list below. 'optval' is a pointer to the value to set, 'optvallen' is the size
-of the value in bytes.
-
-*ZMQ_HWM*::
-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*::
-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
-exceeded there is no disk activity involved though. The value of the option
-defines maximal size of the swap file.
-+
-Type: int64_t  Unit: bytes  Default: 0
-
-*ZMQ_AFFINITY*::
-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*::
-Identity of the socket. Identity is important when restarting applications.
-If the socket has no identity, each run of the application is completely
-separated from other runs. However, with identity application reconnects to
-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*::
-Applicable only to ZMQ_SUB socket type. Removes existing message filter.
-The filter specified must match the string passed to ZMQ_SUBSCRIBE options
-exactly. If there were several instances of the same filter created,
-this options removes only one of them, leaving the rest in place
-and functional.
-+
-Type: BLOB  Unit: N/A  Default: N/A
-
-*ZMQ_RATE*::
-This option applies only to sending side of multicast transports (pgm & udp).
-It specifies maximal outgoing data rate that an individual sender socket
-can send.
-+
-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*::
-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
-from. Setting the value to 0 disables the loopback functionality which
-can have negative impact on the performance. If possible, disable
-the loopback in production environments.
-+
-Type: uint64_t Unit: N/A (boolean value) Default: 1
-
-*ZMQ_SNDBUF*::
-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*::
-Sets the underlying kernel receive buffer size to the specified size. See
-'SO_RCVBUF' POSIX socket option. Value of zero means leaving the OS default
-unchanged.
-+
-Type: uint64_t Unit: bytes Default: 0
+The _zmq_setsockopt()_ function shall set the option specified by the
+'option_name' argument to the value pointed to by the 'option_value' argument
+for the 0MQ socket pointed to by the 'socket' argument. The 'option_len'
+argument is the size of the option value in bytes.
+
+The following options are defined:
+
+
+ZMQ_HWM: Set high water mark
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_HWM' option shall set the high water mark for the _message queue_
+associated with the socket.  The high water mark is a hard limit on the number
+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
+take appropriate action such as blocking or dropping new messages entering the
+queue.
+
+The default 'ZMQ_HWM' value of zero means "no limit".
+
+Option value type:: int64_t
+Option value unit:: messages
+Default value:: 0
+Applicable socket types:: all
+
+
+ZMQ_LWM: Set low water mark
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_LWM' option shall set the low water mark for the _message queue_
+associated with the socket.  This option only makes sense when used in
+conjunction with the 'ZMQ_HWM' option. A socket which has reached it's high
+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
+which point normal message processing is resumed.
+
+Option value type:: int64_t
+Option value unit:: messages
+Default value:: 0
+Applicable socket types:: all
+
+
+ZMQ_SWAP: Set disk offload size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_SWAP' option shall set the disk offload (swap) size for the _message
+queue_ associated with the socket. A socket which has 'ZMQ_SWAP' set to a
+non-zero value may exceed it's high water mark; in this case outstanding
+messages shall be offloaded to storage on disk rather than held in memory.
+
+The value of 'ZMQ_SWAP' defines the maximum size of the swap space in bytes.
+
+Option value type:: int64_t
+Option value unit:: bytes
+Default value:: 0
+Applicable socket types:: all
+
+
+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
-sets 'errno' to the appropriate value.
+The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index b6cdc35..c53779c 100644
--- 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
-'zmq_init' function. 'type' argument can be one of the values defined below.
-Note that each socket is owned by exactly one thread (the one that it was
-created from) and should not be used from any other thread.
-
-*ZMQ_P2P*::
-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*::
-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
-to specify which messages to subscribe for.
-+
-Compatible peer sockets: ZMQ_PUB.
-
-*ZMQ_REQ*::
-Socket to send requests and receive replies. Requests are load-balanced among
-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*::
-Socket to receive requests and send replies. This socket type allows only an
-alternated sequence of recv's and send's. Each send is routed to the peer that
-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*::
-Special socket type to be used in request/reply middleboxes such as
-linkzmq:zmq_queue[7]. Requests received using this socket are already properly
-tagged with prefix identifying the original requester. When sending a reply via
-XREP socket the message should be tagged with a prefix from a corresponding
-request.
-+
-Compatible peer sockets: ZMQ_REQ, ZMQ_XREQ.
-
-*ZMQ_UPSTREAM*::
-Socket to receive messages from up the stream. Messages are fair-queued from
-among all the connected peers. Send function is not implemented for this socket
-type.
-+
-Compatible peer sockets: ZMQ_DOWNSTREAM.
-
-*ZMQ_DOWNSTREAM*::
-Socket to send messages down stream. Messages are load-balanced among all the
-connected peers. Recv function is not implemented for this socket type.
-+
-Compatible peer sockets: ZMQ_UPSTREAM.
+The 'zmq_socket()' function shall create a 0MQ socket within the specified
+'context' and return an opaque handle to the newly created socket. The 'type'
+argument specifies the _messaging pattern_, which determines the semantics of
+communication over the socket.
+
+The following _messaging patterns_ are defined:
+
+
+Peer to peer pattern
+~~~~~~~~~~~~~~~~~~~~
+The simplest messaging pattern, used for communicating between two peers.
+
+Socket type:: 'ZMQ_P2P'
+Compatible peer sockets:: 'ZMQ_P2P'
+
+A socket of type 'ZMQ_P2P' can only be connected to a single peer at any one
+time.  No message routing or filtering is performed on messages sent over a
+'ZMQ_P2P' socket.
+
+
+Publish-subscribe pattern
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The publish-subscribe pattern is used for one-to-many distribution of data from
+a single _publisher_ to multiple _subscribers_ in a fanout fashion.
+
+Socket type:: 'ZMQ_PUB'
+Compatible peer sockets:: 'ZMQ_SUB'
+
+A socket of type 'ZMQ_PUB' is used by a _publisher_ to distribute data.
+Messages sent are distributed in a fanout fashion to all connected peers.
+The _zmq_recv()_ function is not implemented for this socket type.
+
+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
-sets errno to one of the values below.
+The _zmq_socket()_ function shall return an opaque handle to the newly created
+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.
-    See 'app_threads' parameter to '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);
-----
+The number of application threads using sockets within this 'context' has been
+exceeded. See the 'app_threads' parameter of the _zmq_init()_ function.
 
 
 SEE ALSO
@@ -121,6 +128,7 @@ linkzmq:zmq_flush[3]
 linkzmq:zmq_recv[3]
 
 
-AUTHOR
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_streamer.txt b/doc/zmq_streamer.txt
index d0df514..c8d517b 100644
--- 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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_strerror.txt b/doc/zmq_strerror.txt
index 2bdf762..61f30e3 100644
--- 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
-'strerror' isn't capable of translating those errors into human readable
-strings. Instead, 'zmq_strerror' should be used.
+The _zmq_strerror()_ function shall return a pointer to an error message string
+corresponding to the error number specified by the 'errnum' argument. As 0MQ
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_tcp.txt b/doc/zmq_tcp.txt
index 98f1219..c6eba21 100644
--- 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
-applications, you will mostly use TCP transport.
+TCP is an ubiquitous, reliable, unicast transport. When connecting distributed
+applications over a network with 0MQ, using the TCP transport will likely be
+your first choice.
 
 
-CONNECTION STRING
------------------
-Connection string for TCP transport is "tcp://" followed by an IP address,
-colon and port number. IP address can be either its numeric representation,
-a NIC name or a hostname (resolved by DNS):
+ADDRESSING
+----------
+A 0MQ address string consists of two parts as follows:
+'transport'`://`'endpoint'. The 'transport' part specifies the underlying
+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
-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.
+Assigning a local address to a socket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When assigning a local address to a socket using _zmq_bind()_ with the 'tcp'
+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:
 
-WIRE FORMAT
------------
-A message consists of a message length followed by message data.
-Size of message data MUST correspond to the message length.
+* 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.
 
-For messages of 0 to 254 octets, the length is represented by single octet. 
+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'.
 
-For messages of 255 or more octets the length is represented by a single octet
-%xFF followed by a 64-bit unsigned integer length in network byte order.
+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.
 
-The protocol can be defined by this BNF grammar:
+A 'peer address' may be specified by either of the following:
 
-----
-    frame   = length data
-    length  = OCTET | escape 8*OCTET
-    escape  = %xFF
-    data    = *OCTET
-----
+* The DNS name of the peer.
+* The IPv4 address of the peer, in it's numeric representation.
 
-Binary layout of a message (up to 254 bytes long):
 
-----
+WIRE FORMAT
+-----------
+0MQ messages are transmitted over TCP in frames consisting of the message
+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:
+
+....
+    frame           = (message-length message-data)
+    message-length  = OCTET / (escape 8OCTET)
+    escape          = %xFF
+    message-data    = *OCTET
+....
+
+
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
-
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_term.txt b/doc/zmq_term.txt
index 451c1ac..eea9f48 100644
--- 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 context, 'zmq_term' succeeds but shutdown of the context is delayed till
-the last socket is closed.
+The _zmq_term()_ function terminates the 0MQ context 'context'.
+
+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
-one of the values below.
+The _zmq_term()_ function shall return zero if successful. Otherwise it shall
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.
diff --git a/doc/zmq_udp.txt b/doc/zmq_udp.txt
deleted file mode 100644
index ecc6bdf..0000000
--- a/doc/zmq_udp.txt
+++ /dev/null
@@ -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>
-
diff --git a/doc/zmq_version.txt b/doc/zmq_version.txt
index 8c038ae..0ad3a55 100644
--- 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
-linking with 0MQ dynamically to make sure the right version of 0MQ is installed
-on the system.
+The _zmq_version()_ function shall fill in the integer variables pointed to by
+the 'major', 'minor' and 'patch' arguments with the major, minor and patchlevel
+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
-------
-Martin Sustrik <sustrik at 250bpm dot com>
+AUTHORS
+-------
+The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
+Martin Lucina <mato@kotelna.sk>.