diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 61993969..5feffa33 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1930,7 +1930,9 @@
Unless a message has the flag NO_AUTO_START, 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
+ .
+ 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
@@ -4979,15 +4981,34 @@
service or an
activatable service.
+
- 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 com.example.TextEditor.
- This implies a contract documented along with the name
+ In D-Bus, starting a service is normally done by
+ auto-starting, which is one form of activation.
+ In auto-starting, applications send a
+ message to a particular well-known name, such as
+ com.example.TextEditor, without specifying the
+ NO_AUTO_START 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, wait for it to request
+ that name, and deliver the message to it.
+
+
+
+ It is also possible for applications to send an explicit request to
+ start a service: this is another form of activation, distinct from
+ auto-starting. See
+ for details.
+
+
+
+ In either case, this implies a contract documented along with the name
com.example.TextEditor for which object
the owner of that name will provide, and what interfaces those
objects will have.
+
To find an executable corresponding to a particular name, the bus daemon
looks for service description files. Service
@@ -5762,8 +5783,27 @@
- Tries to launch the executable associated with a name. For more information, see .
-
+ Tries to launch the executable associated with a name (service
+ activation), as an explicit request. This is an alternative to
+ relying on auto-starting. For more information on how services
+ are activated and the difference between auto-starting and explicit
+ activation, see
+ .
+
+
+ It is often preferable to carry out auto-starting
+ instead of calling this method. This is because calling this method
+ is subject to a
+ time-of-check/time-of-use
+ issue: if a caller asks the message bus to start a service so that
+ the same caller can make follow-up method calls to that service,
+ the fact that the message bus was able to start the required
+ service is no guarantee that it will not have crashed or otherwise
+ exited by the time the caller makes those follow-up method calls.
+ As a result, calling this method does not remove the need for
+ the caller to handle errors from method calls. Given that fact,
+ it is usually simpler to rely on auto-starting, in which the
+ required service starts as a side-effect of the first method call.
The return value can be one of the following values: