Documentation rewrite

1 files changed, 25 insertions, 27 deletions

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>.