diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 17:49:37 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-07 17:49:37 +0000 |
commit | 35504d91654321ff2b378229ff13150f53d5aad2 (patch) | |
tree | cb85edefc751b37c8423d78c5e5888f42cc01e4b /doc/man | |
parent | Initial commit. (diff) | |
download | gnome-session-35504d91654321ff2b378229ff13150f53d5aad2.tar.xz gnome-session-35504d91654321ff2b378229ff13150f53d5aad2.zip |
Adding upstream version 43.0.upstream/43.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/man')
-rw-r--r-- | doc/man/gnome-session-inhibit.xml | 106 | ||||
-rw-r--r-- | doc/man/gnome-session-quit.1 | 34 | ||||
-rw-r--r-- | doc/man/gnome-session-selector.xml | 52 | ||||
-rw-r--r-- | doc/man/gnome-session.1 | 184 | ||||
-rw-r--r-- | doc/man/meson.build | 43 |
5 files changed, 419 insertions, 0 deletions
diff --git a/doc/man/gnome-session-inhibit.xml b/doc/man/gnome-session-inhibit.xml new file mode 100644 index 0000000..1cc03b1 --- /dev/null +++ b/doc/man/gnome-session-inhibit.xml @@ -0,0 +1,106 @@ +<refentry id="gnome-session-inhibit" lang="en"> + +<refentryinfo> +<title>gnome-session-inhibit</title> +<productname>gnome-session</productname> +</refentryinfo> + +<refmeta> +<refentrytitle>gnome-session-inhibit</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="manual">User Commands</refmiscinfo> +</refmeta> + +<refnamediv> +<refname>gnome-session-inhibit</refname> +<refpurpose>inhibit gnome-session functionality</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>gnome-session-inhibit</command> +<arg choice="opt" rep="repeat">OPTION</arg> +<arg choice="opt">COMMAND</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para><command>gnome-session-inhibit</command> can inhibit certain +gnome-session functionality while executing the given COMMAND. To +achieve this, it calls the Inhibit() method of the gnome-session +D-Bus API and creates an inhibitor. The inhibitor is automatically +removed when gnome-session-inhibit exits. +</para> +<para> +A typical use case is to prevent the session from going idle (and +thus locking the screen) while a movie player is running. +</para> + +</refsect1> + +<refsect1><title>Options</title> +<variablelist> + +<varlistentry> +<term><option>-h</option>, <option>--help</option></term> +<listitem><para> +print help and exit +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--version</option></term> +<listitem><para> +print version information and exit +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--app-id</option> ID</term> +<listitem><para> +The application id to use when calling the gnome-session Inhibit() method. +If this option is not specified, "unknown" is used. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--reason</option> REASON</term> +<listitem><para> +A human-readable reason to pass along when calling the gnome-session +Inhibit() method. If this option is not specified, "not specified" is used. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--inhibit</option> ARG</term> +<listitem><para> +ARG specifies the things to inhibit, as a colon-separated list. The +possible values are logout, switch-user, suspend, idle, automount. +If this option is used more than once, the values are combined. +If this option is not specified, "idle" is assumed. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--inhibit-only</option></term> +<listitem><para> +Do not launch COMMAND and wait forever instead +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>-l</option>, <option>--list</option></term> +<listitem><para> +list the existing inhibitions and exit +</para></listitem> +</varlistentry> + +</variablelist> +</refsect1> + +<refsect1><title>See also</title> +<para> +<citerefentry><refentrytitle>systemd-inhibit</refentrytitle><manvolnum>1</manvolnum></citerefentry> +</para> +</refsect1> +</refentry> diff --git a/doc/man/gnome-session-quit.1 b/doc/man/gnome-session-quit.1 new file mode 100644 index 0000000..f0fdd16 --- /dev/null +++ b/doc/man/gnome-session-quit.1 @@ -0,0 +1,34 @@ +.\" +.\" gnome-session-quit manual page. +.\" (C) 2000 Miguel de Icaza (miguel@helixcode.com) +.\" (C) 2009-2010 Vincent Untz (vuntz@gnome.org) +.\" +.TH GNOME-SESSION-QUIT 1 "GNOME" +.SH NAME +gnome-session-quit \- End the current GNOME session +.SH SYNOPSIS +.B gnome-session-quit [\-\-logout|\-\-power-off|\-\-reboot] [\-\-force] [\-\-no-prompt] +.SH DESCRIPTION +The \fIgnome-session-quit\fP program can be used to end a GNOME session. +.SH OPTIONS +The following options are supported: +.TP +.I "--logout" +Prompt the user to confirm logout. This is the default behavior. +.TP +.I "--power-off" +Prompt the user to confirm system power off. +.TP +.I "--reboot" +Prompt the user to confirm system reboot. +.TP +.I "--force" +Ignore any inhibitors. +.TP +.I "--no-prompt" +End the session without user interaction. This only works with \fI--logout\fP. +.SH BUGS +If you find bugs in the \fIgnome-session-quit\fP program, please report +these on https://bugzilla.gnome.org. +.SH SEE ALSO +.BR gnome-session(1) diff --git a/doc/man/gnome-session-selector.xml b/doc/man/gnome-session-selector.xml new file mode 100644 index 0000000..7beb1e4 --- /dev/null +++ b/doc/man/gnome-session-selector.xml @@ -0,0 +1,52 @@ +<refentry id="gnome-session-selector" lang="en"> + +<refentryinfo> +<title>gnome-session-selector</title> +<productname>gnome-session</productname> +</refentryinfo> + +<refmeta> +<refentrytitle>gnome-session-selector</refentrytitle> +<manvolnum>1</manvolnum> +<refmiscinfo class="manual">User Commands</refmiscinfo> +</refmeta> + +<refnamediv> +<refname>gnome-session-selector</refname> +<refpurpose>Selects a session to use with gnome-session</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>gnome-session-selector</command> +<arg choice="opt">session</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1><title>Description</title> +<para><command>gnome-session-selector</command> can be used from a +xsession desktop file to select a session before gnome-session is run. +gnome-session reads and stores its session in the +<filename><envar>$XDG_DATA_HOME</envar>/gnome-session/saved-session</filename> +directory. <command>gnome-session-selector</command> works by replacing +the saved-session directory by a symlink to another directory. Since the +session name is used as the directory name, it may not contain '/' characters +or begin with a '.'. +</para> +<para> +When a session name is specified, <command>gnome-session-selector</command> +will create a symlink to select this session. +</para> +<para> +When started without arguments, <command>gnome-session-selector</command> +will present a dialog that allows to choose one of the existing sessions +or create a new one. +</para> +</refsect1> + +<refsect1><title>See also</title> +<para> +<citerefentry><refentrytitle>gnome-session</refentrytitle><manvolnum>1</manvolnum></citerefentry> +</para> +</refsect1> +</refentry> 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) diff --git a/doc/man/meson.build b/doc/man/meson.build new file mode 100644 index 0000000..4a389bc --- /dev/null +++ b/doc/man/meson.build @@ -0,0 +1,43 @@ +man1_dir = join_paths(session_mandir, 'man1') + +xsltproc_cmd = [ + xsltproc, + '--output', '@OUTPUT@', + '--nonet', + '--stringparam', 'man.output.quietly', '1', + '--stringparam', 'funcsynopsis.style', 'ansi', + '--stringparam', 'man.th.extra1.suppress', '1', + '--stringparam', 'man.authors.section.enabled', '0', + '--stringparam', 'man.copyright.section.enabled', '0', + 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl', + '@INPUT@' +] + +mans = ['gnome-session-inhibit'] + +if enable_session_selector + mans += 'gnome-session-selector' +endif + +foreach man: mans + output = man + '.1' + + custom_target( + output, + input: man + '.xml', + output: output, + command: xsltproc_cmd, + install: true, + install_dir: man1_dir + ) +endforeach + +man_data = files( + 'gnome-session.1', + 'gnome-session-quit.1' +) + +install_data( + man_data, + install_dir: man1_dir +) |