Merge branch 'master' into gnome-team

Change-Id: I88d3789460d1a89917451d80405d89a2824006ac

3 files changed, 153 insertions, 157 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index ac7f8d2e0f..30876447d4 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1666,7 +1666,7 @@ relies on the @file{etc/teams.scm} script, which can also be invoked
 manually if you do not use the preferred @command{git send-email}
 command to submit patches.  To list the available actions of the script,
 you can invoke it via the @command{etc/teams.scm help} command.  For
-more information regarding teams, see @xref{Teams}.
+more information regarding teams, @pxref{Teams}.
 
 @unnumberedsubsubsec Multiple Patches
 @anchor{Multiple Patches}
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 712c131a51..3d86fca396 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3714,7 +3714,7 @@ reference.
 @section Guix Profiles in Practice
 
 Guix provides a very useful feature that may be quite foreign to newcomers:
-@emph{profiles}.  They are a way to group package installations together and all users
+@dfn{profiles}.  They are a way to group package installations together and all users
 on the same system are free to use as many profiles as they want.
 
 Whether you're a developer or not, you may find that multiple profiles bring you
@@ -3722,6 +3722,16 @@ great power and flexibility.  While they shift the paradigm somewhat compared to
 @emph{traditional package managers}, they are very convenient to use once you've
 understood how to set them up.
 
+@quotation Note
+This section is an opinionated guide on the use of multiple profiles.
+It predates @command{guix shell} and its fast profile cache
+(@pxref{Invoking guix shell,,, guix, GNU Guix Reference Manual}).
+
+In many cases, you may find that using @command{guix shell} to set up
+the environment you need, when you need it, is less work that
+maintaining a dedicated profile.  Your call!
+@end quotation
+
 If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a
 kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not
 just Python software.  Furthermore, profiles are self-sufficient: they capture
@@ -3977,7 +3987,9 @@ without having to specify the path to a profile.
 @node The benefits of manifests
 @subsection The benefits of manifests
 
-Manifests are a convenient way to keep your package lists around and, say,
+Manifests let you @dfn{declare} the set of packages you'd like to have
+in a profile (@pxref{Writing Manifests,,, guix, GNU Guix Reference Manual}).
+They are a convenient way to keep your package lists around and, say,
 to synchronize them across multiple machines using a version control system.
 
 A common complaint about manifests is that they can be slow to install when they
@@ -4034,29 +4046,12 @@ profiles, they are not strictly equivalent: profiles have the side effect that
 they ``pin'' packages in the store, which prevents them from being
 garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
 and ensures that they will still be available at any point in
-the future.
-
-Let's take an example:
-
-@enumerate
-@item
-We have an environment for hacking on a project for which there isn't a Guix
-package yet.  We build the environment using a manifest, and then run @code{guix
-   environment -m manifest.scm}.  So far so good.
+the future.  The @command{guix shell} command also protects
+recently-used profiles from garbage collection; profiles that have not
+been used for a while may be garbage-collected though, along with the
+packages they refer to.
 
-@item
-Many weeks pass and we have run a couple of @code{guix pull} in the mean time.
-Maybe a dependency from our manifest has been updated; or we may have run
-@code{guix gc} and some packages needed by our manifest have been
-garbage-collected.
-
-@item
-Eventually, we set to work on that project again, so we run @code{guix shell
-   -m manifest.scm}.  But now we have to wait for Guix to build and install
-stuff!
-@end enumerate
-
-Ideally, we could spare the rebuild time.  And indeed we can, all we need is to
+To be 100% sure that a given profile will never be collected,
 install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile;
 . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our
 hacking environment will be available at all times.
@@ -4071,16 +4066,18 @@ To reproduce a profile bit-for-bit, we need two pieces of information:
 
 @itemize
 @item
-a manifest,
+a manifest (@pxref{Writing Manifests,,, guix, GNU Guix Reference Manual});
 @item
-a Guix channel specification.
+a Guix channel specification (@pxref{Replicating Guix,,, guix, GNU Guix
+Reference Manual}).
 @end itemize
 
 Indeed, manifests alone might not be enough: different Guix versions (or
 different channels) can produce different outputs for a given manifest.
 
 You can output the Guix channel specification with @samp{guix describe
---format=channels}.
+--format=channels} (@pxref{Invoking guix describe,,, guix, GNU Guix
+Reference Manual}).
 Save this to a file, say @samp{channel-specs.scm}.
 
 On another computer, you can use the channel specification file and the manifest
@@ -4331,7 +4328,7 @@ guix build -f guix.scm --target=x86_64-w64-mingw32
 @end lisp
 
 You can also use @dfn{package transformations} to test package variants
-(@pxref{Package Transformations,,, guix, GNU Guix Reference Manual}):
+(@pxref{Package Transformation Options,,, guix, GNU Guix Reference Manual}):
 
 @example
 # What if we built with Clang instead of GCC?
diff --git a/doc/guix.texi b/doc/guix.texi
index c67404a007..61892866af 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -185,7 +185,6 @@ Weblate} (@pxref{Translating Guix}).
 * Introduction::                What is Guix about?
 * Installation::                Installing Guix.
 * System Installation::         Installing the whole operating system.
-* System Troubleshooting Tips::  When things don't go as planned.
 * Getting Started::             Your first steps.
 * Package Management::          Package installation, upgrade, etc.
 * Channels::                    Customizing the package collection.
@@ -194,6 +193,7 @@ Weblate} (@pxref{Translating Guix}).
 * Utilities::                   Package management commands.
 * Foreign Architectures::       Build for foreign architectures.
 * System Configuration::        Configuring the operating system.
+* System Troubleshooting Tips::  When things don't go as planned.
 * Home Configuration::          Configuring the home environment.
 * Documentation::               Browsing software user manuals.
 * Platforms::                   Defining platforms.
@@ -251,10 +251,6 @@ Manual Installation
 * Keyboard Layout and Networking and Partitioning::  Initial setup.
 * Proceeding with the Installation::  Installing.
 
-System Troubleshooting Tips
-
-* Chrooting into an existing system::
-
 Package Management
 
 * Features::                    How Guix will make your life brighter.
@@ -427,6 +423,10 @@ Defining Services
 * Shepherd Services::           A particular type of service.
 * Complex Configurations::      Defining bindings for complex configurations.
 
+System Troubleshooting Tips
+
+* Chrooting into an existing system::
+
 Home Configuration
 
 * Declaring the Home Environment::  Customizing your Home.
@@ -2978,123 +2978,6 @@ guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-b
 @code{A20-OLinuXino-Lime2} is the name of the board.  If you specify an invalid
 board, a list of possible boards will be printed.
 
-@c *********************************************************************
-@cindex troubleshooting, guix system
-@cindex guix system troubleshooting
-@node System Troubleshooting Tips
-@chapter System Troubleshooting Tips
-
-Guix System allows rebooting into a previous generation should the last
-one be malfunctioning, which makes it quite robust against being broken
-irreversibly.  This feature depends on GRUB being correctly functioning
-though, which means that if for whatever reasons your GRUB installation
-becomes corrupted during a system reconfiguration, you may not be able
-to easily boot into a previous generation.  A technique that can be used
-in this case is to @i{chroot} into your broken system and reconfigure it
-from there.  Such technique is explained below.
-
-@cindex chroot, guix system
-@cindex chrooting, guix system
-@cindex repairing GRUB, via chroot
-@menu
-* Chrooting into an existing system::
-@end menu
-
-@node Chrooting into an existing system
-@section Chrooting into an existing system
-
-This section details how to @i{chroot} to an already installed Guix
-System with the aim of reconfiguring it, for example to fix a broken
-GRUB installation.  The process is similar to how it would be done on
-other GNU/Linux systems, but there are some Guix System particularities
-such as the daemon and profiles that make it worthy of explaining here.
-
-@enumerate
-@item
-Obtain a bootable image of Guix System.  It is recommended the latest
-development snapshot so the kernel and the tools used are at least as as
-new as those of your installed system; it can be retrieved from the
-@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
-https://ci.guix.gnu.org} URL.  Follow the @pxref{USB Stick and DVD
-Installation} section for copying it to a bootable media.
-
-@item
-Boot the image, and proceed with the graphical text-based installer
-until your network is configured.  Alternatively, you could configure
-the network manually by following the
-@ref{manual-installation-networking} section.  If you get the error
-@samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
-@samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
-is your device identifier (ID).
-
-@item
-Switch to a virtual console (tty) if you haven't already by pressing
-simultaneously the @kbd{Control + Alt + F4} keys.  Mount your file
-system at @file{/mnt}.  Assuming your root partition is
-@file{/dev/sda2}, you would do:
-
-@example sh
-mount /dev/sda2 /mnt
-@end example
-
-@item
-Mount special block devices and Linux-specific directories:
-
-@example sh
-mount --rbind /proc /mnt/proc
-mount --rbind /sys /mnt/sys
-mount --rbind /dev /mnt/dev
-@end example
-
-If your system is EFI-based, you must also mount the ESP partition.
-Assuming it is @file{/dev/sda1}, you can do so with:
-
-@example sh
-mount /dev/sda1 /mnt/boot/efi
-@end example
-
-@item
-Enter your system via chroot:
-
-@example sh
-chroot /mnt /bin/sh
-@end example
-
-@item
-Source the system profile as well as your @var{user} profile to setup
-the environment, where @var{user} is the user name used for the Guix
-System you are attempting to repair:
-
-@example sh
-source /var/guix/profiles/system/profile/etc/profile
-source /home/@var{user}/.guix-profile/etc/profile
-@end example
-
-To ensure you are working with the Guix revision you normally would as
-your normal user, also source your current Guix profile:
-
-@example sh
-source /home/@var{user}/.config/guix/current/etc/profile
-@end example
-
-@item
-Start a minimal @command{guix-daemon} in the background:
-
-@example sh
-guix-daemon --build-users-group=guixbuild --disable-chroot &
-@end example
-
-@item
-Edit your Guix System configuration if needed, then reconfigure with:
-
-@example sh
-guix system reconfigure your-config.scm
-@end example
-
-@item
-Finally, you should be good to reboot the system to test your fix.
-
-@end enumerate
 
 @c *********************************************************************
 @node Getting Started
@@ -3191,6 +3074,10 @@ deleting old generations, collecting garbage, and other nifty features
 that will come in handy as you become more familiar with Guix.  If you
 are a developer, @pxref{Development} for additional tools.  And if
 you're curious, @pxref{Features}, to peek under the hood.
+
+You can also manage the configuration of your entire @dfn{home
+environment}---your user ``dot files'', services, and packages---using
+Guix Home.  @xref{Home Configuration}, to learn more about it!
 @end quotation
 
 Once you've installed a set of packages, you will want to periodically
@@ -43148,6 +43035,124 @@ is-married = true
 @end example
 
 
+@c *********************************************************************
+@cindex troubleshooting, Guix System
+@cindex guix system troubleshooting
+@node System Troubleshooting Tips
+@chapter System Troubleshooting Tips
+
+Guix System allows rebooting into a previous generation should the last
+one be malfunctioning, which makes it quite robust against being broken
+irreversibly.  This feature depends on GRUB being correctly functioning
+though, which means that if for whatever reasons your GRUB installation
+becomes corrupted during a system reconfiguration, you may not be able
+to easily boot into a previous generation.  A technique that can be used
+in this case is to @i{chroot} into your broken system and reconfigure it
+from there.  Such technique is explained below.
+
+@cindex chroot, guix system
+@cindex chrooting, guix system
+@cindex repairing GRUB, via chroot
+@menu
+* Chrooting into an existing system::
+@end menu
+
+@node Chrooting into an existing system
+@section Chrooting into an existing system
+
+This section details how to @i{chroot} to an already installed Guix
+System with the aim of reconfiguring it, for example to fix a broken
+GRUB installation.  The process is similar to how it would be done on
+other GNU/Linux systems, but there are some Guix System particularities
+such as the daemon and profiles that make it worthy of explaining here.
+
+@enumerate
+@item
+Obtain a bootable image of Guix System.  It is recommended the latest
+development snapshot so the kernel and the tools used are at least as as
+new as those of your installed system; it can be retrieved from the
+@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
+https://ci.guix.gnu.org} URL.  Follow the @pxref{USB Stick and DVD
+Installation} section for copying it to a bootable media.
+
+@item
+Boot the image, and proceed with the graphical text-based installer
+until your network is configured.  Alternatively, you could configure
+the network manually by following the
+@ref{manual-installation-networking} section.  If you get the error
+@samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
+@samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
+is your device identifier (ID).
+
+@item
+Switch to a virtual console (tty) if you haven't already by pressing
+simultaneously the @kbd{Control + Alt + F4} keys.  Mount your file
+system at @file{/mnt}.  Assuming your root partition is
+@file{/dev/sda2}, you would do:
+
+@example sh
+mount /dev/sda2 /mnt
+@end example
+
+@item
+Mount special block devices and Linux-specific directories:
+
+@example sh
+mount --rbind /proc /mnt/proc
+mount --rbind /sys /mnt/sys
+mount --rbind /dev /mnt/dev
+@end example
+
+If your system is EFI-based, you must also mount the ESP partition.
+Assuming it is @file{/dev/sda1}, you can do so with:
+
+@example sh
+mount /dev/sda1 /mnt/boot/efi
+@end example
+
+@item
+Enter your system via chroot:
+
+@example sh
+chroot /mnt /bin/sh
+@end example
+
+@item
+Source the system profile as well as your @var{user} profile to setup
+the environment, where @var{user} is the user name used for the Guix
+System you are attempting to repair:
+
+@example sh
+source /var/guix/profiles/system/profile/etc/profile
+source /home/@var{user}/.guix-profile/etc/profile
+@end example
+
+To ensure you are working with the Guix revision you normally would as
+your normal user, also source your current Guix profile:
+
+@example sh
+source /home/@var{user}/.config/guix/current/etc/profile
+@end example
+
+@item
+Start a minimal @command{guix-daemon} in the background:
+
+@example sh
+guix-daemon --build-users-group=guixbuild --disable-chroot &
+@end example
+
+@item
+Edit your Guix System configuration if needed, then reconfigure with:
+
+@example sh
+guix system reconfigure your-config.scm
+@end example
+
+@item
+Finally, you should be good to reboot the system to test your fix.
+
+@end enumerate
+
 @node Home Configuration
 @chapter Home Configuration
 @cindex home configuration
@@ -43163,12 +43168,6 @@ command (@pxref{Invoking guix home}).
 @c Maybe later, it will be possible to make home configuration a part of
 @c system configuration to make everything managed by guix system.
 
-@quotation Note
-The functionality described in this section is still under development
-and is subject to change.  Get in touch with us on
-@email{guix-devel@@gnu.org}!
-@end quotation
-
 The user's home environment usually consists of three basic parts:
 software, configuration, and state.  Software in mainstream distros are
 usually installed system-wide, but with GNU Guix most software packages