From cc02f613f361981a338db8916e7516e5001253c0 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 16:41:01 +0200 Subject: Adding upstream version 3.38.0. Signed-off-by: Daniel Baumann --- doc/dbus/config.xsl | 6 + doc/dbus/dbus-introspect-docs.dtd | 32 +++ doc/dbus/docbook.css | 78 ++++++ doc/dbus/gnome-session.xml.in | 52 ++++ doc/dbus/meson.build | 46 +++ doc/dbus/spec-to-docbook.xsl | 555 +++++++++++++++++++++++++++++++++++++ doc/man/gnome-session-inhibit.xml | 106 +++++++ doc/man/gnome-session-quit.1 | 34 +++ doc/man/gnome-session-selector.xml | 52 ++++ doc/man/gnome-session.1 | 184 ++++++++++++ doc/man/meson.build | 43 +++ doc/meson.build | 9 + 12 files changed, 1197 insertions(+) create mode 100644 doc/dbus/config.xsl create mode 100644 doc/dbus/dbus-introspect-docs.dtd create mode 100644 doc/dbus/docbook.css create mode 100644 doc/dbus/gnome-session.xml.in create mode 100644 doc/dbus/meson.build create mode 100644 doc/dbus/spec-to-docbook.xsl create mode 100644 doc/man/gnome-session-inhibit.xml create mode 100644 doc/man/gnome-session-quit.1 create mode 100644 doc/man/gnome-session-selector.xml create mode 100644 doc/man/gnome-session.1 create mode 100644 doc/man/meson.build create mode 100644 doc/meson.build (limited to 'doc') diff --git a/doc/dbus/config.xsl b/doc/dbus/config.xsl new file mode 100644 index 0000000..7aa9def --- /dev/null +++ b/doc/dbus/config.xsl @@ -0,0 +1,6 @@ + + + + diff --git a/doc/dbus/dbus-introspect-docs.dtd b/doc/dbus/dbus-introspect-docs.dtd new file mode 100644 index 0000000..ca918fb --- /dev/null +++ b/doc/dbus/dbus-introspect-docs.dtd @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/dbus/docbook.css b/doc/dbus/docbook.css new file mode 100644 index 0000000..6a7373e --- /dev/null +++ b/doc/dbus/docbook.css @@ -0,0 +1,78 @@ +body +{ + font-family: sans-serif; +} +h1.title +{ +} +.permission +{ + color: #ee0000; + text-decoration: underline; +} +.synopsis, .classsynopsis +{ + background: #eeeeee; + border: solid 1px #aaaaaa; + padding: 0.5em; +} +.programlisting +{ + background: #eeeeff; + border: solid 1px #aaaaff; + padding: 0.5em; +} +.variablelist +{ + padding: 4px; + margin-left: 3em; +} +.variablelist td:first-child +{ + vertical-align: top; +} +td.shortcuts +{ + color: #770000; + font-size: 80%; +} +div.refnamediv +{ + margin-top: 2em; +} +div.toc +{ + border: 2em; +} +a +{ + text-decoration: none; +} +a:hover +{ + text-decoration: underline; + color: #FF0000; +} + +div.table table +{ + border-collapse: collapse; + border-spacing: 0px; + border-style: solid; + border-color: #777777; + border-width: 1px; +} + +div.table table td, div.table table th +{ + border-style: solid; + border-color: #777777; + border-width: 1px; + padding: 3px; + vertical-align: top; +} + +div.table table th +{ + background-color: #eeeeee; +} diff --git a/doc/dbus/gnome-session.xml.in b/doc/dbus/gnome-session.xml.in new file mode 100644 index 0000000..5ffdaaf --- /dev/null +++ b/doc/dbus/gnome-session.xml.in @@ -0,0 +1,52 @@ + + + + + + +]> + + + + GNOME Session @VERSION@ Documentation + Version @VERSION@ + + + William Jon + McCann + +
+ jmccann@redhat.com +
+ + + + + + + Reference + + + D-Bus API Reference + + + + This API is not yet stable and is likely to change in the future. + + + + &dbus-Manager; + &dbus-Client; + &dbus-ClientPrivate; + &dbus-Inhibitor; + &dbus-Presence; + + + + + + Index + + + diff --git a/doc/dbus/meson.build b/doc/dbus/meson.build new file mode 100644 index 0000000..12ebce6 --- /dev/null +++ b/doc/dbus/meson.build @@ -0,0 +1,46 @@ +ifaces_refs = [] + +ifaces = [ + 'org.gnome.SessionManager', + 'org.gnome.SessionManager.Client', + 'org.gnome.SessionManager.ClientPrivate', + 'org.gnome.SessionManager.Inhibitor', + 'org.gnome.SessionManager.Presence' +] + +gnome_session_dir = join_paths(meson.source_root(), 'gnome-session') +spec_to_docbook = files('spec-to-docbook.xsl') + +foreach iface: ifaces + iface_ref = iface + '.ref.xml' + + ifaces_refs += custom_target( + iface_ref, + input: files(join_paths(gnome_session_dir, iface + '.xml')), + output: iface_ref, + command: [xsltproc, '--output', '@OUTPUT@', spec_to_docbook, '@INPUT@'] + ) +endforeach + +session_conf = configuration_data() +session_conf.set('VERSION', session_version) + +session = meson.project_name() + +xml_in = configure_file( + input: session + '.xml.in', + output: session + '.xml', + configuration: session_conf +) + +config_xsl = files('config.xsl') + +custom_target( + session, + input: xml_in, + output: session + '.html', + command: [find_program('xmlto'), 'xhtml-nochunks', '-o', meson.current_build_dir(), '-m', config_xsl, '@INPUT@'], + depends: ifaces_refs, + install: true, + install_dir: join_paths(session_datadir, 'doc', meson.project_name(), 'dbus') +) diff --git a/doc/dbus/spec-to-docbook.xsl b/doc/dbus/spec-to-docbook.xsl new file mode 100644 index 0000000..9a6a8da --- /dev/null +++ b/doc/dbus/spec-to-docbook.xsl @@ -0,0 +1,555 @@ + + + + + + + + + + + + + + + + + + + + + + interface + + + + Methods + + + + + + + + + + + Signals + + + + + + + + + + + Implemented Interfaces + + Objects implementing also implements + org.freedesktop.DBus.Introspectable, + org.freedesktop.DBus.Properties + + + + + + + Properties + + + + + + + + + + + Description + + + + + + + Details + + + + + + + + + Signal Details + + + + + + + + + + + Property Details + + + + + + + + + + + + + + + + + + + : + + + + + + + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$interface"/>:<xsl:value-of select="@name"/></xsl:attribute></anchor>The "<xsl:value-of select="@name"/>" property + +'' + + + + + + + + + + + + + + + + : + + + + + + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$interface"/>::<xsl:value-of select="@name"/></xsl:attribute></anchor>The <xsl:value-of select="@name"/> signal + + () + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + : + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Since + + + + + + + + /> + + + + + + + is deprecated since version and should not be used in newly-written code. Use + + + + + : + + + :: + + + . + + + + + + + + + + + + + + + +instead. + + + + + + + + + + + + + + + + + +See also: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + : + + + + + + + + + + + + + + Errors + + + + : + + + + + + + + + + + + Permissions + + + + + + + + + + + + + + + + + + <anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$interface"/>.<xsl:value-of select="@name"/></xsl:attribute></anchor><xsl:value-of select="@name"/> () + + () + + + + + + + + + + + + + + + + +:'' + + + + + + + + + + + + +::() + + + + + + + + + + + + +.() + + + + + +'' +, + + + + + +'' +, + + + + + + +'' + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 @@ + + + +gnome-session-inhibit +gnome-session + + + +gnome-session-inhibit +1 +User Commands + + + +gnome-session-inhibit +inhibit gnome-session functionality + + + + +gnome-session-inhibit +OPTION +COMMAND + + + +Description +gnome-session-inhibit 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. + + +A typical use case is to prevent the session from going idle (and +thus locking the screen) while a movie player is running. + + + + +Options + + + +, + +print help and exit + + + + + + +print version information and exit + + + + + ID + +The application id to use when calling the gnome-session Inhibit() method. +If this option is not specified, "unknown" is used. + + + + + REASON + +A human-readable reason to pass along when calling the gnome-session +Inhibit() method. If this option is not specified, "not specified" is used. + + + + + ARG + +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. + + + + + + +Do not launch COMMAND and wait forever instead + + + + +, + +list the existing inhibitions and exit + + + + + + +See also + +systemd-inhibit1 + + + 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 @@ + + + +gnome-session-selector +gnome-session + + + +gnome-session-selector +1 +User Commands + + + +gnome-session-selector +Selects a session to use with gnome-session + + + + +gnome-session-selector +session + + + +Description +gnome-session-selector 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 +$XDG_DATA_HOME/gnome-session/saved-session +directory. gnome-session-selector 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 '.'. + + +When a session name is specified, gnome-session-selector +will create a symlink to select this session. + + +When started without arguments, gnome-session-selector +will present a dialog that allows to choose one of the existing sessions +or create a new one. + + + +See also + +gnome-session1 + + + 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 +) diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 0000000..6d323bb --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,9 @@ +xsltproc = find_program('xsltproc') + +if enable_docbook + subdir('dbus') +endif + +if enable_man + subdir('man') +endif -- cgit v1.2.3