Merge branch 'doc-updates' of git.lucina.net:libxs

3 files changed, 135 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index fcd1b4c..7cfc637 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -6,6 +6,10 @@ MAN3 = xs_bind.3 xs_close.3 xs_connect.3 xs_init.3 \
     xs_sendmsg.3 xs_recvmsg.3 xs_getmsgopt.3 xs_setctxopt.3
 MAN7 = xs.7 xs_tcp.7 xs_pgm.7 xs_inproc.7 xs_ipc.7
 
+if BUILD_LIBZMQ
+MAN7 += zmq.7
+endif
+
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
 
 MAN_TXT = $(MAN3:%.3=%.txt)
diff --git a/doc/xs.txt b/doc/xs.txt
index 79a2443..93ff16a 100644
--- a/doc/xs.txt
+++ b/doc/xs.txt
@@ -175,11 +175,21 @@ used by C programmers. The intent is that programmers using Crossroads from
 other languages shall refer to this documentation alongside any documentation
 provided by the vendor of their language binding.
 
+
+ZEROMQ COMPATIBILITY
+--------------------
+The Crossroads library provides an optional drop-in 'libzmq' compatibility
+library for ZeroMQ applications.  If your version of Crossroads was built with
+the `--enable-libzmq` option, you can find the compatibility library
+documentation in linkxs:zmq[7].
+
+
 AUTHORS
 -------
 The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com>
 and Martin Lucina <martin@lucina.net>.
 
+
 COPYING
 -------
 Free use of Crossroads library is granted under the terms of the GNU Lesser
diff --git a/doc/zmq.txt b/doc/zmq.txt
new file mode 100644
index 0000000..f1e1abf
--- /dev/null
+++ b/doc/zmq.txt
@@ -0,0 +1,121 @@
+zmq(7)
+======
+
+
+NAME
+----
+zmq - Crossroads I/O ZeroMQ compatibility library
+
+
+SYNOPSIS
+--------
+*#include <zmq.h>*
+
+*cc* ['flags'] 'files' *-lzmq* ['libraries']
+
+
+DESCRIPTION
+-----------
+This 'libzmq' compatibility library is provided by the Crossroads I/O project
+as a transitional drop-in replacement for existing applications and language
+bindings written for the ZeroMQ library.
+
+The interfaces provided emulate those provided by ZeroMQ release 2.1.11, and
+binary compatibility is provided for ABI version 1.0.0.
+
+Existing applications can use these interfaces as a drop-in replacement for the
+ZeroMQ-provided 'libzmq' by installing the Crossroads version of this library
+in its place.
+
+Applications can also be recompiled against this library with no code or build
+system changes.
+
+IMPORTANT: The 'libzmq' compatibility library is an optional component of
+the Crossroads project, intended as a way to ease transition of existing
+applications and language bindings to the native 'libxs' interfaces, this
+feature will not be maintained indefinitely, hence developers are strongly
+encouraged to migrate their applications to 'libxs'.
+
+CONSTANTS
+---------
+
+All constants defined by the ZeroMQ 2.1.11 version of *<zmq.h>* are also
+defined in the Crossroads version.
+
+INTERFACES
+----------
+
+Context
+~~~~~~~
+[verse]
+*void *zmq_init (int 'io_threads');*
+*int zmq_term (void '*context');*
+
+
+Sockets
+~~~~~~~
+[verse]
+*void *zmq_socket (void '*context', int 'type');*
+*int zmq_close (void '*socket');*
+*int zmq_connect (void '*socket', const char '*endpoint');*
+*int zmq_bind (void '*socket', const char '*endpoint');*
+*int zmq_setsockopt (void '*socket', int 'option_name', const void '*option_value', size_t 'option_len');*
+*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');*
+*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
+
+
+Messages
+~~~~~~~~
+[verse]
+*int zmq_msg_init (zmq_msg_t '*msg');*
+*int zmq_msg_init_size (zmq_msg_t '*msg', size_t 'size');*
+*int zmq_msg_init_data (zmq_msg_t '*msg', void '*data', size_t 'size', zmq_free_fn '*ffn', void '*hint');*
+*int zmq_msg_close (zmq_msg_t '*msg');*
+*int zmq_msg_copy (zmq_msg_t '*dest', zmq_msg_t '*src');*
+*int zmq_msg_move (zmq_msg_t '*dest', zmq_msg_t '*src');*
+
+
+Sending and receiving
+~~~~~~~~~~~~~~~~~~~~~
+[verse]
+*int zmq_send (void '*socket', zmq_msg_t '*msg', int 'flags');*
+*int zmq_recv (void '*socket', zmq_msg_t '*msg', int 'flags');*
+
+
+Devices
+~~~~~~~
+[verse]
+*int zmq_device (int 'device', const void '*frontend', const void '*backend');*
+
+
+Error handling
+~~~~~~~~~~~~~~
+[verse]
+*int zmq_errno (void);*
+*const char *zmq_strerror (int 'errnum');*
+
+
+Version detection
+~~~~~~~~~~~~~~~~~
+[verse]
+*void zmq_version (int '*major', int '*minor', int '*patch');*
+
+NOTE: The version numbers returned by this function are the emulated ZeroMQ API
+version, i.e. 2.1.11.
+
+
+COPYING
+-------
+Free use of Crossroads library 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 Crossroads distribution.
+
+SEE ALSO
+--------
+linkxs:xs[7]
+
+
+AUTHORS
+-------
+The Crossroads documentation was written by Martin Sustrik <sustrik@250bpm.com>
+and Martin Lucina <martin@lucina.net>.