Add docbook-based man pages for tools

6 files changed, 542 insertions, 1 deletions

diff --git a/tools/Makefile.am b/tools/Makefile.am
index dc9603b..307fbd2 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -10,3 +10,26 @@ noinst_HEADERS = common.h
 amqp_publish_SOURCES = publish.c common.c
 amqp_get_SOURCES = get.c common.c
 amqp_consume_SOURCES = consume.c common.c
+
+if TOOLS_DOC
+man_MANS = doc/amqp-publish.1 doc/amqp-consume.1 doc/amqp-get.1 doc/librabbitmq-tools.7
+MOSTLYCLEANFILES = doc/man-date.ent
+
+# automake complains about % pattern rules, and suffix rules don't
+# support multiple dependencies, so we have to expand all these out.
+doc/amqp-publish.1: doc/publish.xml doc/man-date.ent
+	$(XMLTO) man -o doc $<
+doc/amqp-consume.1: doc/consume.xml doc/man-date.ent
+	$(XMLTO) man -o doc $<
+doc/amqp-get.1: doc/get.xml doc/man-date.ent
+	$(XMLTO) man -o doc $<
+doc/librabbitmq-tools.7: doc/librabbitmq-tools.xml doc/man-date.ent
+	$(XMLTO) man -o doc $<
+
+doc/man-date.ent:
+	date +'%Y-%m-%d' >$@
+
+clean::
+	rm -f doc/man-date.ent
+
+endif
diff --git a/tools/common.c b/tools/common.c
index 37fd301..6a38a95 100644
--- a/tools/common.c
+++ b/tools/common.c
@@ -187,7 +187,7 @@ static char *amqp_password = "guest";
 const char *connect_options_title = "Connection options";
 struct poptOption connect_options[] = {
 	{"server", 's', POPT_ARG_STRING, &amqp_server, 0,
-	 "the AMQP server to connect to", "server"},
+	 "the AMQP server to connect to", "hostname:port"},
 	{"vhost", 0, POPT_ARG_STRING, &amqp_vhost, 0,
 	 "the vhost to use when connecting", "vhost"},
 	{"username", 0, POPT_ARG_STRING, &amqp_username, 0,
diff --git a/tools/doc/consume.xml b/tools/doc/consume.xml
new file mode 100644
index 0000000..448ade6
--- /dev/null
+++ b/tools/doc/consume.xml
@@ -0,0 +1,173 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
+[
+<!ENTITY date SYSTEM "man-date.ent" >
+]
+>
+<refentry lang="en">
+    <refentryinfo>
+        <productname>RabbitMQ C Client</productname>
+        <authorgroup>
+            <corpauthor>The RabbitMQ Team &lt;<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>&gt;</corpauthor>
+        </authorgroup>
+        <date>&date;</date>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>amqp-consume</refentrytitle>
+        <manvolnum>1</manvolnum>
+        <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo>
+    </refmeta>
+
+    <refnamediv>
+        <refname>amqp-consume</refname>
+        <refpurpose>Consume messages from a queue on an AMQP server</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+        <cmdsynopsis>
+            <command>amqp-consume</command>
+            <arg choice="opt" rep="repeat">
+                <replaceable>OPTION</replaceable>
+            </arg>
+            <arg choice="req">
+                <replaceable>command</replaceable>
+            </arg>
+            <arg choice="opt" rep="repeat">
+                <replaceable>args</replaceable>
+            </arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+    
+    <refsect1>
+        <title>Description</title>
+        <para>
+            <command>amqp-consume</command> consumes messages from a
+            queue on an AMQP server.  For each message that arrives, a
+            receiving command is run, with the message body supplied
+            to it on standard input.
+        </para>
+        <para>
+            <command>amqp-consume</command> can consume from an
+            existing queue, or it can create a new queue.  It can
+            optionally bind the queue to an existing exchange, or to a
+            newly created exchange.
+        </para>
+        <para>
+            By default, messages will be consumed with explicit
+            acknowledgements.  A message will only be acknowledged if
+            the receiving command exits successfully (i.e. with an
+            exit code of zero).  The AMQP <quote>no ack</quote> mode
+            (a.k.a. auto-ack mode) can be enable with the
+            <option>-A</option> option.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Options</title>
+        <variablelist>
+            <varlistentry>
+                <term><option>-q</option></term>
+                <term><option>--queue</option>=<replaceable class="parameter">queue name</replaceable></term>
+                <listitem>
+                    <para>
+                        The name of the queue to consume messages
+                        from.  If the specified queue does not exist,
+                        an auto-delete queue is created with the given
+                        name.  If this option is omitted, a new
+                        auto-delete queue will be created, with a
+                        unique name assigned to the queue by the AMQP
+                        server; that unique name will be displayed on
+                        stderr.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-e</option></term>
+                <term><option>--exchange</option>=<replaceable class="parameter">exchange name</replaceable></term>
+                <listitem>
+                    <para>
+                        The name of the exchange to bind the queue to.
+                        If omitted, binding is not performed.  The
+                        specified exchange should already exist unless
+                        the <option>--exchange-type</option> option is
+                        used to request the creation of an exchange.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-t</option></term>
+                <term><option>--exchange-type</option>=<replaceable class="parameter">type</replaceable></term>
+                <listitem>
+                    <para>
+                        This option indicates that an auto-delete
+                        exchange of the specified type should be
+                        created.  The name of the exchange should be
+                        given by the <option>--exchange</option>
+                        option.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-r</option></term>
+                <term><option>--routing-key</option>=<replaceable class="parameter">routing key</replaceable></term>
+                <listitem>
+                    <para>
+                        The routing key for the binding.  If omitted,
+                        an empty routing key is assumed.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-A</option></term>
+                <term><option>--no-ack</option>=<replaceable class="parameter">routing key</replaceable></term>
+                <listitem>
+                    <para>
+                        Enable <quote>no ack</quote> mode: The AMQP
+                        server will unconditionally acknowledge each
+                        message that is delivered, regardless of
+                        whether the target command exits successfully
+                        or not.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>Examples</title>
+        <variablelist>
+            <varlistentry>
+                <term>Consume messages from the queue
+                <quote><systemitem
+                class="resource">myqueue</systemitem></quote>, and
+                output the message bodies on standard output via
+                <command>cat</command>:</term>
+                <listitem>
+                    <screen><prompt>$ </prompt><userinput>amqp-publish -q myqueue cat</userinput></screen>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>Bind a newly created auto-delete queue to an
+                exchange <quote><systemitem
+                class="resource">myexch</systemitem></quote>, and send
+                each message body to the script
+                <filename>myscript</filename>, automatically
+                acknowledging them on the server:</term>
+                <listitem>
+                    <screen><prompt>$ </prompt><userinput>amqp-consume -A -e myexch ./myscript</userinput></screen>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>See also</title>
+        <para>
+            <citerefentry><refentrytitle>librabbitmq-tools</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+            describes connection-related options common to all the
+            RabbitMQ C Client tools.
+        </para>
+    </refsect1>
+</refentry>
diff --git a/tools/doc/get.xml b/tools/doc/get.xml
new file mode 100644
index 0000000..9770a8b
--- /dev/null
+++ b/tools/doc/get.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
+[
+<!ENTITY date SYSTEM "man-date.ent" >
+]
+>
+<refentry lang="en">
+    <refentryinfo>
+        <productname>RabbitMQ C Client</productname>
+        <authorgroup>
+            <corpauthor>The RabbitMQ Team &lt;<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>&gt;</corpauthor>
+        </authorgroup>
+        <date>&date;</date>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>amqp-get</refentrytitle>
+        <manvolnum>1</manvolnum>
+        <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo>
+    </refmeta>
+
+    <refnamediv>
+        <refname>amqp-get</refname>
+        <refpurpose>Get a message from a queue on an AMQP server</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+        <cmdsynopsis>
+            <command>amqp-get</command>
+            <arg choice="opt" rep="repeat">
+                <replaceable>OPTION</replaceable>
+            </arg>
+            <arg choice="req">-q <replaceable>queue name</replaceable></arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+    
+    <refsect1>
+        <title>Description</title>
+        <para>
+            <command>amqp-get</command> attempts to consume a single
+            message from a queue on an AMQP server, and exits.  Unless
+            the queue was empty, the body of the resulting message is
+            sent to standard output.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Options</title>
+        <variablelist>
+            <varlistentry>
+                <term><option>-q</option></term>
+                <term><option>--queue</option>=<replaceable class="parameter">queue name</replaceable></term>
+                <listitem>
+                    <para>
+                        The name of the queue to consume messages
+                        from.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>Exit Status</title>
+        <para>
+            If the queue is not empty, and a message is successfully
+            retrieved, the exit status is 0.  If an error occurs, the
+            exit status is 1.  If the queue is found to be empty, the
+            exit status is 2.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Examples</title>
+        <variablelist>
+            <varlistentry>
+                <term>Get a message from the queue <quote><systemitem
+                class="resource">myqueue</systemitem></quote>, and
+                display its body on standard output:</term>
+                <listitem>
+                    <screen><prompt>$ </prompt><userinput>amqp-get -q myqueue</userinput></screen>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>See also</title>
+        <para>
+            <citerefentry><refentrytitle>librabbitmq-tools</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+            describes connection-related options common to all the
+            RabbitMQ C Client tools.
+        </para>
+    </refsect1>
+</refentry>
diff --git a/tools/doc/librabbitmq-tools.xml b/tools/doc/librabbitmq-tools.xml
new file mode 100644
index 0000000..41f092a
--- /dev/null
+++ b/tools/doc/librabbitmq-tools.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
+[
+<!ENTITY date SYSTEM "man-date.ent" >
+]
+>
+<refentry lang="en">
+    <refentryinfo>
+        <productname>RabbitMQ C Client</productname>
+        <authorgroup>
+            <corpauthor>The RabbitMQ Team &lt;<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>&gt;</corpauthor>
+        </authorgroup>
+        <date>&date;</date>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>librabbitmq-tools</refentrytitle>
+        <manvolnum>7</manvolnum>
+        <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo>
+    </refmeta>
+
+    <refnamediv>
+        <refname>librabbitmq-tools</refname>
+        <refpurpose>Command line AMQP tools</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Description</title>
+        <para>
+            A set of command line AMQP tools based on <systemitem
+            class="library">librabbitmq</systemitem>.  This page
+            describes common options and conventions used by all of
+            the tools.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Common Options</title>
+        <variablelist>
+            <varlistentry>
+                <term><option>-s</option></term>
+                <term><option>--server</option>=<replaceable class="parameter">hostname:port</replaceable></term>
+                <listitem>
+                    <para>
+                        The host name (or address) to connect to.
+                        Defaults to localhost.  The port number may
+                        also be specified; if omitted, it defaults to
+                        the standard AMQP port number (5672).
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>--vhost</option>=<replaceable class="parameter">vhost</replaceable></term>
+                <listitem>
+                    <para>
+                        The AMQP vhost to specify when connnecting.
+                        Defaults to <literal>/</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>--username</option>=<replaceable class="parameter">username</replaceable></term>
+                <listitem>
+                    <para>
+                        The username to authenticate to the AMQP server with.  Defaults to <literal>guest</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>--password</option>=<replaceable class="parameter">password</replaceable></term>
+                <listitem>
+                    <para>
+                        The password to authenticate to the AMQP server with.  Defaults to <literal>guest</literal>.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>See also</title>
+        <para>
+            <simplelist type='inline'>
+                <member><citerefentry><refentrytitle>amqp-publish</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+                <member><citerefentry><refentrytitle>amqp-consume</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+                <member><citerefentry><refentrytitle>amqp-get</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+            </simplelist>
+        </para>
+    </refsect1>
+</refentry>
diff --git a/tools/doc/publish.xml b/tools/doc/publish.xml
new file mode 100644
index 0000000..d2e8d2e
--- /dev/null
+++ b/tools/doc/publish.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd"
+[
+<!ENTITY date SYSTEM "man-date.ent" >
+]
+>
+<refentry lang="en">
+    <refentryinfo>
+        <productname>RabbitMQ C Client</productname>
+        <authorgroup>
+            <corpauthor>The RabbitMQ Team &lt;<ulink url="mailto:info@rabbitmq.com"><email>info@rabbitmq.com</email></ulink>&gt;</corpauthor>
+        </authorgroup>
+        <date>&date;</date>
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>amqp-publish</refentrytitle>
+        <manvolnum>1</manvolnum>
+        <refmiscinfo class="manual">RabbitMQ C Client</refmiscinfo>
+    </refmeta>
+
+    <refnamediv>
+        <refname>amqp-publish</refname>
+        <refpurpose>Publish a message on an AMQP server</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+        <cmdsynopsis>
+            <command>amqp-publish</command>
+            <arg choice="opt" rep="repeat">
+                <replaceable>OPTION</replaceable>
+            </arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+    
+    <refsect1>
+        <title>Description</title>
+        <para>
+            Publishes a message to an exchange on an AMQP server.
+            Options allow the various properties of the message and
+            parameters of the AMQP <function>basic.publish</function>
+            method to be specified.
+        </para>
+        <para>
+            By default, the message body is read from standard input.
+            Alternatively, the <option>-b</option> option allows the message
+            body to be provided as part of the command.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Options</title>
+        <variablelist>
+            <varlistentry>
+                <term><option>-e</option></term>
+                <term><option>--exchange</option>=<replaceable class="parameter">exchange name</replaceable></term>
+                <listitem>
+                    <para>
+                        The name of the exchange to publish to.  If
+                        omitted, the default exchange (also known as
+                        the nameless exchange) is used.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-r</option></term>
+                <term><option>--routing-key</option>=<replaceable class="parameter">routing key</replaceable></term>
+                <listitem>
+                    <para>
+                        The routing key to publish with.  If omitted,
+                        an empty routing key is assumed.  A routing
+                        key must be specified when publishing to the
+                        default exchange; in that case, accoding to
+                        the AMQP specification, the routing key
+                        corresponds to a queue name.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-p</option></term>
+                <term><option>--persistent</option></term>
+                <listitem>
+                    <para>
+                        Use the persistent delivery mode.  Without
+                        this option, non-persistent delivery is used.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-C</option></term>
+                <term><option>--content-type</option>=<replaceable class="parameter">MIME type</replaceable></term>
+                <listitem>
+                    <para>
+                        Specifies the content-type property for the
+                        message.  If omitted, the content-type
+                        property is not set on the message.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-E</option></term>
+                <term><option>--content-encoding</option>=<replaceable class="parameter">content coding</replaceable></term>
+                <listitem>
+                    <para>
+                        Specifies the content-encoding property for
+                        the message.  If omitted, the content-encoding
+                        property is not set on the message.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term><option>-b</option></term>
+                <term><option>--body</option>=<replaceable class="parameter">message body</replaceable></term>
+                <listitem>
+                    <para>
+                        Specifies the message body.  If omitted, the
+                        message body is read from standard input.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>Examples</title>
+        <variablelist>
+            <varlistentry>
+                <term>Send a short message, consisting of the word
+                <quote><literal>Hello</literal></quote> to the queue
+                <quote><systemitem
+                class="resource">myqueue</systemitem></quote> via the
+                default exchange:</term>
+                <listitem>
+                    <screen><prompt>$ </prompt><userinput>amqp-publish -r myqueue -b Hello</userinput></screen>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>Send some XML data from a file to the exchange
+                <quote><systemitem
+                class="resource">events</systemitem></quote>, with
+                persistent delivery mode, setting the content-type
+                property on the message to make the data format
+                explicit:</term>
+                <listitem>
+                    <screen><prompt>$ </prompt><userinput>amqp-publish -e events -p -C text/xml &lt;event.xml</userinput></screen>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsect1>
+
+    <refsect1>
+        <title>See also</title>
+        <para>
+            <citerefentry><refentrytitle>librabbitmq-tools</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+            describes connection-related options common to all the
+            RabbitMQ C Client tools.
+        </para>
+    </refsect1>
+</refentry>