04/06: doc: Document polkit and elogind services.

[Andy Wingo]

wingo pushed a commit to branch wip-pam-elogind
in repository guix.

commit e31c07961df4a44969deff9724a47aceb1bf95cd
Author: Andy Wingo <address@hidden>
Date:   Wed Sep 2 22:53:09 2015 +0200

    doc: Document polkit and elogind services.
    
    * doc/guix.texi (Desktop Services): Add polkit-service and
      elogind-service documentation.
---
 doc/guix.texi |   82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 82 insertions(+), 0 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index c42aedb..46e40e0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -6049,6 +6049,7 @@ adds or adjust services for a typical ``desktop'' setup.
 In particular, it adds a graphical login manager (@pxref{X Window,
 @code{slim-service}}), a network management tool (@pxref{Networking
 Services, @code{wicd-service}}), energy and color management services,
+the @code{elogind} login and seat manager, the Polkit privilege service,
 the GeoClue location service, an NTP client (@pxref{Networking
 Services}), the Avahi daemon, and has the name service switch service
 configured to be able to use @code{nss-mdns} (@pxref{Name Service
@@ -6077,6 +6078,87 @@ and policy files.  For example, to allow avahi-daemon to 
use the system bus,
 @var{services} must be equal to @code{(list avahi)}.
 @end deffn
 
address@hidden {Monadic Procedure} elogind-service @
+                         [#:elogind @var{elogind}] [#:config @var{config}]
+Return a service that runs the @code{elogind} login and
+seat management daemon.  @uref{https://github.com/andywingo/elogind,
+Elogind} exposes a D-Bus interface that can be used to know which users
+are logged in, know what kind of sessions they have open, suspend the
+system, inhibit system suspend, reboot the system, and other tasks.
+
+Elogind handles most system-level power events for a computer, for
+example suspending the system when a lid is closed, or shutting it down
+when the power button is pressed.
+
+The @var{config} keyword argument specifies the configuration for
+elogind, and should be the result of a @code{(elogind-configuration
+(@var{parameter} @var{value})...)} invocation.  Available parameters and
+their default values are:
+
address@hidden @code
address@hidden kill-user-processes?
address@hidden
address@hidden kill-only-users
address@hidden()}
address@hidden kill-exclude-users
address@hidden("root")}
address@hidden inhibit-delay-max-seconds
address@hidden
address@hidden handle-power-key
address@hidden
address@hidden handle-suspend-key
address@hidden
address@hidden handle-hibernate-key
address@hidden
address@hidden handle-lid-switch
address@hidden
address@hidden handle-lid-switch-docked
address@hidden
address@hidden power-key-ignore-inhibited?
address@hidden
address@hidden suspend-key-ignore-inhibited?
address@hidden
address@hidden hibernate-key-ignore-inhibited?
address@hidden
address@hidden lid-switch-ignore-inhibited?
address@hidden
address@hidden holdoff-timeout-seconds
address@hidden
address@hidden idle-action
address@hidden
address@hidden idle-action-seconds
address@hidden(* 30 60)}
address@hidden runtime-directory-size-percent
address@hidden
address@hidden runtime-directory-size
address@hidden
address@hidden remove-ipc?
address@hidden
address@hidden suspend-state
address@hidden("mem" "standby" "freeze")}
address@hidden suspend-mode
address@hidden()}
address@hidden hibernate-state
address@hidden("disk")}
address@hidden hibernate-mode
address@hidden("platform" "shutdown")}
address@hidden hybrid-sleep-state
address@hidden("disk")}
address@hidden hybrid-sleep-mode
address@hidden("suspend" "platform" "shutdown")}
address@hidden table
address@hidden deffn
+
address@hidden {Monadic Procedure} polkit-service @
+                         [#:polkit @var{polkit}]
+Return a service that runs the Polkit privilege manager.
address@hidden://www.freedesktop.org/wiki/Software/polkit/ Polkit} allows
+system administrators to grant access to privileged operations in a
+structured way.  For example, polkit rules can allow a logged-in user
+whose session is active to shut down the machine, if there are no other
+users active.
address@hidden deffn
+
 @deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
                          [#:watts-up-pro? #f] @
                          [#:poll-batteries? #t] @