From c0d9495a06e9cd5b2a2af24e66d1e8249be4a399 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Wed, 25 Sep 2024 18:08:19 +0100
Subject: [PATCH] spec: Improve flow of text when cross-referencing methods,
 etc.
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

`<xref>` will typically be replaced by something like
"the section called “Foo”", so if we want to name a specific method
in running text, we need to use `<link>`.

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 doc/dbus-specification.xml | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index f5c92fb41..69789ded1 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -4892,7 +4892,7 @@
         message: they are delivered to the specified receipient,
         regardless of its match rules.  One use for unicast signals is to
         avoid a race condition in which a signal is emitted before the intended
-        recipient can call <xref linkend="bus-messages-add-match"/> to
+        recipient can call <link linkend="bus-messages-add-match">AddMatch</link> to
         receive that signal: if the signal is sent directly to that recipient
         using a unicast message, it does not need to add a match rule at all,
         and there is no race condition.  Another use for unicast signals,
@@ -5529,8 +5529,9 @@
         </para>
 
         <para>
-          Explicit activation via
-          <xref linkend="bus-messages-start-service-by-name"/> is not currently
+          Explicit activation via the
+          <link linkend="bus-messages-start-service-by-name">StartServiceByName</link>
+          method call is not currently
           affected by this mediation: if a confined process is to be prevented
           from starting arbitrary services, then it must not be allowed to call
           that method.
@@ -5862,8 +5863,8 @@
         The special message bus name <literal>org.freedesktop.DBus</literal>
         responds to a number of additional messages at the object path
         <literal>/org/freedesktop/DBus</literal>.
-        That object path is also used when emitting the
-        <xref linkend='bus-messages-name-owner-changed'/> signal.
+        That object path is also used when emitting signals such as
+        <link linkend='bus-messages-name-owner-changed'>NameOwnerChanged</link>.
       </para>
 
       <para>
@@ -7042,7 +7043,7 @@
           required to list a process's credentials. In older versions, calling
           this method will fail: applications should recover by using the
           separate methods such as
-          <xref linkend="bus-messages-get-connection-unix-user"/>
+          <link linkend="bus-messages-get-connection-unix-user">GetConnectionUnixUser</link>
           instead.
         </para>
       </sect3>
@@ -7099,9 +7100,9 @@
           binary format. If you know what this means, please contribute
           documentation via the D-Bus bug tracking system.
           This method is on the core DBus interface for historical reasons;
-          the same information should be made available via
-          <xref linkend="bus-messages-get-connection-credentials"/>
-          in future.
+          the same information should be made available via the
+          <link linkend="bus-messages-get-connection-credentials">GetConnectionCredentials</link>
+          method in future.
         </para>
       </sect3>
 
@@ -7157,9 +7158,9 @@
           format. If you know what this means, please contribute
           documentation via the D-Bus bug tracking system.
           This method is on the core DBus interface for historical reasons;
-          the same information should be made available via
-          <xref linkend="bus-messages-get-connection-credentials"/>
-          in future.
+          the same information should be made available via the
+          <link linkend="bus-messages-get-connection-credentials">GetConnectionCredentials</link>
+          method in future.
         </para>
       </sect3>
 
-- 
2.47.3