Convert documentation to AsciiDoc

64 files changed, 1827 insertions, 1501 deletions

diff --git a/.gitignore b/.gitignore
index 5a4133d..1c68975 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,3 +32,8 @@ perf/cpp/local_lat
 perf/cpp/local_thr
 perf/cpp/remote_lat
 perf/cpp/remote_thr
+doc/*.1
+doc/*.3
+doc/*.7
+doc/*.html
+doc/*.xml
diff --git a/Makefile.am b/Makefile.am
index 81d1598..8795e14 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -4,12 +4,8 @@ if BUILD_PERF
 DIR_PERF = perf
 endif
 
-if INSTALL_MAN
-DIR_MAN = man
-endif
-
-SUBDIRS = src $(DIR_MAN) $(DIR_PERF) devices bindings examples
-DIST_SUBDIRS = src man perf devices bindings examples
+SUBDIRS = src doc $(DIR_PERF) devices bindings examples
+DIST_SUBDIRS = src doc perf devices bindings examples
 
 EXTRA_DIST = \
 $(top_srcdir)/foreign/openpgm/@pgm2_basename@.tar.bz2 \
diff --git a/configure.in b/configure.in
index 078f27c..af69a59 100644
--- a/configure.in
+++ b/configure.in
@@ -50,9 +50,20 @@ on_mingw32="no"
 # Host speciffic checks
 AC_CANONICAL_HOST
 
-# Whether or not install manual pages.
-# Note that on MinGW manpages are not installed.
+# Determine whether or not documentation should be built.
+build_doc="yes"
 install_man="yes"
+if test ! -f "doc/zmq.html"; then
+# We are building from git.
+# Check for asciidoc and xmlto and don't build the docs if these are not installed.
+    AC_CHECK_PROG(have_asciidoc, asciidoc, yes, no)
+    AC_CHECK_PROG(have_xmlto, xmlto, yes, no)
+    if test "x$have_asciidoc" = "xno" -o "x$have_xmlto" = "xno"; then
+        build_doc="no"
+        install_man="no"
+        AC_MSG_WARN([You are building from git and asciidoc is not installed. Documentation will not be built or installed.])
+    fi
+fi
 
 case "${host_os}" in
     *linux*)
@@ -551,6 +562,7 @@ AM_CONDITIONAL(BUILD_CHAT, test "x$chat" = "xyes")
 AM_CONDITIONAL(ON_MINGW, test "x$on_mingw32" = "xyes")
 AM_CONDITIONAL(BUILD_PGM2_EXAMPLES, test "x$with_pgm2_examples" = "xyes")
 AM_CONDITIONAL(INSTALL_MAN, test "x$install_man" = "xyes")
+AM_CONDITIONAL(BUILD_DOC, test "x$build_doc" = "xyes")
 
 AC_SUBST(stdint)
 AC_SUBST(inttypes)
@@ -565,7 +577,7 @@ AC_FUNC_MALLOC
 AC_TYPE_SIGNAL
 AC_CHECK_FUNCS(perror gettimeofday memset socket getifaddrs freeifaddrs)
 
-AC_OUTPUT(Makefile src/Makefile man/Makefile bindings/python/Makefile \
+AC_OUTPUT(Makefile src/Makefile doc/Makefile bindings/python/Makefile \
     bindings/python/setup.py bindings/ruby/Makefile \
     bindings/java/Makefile perf/Makefile perf/c/Makefile perf/cpp/Makefile \
     perf/python/Makefile perf/ruby/Makefile perf/java/Makefile src/libzmq.pc \
@@ -615,6 +627,7 @@ AC_MSG_RESULT([     Queue: $queue])
 AC_MSG_RESULT([   Performance tests: $perf])
 AC_MSG_RESULT([   Examples:])
 AC_MSG_RESULT([     Chat: $chat])
+AC_MSG_RESULT([   Documentation: $build_doc])
 AC_MSG_RESULT([])
 AC_MSG_RESULT([ ******************************************************** ])
 AC_MSG_RESULT([])
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..07dfb02
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,41 @@
+MAN1 = zmq_forwarder.1 zmq_streamer.1 zmq_queue.1
+MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_flush.3 zmq_init.3 \
+    zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_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
+MAN7 = zmq.7 zmq_tcp.7 zmq_udp.7 zmq_pgm.7 zmq_inproc.7 zmq_ipc.7 \
+    zmq_cpp.7 zmq_java.7 zmq_python.7
+MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
+
+MAN_TXT = $(MAN1:%.1=%.txt)
+MAN_TXT += $(MAN3:%.3=%.txt)
+MAN_TXT += $(MAN7:%.7=%.txt)
+MAN_HTML = $(MAN_TXT:%.txt=%.html)
+
+if INSTALL_MAN
+dist_man_MANS = $(MAN_DOC)
+endif
+
+EXTRA_DIST = $(MAN_TXT)
+if BUILD_DOC
+EXTRA_DIST += $(MAN_HTML)
+endif
+
+MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML)
+
+dist-hook : $(MAN_DOC) $(MAN_HTML)
+
+SUFFIXES=.html .txt .xml .1 .3 .7
+
+.txt.html:
+	asciidoc -d manpage -b xhtml11 -f asciidoc.conf $<
+.txt.xml:
+	asciidoc -d manpage -b docbook -f asciidoc.conf $<
+.xml.1:
+	xmlto man $<
+.xml.3:
+	xmlto man $<
+.xml.7:
+	xmlto man $<
+
diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
new file mode 100644
index 0000000..d1dac78
--- /dev/null
+++ b/doc/asciidoc.conf
@@ -0,0 +1,34 @@
+[macros]
+(?su)[\\]?(?P<name>linkzmq):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+ifdef::backend-docbook[]
+[linkzmq-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[linkzmq-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">0MQ</refmiscinfo>
+<refmiscinfo class="version">2.0.0</refmiscinfo>
+<refmiscinfo class="manual">0MQ Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
diff --git a/man/man7/zmq.7 b/doc/zmq.txt
index ed7e08b..0c911c3 100644
--- a/man/man7/zmq.7
+++ b/doc/zmq.txt
@@ -1,8 +1,14 @@
-.TH zmq 7 "" "(c)2007-2010 iMatix Corporation" "0MQ User Manuals"
-.SH NAME
-0MQ \- a lightweight messaging kernel
-.SH SYNOPSIS
+zmq(7)
+======
 
+
+NAME
+----
+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
@@ -25,19 +31,23 @@ microarchitectures.
 
 0MQ is fully open sourced LGPL-licensed software.
 
-.SH CONTEXT
+
+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)
+Initialise 0MQ context::
+    linkzmq:zmq_init[3]
 
-Uninitialise 0MQ context:
-.BR zmq_term(3)
+Uninitialise 0MQ context::
+    linkzmq:zmq_term[3]
 
-.SH MESSAGES
+
+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
@@ -46,106 +56,120 @@ 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)
+Initialise a message::
+    linkzmq:zmq_msg_init[3]
+    linkzmq:zmq_msg_size[3]
+    linkzmq:zmq_msg_data[3]
+
+Uninitialise a message::
+    linkzmq:zmq_msg_close[3]
 
-Uninitialise a message:
-.BR zmq_msg_close(3)
+Access message content::
+    linkzmq:zmq_msg_data[3]
+    linkzmq:zmq_msg_size[3]
 
-Access message content:
-.BR zmq_msg_data(3)
-.BR zmq_msg_size(3)
+Message manipulation::
+    linkzmq:zmq_msg_copy[3]
+    linkzmq:zmq_msg_move[3]
 
-Message manipulation:
-.BR zmq_msg_copy(3)
-.BR zmq_msg_move(3)
 
-.SH SOCKETS
+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)
+Creating a socket::
+    linkzmq:zmq_socket[3]
+
+Closing a socket::
+    linkzmq:zmq_close[3]
 
-Closing a socket:
-.BR zmq_close(3)
+Setting socket options::
+    linkzmq:zmq_setsockopt[3]
 
-Setting socket options:
-.BR zmq_setsockopt(3)
+Establishing a message flow::
+    linkzmq:zmq_bind[3]
+    linkzmq:zmq_connect[3]
 
-Establishing a message flow:
-.BR zmq_bind(3)
-.BR zmq_connect(3)
+Sending & receiving messages::
+    linkzmq:zmq_send[3]
+    linkzmq:zmq_flush[3]
+    linkzmq:zmq_recv[3]
 
-Sending & receiving messages:
-.BR zmq_send(3)
-.BR zmq_flush(3)
-.BR zmq_recv(3)
 
-.SH MULTIPLEXING
+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)
+Poll for I/O events::
+    linkzmq:zmq_poll[3]
 
-.SH ERROR HANDLING
+
+ERROR HANDLING
+--------------
 0MQ defines couple of non-POSIX error codes. Use following functions to handle
 them neatly.
 
-Convert error code into human readable string:
-.BR zmq_strerror(3)
+Convert error code into human readable string::
+    linkzmq:zmq_strerror[3]
+
 
-.SH TRANSPORTS
+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)
+TCP/IP transport::
+    linkzmq:zmq_tcp[7]
 
-UDP reliable multicast transport:
-.BR zmq_udp(7)
+UDP reliable multicast transport::
+    linkzmq:zmq_udp[7]
 
-PGM reliable multicast transport:
-.BR zmq_pgm(7)
+PGM reliable multicast transport::
+    linkzmq:zmq_pgm[7]
 
-Inter-process transport:
-.BR zmq_ipc (7)
+Inter-process transport::
+    linkzmq:zmq_ipc[7]
 
-In-process (inter-thread) transport:
-.BR zmq_inproc(7)
+In-process (inter-thread) transport::
+    linkzmq:zmq_inproc[7]
 
-.SH DEVICES
+
+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)
+Forwarder device for PUB/SUB messaging::
+    linkzmq:zmq_forwarder[1]
+
+Streamer device for UPSTREAM/DOWNSTREAM messaging::
+    linkzmq:zmq_streamer[1]
 
-Streamer device for UPSTREAM/DOWNSTREAM messaging:
-.BR zmq_streamer(1)
-.SH LANGUAGES
+Forwarder device for REQ/REP messaging::
+    linkzmq:zmq_queue[1]
+
+
+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)
+$$C++$$::
+    linkzmq:zmq_cpp[7]
 
-Common Lisp:
-.BR zmq_cl(7)
+Java::
+    linkzmq:zmq_java[7]
 
-Python:
-.BR zmq_python(7)
+Python::
+    linkzmq:zmq_python[7]
 
-Ruby:
-.BR zmq_ruby(7)
 
-.SH AUTHOR
+AUTHOR
+------
 Martin Sustrik <sustrik at 250bpm dot com>
-
diff --git a/doc/zmq_bind.txt b/doc/zmq_bind.txt
new file mode 100644
index 0000000..391238a
--- /dev/null
+++ b/doc/zmq_bind.txt
@@ -0,0 +1,67 @@
+zmq_bind(3)
+===========
+
+
+NAME
+----
+zmq_bind - binds the socket to the specified address
+
+
+SYNOPSIS
+--------
+'int zmq_bind (void *s, const char *addr);'
+
+
+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.
+
+Note that single socket can be bound (and connected) to
+arbitrary number of peers using different transport mechanisms.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EPROTONOSUPPORT*::
+unsupported protocol.
+*ENOCOMPATPROTO*::
+protocol is not compatible with the socket type.
+*EADDRINUSE*::
+the given address is already in use.
+*EADDRNOTAVAIL*::
+a nonexistent interface was requested or the requested address was not local.
+
+
+EXAMPLE
+-------
+----
+void *s = zmq_socket (context, ZMQ_PUB);
+assert (s);
+int rc = zmq_bind (s, "inproc://my_publisher");
+assert (rc == 0);
+rc = zmq_bind (s, "tcp://eth0:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_connect[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_close.txt b/doc/zmq_close.txt
new file mode 100644
index 0000000..9964d36
--- /dev/null
+++ b/doc/zmq_close.txt
@@ -0,0 +1,52 @@
+zmq_close(3)
+============
+
+
+NAME
+----
+zmq_close - destroys 0MQ socket
+
+
+SYNOPSIS
+--------
+'int zmq_close (void *s);'
+
+
+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.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+No errors are defined.
+
+
+EXAMPLE
+-------
+----
+int rc = zmq_close (s);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_socket[3]
+linkzmq:zmq_term[3]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_connect.txt b/doc/zmq_connect.txt
new file mode 100644
index 0000000..375873d
--- /dev/null
+++ b/doc/zmq_connect.txt
@@ -0,0 +1,63 @@
+zmq_connect(3)
+==============
+
+
+NAME
+----
+zmq_connect - connect the socket to the specified peer
+
+
+SYNOPSIS
+--------
+'int zmq_connect (void *s, const char *addr);'
+
+
+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.
+
+Note that single socket can be connected (and bound) to
+arbitrary number of peers using different transport mechanisms.
+
+
+RETURN VALUE
+------------
+In case of success the function returns zero. Otherwise it returns -1 and
+sets 'errno' to the appropriate value.
+
+
+ERRORS
+------
+*EPROTONOSUPPORT*::
+unsupported protocol.
+*ENOCOMPATPROTO*::
+protocol is not compatible with the socket type.
+
+
+EXAMPLE
+-------
+----
+void *s = zmq_socket (context, ZMQ_SUB);
+assert (s);
+int rc = zmq_connect (s, "inproc://my_publisher");
+assert (rc == 0);
+rc = zmq_connect (s, "tcp://server001:5555");
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_bind[3]
+linkzmq:zmq_socket[3]
+linkzmq:zmq[7]
+
+
+AUTHOR
+------
+Martin Sustrik <sustrik at 250bpm dot com>
diff --git a/doc/zmq_cpp.txt b/doc/zmq_cpp.txt
new file mode 100644
index 0000000..8b58f2d
--- /dev/null
+++ b/doc/zmq_cpp.txt
@@ -0,0 +1,89 @@
+zmq_cpp(7)
+==========
+
+
+NAME
+----
+zmq_cpp - interface between 0MQ and C++ applications
+
+
+SYNOPSIS
+--------
+This manual page explains how C++ API maps to underlying C API. To learn about
+individual functions and parameters check appropriate C API manual
+pages.
+
+For example, to understand 'zmq::socket_t::setsockopt' function check
+linkzmq:zmq_setsockopt[3].
+
+All 0MQ constants defined with C API are available with C++ API.
+
+
+zmq::context_t
+--------------
+This class encapsulates the functions dealing with initialisation and
+termination of 0MQ context. Constructor of the class invokes
+linkzmq:zmq_init[3] while destructor calls linkzmq:zmq_term[3].
+
+
+zmq::socket_t
+-------------
+This class encapsulates all the functions to deal with 0MQ sockets. Constructor
+calls linkzmq:zmq_socket[3], destructor calls linkzmq:zmq_close[3].  Other
+functions of the class are mapped to C functions with corresponding names.
+'zmq::socket_t::bind' calls linkzmq:zmq_bind[3] etc.
+
+
+zmq::message_t
+--------------
+This class encapsulates 'zmq_msg_t' structure and all the C functions that deal
+with 0MQ messages.  Constructors of the class invoke corresponding
+initialisation functions linkzmq:zmq_msg_init[3], linkzmq:zmq_msg_init_size[3]
+and linkzmq:zmq_msg_init_data[3], while destructor invokes
+linkzmq:zmq_msg_close[3] function.
+
+Remaining functions are mapped to C functions with corresponding names.
+For instance, 'zmq::message_t::copy' is mapped to linkzmq:zmq_msg_copy[3]
+etc.
+
+C++ provides an additional function not available with C API.
+'zmq::message_t::rebuild' is equivalent to calling linkzmq:zmq_close[3]
+followed by linkzmq:zmq_msg_init[3], linkzmq:zmq_msg_init_size[3] or
+linkzmq:zmq_msg_init_data[3].  It provides a way to reuse existing
+'zmq::message_t' instances to store different message content.
+
+
+zmq::error_t
+------------
+All the errors reported using 'errno' mechanism in C API are automatically
+converted to exceptions in C++ API.  'zmq::error_t' is derived from
+'std::exception' and uses linkzmq:zmq_strerror[3] function to convert the error
+code to human-readable string.
+
+
+zmq::poll
+---------
+'zmq::poll' function is a namespaced equivalent of raw C linkzmq:zmq_poll[3]
+function.
+
+
+EXAMPLE
+-------
+----