Merge branch 'staging' into core-updates.

5 files changed, 1353 insertions, 257 deletions

diff --git a/doc/build.scm b/doc/build.scm
index 47cff15985..9d79215b98 100644
--- a/doc/build.scm
+++ b/doc/build.scm
@@ -65,7 +65,7 @@
 (define %languages
   ;; The cookbook is not translated in the same languages as the manual
   (if (string=? %manual "guix-cookbook")
-      '("de" "en" "fr")
+      '("de" "en" "fr" "sk")
       '("de" "en" "es" "fr" "ru" "zh_CN")))
 
 (define (texinfo-manual-images source)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9f97788c0b..207efc4ee6 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -98,8 +98,14 @@ shell}:
 guix shell -D guix help2man git strace --pure
 @end example
 
-Run @command{./bootstrap} to generate the build system infrastructure
-using Autoconf and Automake.  If you get an error like this one:
+From there you can generate the build system infrastructure
+using Autoconf and Automake:
+
+@example
+./bootstrap
+@end example
+
+If you get an error like this one:
 
 @example
 configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES
@@ -120,17 +126,30 @@ export ACLOCAL_PATH=/usr/share/aclocal
 @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
 more information.
 
-Then, run @command{./configure --localstatedir=@var{directory}}, where
-@var{directory} is the @code{localstatedir} value used by your current
-installation (@pxref{The Store}, for information about this), usually
-@file{/var}.  Note that you will probably not run @command{make install}
-at the end (you don't have to) but it's still important to pass the
-right @code{localstatedir}.
+Then, run:
+
+@example
+./configure --localstatedir=/var
+@end example
+
+@noindent
+... where @file{/var} is the normal @code{localstatedir} value
+(@pxref{The Store}, for information about this).  Note that you will
+probably not run @command{make install} at the end (you don't have to)
+but it's still important to pass the right @code{localstatedir}.
+
+Finally, you can build Guix and, if you feel so inclined, run the tests
+(@pxref{Running the Test Suite}):
 
-Finally, you have to invoke @code{make && make check} to build Guix and
-run the tests (@pxref{Running the Test Suite}).  If anything fails, take
-a look at installation instructions (@pxref{Installation}) or send a
-message to the @email{guix-devel@@gnu.org, mailing list}.
+@example
+make
+make check
+@end example
+
+@noindent
+If anything fails, take a look at installation instructions
+(@pxref{Installation}) or send a message to the
+@email{guix-devel@@gnu.org, mailing list}.
 
 From there on, you can authenticate all the commits included in your
 checkout by running:
@@ -157,6 +176,18 @@ You are advised to run @command{make authenticate} after every
 changes to the repository.
 @end quotation
 
+After updating the repository, @command{make} might fail with an error
+similar to the following example:
+
+@example
+error: failed to load 'gnu/packages/dunst.scm':
+ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
+@end example
+
+This means that one of the record types that Guix defines (in this
+example, the @code{origin} record) has changed, and all of guix needs
+to be recompiled to take that change into account.  To do so, run
+@command{make clean-go} followed by @command{make}.
 
 @node Running Guix Before It Is Installed
 @section Running Guix Before It Is Installed
@@ -231,6 +262,24 @@ local source tree; it simply updates the @file{~/.config/guix/current}
 symlink (@pxref{Invoking guix pull}).  Run @command{git pull} instead if
 you want to upgrade your local source tree.
 
+Sometimes, especially if you have recently updated your repository,
+running @command{./pre-inst-env} will print a message similar to the
+following example:
+
+@example
+;;; note: source file /home/user/projects/guix/guix/progress.scm
+;;;       newer than compiled /home/user/projects/guix/guix/progress.go
+@end example
+
+This is only a note and you can safely ignore it.  You can get rid of
+the message by running @command{make -j4}.  Until you do, Guile will run
+slightly slower because it will interpret the code instead of using
+prepared Guile object (@file{.go}) files.
+
+You can run @command{make} automatically as you work using
+@command{watchexec} from the @code{watchexec} package.  For example,
+to build again each time you update a package file, you can run
+@samp{watchexec -w gnu/packages make -j4}.
 
 @node The Perfect Setup
 @section The Perfect Setup
@@ -1386,9 +1435,14 @@ what your usertag means.
 @cindex commit access, for developers
 Everyone can contribute to Guix without having commit access
 (@pxref{Submitting Patches}).  However, for frequent contributors,
-having write access to the repository can be convenient.  Commit access
-should not be thought of as a ``badge of honor'' but rather as a
-responsibility a contributor is willing to take to help the project.
+having write access to the repository can be convenient.  As a rule of
+thumb, a contributor should have accumulated fifty (50) reviewed commits
+to be considered as a committer and have sustained their activity in the
+project for at least 6 months.  This ensures enough interactions with
+the contributor, which is essential for mentoring and assessing whether
+they are ready to become a committer.  Commit access should not be
+thought of as a ``badge of honor'' but rather as a responsibility a
+contributor is willing to take to help the project.
 
 The following sections explain how to get commit access, how to be ready
 to push commits, and the policies and community expectations for commits
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index d2ce525998..d89ce66017 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -7,6 +7,9 @@
 @settitle GNU Guix Cookbook
 @c %**end of header
 
+@c Onion service for ci.guix.gnu.org.
+@set SUBSTITUTE-TOR-URL https://4zwzi66wwdaalbhgnix55ea3ab4pvvw66ll2ow53kjub6se4q2bclcyd.onion
+
 @copying
 Copyright @copyright{} 2019 Ricardo Wurmus@*
 Copyright @copyright{} 2019 Efraim Flashner@*
@@ -2354,7 +2357,8 @@ follow:
           config => (guix-configuration
                       (inherit config)
                       ;; ci.guix.gnu.org's Onion service
-                      (substitute-urls "https://bp7o7ckwlewr4slm.onion")
+                      (substitute-urls
+                       "@value{SUBSTITUTE-TOR-URL}")
                       (http-proxy "http://localhost:9250")))))))
 @end lisp
 
@@ -2372,7 +2376,8 @@ want to get a substitute from the Tor tunnel run:
 
 @example
 sudo herd set-http-proxy guix-daemon http://localhost:9250
-guix build --substitute-urls=https://bp7o7ckwlewr4slm.onion …
+guix build \
+  --substitute-urls=@value{SUBSTITUTE-TOR-URL} @dots{}
 @end example
 
 @node Setting up NGINX with Lua
diff --git a/doc/guix.texi b/doc/guix.texi
index 8ab86b1181..7bd80a1592 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -47,7 +47,7 @@ Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
 Copyright @copyright{} 2017 Thomas Danckaert@*
 Copyright @copyright{} 2017 humanitiesNerd@*
 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
-Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Marius Bakke@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
 Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
 Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
@@ -175,6 +175,7 @@ Weblate} (@pxref{Translating Guix}).
 * Home Configuration::          Configuring the home environment.
 * Documentation::               Browsing software user manuals.
 * Installing Debugging Files::  Feeding the debugger.
+* Using TeX and LaTeX::         Typesetting.
 * Security Updates::            Deploying security fixes quickly.
 * Bootstrapping::               GNU/Linux built from scratch.
 * Porting::                     Targeting another platform or kernel.
@@ -1867,8 +1868,24 @@ $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
 
 Note that the @code{glibc-locales} package contains data for all the
 locales supported by the GNU@tie{}libc and weighs in at around
-917@tie{}MiB@.  Alternatively, the @code{glibc-utf8-locales} is smaller but
-limited to a few UTF-8 locales.
+930@tie{}MiB@footnote{The size of the @code{glibc-locales} package is
+reduced down to about 213@tie{}MiB with store deduplication and further
+down to about 67@tie{}MiB when using a zstd-compressed Btrfs file
+system.}.  If you only need a few locales, you can define your custom
+locales package via the @code{make-glibc-utf8-locales} procedure from
+the @code{(gnu packages base)} module.  The following example defines a
+package containing the various Canadian UTF-8 locales known to the
+GNU@tie{}libc, that weighs around 14@tie{}MiB:
+
+@lisp
+(use-modules (gnu packages base))
+
+(define my-glibc-locales
+  (make-glibc-utf8-locales
+   glibc
+   #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA")
+   #:name "glibc-canadian-utf8-locales"))
+@end lisp
 
 The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
 (@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
@@ -4426,18 +4443,12 @@ Generation 2	Jun 11 2018 11:02:49
     repository URL: https://git.savannah.gnu.org/git/guix.git
     branch: origin/master
     commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
-  2 new packages: keepalived, libnfnetlink
-  6 packages upgraded: emacs-nix-mode@@2.0.4,
-    guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
-    heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
 
 Generation 3	Jun 13 2018 23:31:07	(current)
   guix 844cc1c
     repository URL: https://git.savannah.gnu.org/git/guix.git
     branch: origin/master
     commit: 844cc1c8f394f03b404c5bb3aee086922373490c
-  28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
-  69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
 @end example
 
 @xref{Invoking guix describe, @command{guix describe}}, for other ways to
@@ -4492,13 +4503,13 @@ information.
 @cindex channel news
 @item --news
 @itemx -N
-Display the list of packages added or upgraded since the previous
-generation, as well as, occasionally, news written by channel authors
-for their users (@pxref{Channels, Writing Channel News}).
+Display news written by channel authors for their users for changes made
+since the previous generation (@pxref{Channels, Writing Channel News}).
+When @option{--details} is passed, additionally display new and upgraded
+packages.
 
-The package information is the same as displayed upon @command{guix
-pull} completion, but without ellipses; it is also similar to the output
-of @command{guix pull -l} for the last generation (see below).
+You can view that information for previous generations with
+@command{guix pull -l}.
 
 @item --list-generations[=@var{pattern}]
 @itemx -l [@var{pattern}]
@@ -4507,6 +4518,16 @@ is provided, the subset of generations that match @var{pattern}.
 The syntax of @var{pattern} is the same as with @code{guix package
 --list-generations} (@pxref{Invoking guix package}).
 
+By default, this prints information about the channels used in each
+revision as well as the corresponding news entries.  If you pass
+@option{--details}, it will also print the list of packages added and
+upgraded in each generation compared to the previous one.
+
+@item --details
+Instruct @option{--list-generations} or @option{--news} to display more
+information about the differences between subsequent generations---see
+above.
+
 @item --roll-back
 @cindex rolling back
 @cindex undoing transactions
@@ -5448,7 +5469,9 @@ commit of a channel that should be authenticated.  The first time a
 channel is fetched with @command{guix pull} or @command{guix
 time-machine}, the command looks up the introductory commit and verifies
 that it is signed by the specified OpenPGP key.  From then on, it
-authenticates commits according to the rule above.
+authenticates commits according to the rule above.  Authentication fails
+if the target commit is neither a descendant nor an ancestor of the
+introductory commit.
 
 Additionally, your channel must provide all the OpenPGP keys that were
 ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
@@ -5824,6 +5847,12 @@ This is similar to the same-named option in @command{guix package}
 (@pxref{profile-manifest, @option{--manifest}}) and uses the same
 manifest files.
 
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Create an environment containing the packages installed in @var{profile}. 
+Use @command{guix package} (@pxref{Invoking guix package}) to create
+and manage profiles.
+
 @item --pure
 Unset existing environment variables when building the new environment, except
 those specified with @option{--preserve} (see below).  This has the effect of
@@ -6231,6 +6260,12 @@ interpreted as packages whose dependencies will be added to the
 environment, the default behavior.  Packages appearing after are
 interpreted as packages that will be added to the environment directly.
 
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Create an environment containing the packages installed in @var{profile}. 
+Use @command{guix package} (@pxref{Invoking guix package}) to create
+and manage profiles.
+
 @item --pure
 Unset existing environment variables when building the new environment, except
 those specified with @option{--preserve} (see below).  This has the effect of
@@ -9472,8 +9507,7 @@ scripts so that they refer to @code{grep} by its absolute file name:
         (substitute* (list (string-append bin "/egrep")
                            (string-append bin "/fgrep"))
           (("^exec grep")
-           (string-append "exec " bin "/grep")))
-        #t))))
+           (string-append "exec " bin "/grep")))))))
 @end lisp
 
 In the example below, phases are modified in two ways: the standard
@@ -9492,12 +9526,95 @@ executable files to be installed:
       (let ((bin (string-append (assoc-ref outputs "out")
                                 "/bin")))
         (install-file "footswitch" bin)
-        (install-file "scythe" bin)
-        #t))))
+        (install-file "scythe" bin)))))
 @end lisp
 
 @c TODO: Add more examples.
 
+@subsection Wrappers
+
+@cindex program wrappers
+@cindex wrapping programs
+It is not unusual for a command to require certain environment variables
+to be set for proper functioning, typically search paths (@pxref{Search
+Paths}).  Failing to do that, the command might fail to find files or
+other commands it relies on, or it might pick the ``wrong''
+ones---depending on the environment in which it runs.  Examples include:
+
+@itemize
+@item
+a shell script that assumes all the commands it uses are in @env{PATH};
+
+@item
+a Guile program that assumes all its modules are in @env{GUILE_LOAD_PATH}
+and @env{GUILE_LOAD_COMPILED_PATH};
+
+@item
+a Qt application that expects to find certain plugins in
+@env{QT_PLUGIN_PATH}.
+@end itemize
+
+For a package writer, the goal is to make sure commands always work the
+same rather than depend on some external settings.  One way to achieve
+that is to @dfn{wrap} commands in a thin script that sets those
+environment variables, thereby ensuring that those run-time dependencies
+are always found.  The wrapper would be used to set @env{PATH},
+@env{GUILE_LOAD_PATH}, or @env{QT_PLUGIN_PATH} in the examples above.
+
+To ease that task, the @code{(guix build utils)} module provides a
+couple of helpers to wrap commands.
+
+@deffn {Scheme Procedure} wrap-program @var{program} @
+  [#:sh @var{sh}] [#:rest @var{variables}]
+Make a wrapper for @var{program}.  @var{variables} should look like this:
+
+@lisp
+'(@var{variable} @var{delimiter} @var{position} @var{list-of-directories})
+@end lisp
+
+where @var{delimiter} is optional.  @code{:} will be used if
+@var{delimiter} is not given.
+
+For example, this call:
+
+@lisp
+(wrap-program "foo"
+              '("PATH" ":" = ("/gnu/.../bar/bin"))
+              '("CERT_PATH" suffix ("/gnu/.../baz/certs"
+                                    "/qux/certs")))
+@end lisp
+
+will copy @file{foo} to @file{.foo-real} and create the file @file{foo}
+with the following contents:
+
+@example
+#!location/of/bin/bash
+export PATH="/gnu/.../bar/bin"
+export CERT_PATH="$CERT_PATH$@{CERT_PATH:+:@}/gnu/.../baz/certs:/qux/certs"
+exec -a $0 location/of/.foo-real "$@@"
+@end example
+
+If @var{program} has previously been wrapped by @code{wrap-program}, the
+wrapper is extended with definitions for @var{variables}.  If it is not,
+@var{sh} will be used as the interpreter.
+@end deffn
+
+@deffn {Scheme Procedure} wrap-script @var{program} @
+  [#:guile @var{guile}] [#:rest @var{variables}]
+Wrap the script @var{program} such that @var{variables} are set first.
+The format of @var{variables} is the same as in the @code{wrap-program}
+procedure.  This procedure differs from @code{wrap-program} in that it
+does not create a separate shell script.  Instead, @var{program} is
+modified directly by prepending a Guile script, which is interpreted as
+a comment in the script's language.
+
+Special encoding comments as supported by Python are recreated on the
+second line.
+
+Note that this procedure can only be used once per file as Guile scripts are
+not supported.
+@end deffn
+
 @node Search Paths
 @section Search Paths
 
@@ -15734,22 +15851,39 @@ Linux swap partition by running @command{swaplabel @var{device}}, where
 @lisp
 (swap-space
   (target (file-system-label "swap"))
-  (dependencies (list lvm-device)))
+  (dependencies mapped-devices))
 @end lisp
 
-Use the partition with label @code{swap}, which can be found after the
-@var{lvm-device} mapped device has been opened.  Again, the
+Use the partition with label @code{swap}, which can be found after all
+the @var{mapped-devices} mapped devices have been opened.  Again, the
 @command{swaplabel} command allows you to view and change the label of a
 Linux swap partition.
 
+Here's a more involved example with the corresponding @code{file-systems} part
+of an @code{operating-system} declaration.
+
 @lisp
-(swap-space
-  (target "/btrfs/swapfile")
-  (dependencies (list btrfs-fs)))
+(file-systems
+  (list (file-system
+          (device (file-system-label "root"))
+          (mount-point "/")
+          (type "ext4"))
+        (file-system
+          (device (file-system-label "btrfs"))
+          (mount-point "/btrfs")
+          (type "btrfs"))))
+
+(swap-devices
+  (list
+    (swap-space
+      (target "/btrfs/swapfile")
+      (dependencies (filter (file-system-mount-point-predicate "/btrfs")
+                            file-systems)))))
 @end lisp
 
-Use the file @file{/btrfs/swapfile} as swap space, which is present on the
-@var{btrfs-fs} filesystem.
+Use the file @file{/btrfs/swapfile} as swap space, which depends on the
+file system mounted at @file{/btrfs}.  Note how we use Guile's filter to
+select the file system in an elegant fashion!
 
 @node User Accounts
 @section User Accounts
@@ -16631,6 +16765,10 @@ This option accepts, as an integer, the nice value with which to run the
 This option provides an ``escape hatch'' for the user to provide arbitrary
 command-line arguments to @command{agetty} as a list of strings.
 
+@item @code{shepherd-requirement} (default: @code{'()})
+The option can be used to provides extra shepherd requirements (for example
+@code{'syslogd}) to the respective @code{'term-}* shepherd service.
+
 @end table
 @end deftp
 
@@ -16901,6 +17039,18 @@ This example assumes that the file @file{./guix.example.org-key.pub}
 contains the public key that @code{guix.example.org} uses to sign
 substitutes.
 
+@item @code{generate-substitute-key?} (default: @code{#t})
+Whether to generate a @dfn{substitute key pair} under
+@file{/etc/guix/signing-key.pub} and @file{/etc/guix/signing-key.sec} if
+there is not already one.
+
+This key pair is used when exporting store items, for instance with
+@command{guix publish} (@pxref{Invoking guix publish}) or @command{guix
+archive} (@pxref{Invoking guix archive}).  Generating a key pair takes a
+few seconds when enough entropy is available and is only done once; you
+might want to turn it off for instance in a virtual machine that does
+not need it and where the extra boot time is a problem.
+
 @item @code{max-silent-time} (default: @code{0})
 @itemx @code{timeout} (default: @code{0})
 The number of seconds of silence and the number of seconds of activity,
@@ -18716,7 +18866,7 @@ This is the configuration record for OpenSSH's @command{sshd}.
 
 @table @asis
 @item @code{openssh} (default @var{openssh})
-The Openssh package to use.
+The OpenSSH package to use.
 
 @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
 Name of the file where @command{sshd} writes its PID.
@@ -18837,6 +18987,16 @@ Additional authorized keys can be specified @i{via}
 Note that this does @emph{not} interfere with the use of
 @file{~/.ssh/authorized_keys}.
 
+@item @code{generate-host-keys?} (default: @code{#t})
+Whether to generate host key pairs with @command{ssh-keygen -A} under
+@file{/etc/ssh} if there are none.
+
+Generating key pairs takes a few seconds when enough entropy is
+available and is only done once.  You might want to turn it off for
+instance in a virtual machine that does not need it because host keys
+are provided in some other way, and where the extra boot time is a
+problem.
+
 @item @code{log-level} (default: @code{'info})
 This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
 @code{error}, @code{info}, @code{verbose}, @code{debug}, etc.  See the man
@@ -21249,6 +21409,448 @@ bluetooth keyboard or mouse.
 Users need to be in the @code{lp} group to access the D-Bus service.
 @end deffn
 
+@deffn {Scheme Variable} bluetooth-service-type
+This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol
+Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf}
+configuration file.  The value for this type is a @command{bluetooth-configuration}
+record as in this example:
+
+@lisp
+(service bluetooth-service-type)
+@end lisp
+
+See below for details about @code{bluetooth-configuration}.
+@end deffn
+
+@deftp {Data Type} bluetooth-configuration
+Data type representing the configuration for @code{bluetooth-service}.
+
+@table @asis
+@item @code{bluez} (default: @code{bluez})
+@code{bluez} package to use.
+
+@item @code{name} (default: @code{"BlueZ"})
+Default adapter name.
+
+@item @code{class} (default: @code{#x000000})
+Default device class. Only the major and minor device class bits are considered.
+
+@item @code{discoverable-timeout} (default: @code{180})
+How long to stay in discoverable mode before going back to non-discoverable. The
+value is in seconds.
+
+@item @code{always-pairable?} (default: @code{#f})
+Always allow pairing even if there are no agents registered.
+
+@item @code{pairable-timeout} (default: @code{0})
+How long to stay in pairable mode before going back to non-discoverable. The
+value is in seconds.
+
+@item @code{device-id} (default: @code{#f})
+Use vendor id source (assigner), vendor, product and version information for
+DID profile support. The values are separated by ":" and @var{assigner}, @var{VID},
+@var{PID} and @var{version}.
+
+Possible values are:
+
+@itemize @bullet
+@item
+@code{#f} to disable it,
+
+@item
+@code{"assigner:1234:5678:abcd"}, where @var{assigner} is either @code{usb} (default)
+or @code{bluetooth}.
+
+@end itemize
+
+@item @code{reverse-service-discovery?} (default: @code{#t})
+Do reverse service discovery for previously unknown devices that connect to
+us. For BR/EDR this option is really only needed for qualification since the
+BITE tester doesn't like us doing reverse SDP for some test cases, for LE
+this disables the GATT client functionally so it can be used in system which
+can only operate as peripheral.
+
+@item @code{name-resolving?} (default: @code{#t})
+Enable name resolving after inquiry. Set it to @code{#f} if you don't need
+remote devices name and want shorter discovery cycle.
+
+@item @code{debug-keys?} (default: @code{#f})
+Enable runtime persistency of debug link keys. Default is false which makes
+debug link keys valid only for the duration of the connection that they were
+created for.
+
+@item @code{controller-mode} (default: @code{'dual})
+Restricts all controllers to the specified transport. @code{'dual} means both
+BR/EDR and LE are enabled (if supported by the hardware).
+
+Possible values are: 
+
+@itemize @bullet
+@item
+@code{'dual}
+
+@item
+@code{'bredr}
+
+@item
+@code{'le}
+
+@end itemize
+
+@item @code{multi-profile} (default: @code{'off})
+Enables Multi Profile Specification support. This allows to specify if system
+supports only Multiple Profiles Single Device (MPSD) configuration or both
+Multiple Profiles Single Device (MPSD) and Multiple Profiles Multiple Devices
+(MPMD) configurations.
+
+Possible values are:
+
+@itemize @bullet
+@item
+@code{'off}
+
+@item
+@code{'single}
+
+@item
+@code{'multiple}
+
+@end itemize
+
+@item @code{fast-connectable?} (default: @code{#f})
+Permanently enables the Fast Connectable setting for adapters that support
+it. When enabled other devices can connect faster to us, however the
+tradeoff is increased power consumptions. This feature will fully work only
+on kernel version 4.1 and newer.
+
+@item @code{privacy} (default: @code{'off})
+Default privacy settings.
+
+@itemize @bullet
+@item
+@code{'off}: Disable local privacy
+
+@item
+@code{'network/on}: A device will only accept advertising packets from peer
+devices that contain private addresses. It may not be compatible with some
+legacy devices since it requires the use of RPA(s) all the time
+
+@item
+@code{'device}: A device in device privacy mode is only concerned about the
+privacy of the device and will accept advertising packets from peer devices
+that contain their Identity Address as well as ones that contain a private
+address, even if the peer device has distributed its IRK in the past
+
+@end itemize
+
+and additionally, if @var{controller-mode} is set to @code{'dual}:
+
+@itemize @bullet
+@item
+@code{'limited-network}: Apply Limited Discoverable Mode to advertising, which
+follows the same policy as to BR/EDR that publishes the identity address when
+discoverable, and Network Privacy Mode for scanning
+
+@item
+@code{'limited-device}: Apply Limited Discoverable Mode to advertising, which
+follows the same policy as to BR/EDR that publishes the identity address when
+discoverable, and Device Privacy Mode for scanning.
+
+@end itemize
+
+@item @code{just-works-repairing} (default: @code{'never})
+Specify the policy to the JUST-WORKS repairing initiated by peer.
+
+Possible values:
+@itemize @bullet
+@item
+@code{'never}
+
+@item
+@code{'confirm}
+
+@item
+@code{'always}
+
+@end itemize
+
+@item @code{temporary-timeout} (default: @code{30})
+How long to keep temporary devices around. The value is in seconds. @code{0}
+disables the timer completely.
+
+@item @code{refresh-discovery?} (default: @code{#t})
+Enables the device to issue an SDP request to update known services when
+profile is connected.
+
+@item @code{experimental} (default: @code{#f})
+Enables experimental features and interfaces, alternatively a list of UUIDs
+can be given.
+
+Possible values:
+
+@itemize @bullet
+@item
+@code{#t}
+
+@item
+@code{#f}
+
+@item
+@code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
+@end itemize
+
+List of possible UUIDs:
+@itemize @bullet
+@item
+@code{d4992530-b9ec-469f-ab01-6c481c47da1c}: BlueZ Experimental Debug,
+
+@item
+@code{671b10b5-42c0-4696-9227-eb28d1b049d6}: BlueZ Experimental Simultaneous Central and Peripheral,
+
+@item
+@code{"15c0a148-c273-11ea-b3de-0242ac130004}: BlueZ Experimental LL privacy,
+
+@item
+@code{330859bc-7506-492d-9370-9a6f0614037f}: BlueZ Experimental Bluetooth Quality Report,
+
+@item
+@code{a6695ace-ee7f-4fb9-881a-5fac66c629af}: BlueZ Experimental Offload Codecs.
+@end itemize
+
+@item @code{remote-name-request-retry-delay} (default: @code{300})
+The duration to avoid retrying to resolve a peer's name, if the previous
+try failed.
+
+@item @code{page-scan-type} (default: @code{#f})
+BR/EDR Page scan activity type.
+
+@item @code{page-scan-interval} (default: @code{#f})
+BR/EDR Page scan activity interval.
+
+@item @code{page-scan-window} (default: @code{#f})
+BR/EDR Page scan activity window.
+
+@item @code{inquiry-scan-type} (default: @code{#f})
+BR/EDR Inquiry scan activity type.
+
+@item @code{inquiry-scan-interval} (default: @code{#f})
+BR/EDR Inquiry scan activity interval.
+
+@item @code{inquiry-scan-window} (default: @code{#f})
+BR/EDR Inquiry scan activity window.
+
+@item @code{link-supervision-timeout} (default: @code{#f})
+BR/EDR Link supervision timeout.
+
+@item @code{page-timeout} (default: @code{#f})
+BR/EDR Page timeout.
+
+@item @code{min-sniff-interval} (default: @code{#f})
+BR/EDR minimum sniff interval.
+
+@item @code{max-sniff-interval} (default: @code{#f})
+BR/EDR maximum sniff interval.
+
+@item @code{min-advertisement-interval} (default: @code{#f})
+LE minimum advertisement interval (used for legacy advertisement only).
+
+@item @code{max-advertisement-interval} (default: @code{#f})
+LE maximum advertisement interval (used for legacy advertisement only).
+
+@item @code{multi-advertisement-rotation-interval} (default: @code{#f})
+LE multiple advertisement rotation interval.
+
+@item @code{scan-interval-auto-connect} (default: @code{#f})
+LE scanning interval used for passive scanning supporting auto connect.
+
+@item @code{scan-window-auto-connect} (default: @code{#f})
+LE scanning window used for passive scanning supporting auto connect.
+
+@item @code{scan-interval-suspend} (default: @code{#f})
+LE scanning interval used for active scanning supporting wake from suspend.
+
+@item @code{scan-window-suspend} (default: @code{#f})
+LE scanning window used for active scanning supporting wake from suspend.
+
+@item @code{scan-interval-discovery} (default: @code{#f})
+LE scanning interval used for active scanning supporting discovery.
+
+@item @code{scan-window-discovery} (default: @code{#f})
+LE scanning window used for active scanning supporting discovery.
+
+@item @code{scan-interval-adv-monitor} (default: @code{#f})
+LE scanning interval used for passive scanning supporting the advertisement monitor APIs.
+
+@item @code{scan-window-adv-monitor} (default: @code{#f})
+LE scanning window used for passive scanning supporting the advertisement monitor APIs.
+
+@item @code{scan-interval-connect} (default: @code{#f})
+LE scanning interval used for connection establishment.
+
+@item @code{scan-window-connect} (default: @code{#f})
+LE scanning window used for connection establishment.
+
+@item @code{min-connection-interval} (default: @code{#f})
+LE default minimum connection interval. This value is superceeded by any specific
+value provided via the Load Connection Parameters interface.
+
+@item @code{max-connection-interval} (default: @code{#f})
+LE default maximum connection interval. This value is superceeded by any specific
+value provided via the Load Connection Parameters interface.
+
+@item @code{connection-latency} (default: @code{#f})
+LE default connection latency. This value is superceeded by any specific
+value provided via the Load Connection Parameters interface.
+
+@item @code{connection-supervision-timeout} (default: @code{#f})
+LE default connection supervision timeout. This value is superceeded by any specific
+value provided via the Load Connection Parameters interface.
+
+@item @code{autoconnect-timeout} (default: @code{#f})
+LE default autoconnect timeout. This value is superceeded by any specific
+value provided via the Load Connection Parameters interface.
+
+@item @code{adv-mon-allowlist-scan-duration} (default: @code{300})
+Allowlist scan duration during interleaving scan. Only used when scanning for ADV
+monitors. The units are msec.
+
+@item @code{adv-mon-no-filter-scan-duration} (default: @code{500})
+No filter scan duration during interleaving scan. Only used when scanning for ADV
+monitors. The units are msec.
+
+@item @code{enable-adv-mon-interleave-scan?} (default: @code{#t})
+Enable/Disable Advertisement Monitor interleave scan for power saving.
+
+@item @code{cache} (default: @code{'always})
+GATT attribute cache.
+
+Possible values are:
+@itemize @bullet
+@item
+@code{'always}: Always cache attributes even for devices not paired, this is
+recommended as it is best for interoperability, with more consistent
+reconnection times and enables proper tracking of notifications for all
+devices
+
+@item
+@code{'yes}: Only cache attributes of paired devices
+
+@item
+@code{'no}: Never cache attributes.
+@end itemize
+
+@item @code{key-size} (default: @code{0})
+Minimum required Encryption Key Size for accessing secured characteristics.
+
+Possible values are:
+@itemize @bullet
+@item
+@code{0}: Don't care
+
+@item
+@code{7 <= N <= 16}
+@end itemize
+
+@item @code{exchange-mtu} (default: @code{517})
+Exchange MTU size. Possible values are:
+
+@itemize @bullet
+@item
+@code{23 <= N <= 517}
+@end itemize
+
+@item @code{att-channels} (default: @code{3})
+Number of ATT channels. Possible values are:
+
+@itemize @bullet
+@item
+@code{1}: Disables EATT
+
+@item
+@code{2 <= N <= 5}
+@end itemize
+
+@item @code{session-mode} (default: @code{'basic})
+AVDTP L2CAP signalling channel mode.
+
+Possible values are:
+
+@itemize @bullet
+@item
+@code{'basic}: Use L2CAP basic mode
+
+@item
+@code{'ertm}: Use L2CAP enhanced retransmission mode.
+@end itemize
+
+@item @code{stream-mode} (default: @code{'basic})
+AVDTP L2CAP transport channel mode.
+
+Possible values are:
+
+@itemize @bullet
+@item
+@code{'basic}: Use L2CAP basic mode
+
+@item
+@code{'streaming}: Use L2CAP streaming mode.
+@end itemize
+
+@item @code{reconnect-uuids} (default: @code{'()})
+The ReconnectUUIDs defines the set of remote services that should try
+to be reconnected to in case of a link loss (link supervision
+timeout). The policy plugin should contain a sane set of values by
+default, but this list can be overridden here. By setting the list to
+empty the reconnection feature gets disabled.
+
+Possible values:
+
+@itemize @bullet
+@item
+@code{'()}
+
+@item
+@code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
+@end itemize
+
+@item @code{reconnect-attempts} (default: @code{7})
+Defines the number of attempts to reconnect after a link lost. Setting
+the value to 0 disables reconnecting feature.
+
+@item @code{reconnect-intervals} (default: @code{'(1 2 4 8 16 32 64)})
+Defines a list of intervals in seconds to use in between attempts. If
+the number of attempts defined in @var{reconnect-attempts} is bigger than
+the list of intervals the last interval is repeated until the last attempt.
+
+@item @code{auto-enable?} (default: @code{#f})
+Defines option to enable all controllers when they are found. This includes
+adapters present on start as well as adapters that are plugged in later on.
+
+@item @code{resume-delay} (default: @code{2})
+Audio devices that were disconnected due to suspend will be reconnected on
+resume. @var{resume-delay} determines the delay between when the controller
+resumes from suspend and a connection attempt is made. A longer delay is
+better for better co-existence with Wi-Fi. The value is in seconds.
+
+@item @code{rssi-sampling-period} (default: @code{#xFF})
+Default RSSI Sampling Period. This is used when a client registers an
+advertisement monitor and leaves the RSSISamplingPeriod unset.
+
+Possible values are:
+@itemize @bullet
+@item
+@code{#x0}: Report all advertisements
+
+@item
+@code{N = #xXX}: Report advertisements every N x 100 msec (range: #x01 to #xFE)
+
+@item
+@code{#xFF}: Report only one advertisement per device during monitoring period.
+@end itemize
+
+@end table
+@end deftp
+
 @defvr {Scheme Variable} gnome-keyring-service-type
 This is the type of the service that adds the
 @uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}.  Its
@@ -21283,7 +21885,6 @@ and ``passwd'' is with the value @code{passwd}.
 @end table
 @end deftp
 
-
 @node Sound Services
 @subsection Sound Services
 
@@ -21391,7 +21992,7 @@ Data type representing the configuration for @code{pulseaudio-service}.
 @table @asis
 @item @code{client-conf} (default: @code{'()})
 List of settings to set in @file{client.conf}.
-Accepts a list of strings or a symbol-value pairs.  A string will be
+Accepts a list of strings or symbol-value pairs.  A string will be
 inserted as-is with a newline added.  A pair will be formatted as
 ``key = value'', again with a newline added.
 
@@ -21400,11 +22001,44 @@ List of settings to set in @file{daemon.conf}, formatted just like
 @var{client-conf}.
 
 @item @code{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
-Script file to use as @file{default.pa}.
+Script file to use as @file{default.pa}.  In case the
+@code{extra-script-files} field below is used, an @code{.include}
+directive pointing to @file{/etc/pulse/default.pa.d} is appended to the
+provided script.
+
+@item @code{extra-script-files} (default: @code{'())})
+A list of file-like objects defining extra PulseAudio scripts to run at
+the initialization of the @command{pulseaudio} daemon, after the main
+@code{script-file}.  The scripts are deployed to the
+@file{/etc/pulse/default.pa.d} directory; they should have the
+@samp{.pa} file name extension.  For a reference of the available
+commands, refer to @command{man pulse-cli-syntax}.
 
 @item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
 Script file to use as @file{system.pa}.
 @end table
+
+The example below sets the default PulseAudio card profile, the default
+sink and the default source to use for a old SoundBlaster Audigy sound
+card:
+@lisp
+(pulseaudio-configuration
+ (extra-script-files
+  (list (plain-file "audigy.pa"
+                    (string-append "\
+set-card-profile alsa_card.pci-0000_01_01.0 \
+  output:analog-surround-40+input:analog-mono
+set-default-source alsa_input.pci-0000_01_01.0.analog-mono
+set-default-sink alsa_output.pci-0000_01_01.0.analog-surround-40\n")))))
+@end lisp
+
+Note that @code{pulseaudio-service-type} is part of
+@code{%desktop-services}; if your operating system declaration was
+derived from one of the desktop templates, you'll want to adjust the
+above example to modify the existing @code{pulseaudio-service-type} via
+@code{modify-services} (@pxref{Service Reference,
+@code{modify-services}}), instead of defining a new one.
+
 @end deftp
 
 @deffn {Scheme Variable} ladspa-service-type
@@ -23197,7 +23831,7 @@ Data type representing the configuration of opensmtpd.
 @item @code{package} (default: @var{opensmtpd})
 Package object of the OpenSMTPD SMTP server.
 
-@item @code{config-file} (default: @code{%default-opensmtpd-file})
+@item @code{config-file} (default: @code{%default-opensmtpd-config-file})
 File-like object of the OpenSMTPD configuration file to use.  By default
 it listens on the loopback network interface, and allows for mail from
 users and daemons on the local machine, as well as permitting email to
@@ -25504,9 +26138,10 @@ Specify the path of the base URL@.  This can be useful if
 @end table
 @end deftp
 
+@anchor{prometheus-node-exporter}
 @subsubheading Prometheus Node Exporter Service
-
 @cindex prometheus-node-exporter
+
 The Prometheus ``node exporter'' makes hardware and operating system statistics
 provided by the Linux kernel available for the Prometheus monitoring system.
 This service should be deployed on all physical nodes and virtual machines,
@@ -25545,320 +26180,229 @@ Extra options to pass to the Prometheus node exporter.
 
 @subsubheading Zabbix server
 @cindex zabbix zabbix-server
-Zabbix provides monitoring metrics, among others network utilization, CPU load
-and disk space consumption:
-
-@itemize
-@item High performance, high capacity (able to monitor hundreds of thousands of devices).
-@item Auto-discovery of servers and network devices and interfaces.
-@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others.
-@item Distributed monitoring with centralized web administration.
-@item Native high performance agents.
-@item SLA, and ITIL KPI metrics on reporting.
-@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards.
-@item Remote command execution through Zabbix proxies.
-@end itemize
+Zabbix is a high performance monitoring system that can collect data from a
+variety of sources and provide the results in a web-based interface.  Alerting
+and reporting is built-in, as well as @dfn{templates} for common operating
+system metrics such as network utilization, CPU load, and disk space consumption.
+
+This service provides the central Zabbix monitoring service; you also need
+@ref{zabbix-front-end,@code{zabbix-front-end-service-type}} to configure Zabbix
+and display results, and optionally @ref{zabbix-agent,
+@code{zabbix-agent-service-type}} on machines that should be monitored (other
+data sources are supported, such as @ref{prometheus-node-exporter,
+Prometheus Node Exporter}).
+
+@defvar {Scheme variable} zabbix-server-service-type
+This is the service type for the Zabbix server service.  Its value must be a
+@code{zabbix-server-configuration} record, shown below.
+@end defvar
 
 @c %start of fragment
 
+@deftp {Data Type} zabbix-server-configuration
 Available @code{zabbix-server-configuration} fields are:
 
-@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server
+@table @asis
+@item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
 The zabbix-server package.
 
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string user
+@item @code{user} (default: @code{"zabbix"}) (type: string)
 User who will run the Zabbix server.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} group group
+@item @code{group} (default: @code{"zabbix"}) (type: group)
 Group who will run the Zabbix server.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-host
+@item @code{db-host} (default: @code{"127.0.0.1"}) (type: string)
 Database host name.
 
-Defaults to @samp{"127.0.0.1"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-name
+@item @code{db-name} (default: @code{"zabbix"}) (type: string)
 Database name.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-user
+@item @code{db-user} (default: @code{"zabbix"}) (type: string)
 Database user.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-password
+@item @code{db-password} (default: @code{""}) (type: string)
 Database password.  Please, use @code{include-files} with
 @code{DBPassword=SECRET} inside a specified file instead.
 
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} number db-port
+@item @code{db-port} (default: @code{5432}) (type: number)
 Database port.
 
-Defaults to @samp{5432}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string log-type
+@item @code{log-type} (default: @code{""}) (type: string)
 Specifies where log messages are written to:
 
 @itemize @bullet
-@item
-@code{system} - syslog.
 
-@item
-@code{file} - file specified with @code{log-file} parameter.
+@item @code{system} - syslog.
 
-@item
-@code{console} - standard output.
+@item @code{file} - file specified with @code{log-file} parameter.
 
-@end itemize
-
-Defaults to @samp{""}.
+@item @code{console} - standard output.
 
-@end deftypevr
+@end itemize
 
-@deftypevr {@code{zabbix-server-configuration} parameter} string log-file
+@item @code{log-file} (default: @code{"/var/log/zabbix/server.log"}) (type: string)
 Log file name for @code{log-type} @code{file} parameter.
 
-Defaults to @samp{"/var/log/zabbix/server.log"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file
+@item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_server.pid"}) (type: string)
 Name of PID file.
 
-Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location
+@item @code{ssl-ca-location} (default: @code{"/etc/ssl/certs/ca-certificates.crt"}) (type: string)
 The location of certificate authority (CA) files for SSL server
 certificate verification.
 
-Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location
+@item @code{ssl-cert-location} (default: @code{"/etc/ssl/certs"}) (type: string)
 Location of SSL client certificates.
 
-Defaults to @samp{"/etc/ssl/certs"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options
+@item @code{extra-options} (default: @code{""}) (type: extra-options)
 Extra options will be appended to Zabbix server configuration file.
 
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files
+@item @code{include-files} (default: @code{()}) (type: include-files)
 You may include individual files or all files in a directory in the
 configuration file.
 
-Defaults to @samp{()}.
+@end table
+
+@end deftp
 
-@end deftypevr
 
 @c %end of fragment
 
+@anchor{zabbix-agent}
 @subsubheading Zabbix agent
 @cindex zabbix zabbix-agent
 
-Zabbix agent gathers information for Zabbix server.
+The Zabbix agent gathers information about the running system for the Zabbix
+monitoring server.  It has a variety of built-in checks, and can be extended
+with custom
+@uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters,
+@dfn{user parameters}}.
+
+@defvar {Scheme variable} zabbix-agent-service-type
+This is the service type for the Zabbix agent service.  Its value must be a
+@code{zabbix-agent-configuration} record, shown below.
+@end defvar
 
 @c %start of fragment
 
+@deftp {Data Type} zabbix-agent-configuration
 Available @code{zabbix-agent-configuration} fields are:
 
-@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent
+@table @asis
+@item @code{zabbix-agent} (default: @code{zabbix-agentd}) (type: file-like)
 The zabbix-agent package.
 
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} string user
+@item @code{user} (default: @code{"zabbix"}) (type: string)
 User who will run the Zabbix agent.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} group group
+@item @code{group} (default: @code{"zabbix"}) (type: group)
 Group who will run the Zabbix agent.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} string hostname
+@item @code{hostname} (default: @code{""}) (type: string)
 Unique, case sensitive hostname which is required for active checks and
 must match hostname as configured on the server.
 
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type
+@item @code{log-type} (default: @code{""}) (type: string)
 Specifies where log messages are written to:
 
 @itemize @bullet
 @item
 @code{system} - syslog.
 
-@item
-@code{file} - file specified with @code{log-file} parameter.
+@item @code{file} - file specified with
+@code{log-file} parameter.
 
-@item
-@code{console} - standard output.
+@item @code{console} - standard output.
 
 @end itemize
 
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file
+@item @code{log-file} (default: @code{"/var/log/zabbix/agent.log"}) (type: string)
 Log file name for @code{log-type} @code{file} parameter.
 
-Defaults to @samp{"/var/log/zabbix/agent.log"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file
+@item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_agent.pid"}) (type: string)
 Name of PID file.
 
-Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} list server
+@item @code{server} (default: @code{("127.0.0.1")}) (type: list)
 List of IP addresses, optionally in CIDR notation, or hostnames of
 Zabbix servers and Zabbix proxies.  Incoming connections will be
 accepted only from the hosts listed here.
 
-Defaults to @samp{("127.0.0.1")}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} list server-active
+@item @code{server-active} (default: @code{("127.0.0.1")}) (type: list)
 List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
 proxies for active checks.  If port is not specified, default port is
 used.  If this parameter is not specified, active checks are disabled.
 
-Defaults to @samp{("127.0.0.1")}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options
+@item @code{extra-options} (default: @code{""}) (type: extra-options)
 Extra options will be appended to Zabbix server configuration file.
 
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files
+@item @code{include-files} (default: @code{()}) (type: include-files)
 You may include individual files or all files in a directory in the
 configuration file.
 
-Defaults to @samp{()}.
+@end table
+
+@end deftp
 
-@end deftypevr
 
 @c %end of fragment
 
+@anchor{zabbix-front-end}
 @subsubheading Zabbix front-end
 @cindex zabbix zabbix-front-end
 
-This service provides a WEB interface to Zabbix server.
+The Zabbix front-end provides a web interface to Zabbix.  It does not need
+to run on the same machine as the Zabbix server.  This service works by
+extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration
+necessary for loading the Zabbix user interface.
+
+@defvar {Scheme variable} zabbix-front-end-service-type
+This is the service type for the Zabbix web frontend.  Its value must be a
+@code{zabbix-front-end-configuration} record, shown below.
+@end defvar
 
 @c %start of fragment
 
+@deftp {Data Type} zabbix-front-end-configuration
 Available @code{zabbix-front-end-configuration} fields are:
 
-@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx
-NGINX configuration.
+@table @asis
+@item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
+The Zabbix server package to use.
 
-@end deftypevr
+@item @code{nginx} (default: @code{()}) (type: list)
+List of @ref{nginx-server-configuration,@code{nginx-server-configuration}}
+blocks for the Zabbix front-end.  When empty, a default that listens on
+port 80 is used.
 
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host
+@item @code{db-host} (default: @code{"localhost"}) (type: string)
 Database host name.
 
-Defaults to @samp{"localhost"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port
+@item @code{db-port} (default: @code{5432}) (type: number)
 Database port.
 
-Defaults to @samp{5432}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name
+@item @code{db-name} (default: @code{"zabbix"}) (type: string)
 Database name.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user
+@item @code{db-user} (default: @code{"zabbix"}) (type: string)
 Database user.
 
-Defaults to @samp{"zabbix"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password
+@item @code{db-password} (default: @code{""}) (type: string)
 Database password.  Please, use @code{db-secret-file} instead.
 
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
-Secret file containing the credentials for the Zabbix front-end.  The value
-must be a local file name, not a G-expression.  You are expected to create
-this file manually.  Its contents will be copied into @file{zabbix.conf.php}
-as the value of @code{$DB['PASSWORD']}.
-
-Defaults to @samp{""}.
-
-@end deftypevr
+@item @code{db-secret-file} (default: @code{""}) (type: string)
+Secret file which will be appended to @file{zabbix.conf.php} file.  This
+file contains credentials for use by Zabbix front-end.  You are expected
+to create it manually.
 
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host
+@item @code{zabbix-host} (default: @code{"localhost"}) (type: string)
 Zabbix server hostname.
 
-Defaults to @samp{"localhost"}.
-
-@end deftypevr
-
-@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port
+@item @code{zabbix-port} (default: @code{10051}) (type: number)
 Zabbix server port.
 
-Defaults to @samp{10051}.
+@end table
 
-@end deftypevr
+@end deftp
 
 
 @c %end of fragment
@@ -26832,6 +27376,7 @@ valued G-expression.
 @end table
 @end deffn
 
+@anchor{nginx-server-configuration}
 @deftp {Data Type} nginx-server-configuration
 Data type representing the configuration of an nginx server block.
 This type has the following parameters:
@@ -27282,6 +27827,8 @@ capability also has to be configured on the front-end as well.
 @end table
 @end deftp
 
+@anchor{PHP-FPM}
+@subsubheading PHP-FPM
 @cindex php-fpm
 PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation
 with some additional features useful for sites of any size.
@@ -29920,6 +30467,34 @@ Defaults to @samp{"powersave"}.
 
 @end deftypevr
 
+@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat0
+Percentage when battery 0 should begin charging.  Only supported on some laptops.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat0
+Percentage when battery 0 should stop charging.  Only supported on some laptops.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat1
+Percentage when battery 1 should begin charging.  Only supported on some laptops.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat1
+Percentage when battery 1 should stop charging.  Only supported on some laptops.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
 Radeon graphics clock speed level.  Alternatives are low, mid, high,
 auto, default.
@@ -30121,6 +30696,10 @@ of processors and preventing overheating.
 Data type representing the configuration of @code{thermald-service-type}.
 
 @table @asis
+@item @code{adaptive?} (default: @code{#f})
+Use @acronym{DPTF, Dynamic Power and Thermal Framework} adaptive tables
+when present.
+
 @item @code{ignore-cpuid-check?} (default: @code{#f})
 Ignore cpuid check for supported CPU models.
 
@@ -30840,6 +31419,10 @@ Its value must be a @code{virtlog-configuration}.
 @end lisp
 @end deffn
 
+@deftypevar {@code{libvirt} parameter} package libvirt
+Libvirt package.
+@end deftypevar
+
 @deftypevr {@code{virtlog-configuration} parameter} integer log-level
 Logging level.  4 errors, 3 warnings, 2 information, 1 debug.
 
@@ -33646,6 +34229,92 @@ Extra command line options for @code{guix-data-service-process-jobs}.
 @end table
 @end deftp
 
+@subsubheading Nar Herder
+The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is
+a utility for managing a collection of nars.
+
+@defvar {Scheme Variable} nar-herder-type
+Service type for the Guix Data Service.  Its value must be a
+@code{nar-herder-configuration} object.  The service optionally
+extends the getmail service, as the guix-commits mailing list is used to
+find out about changes in the Guix git repository.
+@end defvar
+
+@deftp {Data Type} nar-herder-configuration
+Data type representing the configuration of the Guix Data Service.
+
+@table @asis
+@item @code{package} (default: @code{nar-herder})
+The Nar Herder package to use.
+
+@item @code{user} (default: @code{"nar-herder"})
+The system user to run the service as.
+
+@item @code{group} (default: @code{"nar-herder"})
+The system group to run the service as.
+
+@item @code{port} (default: @code{8734})
+The port to bind the server to.
+
+@item @code{host} (default: @code{"127.0.0.1"})
+The host to bind the server to.
+
+@item @code{mirror} (default: @code{#f})
+Optional URL of the other Nar Herder instance which should be mirrored.
+This means that this Nar Herder instance will download it's database,
+and keep it up to date.
+
+@item @code{database} (default: @code{"/var/lib/nar-herder/nar_herder.db"})
+Location for the database.  If this Nar Herder instance is mirroring
+another, the database will be downloaded if it doesn't exist.  If this
+Nar Herder instance isn't mirroring another, an empty database will be
+created.
+
+@item @code{database-dump} (default: @code{"/var/lib/nar-herder/nar_herder_dump.db"})
+Location of the database dump.  This is created and regularly updated by
+taking a copy of the database.  This is the version of the database that
+is available to download.
+
+@item @code{storage} (default: @code{#f})
+Optional location in which to store nars.
+
+@item @code{storage-limit} (default: @code{"none"})
+Limit in bytes for the nars stored in the storage location.  This can
+also be set to ``none'' so that there is no limit.
+
+When the storage location exceeds this size, nars are removed according
+to the nar removal criteria.
+
+@item @code{storage-nar-removal-criteria} (default: @code{'()})
+Criteria used to remove nars from the storage location.  These are used
+in conjunction with the storage limit.
+
+When the storage location exceeds the storage limit size, nars will be
+checked against the nar removal criteria and if any of the criteria
+match, they will be removed.  This will continue until the storage
+location is below the storage limit size.
+
+Each criteria is specified by a string, then an equals sign, then
+another string. Currently, only one criteria is supported, checking if a
+nar is stored on another Nar Herder instance.
+
+@item @code{ttl} (default: @code{#f})
+Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
+(TTL) of @var{ttl}.  @var{ttl} must denote a duration: @code{5d} means 5
+days, @code{1m} means 1 month, and so on.
+
+This allows the user's Guix to keep substitute information in cache for
+@var{ttl}.
+
+@item @code{negative-ttl} (default: @code{#f})
+Similarly produce @code{Cache-Control} HTTP headers to advertise the
+time-to-live (TTL) of @emph{negative} lookups---missing store items, for
+which the HTTP 404 code is returned.  By default, no negative TTL is
+advertised.
+
+@end table
+@end deftp
+
 @node Linux Services
 @subsection Linux Services
 
@@ -34454,8 +35123,8 @@ previous example to your operating system declaration by appending it to
   ;; Some fields omitted...
   (setuid-programs
     (append (list (setuid-program
-                    (program (file-append nfs-utils "/sbin/mount.nfs")))
-                  %setuid-programs))))
+                    (program (file-append nfs-utils "/sbin/mount.nfs"))))
+            %setuid-programs)))
 @end lisp
 
 @deftp {Data Type} setuid-program
@@ -34767,7 +35436,7 @@ honors several options passed on the Linux kernel command line
 @code{-append} option of QEMU), notably:
 
 @table @code
-@item --load=@var{boot}
+@item gnu.load=@var{boot}
 Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
 program, once it has mounted the root file system.
 
@@ -34775,12 +35444,22 @@ Guix uses this option to yield control to a boot program that runs the
 service activation programs and then spawns the GNU@tie{}Shepherd, the
 initialization system.
 
-@item --root=@var{root}
+@item root=@var{root}
 Mount @var{root} as the root file system.  @var{root} can be a device
 name like @code{/dev/sda1}, a file system label, or a file system UUID.
 When unspecified, the device name from the root file system of the
 operating system declaration is used.
 
+@item rootfstype=@var{type}
+Set the type of the root file system.  It overrides the @code{type}
+field of the root file system specified via the @code{operating-system}
+declaration, if any.
+
+@item rootflags=@var{options}
+Set the mount @emph{options} of the root file system.  It overrides the
+@code{options} field of the root file system specified via the
+@code{operating-system} declaration, if any.
+
 @item fsck.mode=@var{mode}
 Whether to check the @var{root} file system for errors before mounting
 it.  @var{mode} is one of @code{skip} (never check), @code{force} (always
@@ -34800,7 +35479,7 @@ or @code{preen} to repair problems considered safe to repair automatically.
 @code{preen} is the default if this option is not present or if @var{level}
 is not one of the above.
 
-@item --system=@var{system}
+@item gnu.system=@var{system}
 Have @file{/run/booted-system} and @file{/run/current-system} point to
 @var{system}.
 
@@ -34812,7 +35491,7 @@ Instruct the initial RAM disk as well as the @command{modprobe} command
 must be a comma-separated list of module names---e.g.,
 @code{usbkbd,9pnet}.
 
-@item --repl
+@item gnu.repl
 Start a read-eval-print loop (REPL) from the initial RAM disk before it
 tries to load kernel modules and to mount the root file system.  Our
 marketing team calls it @dfn{boot-to-Guile}.  The Schemer in you will
@@ -34833,7 +35512,7 @@ here is how to use it and customize it further.
        [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
 Return a derivation that builds a raw initrd.  @var{file-systems} is
 a list of file systems to be mounted by the initrd, possibly in addition to
-the root file system specified on the kernel command line via @option{--root}.
+the root file system specified on the kernel command line via @option{root}.
 @var{linux-modules} is a list of kernel modules to be loaded at boot time.
 @var{mapped-devices} is a list of device mappings to realize before
 @var{file-systems} are mounted (@pxref{Mapped Devices}).
@@ -34863,7 +35542,7 @@ to it are lost.
 Return as a file-like object a generic initrd, with kernel
 modules taken from @var{linux}.  @var{file-systems} is a list of file-systems to be
 mounted by the initrd, possibly in addition to the root file system specified
-on the kernel command line via @option{--root}.  @var{mapped-devices} is a list of device
+on the kernel command line via @option{root}.  @var{mapped-devices} is a list of device
 mappings to realize before @var{file-systems} are mounted.
 
 When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
@@ -35733,9 +36412,21 @@ bootloader boot menu:
 @table @code
 
 @item describe
-Describe the current system generation: its file name, the kernel and
+Describe the running system generation: its file name, the kernel and
 bootloader used, etc., as well as provenance information when available.
 
+@quotation Note
+The @emph{running} system generation---referred to by
+@file{/run/current-system}---is not necessarily the @emph{current}
+system generation---referred to by @file{/var/guix/profiles/system}: it
+differs when, for instance, you chose from the bootloader menu to boot
+an older generation.
+
+It can also differ from the @emph{booted} system generation---referred
+to by @file{/run/booted-system}---for instance because you reconfigured
+the system in the meantime.
+@end quotation
+
 @item list-generations
 List a summary of each generation of the operating system available on
 disk, in a human-readable way.  This is similar to the
@@ -35911,6 +36602,30 @@ be accomplished with the following operating system configuration snippet:
 For more information regarding the format of the @file{sudoers} file,
 consult @command{man sudoers}.
 
+Once you've deployed a system on a set of machines, you may find it
+useful to run a command on all of them.  The @option{--execute} or
+@option{-x} option lets you do that; the example below runs
+@command{uname -a} on all the machines listed in the deployment file:
+
+@example
+guix deploy @var{file} -x -- uname -a
+@end example
+
+One thing you may often need to do after deployment is restart specific
+services on all the machines, which you can do like so:
+
+@example
+guix deploy @var{file} -x -- herd restart @var{service}
+@end example
+
+The @command{guix deploy -x} command returns zero if and only if the
+command succeeded on all the machines.
+
+@c FIXME/TODO: Separate the API doc from the CLI doc.
+
+Below are the data types you need to know about when writing a
+deployment file.
+
 @deftp {Data Type} machine
 This is the data type representing a single machine in a heterogeneous Guix
 deployment.
@@ -37369,6 +38084,21 @@ be confused with Shepherd services (@pxref{Shepherd Services}).  Using this exte
 mechanism and some Scheme code that glues things together gives the user
 the freedom to declare their own, very custom, home environments.
 
+@cindex container, for @command{guix home}
+Once the configuration looks good, you can first test it in a throw-away
+``container'':
+
+@example
+guix home container config.scm
+@end example
+
+The command above spawns a shell where your home environment is running.
+The shell runs in a container, meaning it's isolated from the rest of
+the system, so it's a good way to try out your configuration---you can
+see if configuration bits are missing or misbehaving, if daemons get
+started, and so on.  Once you exit that shell, you're back to the prompt
+of your original shell ``in the real world''.
+
 Once you have a configuration file that suits your needs, you can
 reconfigure your home by running:
 
@@ -37470,6 +38200,7 @@ services)}.
 * Shells: Shells Home Services.          POSIX shells, Bash, Zsh.
 * Mcron: Mcron Home Service.             Scheduled User's Job Execution.
 * Shepherd: Shepherd Home Service.       Managing User's Daemons.
+* Desktop: Desktop Home Services.        Services for graphical environments.
 @end menu
 @c In addition to that Home Services can provide
 
@@ -37646,7 +38377,7 @@ The Bash package to use.
 
 @item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
 Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
-@command{ls} to the end of the @file{.bashrc} file.
+@command{ls} to the top of the @file{.bashrc} file.
 
 @item @code{environment-variables} (default: @code{()}) (type: alist)
 Association list of environment variables to set for the Bash session.  The
@@ -37661,13 +38392,13 @@ put in the @file{.bashrc} file.  The alias will automatically be quoted,
 so something line this:
 
 @lisp
-'((\"ls\" . \"ls -alF\"))
+'(("ls" . "ls -alF"))
 @end lisp
 
 turns into
 
 @example
-alias ls=\"ls -alF\"
+alias ls="ls -alF"
 @end example
 
 @item @code{bash-profile} (default: @code{()}) (type: text-config)
@@ -37857,6 +38588,85 @@ mechanism instead (@pxref{Shepherd Services}).
 @end table
 @end deftp
 
+@node Desktop Home Services
+@subsection Desktop Home Services
+
+The @code{(gnu home services desktop)} module provides services that you
+may find useful on ``desktop'' systems running a graphical user
+environment such as Xorg.
+
+@defvr {Scheme Variable} home-redshift-service-type
+This is the service type for @uref{https://github.com/jonls/redshift,
+Redshift}, a program that adjusts the display color temperature
+according to the time of day.  Its associated value must be a
+@code{home-redshift-configuration} record, as shown below.
+
+A typical configuration, where we manually specify the latitude and
+longitude, might look like this:
+
+@lisp
+(service home-redshift-service-type
+         (home-redshift-configuration
+          (location-provider 'manual)
+          (latitude 35.81)    ;northern hemisphere
+          (longitude -0.80))) ;west of Greenwich
+@end lisp
+@end defvr
+
+@deftp {Data Type} home-redshift-configuration
+Available @code{home-redshift-configuration} fields are:
+
+@table @asis
+@item @code{redshift} (default: @code{redshift}) (type: file-like)
+Redshift package to use.
+
+@item @code{location-provider} (default: @code{geoclue2}) (type: symbol)
+Geolocation provider---@code{'manual} or @code{'geoclue2}.  In the
+former case, you must also specify the @code{latitude} and
+@code{longitude} fields so Redshift can determine daytime at your place.
+In the latter case, the Geoclue system service must be running; it will
+be queried for location information.
+
+@item @code{adjustment-method} (default: @code{randr}) (type: symbol)
+Color adjustment method.
+
+@item @code{daytime-temperature} (default: @code{6500}) (type: integer)
+Daytime color temperature (kelvins).
+
+@item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
+Nighttime color temperature (kelvins).
+
+@item @code{daytime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
+Daytime screen brightness, between 0.1 and 1.0.
+
+@item @code{nighttime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
+Nighttime screen brightness, between 0.1 and 1.0.
+
+@item @code{latitude} (default: @code{disabled}) (type: maybe-inexact-number)
+Latitude, when @code{location-provider} is @code{'manual}.
+
+@item @code{longitude} (default: @code{disabled}) (type: maybe-inexact-number)
+Longitude, when @code{location-provider} is @code{'manual}.
+
+@item @code{dawn-time} (default: @code{disabled}) (type: maybe-string)
+Custom time for the transition from night to day in the
+morning---@code{"HH:MM"} format.  When specified, solar elevation is not
+used to determine the daytime/nighttime period.
+
+@item @code{dusk-time} (default: @code{disabled}) (type: maybe-string)
+Likewise, custom time for the transition from day to night in the
+evening.
+
+@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
+Extra content appended as-is to the Redshift configuration file.  Run
+@command{man redshift} for more information about the configuration file
+format.
+
+@end table
+
+@end deftp
+
+
 @node Invoking guix home
 @section Invoking @code{guix home}
 
@@ -37917,6 +38727,49 @@ As for @command{guix search}, the result is written in
 @code{recutils} format, which makes it easy to filter the output
 (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
 
+@cindex container, for @command{guix home}
+@item container
+Spawn a shell in an isolated environment---a
+@dfn{container}---containing your home as specified by @var{file}.
+
+For example, this is how you would start an interactive shell in a
+container with your home:
+
+@example
+guix home container config.scm
+@end example
+
+This is a throw-away container where you can lightheartedly fiddle with
+files; any changes made within the container, any process started---all
+this disappears as soon as you exit that shell.
+
+As with @command{guix shell}, several options control that container:
+
+@table @option
+@item --network
+@itemx -N
+Enable networking within the container (it is disabled by default).
+
+@item --expose=@var{source}[=@var{target}]
+@itemx --share=@var{source}[=@var{target}]
+As with @command{guix shell}, make directory @var{source} of the host
+system available as @var{target} inside the container---read-only if you
+pass @option{--expose}, and writable if you pass @option{--share}
+(@pxref{Invoking guix shell, @option{--expose} and @option{--share}}).
+@end table
+
+Additionally, you can run a command in that container, instead of
+spawning an interactive shell.  For instance, here is how you would
+check which Shepherd services are started in a throw-away home
+container:
+
+@example
+guix home container config.scm -- herd status
+@end example
+
+The command to run in the container must come after @code{--} (double
+hyphen).
+
 @item reconfigure
 Build the home environment described in @var{file}, and switch to it.
 Switching means that the activation script will be evaluated and (in
@@ -38066,7 +38919,38 @@ environment.  Note that not every home service that exists is supported
 $ guix home import ~/guix-config
 guix home: '/home/alice/guix-config' populated with all the Home configuration files
 @end example
+@end table
+
+And there's more!  @command{guix home} also provides the following
+sub-commands to visualize how the services of your home environment
+relate to one another:
+
+@table @code
+@cindex service extension graph, of a home environment
+@item extension-graph
+Emit to standard output the @dfn{service extension graph} of the home
+environment defined in @var{file} (@pxref{Service Composition}, for more
+information on service extensions).  By default the output is in
+Dot/Graphviz format, but you can choose a different format with
+@option{--graph-backend}, as with @command{guix graph} (@pxref{Invoking
+guix graph, @option{--backend}}):
+
+The command:
+
+@example
+guix home extension-graph @var{file} | xdot -
+@end example
+
+shows the extension relations among services.
+
+@cindex Shepherd dependency graph, for a home environment
+@item shepherd-graph
+Emit to standard output the @dfn{dependency graph} of shepherd services
+of the home environment defined in @var{file}.  @xref{Shepherd
+Services}, for more information and for an example graph.
 
+Again, the default output format is Dot/Graphviz, but you can pass
+@option{--graph-backend} to select a different one.
 @end table
 
 @var{options} can contain any of the common build options (@pxref{Common
@@ -38081,6 +38965,16 @@ Consider the home-environment @var{expr} evaluates to.
 This is an alternative to specifying a file which evaluates to a home
 environment.
 
+@item --allow-downgrades
+Instruct @command{guix home reconfigure} to allow system downgrades.
+
+Just like @command{guix system}, @command{guix home reconfigure}, by
+default, prevents you from downgrading your home to older or unrelated
+revisions compared to the channel revisions that were used to deploy
+it---those shown by @command{guix home describe}.  Using
+@option{--allow-downgrades} allows you to bypass that check, at the risk
+of downgrading your home---be careful!
+
 @end table
 
 @node Documentation
@@ -38304,6 +39198,147 @@ Note that there can be packages for which @option{--with-debug-info}
 will not have the desired effect.  @xref{Package Transformation Options,
 @option{--with-debug-info}}, for more information.
 
+@node Using TeX and LaTeX
+@chapter Using @TeX{} and @LaTeX{}
+
+@cindex @TeX{} packages
+@cindex @LaTeX{} packages
+Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and
+related typesetting systems, taken from the
+@uref{https://www.tug.org/texlive/, @TeX{} Live distribution}.  However,
+because @TeX{} Live is so huge and because finding your way in this maze
+is tricky, we thought that you, dear user, would welcome guidance on how
+to deploy the relevant packages so you can compile your @TeX{} and
+@LaTeX{} documents.
+
+@TeX{} Live currently comes in two flavors in Guix:
+
+@itemize
+@item
+The ``monolithic'' @code{texlive} package: it comes with @emph{every
+single @TeX{} Live package} (more than 7,000 of them), but it is huge
+(more than 4@tie{}GiB for a single package!).
+
+@item
+The ``modular'' @code{texlive-} packages: you install
+@code{texlive-base}, which provides core functionality and the main
+commands---@command{pdflatex}, @command{dvips}, @command{luatex},
+@command{mf}, etc.---together with individual packages that provide just
+the features you need---@code{texlive-listings} for the
+@code{listings} package, @code{texlive-hyperref} for @code{hyperref},
+@code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ,
+and so on.
+@end itemize
+
+We recommend using the modular package set because it is much less
+resource-hungry.  To build your documents, you would use commands such
+as:
+
+@example
+guix shell texlive-base texlive-wrapfig \
+  texlive-hyperref texlive-cm-super -- pdflatex doc.tex
+@end example
+
+You can quickly end up with unreasonably long command lines though.  The
+solution is to instead write a manifest, for example like this one:
+
+@lisp
+(specifications->manifest
+ '("rubber"
+
+   "texlive-base"
+   "texlive-wrapfig"
+
+   "texlive-microtype"
+   "texlive-listings" "texlive-hyperref"
+
+   ;; PGF/TikZ
+   "texlive-pgf"
+
+   ;; Additional fonts.
+   "texlive-cm-super" "texlive-amsfonts"
+   "texlive-times" "texlive-helvetic" "texlive-courier"))
+@end lisp
+
+You can then pass it to any command with the @option{-m} option:
+
+@example
+guix shell -m manifest.scm -- pdflatex doc.tex
+@end example
+
+@xref{Invoking guix package, @option{--manifest}}, for more on
+manifests.  In the future, we plan to provide packages for @TeX{} Live
+@dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
+@code{humanities}, or @code{langarabic} that provide the set of packages
+needed in this particular domain.  That will allow you to list fewer
+packages.
+
+The main difficulty here is that using the modular package set forces
+you to select precisely the packages that you need.  You can use
+@command{guix search}, but finding the right package can prove to be
+tedious.  When a package is missing, @command{pdflatex} and similar
+commands fail with an obscure message along the lines of:
+
+@example
+doc.tex: File `tikz.sty' not found.
+doc.tex:7: Emergency stop.
+@end example
+
+@noindent
+or, for a missing font:
+
+@example
+kpathsea: Running mktexmf phvr7t
+! I can't find file `phvr7t'.
+@end example
+
+How do you determine what the missing package is?  In the first case,
+you'll find the answer by running:
+
+@example
+$ guix search texlive tikz
+name: texlive-pgf
+version: 59745
+@dots{}
+@end example
+
+In the second case, @command{guix search} turns up nothing.  Instead,
+you can search the @TeX{} Live package database using the @command{tlmgr}
+command:
+
+@example
+$ guix shell texlive-base -- tlmgr info phvr7t
+tlmgr: cannot find package phvr7t, searching for other matches:
+
+Packages containing `phvr7t' in their title/description:
+
+Packages containing files matching `phvr7t':
+helvetic:
+        texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
+        texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
+        texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
+        texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
+tex4ht:
+        texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
+@end example
+
+The file is available in the @TeX{} Live @code{helvetic} package, which is
+known in Guix as @code{texlive-helvetic}.  Quite a ride, but we found
+it!
+
+There is one important limitation though: Guix currently provides a
+subset of the @TeX{} Live packages.  If you stumble upon a missing
+package, you can try and import it (@pxref{Invoking guix import}):
+
+@example
+guix import texlive @var{package}
+@end example
+
+@quotation Note
+@TeX{} Live packaging is still very much work in progress, but you can
+help!  @xref{Contributing}, for more information.
+@end quotation
+
 @node Security Updates
 @chapter Security Updates
 
diff --git a/doc/local.mk b/doc/local.mk
index 9619971296..c9a8391993 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -23,7 +23,7 @@
 
 # If adding a language, update the following variables, and info_TEXINFOS.
 MANUAL_LANGUAGES = de es fa fi fr it ko pt_BR ru sk zh_CN
-COOKBOOK_LANGUAGES = de es fa fi fr ko ru sk zh_Hans
+COOKBOOK_LANGUAGES = de es fa fi fr ko pt_BR ru sk uk zh_Hans
 
 # Arg1: A list of languages codes.
 # Arg2: The file name stem.
@@ -50,8 +50,10 @@ info_TEXINFOS = %D%/guix.texi			\
   %D%/guix-cookbook.fi.texi			\
   %D%/guix-cookbook.fr.texi			\
   %D%/guix-cookbook.ko.texi			\
+  %D%/guix-cookbook.pt_BR.texi			\
   %D%/guix-cookbook.ru.texi			\
   %D%/guix-cookbook.sk.texi			\
+  %D%/guix-cookbook.uk.texi			\
   %D%/guix-cookbook.zh_Hans.texi
 
 %C%_guix_TEXINFOS = \