Merge branch 'master' into core-updates

2 files changed, 229 insertions, 39 deletions

diff --git a/doc/emacs.texi b/doc/emacs.texi
index 180037a88f..db2e657d27 100644
--- a/doc/emacs.texi
+++ b/doc/emacs.texi
@@ -1,29 +1,22 @@
 @node Emacs Interface
-@section Emacs Interface
+@chapter Emacs Interface
 
 @cindex Emacs
-GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known
-as ``guix.el''.  It can be used for routine package management tasks,
-pretty much like the @command{guix package} command (@pxref{Invoking
-guix package}).  Specifically, ``guix.el'' makes it easy to:
-
-@itemize
-@item browse and display packages and generations;
-@item search, install, upgrade and remove packages;
-@item display packages from previous generations;
-@item do some other useful things.
-@end itemize
+GNU Guix comes with several useful modules (known as ``guix.el'') for
+GNU@tie{}Emacs which are intended to make an Emacs user interaction with
+Guix convenient and fun.
 
 @menu
 * Initial Setup: Emacs Initial Setup.	Preparing @file{~/.emacs}.
-* Usage: Emacs Usage.			Using the interface.
-* Configuration: Emacs Configuration.	Configuring the interface.
+* Package Management: Emacs Package Management.	Managing packages and generations.
+* Popup Interface: Emacs Popup Interface.	Magit-like interface for guix commands.
 * Prettify Mode: Emacs Prettify.	Abbreviating @file{/gnu/store/@dots{}} file names.
 * Completions: Emacs Completions.       Completing @command{guix} shell command.
 @end menu
 
+
 @node Emacs Initial Setup
-@subsection Initial Setup
+@section Initial Setup
 
 On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el''
 is ready to use, provided Guix is installed system-wide, which is the
@@ -43,6 +36,12 @@ later;
 @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
 used for interacting with the Guile process.
 
+@item
+@uref{https://github.com/magit/magit/, magit-popup library}.  You
+already have this library if you use Magit 2.1.0 or later.  This library
+is an optional dependency---it is required only for @kbd{M-x@tie{}guix}
+command (@pxref{Emacs Popup Interface}).
+
 @end itemize
 
 When it is done ``guix.el'' may be configured by requiring a special
@@ -105,22 +104,32 @@ emacs, The GNU Emacs Manual}).
 You can activate Emacs packages installed in your profile whenever you
 want using @kbd{M-x@tie{}guix-emacs-load-autoloads}.
 
-@node Emacs Usage
-@subsection Usage
+
+@node Emacs Package Management
+@section Package Management
 
 Once ``guix.el'' has been successfully configured, you should be able to
-use commands for displaying packages and generations.  This information
-can be displayed in a ``list'' or ``info'' buffer.
+use a visual interface for routine package management tasks, pretty much
+like the @command{guix package} command (@pxref{Invoking guix package}).
+Specifically, it makes it easy to:
+
+@itemize
+@item browse and display packages and generations;
+@item search, install, upgrade and remove packages;
+@item display packages from previous generations;
+@item do some other useful things.
+@end itemize
 
 @menu
 * Commands: Emacs Commands.			@kbd{M-x guix-@dots{}}
 * General information: Emacs General info.	Common for both interfaces.
 * ``List'' buffer: Emacs List buffer.		List-like interface.
 * ``Info'' buffer: Emacs Info buffer.		Help-like interface.
+* Configuration: Emacs Configuration.		Configuring the interface.
 @end menu
 
 @node Emacs Commands
-@subsubsection Commands
+@subsection Commands
 
 All commands for displaying packages and generations use the current
 profile, which can be changed with
@@ -191,7 +200,7 @@ Once @command{guix pull} has succeeded, the Guix REPL is restared.  This
 allows you to keep using the Emacs interface with the updated Guix.
 
 @node Emacs General info
-@subsubsection General information
+@subsection General information
 
 The following keys are available for both ``list'' and ``info'' types of
 buffers:
@@ -235,7 +244,7 @@ was restarted, you may want to revert ``list'' buffer (by pressing
 @kbd{g}).
 
 @node Emacs List buffer
-@subsubsection ``List'' buffer
+@subsection ``List'' buffer
 
 An interface of a ``list'' buffer is similar to the interface provided
 by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}).
@@ -310,7 +319,7 @@ with another marked generation.
 @end table
 
 @node Emacs Info buffer
-@subsubsection ``Info'' buffer
+@subsection ``Info'' buffer
 
 The interface of an ``info'' buffer is similar to the interface of
 @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}).
@@ -484,12 +493,49 @@ Various settings for ``info'' buffers.
 @end table
 
 
+@node Emacs Popup Interface
+@section Popup Interface
+
+If you ever used Magit, you know what ``popup interface'' is
+(@pxref{Top,,, magit-popup, Magit-Popup User Manual}).  Even if you are
+not acquainted with Magit, there should be no worries as it is very
+intuitive.
+
+So @kbd{M-x@tie{}guix} command provides a top-level popup interface for
+all available guix commands.  When you select an option, you'll be
+prompted for a value in the minibuffer.  Many values have completions,
+so don't hesitate to press @key{TAB} key.  Multiple values (for example,
+packages or lint checkers) should be separated by commas.
+
+After specifying all options and switches for a command, you may choose
+one of the available actions.  The following default actions are
+available for all commands:
+
+@itemize
+
+@item
+Run the command in the Guix REPL.  It is faster than running
+@code{guix@tie{}@dots{}} command directly in shell, as there is no
+need to run another guile process and to load required modules there.
+
+@item
+Run the command in a shell buffer.  You can set
+@code{guix-run-in-shell-function} variable to fine tune the shell buffer
+you want to use.
+
+@item
+Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The
+GNU Emacs Manual}).
+
+@end itemize
+
+
 @node Emacs Prettify
-@subsection Guix Prettify Mode
+@section Guix Prettify Mode
 
-Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''.
-It provides a minor mode for abbreviating store file names by replacing
-hash sequences of symbols with ``@dots{}'':
+GNU@tie{}Guix also comes with ``guix-prettify.el''.  It provides a minor
+mode for abbreviating store file names by replacing hash sequences of
+symbols with ``@dots{}'':
 
 @example
 /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1
@@ -526,7 +572,7 @@ mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example:
 
 
 @node Emacs Completions
-@subsection Shell Completions
+@section Shell Completions
 
 Another feature that becomes available after configuring Emacs interface
 (@pxref{Emacs Initial Setup}) is completing of @command{guix}
diff --git a/doc/guix.texi b/doc/guix.texi
index f69440c325..9ae91a8d1e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -70,6 +70,7 @@ package management tool written for the GNU system.
 * Introduction::                What is Guix about?
 * Installation::                Installing Guix.
 * Package Management::          Package installation, upgrade, etc.
+* Emacs Interface::             Using Guix from Emacs.
 * Programming Interface::       Using Guix in Scheme.
 * Utilities::                   Package management commands.
 * GNU Distribution::            Software for your friendly GNU system.
@@ -101,13 +102,20 @@ Package Management
 
 * Features::                    How Guix will make your life brighter.
 * Invoking guix package::       Package installation, removal, etc.
-* Emacs Interface::             Package management from Emacs.
 * Substitutes::                 Downloading pre-built binaries.
 * Packages with Multiple Outputs::  Single source package, multiple outputs.
 * Invoking guix gc::            Running the garbage collector.
 * Invoking guix pull::          Fetching the latest Guix and distribution.
 * Invoking guix archive::       Exporting and importing store files.
 
+Emacs Interface
+
+* Initial Setup: Emacs Initial Setup.	Preparing @file{~/.emacs}.
+* Package Management: Emacs Package Management.	Managing packages and generations.
+* Popup Interface: Emacs Popup Interface.	Magit-like interface for guix commands.
+* Prettify Mode: Emacs Prettify.	Abbreviating @file{/gnu/store/@dots{}} file names.
+* Completions: Emacs Completions.       Completing @command{guix} shell command.
+
 Programming Interface
 
 * Defining Packages::           Defining new packages.
@@ -964,14 +972,13 @@ features.
 
 This chapter describes the main features of Guix, as well as the package
 management tools it provides.  Two user interfaces are provided for
-routine package management tasks: a command-line interface
-(@pxref{Invoking guix package, @code{guix package}}), and a visual user
-interface in Emacs (@pxref{Emacs Interface}).
+routine package management tasks: A command-line interface described below
+(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user
+interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}).
 
 @menu
 * Features::                    How Guix will make your life brighter.
 * Invoking guix package::       Package installation, removal, etc.
-* Emacs Interface::             Package management from Emacs.
 * Substitutes::                 Downloading pre-built binaries.
 * Packages with Multiple Outputs::  Single source package, multiple outputs.
 * Invoking guix gc::            Running the garbage collector.
@@ -1455,8 +1462,6 @@ Finally, since @command{guix package} may actually start build
 processes, it supports all the common build options that @command{guix
 build} supports (@pxref{Invoking guix build, common build options}).
 
-@include emacs.texi
-
 @node Substitutes
 @section Substitutes
 
@@ -1898,6 +1903,8 @@ automatically builds them.  The build process may be controlled with the
 same options that can be passed to the @command{guix build} command
 (@pxref{Invoking guix build, common build options}).
 
+@c *********************************************************************
+@include emacs.texi
 
 @c *********************************************************************
 @node Programming Interface
@@ -2484,6 +2491,16 @@ passes flags specified by the @code{#:make-maker-flags} or
 Which Perl package is used can be specified with @code{#:perl}.
 @end defvr
 
+@defvr {Scheme Variable} r-build-system
+This variable is exported by @code{(guix build-system r)}.  It
+implements the build procedure used by @uref{http://r-project.org, R}
+packages, which essentially is little more than running @code{R CMD
+INSTALL --library=/gnu/store/@dots{}} in an environment where
+@code{R_LIBS_SITE} contains the paths to all R package inputs.  Tests
+are run after installation using the R function
+@code{tools::testInstalledPackage}.
+@end defvr
+
 @defvr {Scheme Variable} ruby-build-system
 This variable is exported by @code{(guix build-system ruby)}.  It
 implements the RubyGems build procedure used by Ruby packages, which
@@ -3612,7 +3629,7 @@ Make @var{file} a symlink to the result, and register it as a garbage
 collector root.
 
 @item --log-file
-Return the build log file names for the given
+Return the build log file names or URLs for the given
 @var{package-or-derivation}s, or raise an error if build logs are
 missing.
 
@@ -3626,7 +3643,19 @@ guix build --log-file guile
 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
 @end example
 
+If a log is unavailable locally, and unless @code{--no-substitutes} is
+passed, the command looks for a corresponding log on one of the
+substitute servers (as specified with @code{--substitute-urls}.)
+
+So for instance, let's say you want to see the build log of GDB on MIPS
+but you're actually on an @code{x86_64} machine:
 
+@example
+$ guix build --log-file gdb -s mips64el-linux 
+http://hydra.gnu.org/log/@dots{}-gdb-7.10
+@end example
+
+You can freely access a huge library of build logs!
 @end table
 
 @cindex common build options
@@ -3932,6 +3961,21 @@ Perl module:
 guix import cpan Acme::Boolean
 @end example
 
+@item cran
+@cindex CRAN
+Import meta-data from @uref{http://cran.r-project.org/, CRAN}, the
+central repository for the @uref{http://r-project.org, GNU@tie{}R
+statistical and graphical environment}.
+
+Information is extracted from the HTML package description.
+
+The command command below imports meta-data for the @code{Cairo}
+R package:
+
+@example
+guix import cran Cairo
+@end example
+
 @item nix
 Import meta-data from a local copy of the source of the
 @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
@@ -4385,6 +4429,16 @@ the values listed above.
 
 @item --list-types
 List the supported graph types.
+
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This is useful to precisely refer to a package, as in this example:
+
+@example
+guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
+@end example
 @end table
 
 
@@ -5477,7 +5531,7 @@ special-case and is automatically added whether or not it is specified.
 A @dfn{locale} defines cultural conventions for a particular language
 and region of the world (@pxref{Locales,,, libc, The GNU C Library
 Reference Manual}).  Each locale has a name that typically has the form
-@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
+@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
 @code{fr_LU.utf8} designates the locale for the French language, with
 cultural conventions from Luxembourg, and using the UTF-8 encoding.
 
@@ -5538,9 +5592,17 @@ IANA}.
 @end deftp
 
 @defvr {Scheme Variable} %default-locale-definitions
-An arbitrary list of commonly used locales, used as the default value of
-the @code{locale-definitions} field of @code{operating-system}
+An arbitrary list of commonly used UTF-8 locales, used as the default
+value of the @code{locale-definitions} field of @code{operating-system}
 declarations.
+
+@cindex locale name
+@cindex normalized codeset in locale names
+These locale definitions use the @dfn{normalized codeset} for the part
+that follows the dot in the name (@pxref{Using gettextized software,
+normalized codeset,, libc, The GNU C Library Reference Manual}).  So for
+instance it has @code{uk_UA.utf8} but @emph{not}, say,
+@code{uk_UA.UTF-8}.
 @end defvr
 
 @node Services
@@ -6009,6 +6071,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
@@ -6037,6 +6100,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
 
+@deffn {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:
+
+@table @code
+@item kill-user-processes?
+@code{#f}
+@item kill-only-users
+@code{()}
+@item kill-exclude-users
+@code{("root")}
+@item inhibit-delay-max-seconds
+@code{5}
+@item handle-power-key
+@code{poweroff}
+@item handle-suspend-key
+@code{suspend}
+@item handle-hibernate-key
+@code{hibernate}
+@item handle-lid-switch
+@code{suspend}
+@item handle-lid-switch-docked
+@code{ignore}
+@item power-key-ignore-inhibited?
+@code{#f}
+@item suspend-key-ignore-inhibited?
+@code{#f}
+@item hibernate-key-ignore-inhibited?
+@code{#f}
+@item lid-switch-ignore-inhibited?
+@code{#t}
+@item holdoff-timeout-seconds
+@code{30}
+@item idle-action
+@code{ignore}
+@item idle-action-seconds
+@code{(* 30 60)}
+@item runtime-directory-size-percent
+@code{10}
+@item runtime-directory-size
+@code{#f}
+@item remove-ipc?
+@code{#t}
+@item suspend-state
+@code{("mem" "standby" "freeze")}
+@item suspend-mode
+@code{()}
+@item hibernate-state
+@code{("disk")}
+@item hibernate-mode
+@code{("platform" "shutdown")}
+@item hybrid-sleep-state
+@code{("disk")}
+@item hybrid-sleep-mode
+@code{("suspend" "platform" "shutdown")}
+@end table
+@end deffn
+
+@deffn {Monadic Procedure} polkit-service @
+                         [#:polkit @var{polkit}]
+Return a service that runs the Polkit privilege manager.
+@uref{http://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.
+@end deffn
+
 @deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
                          [#:watts-up-pro? #f] @
                          [#:poll-batteries? #t] @