From fe490be6b75a8902e4aae6c14a65ac50362ee879 Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Fri, 17 Feb 2017 20:54:44 +0000
Subject: [PATCH 2/2] dbus-daemon(1): Describe how session services are found

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

diff --git a/doc/dbus-daemon.1.xml.in b/doc/dbus-daemon.1.xml.in
index f2170377..ccf0368e 100644
--- a/doc/dbus-daemon.1.xml.in
+++ b/doc/dbus-daemon.1.xml.in
@@ -484,17 +484,73 @@ not the systemwide bus.</para>
 
 </itemizedlist>
 
-<para>&lt;standard_session_servicedirs/&gt; is equivalent to specifying a series
-of &lt;servicedir/&gt; elements for each of the data directories in the "XDG
-Base Directory Specification" with the subdirectory "dbus-1/services",
-so for example "/usr/share/dbus-1/services" would be among the
-directories searched.</para>
+<para>&lt;standard_session_servicedirs/&gt; requests a standard set of
+  session service directories. Its effect is similar to specifying a series
+  of &lt;servicedir/&gt; elements for each of the data directories.</para>
 
+<para>
+  On Unix, the standard session service directories are:
+  <itemizedlist>
+    <listitem>
+      <para>
+        <emphasis>$XDG_RUNTIME_DIR</emphasis>/dbus-1/services,
+        if XDG_RUNTIME_DIR is set (see the XDG Base Directory
+        Specification for details of XDG_RUNTIME_DIR):
+        this location is suitable for transient services created at runtime
+        by systemd generators, session managers or other session
+        infrastructure
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <emphasis>$XDG_DATA_HOME</emphasis>/dbus-1/services,
+        where XDG_DATA_HOME defaults to ~/.local/share
+        (see the XDG Base Directory Specification): this location is
+        suitable for per-user, locally-installed software
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <emphasis>directory</emphasis>/dbus-1/services for each
+        directory in XDG_DATA_DIRS, where XDG_DATA_DIRS defaults to
+        /usr/local/share:/usr/share
+        (see the XDG Base Directory Specification): these locations are
+        suitable for locally-installed or system-wide software
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        the dbus-1/services subdirectory of the ${datadir} that
+        was specified when dbus was compiled
+      </para>
+    </listitem>
+  </itemizedlist>
+</para>
 
 <para>The "XDG Base Directory Specification" can be found at
 <ulink url='http://freedesktop.org/wiki/Standards/basedir-spec'>http://freedesktop.org/wiki/Standards/basedir-spec</ulink> if it hasn't moved,
 otherwise try your favorite search engine.</para>
 
+<para>
+  On Windows, the standard session service directories are:
+  <itemizedlist>
+    <listitem>
+      <para>
+        <emphasis>%CommonProgramFiles%</emphasis>/dbus-1/services
+        if %CommonProgramFiles% is set: this location is suitable for
+        system-wide installed software packages
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        A share/dbus-1/services directory found in the same
+        directory hierarchy (prefix) as the dbus-daemon: this location
+        is suitable for software stacks installed alongside dbus
+      </para>
+    </listitem>
+  </itemizedlist>
+</para>
+
 
 <para>The &lt;standard_session_servicedirs/&gt; option is only relevant to the
 per-user-session bus daemon defined in
-- 
2.11.0