Actually describe what at-spi-bus-launcher does in bus/README.md

1 files changed, 94 insertions, 6 deletions

diff --git a/bus/README.md b/bus/README.md
index 40b9ad6b..eb14e9f4 100644
--- a/bus/README.md
+++ b/bus/README.md
@@ -1,10 +1,98 @@
-The a11y bus is accessed via two mechanisms:
+# Launcher for the accessibility bus
 
-1) The DBus session bus, service "org.a11y.Bus", method "GetAddress")
-2) The X11 root window property AT_SPI_BUS
+The communications mechanism for accessibility does not run through the user's session
+DBus; it runs in a separate bus just for accessibility purposes.  The accessibility
+interfaces for DBus are very chatty; using a separate bus prevents the main session bus
+from getting too much traffic.
 
-If the "toolkit-accessibility" variable is set, the bus is launched
-immediately (and will be accessible immediately via the X11 property).
-Otherwise, it will be spawned dynamically.
+Throughout this document we will distinguish between the **session bus** and the
+**accessibility bus**.
 
+## Who launches the accessibility bus?
 
+This source directory `bus` contains a little daemon, `at-spi-bus-launcher`, which
+launches the **accessibility bus** and manages its lifetime according to the user's
+session.
+
+The **accessibility bus** is just a separate instance of `dbus-daemon` or equivalent, like
+`dbus-broker`.  That bus allows communication using the accessibility interfaces defined
+in the `xml` directory in this repository.  It also has the accessibility registry —
+`registryd` in this repository, which claims the name `org.a11y.atspi.Registry` in that
+bus.
+
+## When does the accessibility bus get launched?
+
+When a normal application starts up, it will want to find the **accesibility bus**, and
+then contact the accessibility registry in that bus (`registryd` in this repository) to
+inform the world that they are up and running.  Finding the accessibility bus can then be
+done on demand for normal applications, via the `GetAddress` method described below.
+
+However, a screen reader is special: it needs to start up automatically during login, and
+immediatelly tell the accessibility registry (... via the **accessibility bus**) that it
+is running.  If you need a screen reader to use your computer, you cannot easily launch it
+by hand if there is no screen reader already running!
+
+That is, if a screen reader is turned on — and we assume it will start up turned on for
+future sessions — we need to launch the **accessibility bus** unconditionally, not on
+demand, at session startup.  This is why `at-spi-dbus-bus.desktop`, described below, is an
+[XDG autostart][xdg-autostart] file which runs `at-spi-bus-launcher --launch-immediately`,
+but only if a certain GSettings key is turned on.
+
+In summary, `at-spi-bus-launcher` will launch the **accessibility bus** under two situations:
+
+* On demand via the `GetAddress` method; see below.
+
+* Shortly after `at-spi-bus-launcher` starts up, if the gsettings key
+  `org.gnome.desktop.interface toolkit-accessibility` is set to true, due to the
+  `at-spi-dbus-bus.desktop` XDG autostart file.
+
+* The gsettings key `org.gnome.desktop.a11y.applications screen-reader-enabled` is set to true.
+
+## Contents of this `bus` directory
+
+This `bus` source directory has a configuration file for the `dbus-daemon` which will run
+as the **accessibility bus**, and a helper daemon called `at-spi-bus-launcher`, which actually
+starts that bus and makes its address visible to the user's session.  The files are as follows:
+
+* `accessibility.conf.in` - template for the configuration for the accessibility bus,
+  which gets installed in `$(datadir)/defaults/at-spi2/accessibility.conf`.
+
+* `at-spi-bus-launcher.c` - See [`at-spi-bus-launcher`](#at-spi-bus-launcher) below.
+
+* `at-spi-dbus-bus.service.in` - template for a systemd user service to start `at-spi-bus-launcher`.
+
+* `org.a11y.Bus.service.in` - template for a DBus user service to start `at-spi-bus-launcher`.
+
+* `at-spi-dbus-bus.desktop.in` - template for a XDG autostart file to start
+  `at-spi-bus-launcher` at session startup, only if the `org.gnome.desktop.interface
+  toolkit-accessibility` GSettings key is turned on.
+
+* `00-at-spi` - script to set the `AT_SPI_BUS` property on the X root window, for
+  Wayland-based systems where XWayland is started on demand.  That X window property is an
+  alternative way of finding the address of the **accessibility bus**.
+
+## at-spi-bus-launcher
+
+This is a tiny daemon which registers a service in the normal **session bus**, and which
+can then be used to query the address of the actual **accessibility bus**.  The daemon
+claims ownership of the `org.a11y.Bus` name in the **session bus**, and exports a
+single object, `/org/a11y/bus`, with two interfaces:
+
+* `org.a11y.Bus` - has a single `GetAddress` method, which returns the address of the
+  actual **accessibility bus**.  Accessibility clients must use this address when creating
+  their initial DBus connection.
+
+* `org.a11y.Status` - has properties to query whether the **accessibility bus** is enabled
+  and whether a screen reader is running.
+
+`at-spi-bus-launcher` starts the separate `dbus-daemon` (or `dbus-broker` equivalent) for
+the **accessibility bus** on demand.  The following actions can cause it to launch:
+
+* Calling the `GetAddress` method.  The daemon gets launched and queried for its address;
+  the method returns that.  This is the normal way to start the accessibility bus.
+
+* If `at-spi-bus-launcher` was run with the `--launch-immediately` option, the
+  accessibility bus launches as soon as `at-spi-bus-launcher` is able to claim ownership
+  of the `org.a11y.Bus` name in the session bus.  This is intended for session startup.
+
+[xdg-autostart]: https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html