From 48f99d7c069e07671e570161aecbe109af1285e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Fri, 24 Apr 2020 12:08:10 +0200
Subject: [PATCH] man: use --bus-introspect to autogenerate dbus api docs

This has the advantage that the executables are always in place and we don't
need any units to exist on the bus, so we can eventually hook this up into
a normal build system. (Probably as a build time check.)
---
 man/org.freedesktop.hostname1.xml |  19 +++-
 man/org.freedesktop.import1.xml   |  34 +++++--
 man/org.freedesktop.locale1.xml   |  20 +++-
 man/org.freedesktop.login1.xml    | 151 +++++++++++++++++++++++++----
 man/org.freedesktop.machine1.xml  |  36 +++++--
 man/org.freedesktop.resolve1.xml  |  38 +++++---
 man/org.freedesktop.systemd1.xml  | 155 ++++++++++++++----------------
 man/org.freedesktop.timedate1.xml |  20 +++-
 8 files changed, 325 insertions(+), 148 deletions(-)

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index 406a6a369e9..d17d9a55213 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -38,11 +38,7 @@
 
     <para>The service exposes the following interfaces on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.hostname1 \
-        --object-path /org/freedesktop/hostname1
-
+    <programlisting executable="systemd-hostnamed" node="/org/freedesktop/hostname1" interface="org.freedesktop.hostname1">
 node /org/freedesktop/hostname1 {
   interface org.freedesktop.hostname1 {
     methods:
@@ -349,6 +345,19 @@ node /org/freedesktop/hostname1 {
     the usual interface versioning guidelines</ulink>.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.hostname1</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system \
+  --dest org.freedesktop.hostname1 \
+  --object-path /org/freedesktop/hostname1
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>See also</title>
 
diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml
index 4a425f1ac3d..1414cc15d79 100644
--- a/man/org.freedesktop.import1.xml
+++ b/man/org.freedesktop.import1.xml
@@ -46,11 +46,7 @@
 
     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.import1 \
-        --object-path /org/freedesktop/import1
-
+    <programlisting executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager">
 node /org/freedesktop/import1 {
   interface org.freedesktop.import1.Manager {
     methods:
@@ -238,11 +234,7 @@ node /org/freedesktop/import1 {
   <refsect1>
     <title>The Transfer Object</title>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.import1 \
-        --object-path /org/freedesktop/import1/transfer/_1
-
+    <programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer">
 node /org/freedesktop/import1/transfer/_1 {
   interface org.freedesktop.import1.Transfer {
     methods:
@@ -325,6 +317,28 @@ node /org/freedesktop/import1/transfer/_1 {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system \
+  --dest org.freedesktop.import1 \
+  --object-path /org/freedesktop/import1
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system \
+  --dest org.freedesktop.import1 \
+  --object-path /org/freedesktop/import1/transfer/_1
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>
 
diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml
index f15945e766a..3956eaf8a7b 100644
--- a/man/org.freedesktop.locale1.xml
+++ b/man/org.freedesktop.locale1.xml
@@ -34,11 +34,7 @@
 
     <para>The service exposes the following interfaces on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.locale1 \
-        --object-path /org/freedesktop/locale1
-
+    <programlisting executable="systemd-localed" node="/org/freedesktop/locale1" interface="org.freedesktop.locale1">
 node /org/freedesktop/locale1 {
   interface org.freedesktop.locale1 {
     methods:
@@ -169,6 +165,20 @@ node /org/freedesktop/locale1 {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.locale1</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.locale1 \
+  --object-path /org/freedesktop/locale1
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>
 
diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index aedf5d7fc32..8de6cf513de 100644
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -38,11 +38,7 @@
 
     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.login1 \
-        --object-path /org/freedesktop/login1
-
+    <programlisting executable="systemd-logind" node="/org/freedesktop/login1" interface="org.freedesktop.login1.Manager">
 node /org/freedesktop/login1 {
   interface org.freedesktop.login1.Manager {
     methods:
@@ -741,10 +737,7 @@ node /org/freedesktop/login1 {
   <refsect1>
     <title>Seat Objects</title>
 
-    <programlisting>
-$ gdbus introspect --system --dest org.freedesktop.login1 \
-      --object-path /org/freedesktop/login1/seat/seat0
-
+    <programlisting executable="systemd-logind" node="/org/freedesktop/login1/seat/seat0" interface="org.freedesktop.login1.Seat">
 node /org/freedesktop/login1/seat/seat0 {
   interface org.freedesktop.login1.Seat {
     methods:
@@ -856,10 +849,7 @@ node /org/freedesktop/login1/seat/seat0 {
   <refsect1>
     <title>User Objects</title>
 
-    <programlisting>
-$ gdbus introspect --system --dest org.freedesktop.login1 \
-        --object-path /org/freedesktop/login1/user/_1000
-
+    <programlisting executable="systemd-logind" node="/org/freedesktop/login1/user/_1000" interface="org.freedesktop.login1.User">
 node /org/freedesktop/login1/user/_1000 {
   interface org.freedesktop.login1.User {
     methods:
@@ -1004,11 +994,8 @@ node /org/freedesktop/login1/user/_1000 {
   <refsect1>
     <title>Session Objects</title>
 
-    <programlisting>
-$ gdbus introspect --system --dest org.freedesktop.login1 \
-        --object-path /org/freedesktop/login1/session/45
-
-node /org/freedesktop/login1/session/45 {
+    <programlisting executable="systemd-logind" node="/org/freedesktop/login1/session/1" interface="org.freedesktop.login1.Session">
+node /org/freedesktop/login1/session/1 {
   interface org.freedesktop.login1.Session {
     methods:
       Terminate();
@@ -1093,6 +1080,98 @@ node /org/freedesktop/login1/session/45 {
 };
     </programlisting>
 
+    <!--Autogenerated cross-references for systemd.directives, do not edit-->
+
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Session"/>
+
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.login1.Session"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="Lock()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetIdleHint()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetLockedHint()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="TakeControl()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="ReleaseControl()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="TakeDevice()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="ReleaseDevice()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="PauseDeviceComplete()"/>
+
+    <variablelist class="dbus-method" generated="True" extra-ref="SetBrightness()"/>
+
+    <variablelist class="dbus-signal" generated="True" extra-ref="PauseDevice"/>
+
+    <variablelist class="dbus-signal" generated="True" extra-ref="ResumeDevice"/>
+
+    <variablelist class="dbus-signal" generated="True" extra-ref="Lock"/>
+
+    <variablelist class="dbus-signal" generated="True" extra-ref="Unlock"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Id"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="User"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Name"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="VTNr"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Seat"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="TTY"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Display"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Remote"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="RemoteHost"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="RemoteUser"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Service"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Desktop"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Scope"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Leader"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Audit"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Type"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Class"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="Active"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="State"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="IdleHint"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHint"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="IdleSinceHintMonotonic"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="LockedHint"/>
+
+    <!--End of Autogenerated section-->
+
     <refsect2>
       <title>Methods</title>
 
@@ -1257,6 +1336,42 @@ node /org/freedesktop/login1/session/45 {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.login1.Manager</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
+  --object-path /org/freedesktop/login1
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.login1.Seat</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
+ --object-path /org/freedesktop/login1/seat/seat0
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.login1.User</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
+  --object-path /org/freedesktop/login1/user/_1000
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.login1.Session</interfacename> on the bus</title>
+
+      <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
+  --object-path /org/freedesktop/login1/session/45
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>
 
diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml
index bc9779c5212..c18e133e7cb 100644
--- a/man/org.freedesktop.machine1.xml
+++ b/man/org.freedesktop.machine1.xml
@@ -34,11 +34,7 @@
 
     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.machine1 \
-        --object-path /org/freedesktop/machine1
-
+    <programlisting executable="systemd-machined" node="/org/freedesktop/machine1" interface="org.freedesktop.machine1.Manager">
 node /org/freedesktop/machine1 {
   interface org.freedesktop.machine1.Manager {
     methods:
@@ -435,11 +431,7 @@ node /org/freedesktop/machine1 {
   <refsect1>
     <title>Machine Objects</title>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.machine1 \
-        --object-path /org/freedesktop/machine1/machine/rawhide
-
+    <programlisting executable="systemd-machined" node="/org/freedesktop/machine1/machine/rawhide" interface="org.freedesktop.machine1.Machine">
 node /org/freedesktop/machine1/machine/rawhide {
   interface org.freedesktop.machine1.Machine {
     methods:
@@ -617,6 +609,30 @@ node /org/freedesktop/machine1/machine/rawhide {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.machine1.Manager</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.machine1 \
+  --object-path /org/freedesktop/machine1
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.machine1.Machine</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.machine1 \
+  --object-path /org/freedesktop/machine1/machine/rawhide
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>
 
diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml
index 912f73677cf..86bd1c2a622 100644
--- a/man/org.freedesktop.resolve1.xml
+++ b/man/org.freedesktop.resolve1.xml
@@ -46,11 +46,7 @@
 
     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.resolve1 \
-        --object-path /org/freedesktop/resolve1
-
+    <programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1" interface="org.freedesktop.resolve1.Manager">
 node /org/freedesktop/resolve1 {
   interface org.freedesktop.resolve1.Manager {
     methods:
@@ -551,12 +547,8 @@ node /org/freedesktop/resolve1 {
   <refsect1>
     <title>Link Object</title>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.resolve1 \
-        --object-path /org/freedesktop/resolve1/link/_34
-
-node /org/freedesktop/resolve1/link/_34 {
+    <programlisting executable="systemd-resolved" node="/org/freedesktop/resolve1/link/_1" interface="org.freedesktop.resolve1.Link">
+node /org/freedesktop/resolve1/link/_1 {
   interface org.freedesktop.resolve1.Link {
     methods:
       SetDNS(in  a(iay) addresses);
@@ -790,6 +782,30 @@ node /org/freedesktop/resolve1/link/_34 {
     </variablelist>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.resolve1.Manager</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.resolve1 \
+  --object-path /org/freedesktop/resolve1
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.resolve1.Link</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.resolve1 \
+  --object-path /org/freedesktop/resolve1/link/_11
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>
 
diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index da5541be900..741fd3d481a 100644
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -57,11 +57,7 @@
     <para>The main entry point object is available on the fixed
     <constant>/org/freedesktop/systemd1</constant> object path:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.systemd1 \
-        --object-path /org/freedesktop/systemd1
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1" interface="org.freedesktop.systemd1.Manager">
 node /org/freedesktop/systemd1 {
   interface org.freedesktop.systemd1.Manager {
     methods:
@@ -1484,10 +1480,7 @@ node /org/freedesktop/systemd1 {
   <refsect1>
     <title>Unit Objects</title>
 
-    <programlisting interface="org.freedesktop.systemd1.Unit">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice" interface="org.freedesktop.systemd1.Unit">
 node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
   interface org.freedesktop.systemd1.Unit {
     methods:
@@ -1674,7 +1667,6 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
   interface org.freedesktop.DBus.Peer { ... };
   interface org.freedesktop.DBus.Introspectable { ... };
   interface org.freedesktop.DBus.Properties { ... };
-  interface org.freedesktop.systemd1.Service { ... };
 };
     </programlisting>
 
@@ -1746,12 +1738,8 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Service"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Service"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="Start()"/>
@@ -2139,10 +2127,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
     <interfacename>org.freedesktop.systemd1.Service</interfacename> interface (described here) in addition to
     the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Service">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice" interface="org.freedesktop.systemd1.Service">
 node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
   interface org.freedesktop.systemd1.Service {
     methods:
@@ -3135,14 +3120,14 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Service"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Service"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Service"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetProcesses()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="AttachProcesses()"/>
@@ -3746,10 +3731,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
   <refsect1>
     <title>Socket Unit Objects</title>
 
-    <programlisting interface="org.freedesktop.systemd1.Socket">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket" interface="org.freedesktop.systemd1.Socket">
 node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket {
   interface org.freedesktop.systemd1.Socket {
     methods:
@@ -4777,14 +4759,14 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Socket"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Socket"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Socket"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetProcesses()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="AttachProcesses()"/>
@@ -5340,10 +5322,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket {
   <refsect1>
     <title>Target Unit Objects</title>
 
-    <programlisting interface="org.freedesktop.systemd1.Target">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/basic_2etarget
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/basic_2etarget" interface="org.freedesktop.systemd1.Target">
 node /org/freedesktop/systemd1/unit/basic_2etarget {
   interface org.freedesktop.systemd1.Target {
   };
@@ -5364,11 +5343,8 @@ node /org/freedesktop/systemd1/unit/basic_2etarget {
     <para>All device unit objects implement the <interfacename>org.freedesktop.systemd1.Device</interfacename> interface (described here)
     in addition to the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Device">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice
-
-node /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice {
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/dev_2dttyS0_2edevice" interface="org.freedesktop.systemd1.Device">
+node /org/freedesktop/systemd1/unit/dev_2dttyS0_2edevice {
   interface org.freedesktop.systemd1.Device {
     properties:
       readonly s SysFSPath = '...';
@@ -5382,14 +5358,14 @@ node /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Device"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Device"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Device"/>
+
     <variablelist class="dbus-property" generated="True" extra-ref="SysFSPath"/>
 
     <!--End of Autogenerated section-->
@@ -5411,10 +5387,7 @@ node /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Mount">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/home_2emount
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/home_2emount" interface="org.freedesktop.systemd1.Mount">
 node /org/freedesktop/systemd1/unit/home_2emount {
   interface org.freedesktop.systemd1.Mount {
     methods:
@@ -6291,14 +6264,14 @@ node /org/freedesktop/systemd1/unit/home_2emount {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Mount"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Mount"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Mount"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetProcesses()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="AttachProcesses()"/>
@@ -6773,10 +6746,7 @@ node /org/freedesktop/systemd1/unit/home_2emount {
     <interfacename>org.freedesktop.systemd1.Automount</interfacename> interface (described here) in addition
     to the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Automount">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount" interface="org.freedesktop.systemd1.Automount">
 node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount {
   interface org.freedesktop.systemd1.Automount {
     properties:
@@ -6803,14 +6773,14 @@ node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Automount"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Automount"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Automount"/>
+
     <variablelist class="dbus-property" generated="True" extra-ref="Where"/>
 
     <variablelist class="dbus-property" generated="True" extra-ref="DirectoryMode"/>
@@ -6841,10 +6811,7 @@ node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Timer">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer" interface="org.freedesktop.systemd1.Timer">
 node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer {
   interface org.freedesktop.systemd1.Timer {
     properties:
@@ -6901,14 +6868,14 @@ node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Timer"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Timer"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Timer"/>
+
     <variablelist class="dbus-property" generated="True" extra-ref="Unit"/>
 
     <variablelist class="dbus-property" generated="True" extra-ref="TimersMonotonic"/>
@@ -6980,10 +6947,7 @@ node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Swap">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/dev_2dsda3_2eswap" interface="org.freedesktop.systemd1.Swap">
 node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap {
   interface org.freedesktop.systemd1.Swap {
     methods:
@@ -7836,14 +7800,14 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Swap"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Swap"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Swap"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetProcesses()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="AttachProcesses()"/>
@@ -8306,10 +8270,7 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap {
   <refsect1>
     <title>Path Unit Objects</title>
 
-    <programlisting interface="org.freedesktop.systemd1.Path">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/cups_2epath
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/cups_2epath" interface="org.freedesktop.systemd1.Path">
 node /org/freedesktop/systemd1/unit/cups_2epath {
   interface org.freedesktop.systemd1.Path {
     properties:
@@ -8336,14 +8297,14 @@ node /org/freedesktop/systemd1/unit/cups_2epath {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Path"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Path"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Path"/>
+
     <variablelist class="dbus-property" generated="True" extra-ref="Unit"/>
 
     <variablelist class="dbus-property" generated="True" extra-ref="Paths"/>
@@ -8382,10 +8343,7 @@ node /org/freedesktop/systemd1/unit/cups_2epath {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Slice">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/system_2eslice
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/system_2eslice" interface="org.freedesktop.systemd1.Slice">
 node /org/freedesktop/systemd1/unit/system_2eslice {
   interface org.freedesktop.systemd1.Slice {
     methods:
@@ -8645,14 +8603,14 @@ node /org/freedesktop/systemd1/unit/system_2eslice {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Slice"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Slice"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Slice"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetProcesses()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="AttachProcesses()"/>
@@ -8793,10 +8751,7 @@ node /org/freedesktop/systemd1/unit/system_2eslice {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting interface="org.freedesktop.systemd1.Scope">
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/session_2d1_2escope
-
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/unit/session_2d1_2escope" interface="org.freedesktop.systemd1.Scope">
 node /org/freedesktop/systemd1/unit/session_2d1_2escope {
   interface org.freedesktop.systemd1.Scope {
     methods:
@@ -9097,14 +9052,14 @@ node /org/freedesktop/systemd1/unit/session_2d1_2escope {
 
     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 
-    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Scope"/>
-
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Scope"/>
 
     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Unit"/>
 
+    <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.systemd1.Scope"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="Abandon()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="GetProcesses()"/>
@@ -9293,11 +9248,8 @@ node /org/freedesktop/systemd1/unit/session_2d1_2escope {
     <para>Job objects encapsulate scheduled or running jobs. Each unit can have none or one jobs in the
     execution queue. Each job is attached to exactly one unit.</para>
 
-    <programlisting>
-$ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/job/1292
-
-node /org/freedesktop/systemd1/job/1292 {
+    <programlisting executable="systemd" node="/org/freedesktop/systemd1/job/666" interface="org.freedesktop.systemd1.Job">
+node /org/freedesktop/systemd1/job/666 {
   interface org.freedesktop.systemd1.Job {
     methods:
       Cancel();
@@ -9373,6 +9325,41 @@ node /org/freedesktop/systemd1/job/1292 {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.systemd1.Manager</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+        --dest org.freedesktop.systemd1 \
+        --object-path /org/freedesktop/systemd1
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect a unit on the bus</title>
+
+      <programlisting>
+$ busctl introspect org.freedesktop.systemd1 \
+  $(busctl call org.freedesktop.systemd1 \
+     /org/freedesktop/systemd1 \
+     org.freedesktop.systemd1.Manager \
+     GetUnit s systemd-resolved.service | cut -d'"' -f2)
+      </programlisting>
+    </example>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.systemd1.Job</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system --dest org.freedesktop.systemd1 \
+  --object-path /org/freedesktop/systemd1/job/1292
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>
 
diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml
index 3111ebbc422..325c3acfb1e 100644
--- a/man/org.freedesktop.timedate1.xml
+++ b/man/org.freedesktop.timedate1.xml
@@ -34,11 +34,7 @@
 
     <para>The service exposes the following interfaces on the bus:</para>
 
-    <programlisting>
-$ gdbus introspect --system \
-        --dest org.freedesktop.timedate1 \
-        --object-path /org/freedesktop/timedate1
-
+    <programlisting executable="systemd-timedated" node="/org/freedesktop/timedate1" interface="org.freedesktop.timedate1">
 node /org/freedesktop/timedate1 {
   interface org.freedesktop.timedate1 {
     methods:
@@ -180,6 +176,20 @@ node /org/freedesktop/timedate1 {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Introspect <interfacename>org.freedesktop.timedate1</interfacename> on the bus</title>
+
+      <programlisting>
+$ gdbus introspect --system \
+  --dest org.freedesktop.timedate1 \
+  --object-path /org/freedesktop/timedate1
+      </programlisting>
+    </example>
+  </refsect1>
+
   <refsect1>
     <title>Versioning</title>