diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dbus/config.xsl | 6 | ||||
| -rw-r--r-- | doc/dbus/dbus-introspect-docs.dtd | 32 | ||||
| -rw-r--r-- | doc/dbus/docbook.css | 78 | ||||
| -rw-r--r-- | doc/dbus/gnome-session.xml.in | 52 | ||||
| -rw-r--r-- | doc/dbus/meson.build | 46 | ||||
| -rw-r--r-- | doc/dbus/spec-to-docbook.xsl | 555 | ||||
| -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 | ||||
| -rw-r--r-- | doc/meson.build | 9 |
12 files changed, 1197 insertions, 0 deletions
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 @@ +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + <xsl:param name="html.stylesheet" select="'docbook.css'"/> +</xsl:stylesheet> 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 @@ +<!-- DTD for D-Bus Introspection Documentation --> + +<!ELEMENT doc (summary?,description?,errors?,permission?,since?,deprecated,seealso?)> + +<!ELEMENT summary (#PCDATA|ref)*> +<!ELEMENT description (#PCDATA|para|example)*> +<!ELEMENT errors (error)*> +<!ELEMENT permission (#PCDATA|ref|para)*> +<!ELEMENT since EMPTY> +<!ATTLIST since version CDATA #REQUIRED> +<!ELEMENT deprecated (#PCDATA|ref)> +<!ATTLIST deprecated version CDATA #REQUIRED> +<!ATTLIST deprecated instead CDATA #REQUIRED> +<!ELEMENT seealso (ref+)> + +<!ELEMENT error (#PCDATA|para)*> +<!ATTLIST error name CDATA #REQUIRED> +<!ELEMENT para (#PCDATA|example|code|list|ref)*> +<!ELEMENT example (#PCDATA|para|code|ref)*> +<!ATTLIST language (c|glib|python|shell) #REQUIRED> +<!ATTLIST title CDATA #IMPLIED> +<!ELEMENT list (item*)> +<!ATTLIST list type (bullet|number) #REQUIRED> +<!ELEMENT item (term|definition)*> +<!ELEMENT term (#PCDATA|ref)*> +<!ELEMENT definition (#PCDATA|para)*> + +<!ELEMENT code (#PCDATA)> +<!ATTLIST code lang CDATA #IMPLIED> +<!ELEMENT ref CDATA> +<!ATTLIST ref type (parameter|arg|signal|method|interface) #REQUIRED> +<!ATTLIST ref to CDATA #REQUIRED> 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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY dbus-Manager SYSTEM "org.gnome.SessionManager.ref.xml"> +<!ENTITY dbus-Client SYSTEM "org.gnome.SessionManager.Client.ref.xml"> +<!ENTITY dbus-ClientPrivate SYSTEM "org.gnome.SessionManager.ClientPrivate.ref.xml"> +<!ENTITY dbus-Inhibitor SYSTEM "org.gnome.SessionManager.Inhibitor.ref.xml"> +<!ENTITY dbus-Presence SYSTEM "org.gnome.SessionManager.Presence.ref.xml"> +]> + +<book id="index"> + <bookinfo> + <title>GNOME Session @VERSION@ Documentation</title> + <releaseinfo>Version @VERSION@</releaseinfo> + <authorgroup> + <author> + <firstname>William Jon</firstname> + <surname>McCann</surname> + <affiliation> + <address> + <email>jmccann@redhat.com</email> + </address> + </affiliation> + </author> + </authorgroup> + </bookinfo> + + <part> + <title>Reference</title> + + <reference id="dbus-reference"> + <title>D-Bus API Reference</title> + + <partintro> + <para> + This API is not yet stable and is likely to change in the future. + </para> + </partintro> + + &dbus-Manager; + &dbus-Client; + &dbus-ClientPrivate; + &dbus-Inhibitor; + &dbus-Presence; + + </reference> + </part> + + <index> + <title>Index</title> + </index> + +</book> 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 @@ +<?xml version='1.0'?> +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd" + exclude-result-prefixes="doc"> +<!-- + Convert D-Bus Glib xml into DocBook refentries + Copyright (C) 2007-2008 William Jon McCann + License: GPL +--> +<xsl:output method="xml" indent="yes" encoding="UTF-8"/> + +<xsl:template match="/"> + +<xsl:variable name="interface" select="//interface/@name"/> +<xsl:variable name="basename"> + <xsl:call-template name="interface-basename"> + <xsl:with-param name="str" select="$interface"/> + </xsl:call-template> +</xsl:variable> + +<refentry><xsl:attribute name="id"><xsl:value-of select="$interface"/></xsl:attribute> + <refmeta> + <refentrytitle role="top_of_page"><xsl:value-of select="//interface/@name"/></refentrytitle> + </refmeta> + + <refnamediv> + <refname><xsl:value-of select="$interface"/></refname> + <refpurpose><xsl:value-of select="$basename"/> interface</refpurpose> + </refnamediv> + + <refsynopsisdiv role="synopsis"> + <title role="synopsis.title">Methods</title> + <synopsis> + <xsl:call-template name="methods-synopsis"> + <xsl:with-param name="interface" select="$interface"/> + </xsl:call-template> + </synopsis> + </refsynopsisdiv> + + <xsl:choose> + <xsl:when test="count(///signal) > 0"> + <refsect1 role="signal_proto"> + <title role="signal_proto.title">Signals</title> + <synopsis> + <xsl:call-template name="signals-synopsis"> + <xsl:with-param name="interface" select="$interface"/> + </xsl:call-template> + </synopsis> + </refsect1> + </xsl:when> + </xsl:choose> + + <refsect1 role="impl_interfaces"> + <title role="impl_interfaces.title">Implemented Interfaces</title> + <para> + Objects implementing <xsl:value-of select="$interface"/> also implements + org.freedesktop.DBus.Introspectable, + org.freedesktop.DBus.Properties + </para> + </refsect1> + + <xsl:choose> + <xsl:when test="count(///property) > 0"> + <refsect1 role="properties"> + <title role="properties.title">Properties</title> + <synopsis> + <xsl:call-template name="properties-synopsis"> + <xsl:with-param name="interface" select="$interface"/> + </xsl:call-template> + </synopsis> + </refsect1> + </xsl:when> + </xsl:choose> + + <refsect1 role="desc"> + <title role="desc.title">Description</title> + <para> + <xsl:apply-templates select="//interface/doc:doc"/> + </para> + </refsect1> + + <refsect1 role="details"> + <title role="details.title">Details</title> + <xsl:call-template name="method-details"> + <xsl:with-param name="interface" select="$interface"/> + </xsl:call-template> + </refsect1> + + <xsl:choose> + <xsl:when test="count(///signal) > 0"> + <refsect1 role="signals"> + <title role="signals.title">Signal Details</title> + <xsl:call-template name="signal-details"> + <xsl:with-param name="interface" select="$interface"/> + </xsl:call-template> + </refsect1> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="count(///property) > 0"> + <refsect1 role="property_details"> + <title role="property_details.title">Property Details</title> + <xsl:call-template name="property-details"> + <xsl:with-param name="interface" select="$interface"/> + </xsl:call-template> + </refsect1> + </xsl:when> + </xsl:choose> + +</refentry> +</xsl:template> + + +<xsl:template name="property-doc"> + <xsl:apply-templates select="doc:doc/doc:description"/> + + <xsl:choose> + <xsl:when test="count(arg) > 0"> + <variablelist role="params"> + <xsl:for-each select="arg"> + <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term> + <listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem> + </varlistentry> + </xsl:for-each> + </variablelist> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates select="doc:doc/doc:since"/> + <xsl:apply-templates select="doc:doc/doc:deprecated"/> + <xsl:apply-templates select="doc:doc/doc:permission"/> + <xsl:apply-templates select="doc:doc/doc:seealso"/> +</xsl:template> + + +<xsl:template name="property-details"> + <xsl:param name="interface"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///property"> + <refsect2> + <title><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</title> +<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$interface"/></secondary></indexterm> +<programlisting>'<xsl:value-of select="@name"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="2"/></xsl:call-template> +<xsl:call-template name="property-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/></xsl:call-template></programlisting> + + <xsl:call-template name="property-doc"/> + </refsect2> + + </xsl:for-each> +</xsl:template> + +<xsl:template name="signal-doc"> + <xsl:apply-templates select="doc:doc/doc:description"/> + + <xsl:choose> + <xsl:when test="count(arg) > 0"> + <variablelist role="params"> + <xsl:for-each select="arg"> + <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term> + <listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem> + </varlistentry> + </xsl:for-each> + </variablelist> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates select="doc:doc/doc:since"/> + <xsl:apply-templates select="doc:doc/doc:deprecated"/> + <xsl:apply-templates select="doc:doc/doc:permission"/> + <xsl:apply-templates select="doc:doc/doc:seealso"/> +</xsl:template> + +<xsl:template name="signal-details"> + <xsl:param name="interface"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///signal"> + <refsect2> + <title><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</title> +<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$interface"/></secondary></indexterm> +<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting> + + <xsl:call-template name="signal-doc"/> + </refsect2> + + </xsl:for-each> +</xsl:template> + +<xsl:template match="doc:code"> +<programlisting> +<xsl:apply-templates /> +</programlisting> +</xsl:template> + +<xsl:template match="doc:tt"> + <literal> + <xsl:apply-templates /> + </literal> +</xsl:template> + +<xsl:template match="doc:i"> + <emphasis> + <xsl:apply-templates /> + </emphasis> +</xsl:template> + +<xsl:template match="doc:b"> + <emphasis role="bold"> + <xsl:apply-templates /> + </emphasis> +</xsl:template> + +<xsl:template match="doc:ulink"> + <ulink> + <xsl:attribute name="url"><xsl:value-of select="@url"/></xsl:attribute> + <xsl:value-of select="."/> + </ulink> +</xsl:template> + +<xsl:template match="doc:summary"> + <xsl:apply-templates /> +</xsl:template> + +<xsl:template match="doc:example"> +<informalexample> +<xsl:apply-templates /> +</informalexample> +</xsl:template> + +<xsl:template name="listitems-do-term"> + <xsl:param name="str"/> + <xsl:choose> + <xsl:when test="string-length($str) > 0"> + <emphasis role="bold"><xsl:value-of select="$str"/>: </emphasis> + </xsl:when> + </xsl:choose> +</xsl:template> + +<xsl:template name="do-listitems"> + <xsl:for-each select="doc:item"> + <listitem> + <simpara> + <xsl:call-template name="listitems-do-term"><xsl:with-param name="str" select="doc:term"/></xsl:call-template> + <xsl:apply-templates select="doc:definition"/> + </simpara> + </listitem> + </xsl:for-each> +</xsl:template> + +<xsl:template match="doc:list"> + <xsl:choose> + <xsl:when test="contains(@type,'number')"> + <orderedlist> + <xsl:call-template name="do-listitems"/> + </orderedlist> + </xsl:when> + <xsl:otherwise> + <itemizedlist> + <xsl:call-template name="do-listitems"/> + </itemizedlist> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template match="doc:para"> +<para> +<xsl:apply-templates /> +</para> +</xsl:template> + +<xsl:template match="doc:description"> +<xsl:apply-templates /> +</xsl:template> + +<xsl:template match="doc:since"> +<para role="since">Since <xsl:value-of select="@version"/> +</para> +</xsl:template> + +<xsl:template match="doc:deprecated"> + <xsl:variable name="name" select="../../@name"/> + <xsl:variable name="parent"> + <xsl:call-template name="interface-basename"> + <xsl:with-param name="str" select="../../../@name"/>/> + </xsl:call-template> + </xsl:variable> + + <xsl:variable name="type" select="name(../..)"/> + + <para role="deprecated"> + <warning><para><literal><xsl:value-of select="$name"/></literal> is deprecated since version <xsl:value-of select="@version"/> and should not be used in newly-written code. Use + + <xsl:variable name="to"> + <xsl:choose> + <xsl:when test="contains($type,'property')"> + <xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/> + </xsl:when> + <xsl:when test="contains($type,'signal')"> + <xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/> + </xsl:when> + <xsl:when test="contains($type,'method')"> + <xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/> + </xsl:when> + <xsl:when test="contains($type,'interface')"> + <xsl:value-of select="@instead"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="@instead"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + + <xsl:call-template name="create-link"> + <xsl:with-param name="type" select="$type"/> + <xsl:with-param name="to" select="$to"/> + <xsl:with-param name="val" select="@instead"/> + </xsl:call-template> +instead.</para></warning> +</para> +</xsl:template> + +<xsl:template match="doc:permission"> +<para role="permission"> +<xsl:apply-templates /> +</para> +</xsl:template> + +<xsl:template match="doc:errors"> +<para role="errors"> +<xsl:apply-templates /> +</para> +</xsl:template> + +<xsl:template match="doc:seealso"> +<para> +See also: +<xsl:apply-templates /> + +</para> +</xsl:template> + +<xsl:template name="create-link"> + <xsl:param name="type"/> + <xsl:param name="to"/> + <xsl:param name="val"/> + + <xsl:choose> + <xsl:when test="contains($type,'property')"> + <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link> + </xsl:when> + <xsl:when test="contains($type,'signal')"> + <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link> + </xsl:when> + <xsl:when test="contains($type,'method')"> + <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link> + </xsl:when> + <xsl:when test="contains($type,'interface')"> + <link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link> + </xsl:when> + </xsl:choose> +</xsl:template> + +<xsl:template match="doc:ref"> + <xsl:call-template name="create-link"> + <xsl:with-param name="type" select="@type"/> + <xsl:with-param name="to" select="@to"/> + <xsl:with-param name="val" select="."/> + </xsl:call-template> +</xsl:template> + +<xsl:template name="method-doc"> + <xsl:apply-templates select="doc:doc/doc:description"/> + + <xsl:choose> + <xsl:when test="count(arg) > 0"> + <variablelist role="params"> + <xsl:for-each select="arg"> + <varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term> + <listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem> + </varlistentry> + </xsl:for-each> + </variablelist> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates select="doc:doc/doc:since"/> + <xsl:apply-templates select="doc:doc/doc:deprecated"/> + + <xsl:choose> + <xsl:when test="count(doc:doc/doc:errors) > 0"> + <refsect3> + <title>Errors</title> + <variablelist role="errors"> + <xsl:for-each select="doc:doc/doc:errors/doc:error"> + <varlistentry> + <term><parameter><xsl:value-of select="@name"/></parameter>:</term> + <listitem><simpara><xsl:apply-templates select="."/></simpara></listitem> + </varlistentry> + </xsl:for-each> + </variablelist> + </refsect3> + </xsl:when> + </xsl:choose> + + <xsl:choose> + <xsl:when test="count(doc:doc/doc:permission) > 0"> + <refsect3> + <title>Permissions</title> + <xsl:apply-templates select="doc:doc/doc:permission"/> + </refsect3> + </xsl:when> + </xsl:choose> + + <xsl:apply-templates select="doc:doc/doc:seealso"/> +</xsl:template> + +<xsl:template name="method-details"> + <xsl:param name="interface"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///method"> + <refsect2> + <title><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"/> ()</title> +<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$interface"/></secondary></indexterm> +<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="method-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting> + + <xsl:call-template name="method-doc"/> + </refsect2> + + </xsl:for-each> +</xsl:template> + + +<xsl:template name="properties-synopsis"> + <xsl:param name="interface"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="///property/@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///property"> +<link><xsl:attribute name="linkend"><xsl:value-of select="$interface"/>:<xsl:value-of select="@name"/></xsl:attribute>'<xsl:value-of select="@name"/>'</link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template> <xsl:call-template name="property-args"><xsl:with-param name="indent" select="$longest + 2"/></xsl:call-template> +</xsl:for-each> +</xsl:template> + + +<xsl:template name="signals-synopsis"> + <xsl:param name="interface"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="///signal/@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///signal"> +<link><xsl:attribute name="linkend"><xsl:value-of select="$interface"/>::<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template>(<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="$longest + 2"/><xsl:with-param name="prefix" select="///signal"/></xsl:call-template>) +</xsl:for-each> +</xsl:template> + + +<xsl:template name="methods-synopsis"> + <xsl:param name="interface"/> + <xsl:variable name="longest"> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="///method/@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="///method"> +<link><xsl:attribute name="linkend"><xsl:value-of select="$interface"/>.<xsl:value-of select="@name"/></xsl:attribute><xsl:value-of select="@name"/></link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template>(<xsl:call-template name="method-args"><xsl:with-param name="indent" select="$longest + 2"/><xsl:with-param name="prefix" select="///method"/></xsl:call-template>) +</xsl:for-each> +</xsl:template> + + +<xsl:template name="method-args"><xsl:param name="indent"/><xsl:param name="prefix"/><xsl:variable name="longest"><xsl:call-template name="find-longest"><xsl:with-param name="set" select="$prefix/arg/@type"/></xsl:call-template></xsl:variable><xsl:for-each select="arg"><xsl:value-of select="@direction"/> +<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="4 - string-length(@direction)"/></xsl:call-template>'<xsl:value-of select="@type"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@type) + 1"/></xsl:call-template> +<xsl:value-of select="@name"/><xsl:if test="not(position() = last())">, +<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if> +</xsl:for-each> +</xsl:template> + + +<xsl:template name="signal-args"><xsl:param name="indent"/><xsl:param name="prefix"/><xsl:variable name="longest"><xsl:call-template name="find-longest"><xsl:with-param name="set" select="$prefix/arg/@type"/></xsl:call-template></xsl:variable><xsl:for-each select="arg">'<xsl:value-of select="@type"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@type) + 1"/></xsl:call-template> +<xsl:value-of select="@name"/><xsl:if test="not(position() = last())">, +<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$indent"/></xsl:call-template></xsl:if> +</xsl:for-each> +</xsl:template> + + +<xsl:template name="property-args"><xsl:param name="indent"/> +<xsl:value-of select="@access"/><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="9 - string-length(@access) + 1"/></xsl:call-template>'<xsl:value-of select="@type"/>' +</xsl:template> + + +<xsl:template name="pad-spaces"> + <xsl:param name="width"/> + <xsl:variable name="spaces" xml:space="preserve"> </xsl:variable> + <xsl:value-of select="substring($spaces,1,$width)"/> +</xsl:template> + + +<xsl:template name="find-longest"> + <xsl:param name="set"/> + <xsl:param name="index" select="1"/> + <xsl:param name="longest" select="0"/> + + <xsl:choose> + <xsl:when test="$index > count($set)"> + <!--finished looking--> + <xsl:value-of select="$longest"/> + </xsl:when> + <xsl:when test="string-length($set[$index])>$longest"> + <!--found new longest--> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="$set"/> + <xsl:with-param name="index" select="$index + 1"/> + <xsl:with-param name="longest" select="string-length($set[$index])"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <!--this isn't any longer--> + <xsl:call-template name="find-longest"> + <xsl:with-param name="set" select="$set"/> + <xsl:with-param name="index" select="$index + 1"/> + <xsl:with-param name="longest" select="$longest"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<xsl:template name="interface-basename"> + <xsl:param name="str"/> + <xsl:choose> + <xsl:when test="contains($str,'.')"> + <xsl:call-template name="interface-basename"> + <xsl:with-param name="str" select="substring-after($str,'.')"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$str"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +</xsl:stylesheet> 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 +) 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 |