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.