[gnome-session: 3/4] doc: Add description of important systemd units to man page

[Ray Strode <halfline src gnome org>]

commit c6712eca3e91a66d4d74b80c6bde7c659dfacd38
Author: Benjamin Berg <bberg redhat com>
Date:   Mon Dec 9 16:26:55 2019 +0100

    doc: Add description of important systemd units to man page

 doc/man/gnome-session.1 | 53 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
---
diff --git a/doc/man/gnome-session.1 b/doc/man/gnome-session.1
index e27475df..7f6f3605 100644
--- a/doc/man/gnome-session.1
+++ b/doc/man/gnome-session.1
@@ -79,10 +79,63 @@ RequiredComponents=gnome-shell;gnome-settings-daemon;
 .in
 .fi
 .PP
+In \fBsystemd\fP managed sessions the RequiredComponents may be provided by
+systemd units instead. In this case the corresponding \fB.desktop\fP file needs
+to contain \fBX-GNOME-HiddenUnderSystemd=true\fP. \fIgnome-session\fP will
+ignore these components and rely on \fIsystemd\fP to manage them appropriately,
+see the \fIsystemd\fP for more information on how this works.
+.PP
 The \fB.session\fP files are looked for in
 \fB$XDG_CONFIG_HOME/gnome-session/sessions\fP,
 \fB$XDG_CONFIG_DIRS/gnome-session/sessions\fP and
 \fB$XDG_DATA_DIRS/gnome-session/sessions\fP.
+.SH systemd
+\fIgnome-session\fP can pass much of the session management over to systemd
+(see the \fI--systemd\fP option which may be the default since 3.34). In this
+case, startup components that have \fBX-GNOME-HiddenUnderSystemd=true\fP
+set in their \fB.desktop\fP file will be ignored by \fIgnome-session\fP. It
+instead relies on the fact that these components are managed by systemd.
+.PP
+As of GNOME 3.34 the systemd support is new and the customizing the
+configuration is not yet easily possible. With GNOME 3.34 it may be best to use
+\fI--builtin\fP if session customizations are required. This is due to the way
+that GNOME currently defines the components that will be started on each session
+type.
+.PP
+\fBsystemd\fP provides the two special targets \fBgraphical-session.target\fP
+and \fBgraphical-session-pre.target\fP which are fully functional and should be
+used. \fIgnome-session\fP provides the following main targets:
+.TP
+.I "gnome-session.target"
+Generic unit that will be active throughout the session. Similar to
+\fBgraphical-session.target\fP.
+.TP
+.I "gnome-session-pre.target"
+Used for tasks that need to be done before session startup. Similar to
+\fBgraphical-session-pre.target\fP.
+.TP
+.I "gnome-session-x11@SESSION.target" "gnome-session-wayland@SESSION.target"
+Main unit started for X11/wayland based session. \fBSESSION\fP is set according
+to the session that is passed in \fI--session\fP.
+.TP
+.I "gnome-session-x11.target" "gnome-session-wayland.target"
+Convenience units without the session embedded into the target.
+.TP
+.I "gnome-session@SESSION.target"
+Convenience unit with just the \fBSESSION\fP information embedded.
+.TP
+.I "gnome-session-x11-services.target"
+Special unit started when X11 services are needed. This will be used from GNOME
+3.36 onwards. Programs will need to use the special \fBGNOME_SETUP_DISPLAY\fP
+environment variable instead of \fIDISPLAY\fP.
+.PP
+Note that care must be taken to set appropriate \fBAfter=\fP rules. It is also
+strongly recommended to always do this in combination with \fBBindsTo=\fP or
+\fBPartOf=\fP on one of the core targets (e.g. \fBgraphical-session.target\fP).
+.PP
+Units are required to set \fBCollectMode=inactive-or-failed\fP. In addition, it
+is strongly recommended to set \fBTimeoutStopSec=5\fP so that logout
+will not be delayed indefinitely in case the process does not stop properly.
 .SH ENVIRONMENT
 \fIgnome-session\fP sets several environment variables for the use of
 its child processes: