From c176490ef90211b90ca1c593279504a1fd73e9d7 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Wed, 9 Nov 2016 17:52:13 +0000
Subject: [PATCH 6/9] Spec: document what auto-starting is, and recommend it

For something we recommend, that is important enough to have its own
header flag, it doesn't have very good documentation. Redo the text
to suggest that auto-starting is the normal thing and
StartServiceByName is the oddity. That's usually a good principle
to follow, since it dodges time-of-check/time-of-use issues, and the
method call that you presumably wanted to do needs to handle errors
anyway.

Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
---
 doc/dbus-specification.xml | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 64f561b..f50d47f 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1930,7 +1930,9 @@
         <para>
           Unless a message has the flag <literal>NO_AUTO_START</literal>, if the
           destination name does not exist then a program to own the destination
-          name will be started before the message is delivered.  The message
+          name will be started before the message is delivered. See
+          <xref linkend="message-bus-starting-services"/>.
+          The message
           will be held until the new program is successfully started or has
           failed to start; in case of failure, an error will be returned. This
           flag is only relevant in the context of a message bus, it is ignored
@@ -4977,15 +4979,32 @@
         An application that can be started in this way is called a
         <firstterm>service</firstterm>.
       </para>
+
+      <para>
+        With D-Bus, starting a service is normally done by
+        <firstterm>auto-starting</firstterm>. That is, applications send a
+        message to a particular well-known name, such as
+        <literal>com.example.TextEditor</literal>, without specifying the
+        <literal>NO_AUTO_START</literal> flag in the message header.
+        If no application on the bus owns the requested name, but the bus
+        daemon does know how to start an activatable service for that name,
+        then the bus daemon will start that service and deliver the message
+        to it.
+      </para>
+
       <para>
-        With D-Bus, starting a service is normally done by name. That is,
-        applications ask the message bus to start some program that will own a
-        well-known name, such as <literal>com.example.TextEditor</literal>.
-        This implies a contract documented along with the name
+        It is also possible for applications to send an request to
+        start a service. See
+        <xref linkend="bus-messages-start-service-by-name"/> for details.
+      </para>
+
+      <para>
+        In either case, this implies a contract documented along with the name
         <literal>com.example.TextEditor</literal> for which object
         the owner of that name will provide, and what interfaces those
         objects will have.
       </para>
+
       <para>
         To find an executable corresponding to a particular name, the bus daemon
         looks for <firstterm>service description files</firstterm>.  Service
-- 
2.10.2