man pages updated

11 files changed, 153 insertions, 13 deletions

diff --git a/man/man1/zmq_forwarder.1 b/man/man1/zmq_forwarder.1
index 63a0b6b..610767a 100644
--- a/man/man1/zmq_forwarder.1
+++ b/man/man1/zmq_forwarder.1
@@ -6,6 +6,6 @@ zmq_forwarder \- forwards the stream of PUB/SUB messages
 .SH OPTIONS
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
 
diff --git a/man/man1/zmq_streamer.1 b/man/man1/zmq_streamer.1
index 1481231..34b837b 100644
--- a/man/man1/zmq_streamer.1
+++ b/man/man1/zmq_streamer.1
@@ -6,6 +6,6 @@ zmq_streamer \- forwards the stream of UPSTREAM/DOWNSTREAM messages
 .SH OPTIONS
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
 
diff --git a/man/man7/zmq.7 b/man/man7/zmq.7
index 02257a7..584c9ce 100644
--- a/man/man7/zmq.7
+++ b/man/man7/zmq.7
@@ -2,8 +2,147 @@
 .SH NAME
 0MQ \- a lightweight messaging kernel
 .SH SYNOPSIS
-.SH DESCRIPTION
-.SH "SEE ALSO"
+
+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.
+
+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.
+
+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
+datacenters.
+
+0MQ runs on a wide range of operating systems and supports variety of processor
+microarchitectures.
+
+0MQ is accessible from a large set of programming languages.
+
+0MQ is fully open sourced LGPL-licensed software.
+
+.SH 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.
+
+Initialise 0MQ context:
+.BR zmq_init(3)
+
+Uninitialise 0MQ context:
+.BR zmq_term(3)
+
+.SH 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.
+
+Initialise a message:
+.BR zmq_msg_init(3)
+.BR zmq_msg_size(3)
+.BR zmq_msg_data(3)
+
+Uninitialise a message:
+.BR zmq_msg_close(3)
+
+Access message content:
+.BR zmq_msg_data(3)
+.BR zmq_msg_size(3)
+
+Message manipulation:
+.BR zmq_msg_copy(3)
+.BR zmq_msg_move(3)
+
+.SH SOCKETS
+0MQ sockets are very similar to POSIX sockets. See following manual pages to
+understand them in depth.
+
+Creating a socket:
+.BR zmq_socket(3)
+
+Closing a socket:
+.BR zmq_close(3)
+
+Setting socket options:
+.BR zmq_setsockopt(3)
+
+Establishing a message flow:
+.BR zmq_bind(3)
+.BR zmq_connect(3)
+
+Sending & receiving messages:
+.BR zmq_send(3)
+.BR zmq_flush(3)
+.BR zmq_recv(3)
+
+.SH MULTIPLEXING
+0MQ allows you to handle multiple sockets (0MQ as well as standard POSIX)
+in an asynchronous manner.
+
+Poll for I/O events:
+.BR zmq_poll(3)
+
+.SH ERROR HANDLING
+0MQ defines couple of non-POSIX error codes. Use following fuctions to handle
+them neatly.
+
+Convert error code into human readable string:
+.BR zmq_strerror(3)
+
+.SH 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:
+
+TCP/IP transport:
+.BR zmq_tcp(7)
+
+UDP reliable multicast transport:
+.BR zmq_udp(7)
+
+PGM reliable multicast transport:
+.BR zmq_pgm(7)
+
+In-process (inter-thread) transport:
+.BR zmq_inproc(7)
+
+.SH 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:
+
+Forwarder device for PUB/SUB messaging:
+.BR zmq_forwarder(1)
+
+Streamer device for UPSTREAM/DOWNSTREAM messaging:
+.BR zmq_streamer(1)
+.SH 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++:
+.BR zmq_cpp(7)
+
+Common Lisp:
+.BR zmq_cl(7)
+
+Python:
+.BR zmq_python(7)
+
+Ruby:
+.BR zmq_ruby(7)
+
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_cl.7 b/man/man7/zmq_cl.7
index bbe96c1..8dfa032 100644
--- a/man/man7/zmq_cl.7
+++ b/man/man7/zmq_cl.7
@@ -5,5 +5,5 @@ Common Lisp API for 0MQ lightweight messaging kernel
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_cpp.7 b/man/man7/zmq_cpp.7
index d068901..d95a406 100644
--- a/man/man7/zmq_cpp.7
+++ b/man/man7/zmq_cpp.7
@@ -4,6 +4,7 @@ C++ API for 0MQ lightweight messaging kernel
 .SH SYNOPSIS
 .SH DESCRIPTION
 .SH "SEE ALSO"
+.BR zmq(7)
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_inproc.7 b/man/man7/zmq_inproc.7
index b87315f..63779d9 100644
--- a/man/man7/zmq_inproc.7
+++ b/man/man7/zmq_inproc.7
@@ -5,5 +5,5 @@ In-process (inter-thread) tranport for 0MQ
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_pgm.7 b/man/man7/zmq_pgm.7
index cacbfa8..1b46a6b 100644
--- a/man/man7/zmq_pgm.7
+++ b/man/man7/zmq_pgm.7
@@ -5,5 +5,5 @@ PGM-based tranport for 0MQ
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_python.7 b/man/man7/zmq_python.7
index 3538ea7..14f3697 100644
--- a/man/man7/zmq_python.7
+++ b/man/man7/zmq_python.7
@@ -5,5 +5,5 @@ Python API for 0MQ lightweight messaging kernel
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_ruby.7 b/man/man7/zmq_ruby.7
index fb0c654..8c7bde3 100644
--- a/man/man7/zmq_ruby.7
+++ b/man/man7/zmq_ruby.7
@@ -5,5 +5,5 @@ Ruby API for 0MQ lightweight messaging kernel
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_tcp.7 b/man/man7/zmq_tcp.7
index 388704b..5bb867e 100644
--- a/man/man7/zmq_tcp.7
+++ b/man/man7/zmq_tcp.7
@@ -5,5 +5,5 @@ TCP-based tranport for 0MQ
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_udp.7 b/man/man7/zmq_udp.7
index 2e6d7d0..a6ce447 100644
--- a/man/man7/zmq_udp.7
+++ b/man/man7/zmq_udp.7
@@ -5,5 +5,5 @@ UDP-based tranport for 0MQ
 .SH DESCRIPTION
 .SH "SEE ALSO"
 .SH AUTHOR
-Martin Sustrik <sustrik at fastmq dot com>
+Martin Sustrik <sustrik at 250bpm dot com>