From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 5 Nov 2024 13:20:01 +0000 (+0100)
Subject: man: link up D-Bus API docs from daemon man pages
X-Git-Tag: v256.8~30
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=d9ab18e747b4ac9ecbba059398bc449dfab84905;p=thirdparty%2Fsystemd.git

man: link up D-Bus API docs from daemon man pages

Let's systematically make sure that we link up the D-Bus interfaces from
the daemon man pages once in prose and once in short form at the bottom
("See Also"), for all daemons.

Also, add reverse links at the bottom of the D-Bus API docs.

Fixes: #34996
(cherry picked from commit 607d2974870e9769f44ee179dcaf26cbec64cb20)
---

diff --git a/man/org.freedesktop.hostname1.xml b/man/org.freedesktop.hostname1.xml
index d16ae9ab1c2..6c329cbd2c0 100644
--- a/man/org.freedesktop.hostname1.xml
+++ b/man/org.freedesktop.hostname1.xml
@@ -427,8 +427,6 @@ node /org/freedesktop/hostname1 {
     name.</para>
   </refsect1>
 
-  <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
-
   <refsect1>
     <title>Examples</title>
 
@@ -442,12 +440,7 @@ node /org/freedesktop/hostname1 {
     </example>
   </refsect1>
 
-  <refsect1>
-    <title>See Also</title>
-
-    <para>David Zeuthen's original Fedora
-    <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></para>
-  </refsect1>
+  <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
 
   <refsect1>
     <title>History</title>
@@ -462,4 +455,16 @@ node /org/freedesktop/hostname1 {
       <varname>VSockCID</varname> were added in version 256.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member>David Zeuthen's original Fedora
+      <ulink url="https://fedoraproject.org/wiki/Features/BetterHostname">Feature page about xdg-hostname</ulink></member>
+    </simplelist></para>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.import1.xml b/man/org.freedesktop.import1.xml
index 2486eea4b38..cfcf1339755 100644
--- a/man/org.freedesktop.import1.xml
+++ b/man/org.freedesktop.import1.xml
@@ -453,6 +453,7 @@ node /org/freedesktop/import1/transfer/_1 {
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
   <refsect1>
     <title>History</title>
     <refsect2>
@@ -469,4 +470,13 @@ node /org/freedesktop/import1/transfer/_1 {
     </refsect2>
   </refsect1>
 
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
 </refentry>
diff --git a/man/org.freedesktop.locale1.xml b/man/org.freedesktop.locale1.xml
index 6e0d118e255..0fd8876ca89 100644
--- a/man/org.freedesktop.locale1.xml
+++ b/man/org.freedesktop.locale1.xml
@@ -185,4 +185,14 @@ $ gdbus introspect --system \
     <para>These D-Bus interfaces follow <ulink url="https://0pointer.de/blog/projects/versioning-dbus.html">
     the usual interface versioning guidelines</ulink>.</para>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
 </refentry>
diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index aacaa1b9525..dddb7e8acb8 100644
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -1589,4 +1589,13 @@ node /org/freedesktop/login1/session/1 {
       <para><function>SetClass()</function> was added in version 256.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml
index 8abef00e53a..8726e5f9398 100644
--- a/man/org.freedesktop.machine1.xml
+++ b/man/org.freedesktop.machine1.xml
@@ -719,4 +719,13 @@ $ gdbus introspect --system \
       and <varname>SSHPrivateKeyPath</varname> were added in version 256.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.network1.xml b/man/org.freedesktop.network1.xml
index 1d8ce0de811..c7f1a687989 100644
--- a/man/org.freedesktop.network1.xml
+++ b/man/org.freedesktop.network1.xml
@@ -602,4 +602,13 @@ $ gdbus introspect --system \
       <para><varname>NamespaceNSID</varname> was added in version 256.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.oom1.xml b/man/org.freedesktop.oom1.xml
index 1b549c347ca..4b61119d6b9 100644
--- a/man/org.freedesktop.oom1.xml
+++ b/man/org.freedesktop.oom1.xml
@@ -103,4 +103,14 @@ node /org/freedesktop/oom1 {
       <para><function>Killed()</function> was added in version 252.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-oomd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>oomctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
 </refentry>
diff --git a/man/org.freedesktop.portable1.xml b/man/org.freedesktop.portable1.xml
index 4de3da2905d..af5e303e6e4 100644
--- a/man/org.freedesktop.portable1.xml
+++ b/man/org.freedesktop.portable1.xml
@@ -591,4 +591,13 @@ node /org/freedesktop/portable1 {
       <para><function>ReattachWithExtensions()</function> was added in version 254.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-portabled.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml
index f6b70d6e4f4..07c0528b5c5 100644
--- a/man/org.freedesktop.resolve1.xml
+++ b/man/org.freedesktop.resolve1.xml
@@ -935,4 +935,13 @@ $ gdbus introspect --system \
   </refsect1>
 
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>resolvectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
 </refentry>
diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index b08cbe1d005..295106f4fa6 100644
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -12218,4 +12218,13 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       <para><varname>ActivationDetails</varname> was added in version 252.</para>
     </refsect2>
   </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
 </refentry>
diff --git a/man/org.freedesktop.timedate1.xml b/man/org.freedesktop.timedate1.xml
index 1dfb630545c..d0271145f9f 100644
--- a/man/org.freedesktop.timedate1.xml
+++ b/man/org.freedesktop.timedate1.xml
@@ -194,7 +194,11 @@ $ gdbus introspect --system \
 
   <refsect1>
     <title>See Also</title>
-
-      <para><ulink url="https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html">More information on how the system clock and RTC interact</ulink></para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-timedate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>timedatectl.service</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><ulink url="https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html">More information on how the system clock and RTC interact</ulink></member>
+    </simplelist></para>
   </refsect1>
 </refentry>
diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml
index c2a4015ff0b..e7dc8792014 100644
--- a/man/systemd-hostnamed.service.xml
+++ b/man/systemd-hostnamed.service.xml
@@ -76,6 +76,7 @@
       <member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-importd.service.xml b/man/systemd-importd.service.xml
index dfeaff4fd77..cc5ac6af220 100644
--- a/man/systemd-importd.service.xml
+++ b/man/systemd-importd.service.xml
@@ -50,6 +50,7 @@
       <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.import1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-localed.service.xml b/man/systemd-localed.service.xml
index ef597de278b..43a4f66b5a7 100644
--- a/man/systemd-localed.service.xml
+++ b/man/systemd-localed.service.xml
@@ -55,6 +55,7 @@
       <member><citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry project='mankier'><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.locale1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml
index 4ecd700f8b2..93bcd6bc8f9 100644
--- a/man/systemd-logind.service.xml
+++ b/man/systemd-logind.service.xml
@@ -104,6 +104,7 @@
       <member><citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml
index bb931ac50be..7ad35c85846 100644
--- a/man/systemd-machined.service.xml
+++ b/man/systemd-machined.service.xml
@@ -135,6 +135,7 @@
       <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml
index b33a7f65108..2ded90f0f3e 100644
--- a/man/systemd-networkd.service.xml
+++ b/man/systemd-networkd.service.xml
@@ -63,6 +63,12 @@
     <para><command>systemd-networkd</command> may be introspected and controlled at runtime using
     <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
     </para>
+
+    <para>See
+    <citerefentry><refentrytitle>org.freedesktop.network1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    and
+    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for a description of the D-Bus API.</para>
   </refsect1>
 
   <refsect1><title>Configuration Files</title>
@@ -91,6 +97,7 @@
       <member><citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-networkd-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.network1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-oomd.service.xml b/man/systemd-oomd.service.xml
index 51a9377ea02..53a92509830 100644
--- a/man/systemd-oomd.service.xml
+++ b/man/systemd-oomd.service.xml
@@ -57,6 +57,12 @@
 
     <para>See <citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for more information about the configuration of this service.</para>
+
+    <para>See
+    <citerefentry><refentrytitle>org.freedesktop.oom1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    and
+    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for a description of the D-Bus API.</para>
   </refsect1>
 
   <refsect1>
@@ -129,6 +135,7 @@
       <member><citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>oomd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>oomctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.oom1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 </refentry>
diff --git a/man/systemd-portabled.service.xml b/man/systemd-portabled.service.xml
index abf42cff2fc..894b47bf270 100644
--- a/man/systemd-portabled.service.xml
+++ b/man/systemd-portabled.service.xml
@@ -37,6 +37,12 @@
 
     <para>See the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> page
     for details about the concepts this service implements.</para>
+
+    <para>See
+    <citerefentry><refentrytitle>org.freedesktop.portable1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    and
+    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for a description of the D-Bus API.</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 13c0da987fe..6816b85d461 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -514,6 +514,7 @@ search foobar.com barbar.com
       <member><citerefentry project='man-pages'><refentrytitle>hosts</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.resolve1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml
index eb4fc180963..9f119189d2d 100644
--- a/man/systemd-timedated.service.xml
+++ b/man/systemd-timedated.service.xml
@@ -99,6 +99,7 @@ systemd-timesyncd.service
       <member><citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
       <member><citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-timesyncd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.timedate1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
 
diff --git a/man/systemd.xml b/man/systemd.xml
index 47eb8667837..4424818b402 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -1543,6 +1543,7 @@
       <member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
       <member><citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
     </simplelist></para>
 
     <para>For more information about the concepts and