Add patch from upstream to add a man page for dbus-test-tool

4 files changed, 372 insertions, 0 deletions

diff --git a/debian/changelog b/debian/changelog
index 8e43fd6d..68953a95 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -9,6 +9,7 @@ dbus (1.9.10-2) UNRELEASED; urgency=medium
   * Move installed-tests to new dbus-tests package, and add dbus-test-tool
     to that package
   * dbus-x11: use dbus-x11.install for the Xsession hook
+  * Add patch from upstream to add a man page for dbus-test-tool
   * If DEB_BUILD_OPTIONS=noudeb, don't do the udeb build, for a 30% speedup
 
  -- Simon McVittie <smcv@debian.org>  Mon, 09 Feb 2015 17:53:51 +0000
diff --git a/debian/dbus-tests.install b/debian/dbus-tests.install
index a7591142..2a73f982 100644
--- a/debian/dbus-tests.install
+++ b/debian/dbus-tests.install
@@ -1,3 +1,4 @@
 debian/tmp/usr/bin/dbus-test-tool
+debian/tmp/usr/share/man/man1/dbus-test-tool.1
 debian/tmp/usr/share/installed-tests/dbus
 debian/tmp/usr/lib/dbus-1.0/installed-tests
diff --git a/debian/patches/Document-dbus-test-tool.patch b/debian/patches/Document-dbus-test-tool.patch
new file mode 100644
index 00000000..98196c72
--- /dev/null
+++ b/debian/patches/Document-dbus-test-tool.patch
@@ -0,0 +1,369 @@
+From: Simon McVittie <simon.mcvittie@collabora.co.uk>
+Date: Wed, 11 Feb 2015 16:59:42 +0000
+Subject: Document dbus-test-tool
+
+Bug: https://bugs.freedesktop.org/show_bug.cgi?id=89086
+Reviewed-by: Philip Withnall <philip.withnall@collabora.co.uk>
+Applied-upstream: 1.9.12, commit:15506779a70d8ac38c2bb302ab83d2c1924aea6d
+---
+ configure.ac                |   1 +
+ doc/Makefile.am             |   1 +
+ doc/dbus-test-tool.1.xml.in | 325 ++++++++++++++++++++++++++++++++++++++++++++
+ 3 files changed, 327 insertions(+)
+ create mode 100644 doc/dbus-test-tool.1.xml.in
+
+diff --git a/configure.ac b/configure.ac
+index ee87caa..b765b72 100644
+--- a/configure.ac
++++ b/configure.ac
+@@ -1789,6 +1789,7 @@ doc/dbus-launch.1.xml
+ doc/dbus-monitor.1.xml
+ doc/dbus-run-session.1.xml
+ doc/dbus-send.1.xml
++doc/dbus-test-tool.1.xml
+ doc/dbus-uuidgen.1.xml
+ dbus-1.pc
+ dbus-1-uninstalled.pc
+diff --git a/doc/Makefile.am b/doc/Makefile.am
+index b9a4c10..3879a61 100644
+--- a/doc/Makefile.am
++++ b/doc/Makefile.am
+@@ -7,6 +7,7 @@ man_pages = \
+ 	dbus-monitor.1 \
+ 	dbus-run-session.1 \
+ 	dbus-send.1 \
++	dbus-test-tool.1 \
+ 	dbus-uuidgen.1 \
+ 	$(NULL)
+ 
+diff --git a/doc/dbus-test-tool.1.xml.in b/doc/dbus-test-tool.1.xml.in
+new file mode 100644
+index 0000000..091dee1
+--- /dev/null
++++ b/doc/dbus-test-tool.1.xml.in
+@@ -0,0 +1,325 @@
++<?xml version="1.0" encoding="ISO-8859-1"?>
++<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
++<refentry id="dbus-test-tool.1">
++  <refentryinfo>
++    <copyright>
++      <year>2015</year>
++      <holder>Collabora Ltd.</holder>
++    </copyright>
++    <legalnotice>
++      <para>This man page is distributed under the same terms as
++        dbus-test-tool (GPL-2+). There is NO WARRANTY, to the extent
++        permitted by law.</para>
++    </legalnotice>
++  </refentryinfo>
++
++  <refmeta>
++    <refentrytitle>dbus-test-tool</refentrytitle>
++    <manvolnum>1</manvolnum>
++    <refmiscinfo class="manual">User Commands</refmiscinfo>
++    <refmiscinfo class="source">D-Bus</refmiscinfo>
++    <refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo>
++  </refmeta>
++  <refnamediv>
++    <refname>dbus-test-tool</refname>
++    <refpurpose>D-Bus traffic generator and test tool</refpurpose>
++  </refnamediv>
++
++  <refsynopsisdiv id="synopsis">
++    <cmdsynopsis>
++      <command>dbus-test-tool</command>
++      <arg choice="plain">black-hole</arg>
++      <group choice="opt">
++        <arg choice="plain">--session</arg>
++        <arg choice="plain">--system</arg>
++      </group>
++      <arg choice="opt">--name=<replaceable>NAME</replaceable></arg>
++      <arg choice="opt">--no-read</arg>
++    </cmdsynopsis>
++
++    <cmdsynopsis>
++      <command>dbus-test-tool</command>
++      <arg choice="plain">echo</arg>
++      <group choice="opt">
++        <arg choice="plain">--session</arg>
++        <arg choice="plain">--system</arg>
++      </group>
++      <arg choice="opt">--name=<replaceable>NAME</replaceable></arg>
++      <arg choice="opt">--sleep=<replaceable>MS</replaceable></arg>
++    </cmdsynopsis>
++
++    <cmdsynopsis>
++      <command>dbus-test-tool</command>
++      <arg choice="plain">spam</arg>
++      <group choice="opt">
++        <arg choice="plain">--session</arg>
++        <arg choice="plain">--system</arg>
++      </group>
++      <arg choice="opt">--dest=<replaceable>NAME</replaceable></arg>
++      <arg choice="opt">--count=<replaceable>N</replaceable></arg>
++      <arg choice="opt">--flood</arg>
++      <arg choice="opt">--ignore-errors</arg>
++      <arg choice="opt">--messages-per-conn=<replaceable>N</replaceable></arg>
++      <arg choice="opt">--no-reply</arg>
++      <arg choice="opt">--queue=<replaceable>N</replaceable></arg>
++      <arg choice="opt">--seed=<replaceable>SEED</replaceable></arg>
++      <group choice="opt">
++        <arg choice="plain">--string</arg>
++        <arg choice="plain">--bytes</arg>
++        <arg choice="plain">--empty</arg>
++      </group>
++      <group choice="opt">
++        <arg choice="plain">--payload=<replaceable>S</replaceable></arg>
++        <arg choice="plain">--stdin</arg>
++        <arg choice="plain">--message-stdin</arg>
++        <arg choice="plain">--random-size</arg>
++      </group>
++    </cmdsynopsis>
++  </refsynopsisdiv>
++
++  <refsect1 id="description">
++    <title>DESCRIPTION</title>
++    <para><command>dbus-test-tool</command> is a multi-purpose tool
++      for debugging and profiling D-Bus.</para>
++
++    <para><command>dbus-test-tool black-hole</command>
++      connects to D-Bus, optionally requests a name, then does not
++      reply to messages. It normally reads and discards messages from
++      its D-Bus socket, but can be configured to sleep forever without
++      reading.</para>
++
++    <para><command>dbus-test-tool echo</command>
++      connects to D-Bus, optionally requests a name, then sends back an
++      empty reply to every method call, after an optional delay.</para>
++
++    <para><command>dbus-test-tool spam</command>
++      connects to D-Bus and makes repeated method calls,
++      normally named <literal>com.example.Spam</literal>.</para>
++  </refsect1>
++
++  <refsect1 id="options">
++    <title>OPTIONS</title>
++    <refsect2>
++      <title>Common options</title>
++      <variablelist remap="TP">
++
++        <varlistentry>
++          <term><option>--session</option></term>
++          <listitem>
++            <para>Connect to the session bus. This is the default.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--system</option></term>
++          <listitem>
++            <para>Connect to the system bus.</para>
++          </listitem>
++        </varlistentry>
++
++      </variablelist>
++    </refsect2>
++
++    <refsect2>
++      <title>black-hole mode</title>
++      <variablelist remap="TP">
++
++        <varlistentry>
++          <term><option>--name=</option><replaceable>NAME</replaceable></term>
++          <listitem>
++            <para>Before proceeding, request ownership of the well-known
++              bus name <replaceable>NAME</replaceable>, for example
++              <literal>com.example.NoReply</literal>. By default,
++              no name is requested, and the tool can only be addressed by
++              a unique bus name such as <literal>:1.23</literal>.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--no-read</option></term>
++          <listitem>
++            <para>Do not read from the D-Bus socket.</para>
++          </listitem>
++        </varlistentry>
++
++      </variablelist>
++    </refsect2>
++
++    <refsect2>
++      <title>echo mode</title>
++      <variablelist remap="TP">
++
++        <varlistentry>
++          <term><option>--name=</option><replaceable>NAME</replaceable></term>
++          <listitem>
++            <para>Before proceeding, request ownership of the well-known
++              bus name <replaceable>NAME</replaceable>, for example
++              <literal>com.example.Echo</literal>. By default,
++              no name is requested, and the tool can only be addressed by
++              a unique bus name such as <literal>:1.23</literal>.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--sleep=</option><replaceable>MS</replaceable></term>
++          <listitem>
++            <para>Block for <replaceable>MS</replaceable> milliseconds
++              before replying to a method call.</para>
++          </listitem>
++        </varlistentry>
++
++      </variablelist>
++    </refsect2>
++
++    <refsect2>
++      <title>spam mode</title>
++      <variablelist remap="TP">
++
++        <varlistentry>
++          <term><option>--dest=</option><replaceable>NAME</replaceable></term>
++          <listitem>
++            <para>Send method calls to the well-known or unique
++              bus name <replaceable>NAME</replaceable>.
++              The default is the dbus-daemon,
++              <literal>org.freedesktop.DBus</literal>.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--count=</option><replaceable>N</replaceable></term>
++          <listitem>
++            <para>Send <replaceable>N</replaceable> method calls in total.
++              The default is 1.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--queue=</option><replaceable>N</replaceable></term>
++          <listitem>
++            <para>Send <replaceable>N</replaceable> method calls before
++              waiting for any replies, then send one new call per reply
++              received, keeping <replaceable>N</replaceable> method calls
++              "in flight" at all times until the number of messages specified
++              with the <option>--count</option> option have been sent.
++              The default is 1, unless <option>--flood</option>
++              is used.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--flood</option></term>
++          <listitem>
++            <para>Send all messages without waiting for a reply,
++              equivalent to <option>--queue</option> with an arbitrarily
++              large <replaceable>N</replaceable>.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--no-reply</option></term>
++          <listitem>
++            <para>Set the "no reply desired" flag on the messages.
++              This implies <option>--flood</option>, since it disables
++              the replies that would be used for a finite
++              <option>--queue</option> length.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--messages-per-conn=</option><replaceable>N</replaceable></term>
++          <listitem>
++            <para>If given, send <replaceable>N</replaceable> method calls
++              on the same connection, then disconnect and reconnect.
++              The default is to use the same connection for all method
++              calls.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--string</option></term>
++          <listitem>
++            <para>The payload of each message is a UTF-8 string. This is the
++              default. The actual string used is given by the
++              <option>--payload</option> or <option>--stdin</option>
++              option, defaulting to "hello, world!".</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--bytes</option></term>
++          <listitem>
++            <para>The payload of each message is a byte-array.
++              The actual bytes used are given by the
++              <option>--payload</option> or <option>--stdin</option>
++              option, defaulting to the ASCII encoding of
++              "hello, world!".</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--empty</option></term>
++          <listitem>
++            <para>The messages have no payload.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--payload=</option><replaceable>S</replaceable></term>
++          <listitem>
++            <para>Use <replaceable>S</replaceable> as the
++              <option>--string</option> or <option>--bytes</option>
++              in the messages. The default is "hello, world!".</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--stdin</option></term>
++          <listitem>
++            <para>Read from standard input until end-of-file is reached,
++              and use that as the <option>--string</option> or
++              <option>--bytes</option> in the messages.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--message-stdin</option></term>
++          <listitem>
++            <para>Read a complete binary D-Bus method call message from
++              standard input, and use that for each method call.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--random-size</option></term>
++          <listitem>
++            <para>Read whitespace-separated ASCII decimal numbers from
++              standard input, choose one at random for each message,
++              and send a message whose payload is a string of that
++              length.</para>
++          </listitem>
++        </varlistentry>
++
++        <varlistentry>
++          <term><option>--seed=</option><replaceable>SEED</replaceable></term>
++          <listitem>
++            <para>Use <replaceable>SEED</replaceable> as the seed
++              for the pseudorandom number generator, to have somewhat
++              repeatable sequences of random messages.</para>
++          </listitem>
++        </varlistentry>
++
++      </variablelist>
++    </refsect2>
++  </refsect1>
++
++  <refsect1 id="bugs">
++    <title>BUGS</title>
++      <para>Please send bug reports to the D-Bus bug tracker or mailing list.
++        See <ulink url="http://www.freedesktop.org/software/dbus/">http://www.freedesktop.org/software/dbus/</ulink>.</para>
++  </refsect1>
++
++  <refsect1 id="see_also">
++    <title>SEE ALSO</title>
++    <para><citerefentry><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
++  </refsect1>
++</refentry>
diff --git a/debian/patches/series b/debian/patches/series
index 77406a3a..906f1ddf 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -1,2 +1,3 @@
+Document-dbus-test-tool.patch
 Reduce-the-number-of-fds-the-fdpass-test-uses.patch
 Don-t-abort-on-fatal-warnings-by-default.patch