docs/labwc.1: restructure, document session management

diff --git a/docs/labwc.1.scd b/docs/labwc.1.scd
index ca9f1ae9bd6d81de1fc8531b42c2ca5aae51faa0..64eb1a989bec1cda0e4300520e6ce1cd6b0de1ee 100644 (file)
--- a/docs/labwc.1.scd
+++ b/docs/labwc.1.scd
@@ -2,7 +2,7 @@ labwc(1)
 
 # NAME
 
-labwc - a wayland stacking compositor
+labwc - a Wayland stacking compositor
 
 # SYNOPSIS
 
@@ -16,8 +16,10 @@ It is light-weight and independent with a focus on simply stacking windows
 well and rendering some window decorations. Where practicable it uses clients
 for wall-paper, panels, screenshots and so on.
 
+# SIGNALS
+
 The compositor will exit or reload its configuration upon receiving SIGTERM
-and SIGHUP respectively.  For example:
+and SIGHUP respectively. For example:
 
 ```
 kill -s <signal> $LABWC_PID
@@ -40,7 +42,7 @@ the `--exit` and `--reconfigure` options use.
        Enable full logging, including debug information
 
 *-e, --exit*
-       Exit the compositor
+       Exit the compositor by sending SIGTERM to `$LABWC_PID`
 
 *-h, --help*
        Show help message and quit
@@ -49,7 +51,7 @@ the `--exit` and `--reconfigure` options use.
        Merge user config/theme files in all XDG Base Directories
 
 *-r, --reconfigure*
-       Reload the compositor configuration
+       Reload the compositor configuration by sending SIGHUP to `$LABWC_PID`
 
 *-s, --startup* <command>
        Run command on startup
@@ -60,6 +62,48 @@ the `--exit` and `--reconfigure` options use.
 *-V, --verbose*
        Enable more verbose logging
 
+# SESSION MANAGEMENT
+
+To enable the use of graphical clients launched via D-Bus or systemd servie
+activation, labwc can update both activation environments on launch. Provided
+that labwc is aware of an active D-Bus user session (*i.e.*, the environment
+variable `DBUS_SESSION_BUS_ADDRESS` is defined), the compositor will invoke the
+commands
+
+```
+dbus-update-activation-environment
+systemctl --user import-environment
+```
+
+(when available) to notify D-Bus and systemd with the values of the following
+environment variables:
+
+```
+WAYLAND_DISPLAY
+DISPLAY
+XDG_CURRENT_DESKTOP
+XDG_SESSION_TYPE
+XCURSOR_SIZE
+XCURSOR_THEME
+LABWC_PWD
+```
+
+This behavior is enabled by default whenever labwc uses the "DRM" wlroots
+backend (which implies that labwc is the primary compositor on the console).
+When other backends are employed (for example, when labwc runs nested in another
+Wayland compositor or an X11 server), updates to the activation environment are
+disabled by default. Updates to the activation environment can be forced by
+setting the environment variable `LABWC_UPDATE_ACTIVATION_ENV` to one of the
+truthy values `1`, `true`, `yes` or `on`; or suppressed by setting the variable
+to one of the falsy values `0`, `false`, `no` or `off`.
+
+Whenever labwc updates the activation environment on launch, it will also
+attempt to clear the activation environment on exit. For D-Bus, which does not
+provide a means for properly un-setting variables in the activation environment,
+this is accomplished by setting the session variables to empty strings. For
+systemd, the command `systemctl --user unset-environment` will be invoked to
+actually remove the variables from the activation environment.
+
 # SEE ALSO
 
-labwc-config(5), labwc-theme(5), labwc-actions(5)
+labwc-actions(5), labwc-config(5), labwc-menu(5), labwc-theme(5)