Adding upstream version 3.38.0.upstream/3.38.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 184 insertions, 0 deletions

diff --git a/doc/man/gnome-session.1 b/doc/man/gnome-session.1
new file mode 100644
index 0000000..7f6f360
--- /dev/null
+++ b/doc/man/gnome-session.1
@@ -0,0 +1,184 @@
+.\"
+.\" gnome-session manual page.
+.\" (C) 2000 Miguel de Icaza (miguel@helixcode.com)
+.\" (C) 2009-2010 Vincent Untz (vuntz@gnome.org)
+.\" (C) 2019 Benjamin Berg (bberg@redhat.com)
+.\" (C) 2020 Sebastian Geiger (sbastig@gmx.net)
+.\"
+.TH GNOME-SESSION 1 "May 2020" "GNOME"
+.SH NAME
+gnome-session \- Start the GNOME desktop environment
+.SH SYNOPSIS
+.B gnome-session [\-a|\-\-autostart=DIR] [\-\-session=SESSION] [\-\-failsafe|\-f] [\-\-debug] [\-\-whale]
+.SH DESCRIPTION
+The \fIgnome-session\fP program starts up the GNOME desktop
+environment. This command is typically executed by your login manager
+(either gdm, xdm, or from your X startup scripts). It will load
+either your saved session, or it will provide a default session for the
+user as defined by the system administrator (or the default GNOME
+installation on your system). Note that \fIgnome-session\fP is a wrapper
+script for \fIgnome-session-binary\fP.
+.PP
+The default session is defined in \fBgnome.session\fP, a .desktop-like
+file that is 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.
+.PP
+When saving a session, \fIgnome-session\fP saves the currently running
+applications in the \fB$XDG_CONFIG_HOME/gnome-session/saved-session\fP
+directory. Saving sessions is only supported with the legacy non-systemd
+startup method.
+.PP
+\fIgnome-session\fP is an X11R6 session manager. It can manage GNOME
+applications as well as any X11R6 SM compliant application.
+.SH OPTIONS
+The following options are supported:
+.TP
+.I "--autostart=DIR"
+The directory \fBDIR\fP to be searched for autostart .desktop files. This option can be used multiple times.
+When this option is present, then default autostart directories will not be searched.
+.TP
+.I "--session=SESSION"
+Use the applications defined in \fBSESSION.session\fP. If not specified,
+\fBgnome.session\fP will be used.
+.TP
+.I "--builtin"
+Use the legacy non-systemd method of managing the user session. This is the
+opposite of the \fI--systemd\fP option.
+.TP
+.I "--systemd"
+Use the systemd method of managing the user session. This is the opposite of
+the \fI--builtin\fP option.
+.TP
+.I "--failsafe"
+Run in fail-safe mode. User-specified applications will not be started.
+.TP
+.I "--debug"
+Enable debugging code.
+.TP
+.I "--whale"
+Show the fail whale in a dialog for debugging it.
+.SH SESSION DEFINITION
+Sessions are defined in \fB.session\fP files, that are using a .desktop-like
+format, with the following keys in the \fBGNOME Session\fP group:
+.TP
+.I Name
+Name of the session. This can be localized.
+.TP
+.I RequiredComponents
+List of component identifiers (desktop files) that are required by the session. The required components will always run in the session.
+.PP
+Here is an example of a session definition:
+.PP
+.in +4n
+.nf
+[GNOME Session]
+Name=GNOME
+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:
+.PP
+.B SESSION_MANAGER
+.IP
+This variable is used by session-manager aware clients to contact
+gnome-session.
+.PP
+.B DISPLAY
+.IP
+This variable is set to the X display being used by
+\fIgnome-session\fP. Note that if the \fI--display\fP option is used
+this might be different from the setting of the environment variable
+when gnome-session is invoked.
+.PP
+Behavior of \fIgnome-session\fP ifself can be modified via the following environment variable:
+.PP
+.B GNOME_SESSION_AUTOSTART_DIR
+.IP
+This variable specifies a list of directories to the searched for autostart
+files. This variable overrides all directories specified via the
+\fI--autostart\fP option, as well as all default autostart directories.
+.SH FILES
+.PP
+.B $XDG_CONFIG_HOME/autostart
+.B $XDG_CONFIG_DIRS/autostart
+.B /usr/share/gnome/autostart
+.IP
+Applications defined via .desktop files in those directories will be started on login.
+.PP
+.B $XDG_CONFIG_HOME/gnome-session/sessions
+.B $XDG_CONFIG_DIRS/gnome-session/sessions
+.B $XDG_DATA_DIRS/gnome-session/sessions
+.IP
+These directories contain the \fB.session\fP files that can be used
+with the \fI--session\fP option.
+.PP
+.B $XDG_CONFIG_HOME/gnome-session/saved-session
+.IP
+This directory contains the list of applications of the saved session.
+.SH BUGS
+If you find bugs in the \fIgnome-session\fP program, please report
+these on https://gitlab.gnome.org/GNOME/gnome-session/issues.
+.SH SEE ALSO
+.BR gnome-session-quit(1)