man: enhance the description of systemd-stdio-bridge

I hope that this fixes the comment
https://github.com/systemd/systemd/pull/22141#issuecomment-1013960371
> As someone who doesn't know what this prog does

The listing in the man page is sorted according to logical
use: all the options setting the address are now together.

diff --git a/man/systemd-stdio-bridge.xml b/man/systemd-stdio-bridge.xml
index bef61cb7cfe370b3d7ac5de23440785ea13276ab..002a91b12998c270cf6015c326bbff9af348de4d 100644 (file)
--- a/man/systemd-stdio-bridge.xml
+++ b/man/systemd-stdio-bridge.xml
@@ -31,9 +31,23 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-stdio-bridge</command> may be used as a STDIO or socket-activatable
-    proxy to a given D-Bus endpoint.</para>
-
+    <para><command>systemd-stdio-bridge</command> implements a proxy for a D-Bus endpoint. It expects to
+    receive an open connection to a bus when started, and will also connect to a (different) bus as a
+    client. It will then act as a server on the first connection, and forward messages between the two
+    busses. This program is suitable for socket activation: the first connection may be a pipe or a socket
+    and must be passed as either standard input, or as an open file descriptor according to the protocol
+    described in
+    <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
+    second connection will be made by default to the local system bus, but this can be influenced by the
+    <option>--user</option>, <option>--system</option>, <option>--machine=</option>, and
+    <option>--bus-path=</option> options described below.</para>
+
+    <para><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> uses
+    <command>systemd-stdio-bridge</command> to forward D-Bus connections over
+    <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+    or to connect to the bus of a different user, see
+    <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    </para>
   </refsect1>
 
   <refsect1>
@@ -42,6 +56,10 @@
     <para>The following options are understood:</para>
 
     <variablelist>
+      <xi:include href="user-system-options.xml" xpointer="user" />
+      <xi:include href="user-system-options.xml" xpointer="system" />
+      <xi:include href="user-system-options.xml" xpointer="machine" />
+
       <varlistentry>
           <term><option>-p <replaceable>PATH</replaceable></option></term>
           <term><option>--bus-path=<replaceable>PATH</replaceable></option></term>
@@ -52,9 +70,6 @@
 
       <xi:include href="standard-options.xml" xpointer="help" />
       <xi:include href="standard-options.xml" xpointer="version" />
-      <xi:include href="user-system-options.xml" xpointer="user" />
-      <xi:include href="user-system-options.xml" xpointer="system" />
-      <xi:include href="user-system-options.xml" xpointer="machine" />
     </variablelist>
   </refsect1>
 
@@ -70,7 +85,6 @@
       <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='dbus'><refentrytitle>dbus-broker</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <ulink url="https://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
-      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
   </refsect1>

diff --git a/src/stdio-bridge/stdio-bridge.c b/src/stdio-bridge/stdio-bridge.c
index b45f7912cbedf90442d818e3e0bb5b15da4a18cb..5d4ffa5e32329528a8d8fec2f11c88111944377f 100644 (file)
--- a/src/stdio-bridge/stdio-bridge.c
+++ b/src/stdio-bridge/stdio-bridge.c
@@ -28,7 +28,7 @@ static bool arg_user = false;
 static int help(void) {
 
         printf("%s [OPTIONS...]\n\n"
-               "STDIO or socket-activatable proxy to a given DBus endpoint.\n\n"
+               "Forward messages between two D-Bus busses via a pipe or socket.\n\n"
                "  -h --help              Show this help\n"
                "     --version           Show package version\n"
                "  -p --bus-path=PATH     Path to the bus address (default: %s)\n"