Merge branch 'master' into emacs-team

4 files changed, 518 insertions, 100 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 69f0327afb..a0da871f1a 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -300,15 +300,10 @@ Geiser allows for interactive and incremental development from within
 Emacs: code compilation and evaluation from within buffers, access to
 on-line documentation (docstrings), context-sensitive completion,
 @kbd{M-.} to jump to an object definition, a REPL to try out your code,
-and more (@pxref{Introduction,,, geiser, Geiser User Manual}).  For
-convenient Guix development, make sure to augment Guile’s load path so
-that it finds source files from your checkout:
-
-@lisp
-;; @r{Assuming the Guix checkout is in ~/src/guix.}
-(with-eval-after-load 'geiser-guile
-  (add-to-list 'geiser-guile-load-path "~/src/guix"))
-@end lisp
+and more (@pxref{Introduction,,, geiser, Geiser User Manual}).  If you
+allow Emacs to load the @file{.dir-locals.el} file at the root of the
+project checkout, it will cause Geiser to automatically add the local
+Guix sources to the Guile load path.
 
 To actually edit the code, Emacs already has a neat Scheme mode.  But in
 addition to that, you must not miss
@@ -1345,6 +1340,12 @@ should not be delayed.
 When a bug is resolved, please close the thread by sending an email to
 @email{@var{ISSUE_NUMBER}-done@@debbugs.gnu.org}.
 
+@menu
+* Configuring Git::
+* Sending a Patch Series::
+* Teams::
+@end menu
+
 @node Configuring Git
 @subsection Configuring Git
 @cindex git configuration
@@ -1542,10 +1543,10 @@ This section describes how the Guix project tracks its bug reports,
 patch submissions and topic branches.
 
 @menu
-* The Issue Tracker::             The official bug and patch tracker.
-* Managing Patches and Branches:: How changes to Guix are managed.
-* Debbugs User Interfaces::       Ways to interact with Debbugs.
-* Debbugs Usertags::              Tag reports with custom labels.
+* The Issue Tracker::           The official bug and patch tracker.
+* Managing Patches and Branches::  How changes to Guix are managed.
+* Debbugs User Interfaces::     Ways to interact with Debbugs.
+* Debbugs Usertags::            Tag reports with custom labels.
 @end menu
 
 @node The Issue Tracker
@@ -1625,6 +1626,8 @@ information on some builds and substitute availability.
 @node Debbugs User Interfaces
 @subsection Debbugs User Interfaces
 
+@subsubsection Web interface
+
 A web interface (actually @emph{two} web interfaces!) are available to
 browse issues:
 
@@ -1646,6 +1649,88 @@ To view discussions related to issue number @var{n}, go to
 @indicateurl{https://issues.guix.gnu.org/@var{n}} or
 @indicateurl{https://bugs.gnu.org/@var{n}}.
 
+@subsubsection Command-line interface
+
+Mumi also comes with a command-line interface that can be used to search
+existing issues, open new issues and send patches.  You do not need to
+use Emacs to use the mumi command-line client.  You interact with it
+only on the command-line.
+
+To use the mumi command-line interface, navigate to a local clone of the
+Guix git repository, and drop into a shell with mumi, git and
+git:send-email installed.
+
+@example
+$ cd guix
+~/guix$ guix shell mumi git git:send-email
+@end example
+
+To search for issues, say all open issues about "zig", run
+
+@example
+~/guix [env]$ mumi search zig is:open
+
+#60889 Add zig-build-system
+opened on 17 Jan 17:37 Z by Ekaitz Zarraga
+#61036 [PATCH 0/3] Update zig to 0.10.1
+opened on 24 Jan 09:42 Z by Efraim Flashner
+#39136 [PATCH] gnu: services: Add endlessh.
+opened on 14 Jan 2020 21:21 by Nicol? Balzarotti
+#60424 [PATCH] gnu: Add python-online-judge-tools
+opened on 30 Dec 2022 07:03 by gemmaro
+#45601 [PATCH 0/6] vlang 0.2 update
+opened on  1 Jan 2021 19:23 by Ryan Prior
+@end example
+
+Pick an issue and make it the "current" issue.
+
+@example
+~/guix [env]$ mumi current 61036
+
+#61036 [PATCH 0/3] Update zig to 0.10.1
+opened on 24 Jan 09:42 Z by Efraim Flashner
+@end example
+
+Once an issue is the current issue, you can easily create and send
+patches to it using
+
+@example
+~/guix [env]$ git format-patch origin/master
+~/guix [env]$ mumi send-email foo.patch bar.patch
+@end example
+
+Note that you do not have to pass in @samp{--to} or @samp{--cc}
+arguments to @command{git format-patch}.  @command{mumi send-email} will
+put them in correctly when sending the patches.
+
+To open a new issue, run
+
+@example
+~/guix [env]$ mumi new
+@end example
+
+and send patches
+
+@example
+~/guix [env]$ mumi send-email foo.patch bar.patch
+@end example
+
+@command{mumi send-email} is really a wrapper around @command{git
+send-email} that automates away all the nitty-gritty of sending patches.
+It uses the current issue state to automatically figure out the correct
+@samp{To} address to send to, other participants to @samp{Cc}, headers
+to add, etc.
+
+Also note that, unlike @command{git send-email}, @command{mumi
+send-email} works perfectly well with single and multiple patches alike.
+It automates away the debbugs dance of sending the first patch, waiting
+for a response from debbugs and sending the remaining patches.  It does
+so by sending the first patch, polling the server for a response, and
+then sending the remaining patches.  This polling can unfortunately take
+a few minutes.  So, please be patient.
+
+@subsubsection Emacs interface
+
 If you use Emacs, you may find it more convenient to interact with
 issues using @file{debbugs.el}, which you can install with:
 
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index e90d611171..91f08bfcd6 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -23,6 +23,7 @@ Copyright @copyright{} 2020 Christine Lemmer-Webber@*
 Copyright @copyright{} 2021 Joshua Branson@*
 Copyright @copyright{} 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2023 Ludovic Courtès
+Copyright @copyright{} 2023 Thomas Ieong
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -128,6 +129,7 @@ System Configuration
 * Connecting to Wireguard VPN::  Connecting to a Wireguard VPN.
 * Customizing a Window Manager::  Handle customization of a Window manager on Guix System.
 * Running Guix on a Linode Server::  Running Guix on a Linode Server.
+* Running Guix on a Kimsufi Server::  Running Guix on a Kimsufi Server.
 * Setting up a bind mount::     Setting up a bind mount in the file-systems definition.
 * Getting substitutes from Tor::  Configuring Guix daemon to get substitutes through Tor.
 * Setting up NGINX with Lua::   Configuring NGINX web-server to load Lua modules.
@@ -1575,6 +1577,7 @@ reference.
 * Connecting to Wireguard VPN::  Connecting to a Wireguard VPN.
 * Customizing a Window Manager::  Handle customization of a Window manager on Guix System.
 * Running Guix on a Linode Server::  Running Guix on a Linode Server.
+* Running Guix on a Kimsufi Server::  Running Guix on a Kimsufi Server.
 * Setting up a bind mount::     Setting up a bind mount in the file-systems definition.
 * Getting substitutes from Tor::  Configuring Guix daemon to get substitutes through Tor.
 * Setting up NGINX with Lua::   Configuring NGINX web-server to load Lua modules.
@@ -2158,6 +2161,51 @@ the @code{yubikey-manager-qt} package and either wholly disable the
 @samp{Applications -> OTP} view, delete the slot 1 configuration, which
 comes pre-configured with the Yubico OTP application.
 
+@subsection Requiring a Yubikey to open a KeePassXC database
+@cindex yubikey, keepassxc integration
+The KeePassXC password manager application has support for Yubikeys, but
+it requires installing a udev rules for your Guix System and some
+configuration of the Yubico OTP application on the key.
+
+The necessary udev rules file comes from the
+@code{yubikey-personalization} package, and can be installed like:
+
+@lisp
+(use-package-modules ... security-token ...)
+...
+(operating-system
+ ...
+ (services
+  (cons*
+   ...
+   (udev-rules-service 'yubikey yubikey-personalization))))
+@end lisp
+
+After reconfiguring your system (and reconnecting your Yubikey), you'll
+then want to configure the OTP challenge/response application of your
+Yubikey on its slot 2, which is what KeePassXC uses.  It's easy to do so
+via the Yubikey Manager graphical configuration tool, which can be
+invoked with:
+
+@example
+guix shell yubikey-manager-qt -- ykman-gui
+@end example
+
+First, ensure @samp{OTP} is enabled under the @samp{Interfaces} tab,
+then navigate to @samp{Applications -> OTP}, and click the
+@samp{Configure} button under the @samp{Long Touch (Slot 2)} section.
+Select @samp{Challenge-response}, input or generate a secret key, and
+click the @samp{Finish} button.  If you have a second Yubikey you'd like
+to use as a backup, you should configure it the same way, using the
+@emph{same} secret key.
+
+Your Yubikey should now be detected by KeePassXC.  It can be added to a
+database by navigating to KeePassXC's @samp{Database -> Database
+Security...}  menu, then clicking the @samp{Add additional
+protection...} button, then @samp{Add Challenge-Response}, selecting the
+security key from the drop-down menu and clicking the @samp{OK} button
+to complete the setup.
+
 @node Dynamic DNS mcron job
 @section Dynamic DNS mcron job
 
@@ -2634,6 +2682,253 @@ have an easy time spinning up new Guix images!  You may need to
 down-size the Guix image to 6144MB, to save it as an image.  Then you
 can resize it again to the max size.
 
+@node Running Guix on a Kimsufi Server
+@section Running Guix on a Kimsufi Server
+@cindex kimsufi, Kimsufi, OVH
+
+To run Guix on a server hosted by @uref{https://www.kimsufi.com/,
+Kimsufi}, click on the netboot tab then select rescue64-pro and restart.
+
+OVH will email you the credentials required to ssh into a Debian system.
+
+Now you can run the "install guix from @pxref{Binary Installation,,,
+guix, GNU Guix}" steps:
+
+@example
+wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+chmod +x guix-install.sh
+./guix-install.sh
+guix pull
+@end example
+
+Partition the drives and format them, first stop the raid array:
+
+@example
+mdadm --stop /dev/md127
+mdadm --zero-superblock /dev/sda2 /dev/sdb2
+@end example
+
+Then wipe the disks and set up the partitions, we will create
+a RAID 1 array.
+
+@example
+wipefs -a /dev/sda
+wipefs -a /dev/sdb
+
+parted /dev/sda --align=opt -s -m -- mklabel gpt
+parted /dev/sda --align=opt -s -m -- \
+ mkpart bios_grub 1049kb 512MiB \
+ set 1 bios_grub on
+parted /dev/sda --align=opt -s -m -- \
+ mkpart primary 512MiB -512MiB
+ set 2 raid on
+parted /dev/sda --align=opt -s -m -- mkpart primary linux-swap 512MiB 100%
+
+parted /dev/sdb --align=opt -s -m -- mklabel gpt
+parted /dev/sdb --align=opt -s -m -- \
+     mkpart bios_grub 1049kb 512MiB \
+     set 1 bios_grub on
+parted /dev/sdb --align=opt -s -m -- \
+     mkpart primary 512MiB -512MiB \
+     set 2 raid on
+parted /dev/sdb --align=opt -s -m -- mkpart primary linux-swap 512MiB 100%
+@end example
+
+Create the array:
+
+@example
+mdadm --create /dev/md127 --level=1 --raid-disks=2 \
+  --metadata=0.90 /dev/sda2 /dev/sdb2
+@end example
+
+Now create file systems on the relevant partitions, first the boot
+partitions:
+
+@example
+mkfs.ext4  /dev/sda1
+mkfs.ext4  /dev/sdb1
+@end example
+
+Then the root partition:
+
+@example
+mkfs.ext4 /dev/md127
+@end example
+
+Initialize the swap partitions:
+
+@example
+mkswap /dev/sda3
+swapon /dev/sda3
+mkswap /dev/sdb3
+swapon /dev/sdb3
+@end example
+
+Mount the guix drive:
+
+@example
+mkdir /mnt/guix
+mount /dev/md127 /mnt/guix
+@end example
+
+Now is time to write an operating system declaration @file{os.scm} file;
+here is a sample:
+
+@lisp
+(use-modules (gnu) (guix))
+(use-service-modules networking ssh vpn virtualization sysctl admin mcron)
+(use-package-modules ssh certs tls tmux vpn virtualization)
+
+(operating-system
+  (host-name "kimsufi")
+
+  (bootloader (bootloader-configuration
+	       (bootloader grub-bootloader)
+	       (targets (list "/dev/sda" "/dev/sdb"))
+	       (terminal-outputs '(console))))
+
+  ;; Add a kernel module for RAID-1 (aka. "mirror").
+  (initrd-modules (cons* "raid1"  %base-initrd-modules))
+
+  (mapped-devices
+   (list (mapped-device
+          (source (list "/dev/sda2" "/dev/sdb2"))
+          (target "/dev/md127")
+          (type raid-device-mapping))))
+
+  (swap-devices
+   (list (swap-space
+          (target "/dev/sda3"))
+         (swap-space
+          (target "/dev/sdb3"))))
+
+  (issue
+   ;; Default contents for /etc/issue.
+   "\
+This is the GNU system at Kimsufi.  Welcome.\n")
+
+  (file-systems (cons* (file-system
+		         (mount-point "/")
+		         (device "/dev/md127")
+		         (type "ext4")
+		         (dependencies mapped-devices))
+		       %base-file-systems))
+
+  (users (cons (user-account
+	        (name "guix")
+	        (comment "guix")
+	        (group "users")
+	        (supplementary-groups '("wheel"))
+	        (home-directory "/home/guix"))
+	       %base-user-accounts))
+
+  (sudoers-file
+   (plain-file "sudoers" "\
+root ALL=(ALL) ALL
+%wheel ALL=(ALL) ALL
+guix ALL=(ALL) NOPASSWD:ALL\n"))
+
+  ;; Globally-installed packages.
+  (packages (cons* tmux nss-certs gnutls wireguard-tools %base-packages))
+  (services
+   (cons*
+    (service static-networking-service-type
+	     (list (static-networking
+		    (addresses (list (network-address
+				      (device "enp3s0")
+				      (value "@var{server-ip-address}/24"))))
+		    (routes (list (network-route
+				   (destination "default")
+				   (gateway "@var{server-gateway}"))))
+		    (name-servers '("213.186.33.99")))))
+
+    (service unattended-upgrade-service-type)
+
+    (service openssh-service-type
+	     (openssh-configuration
+	      (openssh openssh-sans-x)
+	      (permit-root-login #f)
+	      (authorized-keys
+	       `(("guix" ,(plain-file "@var{ssh-key-name.pub}"
+                                      "@var{ssh-public-key-content}"))))))
+    (modify-services %base-services
+      (sysctl-service-type
+       config =>
+       (sysctl-configuration
+	(settings (append '(("net.ipv6.conf.all.autoconf" . "0")
+			    ("net.ipv6.conf.all.accept_ra" . "0"))
+			  %default-sysctl-settings))))))))
+@end lisp
+
+Don't forget to substitute the @var{server-ip-address},
+@var{server-gateway}, @var{ssh-key-name} and
+@var{ssh-public-key-content} variables with your own values.
+
+The gateway is the last usable IP in your block so if you have a server
+with an IP of @samp{37.187.79.10} then its gateway will be
+@samp{37.187.79.254}.
+
+Transfer your operating system declaration @file{os.scm} file on the
+server via the @command{scp} or @command{sftp} commands.
+
+Now all that is left is to install Guix with a @code{guix system init}
+and restart.
+
+However we first need to set up a chroot, because the root partition of
+the rescue system is mounted on an aufs partition and if you try to
+install Guix it will fail at the GRUB install step complaining about the
+canonical path of "aufs".
+
+Install packages that will be used in the chroot:
+
+@example
+guix install bash-static parted util-linux-with-udev coreutils guix
+@end example
+
+Then run the following to create directories needed for the chroot:
+
+@example
+cd /mnt && \
+mkdir -p bin etc gnu/store root/.guix-profile/ root/.config/guix/current \
+  var/guix proc sys dev
+@end example
+
+Copy the host resolv.conf in the chroot:
+
+@example
+cp /etc/resolv.conf etc/
+@end example
+
+Mount block devices, the store and its database and the current guix config:
+
+@example
+mount --rbind /proc /mnt/proc
+mount --rbind /sys /mnt/sys
+mount --rbind /dev /mnt/dev
+mount --rbind /var/guix/ var/guix/
+mount --rbind /gnu/store gnu/store/
+mount --rbind /root/.config/ root/.config/
+mount --rbind /root/.guix-profile/bin/ bin
+mount --rbind /root/.guix-profile root/.guix-profile/
+@end example
+
+Chroot in /mnt and install the system:
+
+@example
+chroot /mnt/ /bin/bash
+
+guix system init /root/os.scm /guix
+@end example
+
+Finally, from the web user interface (UI), change @samp{netboot} to
+@samp{boot to disk} and restart (also from the web UI).
+
+Wait a few minutes and try to ssh with @code{ssh
+guix@@@var{server-ip-address>} -i @var{path-to-your-ssh-key}}
+
+You should have a Guix system up and running on Kimsufi;
+congratulations!
+
 @node Setting up a bind mount
 @section Setting up a bind mount
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 89306c0b45..fd72761c92 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -53,7 +53,7 @@ Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
 Copyright @copyright{} 2017 George Clemmer@*
 Copyright @copyright{} 2017 Andy Wingo@*
-Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2023 Arun Isaac@*
 Copyright @copyright{} 2017 nee@*
 Copyright @copyright{} 2018 Rutger Helling@*
 Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
@@ -2405,6 +2405,16 @@ BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
 In order to boot from Libreboot, switch to the command mode by pressing
 the @kbd{c} key and type @command{search_grub usb}.
 
+Sadly, on some machines, the installation medium cannot be properly
+booted and you only see a black screen after booting even after you
+waited for ten minutes.  This may indicate that your machine cannot run
+Guix System; perhaps you instead want to install Guix on a foreign
+distro (@pxref{Binary Installation}).  But don't give up just yet; a
+possible workaround is pressing the @kbd{e} key in the GRUB boot menu
+and appending @option{nomodeset} to the Linux bootline.
+Sometimes the black screen issue can also be resolved by connecting a
+different display.
+
 @xref{Installing Guix in a VM}, if, instead, you would like to install
 Guix System in a virtual machine (VM).
 
@@ -14168,6 +14178,16 @@ TeX package:
 guix import texlive fontspec
 @end example
 
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
 @item json
 @cindex JSON, import
 Import package metadata from a local JSON file.  Consider the following
@@ -18060,10 +18080,6 @@ administrator's choice; reconfiguring does @emph{not} change their name.
 @item @code{home-directory}
 This is the name of the home directory for the account.
 
-@item @code{home-directory-permissions} (default: @code{#o700})
-The permission bits for the home directory.  By default, full access is
-granted to the user account and all other access is denied.
-
 @item @code{create-home-directory?} (default: @code{#t})
 Indicates whether the home directory of this account should be created
 if it does not exist yet.
@@ -31342,7 +31358,7 @@ The port on which to connect to the database.
 
 @cindex Mumi, Debbugs Web interface
 @cindex Debbugs, Mumi Web interface
-@uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a
+@uref{https://git.savannah.gnu.org/cgit/guix/mumi.git/, Mumi} is a
 Web interface to the Debbugs bug tracker, by default for
 @uref{https://bugs.gnu.org, the GNU instance}.  Mumi is a Web server,
 but it also fetches and indexes mail retrieved from Debbugs.
@@ -32675,7 +32691,7 @@ can run on headless servers.  The Xvnc implementations provided by the
 
 @defvar xvnc-service-type
 
-The @code{xvnc-server-type} service can be configured via the
+The @code{xvnc-service-type} service can be configured via the
 @code{xvnc-configuration} record, documented below.  A second virtual
 display could be made available on a remote machine via the
 following configuration:
@@ -43941,6 +43957,62 @@ Extra content appended as-is to this @code{Host} block in
 
 @end deftp
 
+@cindex Parcimonie, Home service
+The @code{parcimonie} service runs a daemon that slowly refreshes a GnuPG
+public key from a keyserver.  It refreshes one key at a time; between every
+key update parcimonie sleeps a random amount of time, long enough for the
+previously used Tor circuit to expire.  This process is meant to make it hard
+for an attacker to correlate the multiple key update.
+
+As an example, here is how you would configure @code{parcimonie} to refresh the
+keys in your GnuPG keyring, as well as those keyrings created by Guix, such as
+when running @code{guix import}:
+
+@lisp
+(service home-parcimonie-service-type
+         (home-parcimonie-configuration
+           (refresh-guix-keyrings? #t)))
+@end lisp
+
+This assumes that the Tor anonymous routing daemon is already running on your
+system.  On Guix System, this can be achieved by setting up
+@code{tor-service-type} (@pxref{Networking Services, @code{tor-service-type}}).
+
+The service reference is given below.
+
+@defvar parcimonie-service-type
+This is the service type for @command{parcimonie}
+(@uref{https://salsa.debian.org/intrigeri/parcimonie, Parcimonie's web site}).
+Its value must be a @code{home-parcimonie-configuration}, as shown below.
+@end defvar
+
+@c %start of fragment
+
+@deftp {Data Table} home-parcimonie-configuration
+Available @code{home-parcimonie-configuration} fields are:
+
+@table @asis
+@item @code{parcimonie} (default: @code{parcimonie}) (type: file-like)
+The parcimonie package to use.
+
+@item @code{verbose?} (default: @code{#f}) (type: boolean)
+Whether to have more verbose logging from the service.
+
+@item @code{gnupg-already-torified?} (default: @code{#f}) (type: boolean)
+Whether GnuPG is already configured to pass all traffic through
+@uref{https://torproject.org, Tor}.
+
+@item @code{refresh-guix-keyrings?} (default: @code{#f}) (type: boolean)
+Guix creates a few keyrings in the @var{$XDG_CONFIG_DIR}, such as when running
+@code{guix import} (@pxref{Invoking guix import}).  Setting this to @code{#t}
+will also refresh any keyrings which Guix has created.
+
+@item @code{extra-content} (default: @code{#f}) (type: raw-configuration-string)
+Raw content to add to the parcimonie command.
+
+@end table
+
+@end deftp
 
 @c %end of fragment
 
@@ -45869,47 +45941,48 @@ will not have the desired effect.  @xref{Package Transformation Options,
 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.
+because @TeX{} Live is so huge and because finding one's way in this
+maze is tricky, so this section provides some guidance on how to deploy
+the relevant packages to compile @TeX{} and @LaTeX{} documents.
 
-@TeX{} Live currently comes in two flavors in Guix:
+@TeX{} Live currently comes in two mutually exclusive 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!).
+single @TeX{} Live package} (roughly 4,200), but it is huge---more than
+4@tie{}GiB for a single package!
 
 @item
-The ``modular'' @samp{texlive-} packages: you start off with
-a combination of @TeX{} Live @dfn{collections} and
-@dfn{schemes}---``meta-packages'' such as
-@code{texlive-collection-fontsrecommended}, or
-@code{texlive-collection-context}, that provide the set of packages
-needed in this particular domain, schemes being the name for collections
-of such collections.  This grants you core functionality and the main
-commands---@command{pdflatex}, @command{dvips}, @command{luatex},
-@command{mf}, etc.  You can then complete your selection with additional
-collections or individual packages that provide just the features you
-need---@code{texlive-listings} for the @code{listings} package,
-@code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ, and
-so on.
+A ``modular'' @TeX{} Live distribution, in which you only install the
+packages, always prefixed with @samp{texlive-}, you need.
 @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:
+So to insist, these two flavors cannot be combined@footnote{No rule
+without exception! As the monolithic @TeX{} Live does not contain the
+@command{biber} executable, it is okay to combine it with
+@code{texlive-biber}, which does.}.  If in the modular setting your
+document does not compile, the solution is not to add the monolithic
+@code{texlive} package, but to add the set of missing packages from the
+modular distribution.
+
+Building a coherent system that provides all the essential tools and, at
+the same time, satisfies all of its internal dependencies can be
+a difficult task.  It is therefore recommended to start with sets of
+packages, called @dfn{collections}, and @dfn{schemes}, the name for
+collections of collections.  The following command lists available
+schemes and collections (@pxref{guix-search,, Invoking guix package}):
 
 @example
-guix shell texlive-scheme-basic texlive-cm-super -- pdflatex doc.tex
+guix search texlive-\(scheme\|collection\) | recsel -p name,description
 @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,
-which would probably be a reasonable starting point for a French
-@LaTeX{} user:
+If needed, you may then complete your system with individual packages,
+particularly when they belong to a large collection you're not otherwise
+interested in.
+
+For instance, the following manifest is a reasonable, yet frugal
+starting point for a French @LaTeX{} user:
 
 @lisp
 (specifications->manifest
@@ -45918,31 +45991,18 @@ which would probably be a reasonable starting point for a French
    "texlive-scheme-basic"
    "texlive-collection-latexrecommended"
    "texlive-collection-fontsrecommended"
-
    "texlive-babel-french"
 
-   ;; PGF/TikZ
-   "texlive-pgf"
-
-   ;; Additional font.
-   "texlive-kpfonts"))
+   ;; From "latexextra" collection.
+   "texlive-tabularray"
+   ;; From "binextra" collection.
+   "texlive-texdoc"))
 @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{Writing Manifests}, for more on manifests.  In the future, we plan
-to provide more collections and schemes.  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:
+If you come across a document that does not compile in such a basic
+setting, the main difficulty is finding the missing packages.  In this
+case, @command{pdflatex} and similar commands tend to fail with obscure
+error messages along the lines of:
 
 @example
 doc.tex: File `tikz.sty' not found.
@@ -45958,7 +46018,7 @@ kpathsea: Running mktexmf phvr7t
 @end example
 
 How do you determine what the missing package is?  In the first case,
-you'll find the answer by running:
+you will find the answer by running:
 
 @example
 $ guix search texlive tikz
@@ -45968,11 +46028,11 @@ version: 59745
 @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:
+you can search the @TeX{} Live package database using the
+@command{tlmgr} command:
 
 @example
-$ guix shell texlive-bin -- tlmgr info phvr7t
+$ tlmgr info phvr7t
 tlmgr: cannot find package phvr7t, searching for other matches:
 
 Packages containing `phvr7t' in their title/description:
@@ -45987,32 +46047,10 @@ 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
-
-Additional options include:
-
-@table @code
-@item --recursive
-@itemx -r
-Traverse the dependency graph of the given upstream package recursively
-and generate package expressions for all those packages that are not yet
-in Guix.
-@end table
-
-@quotation Note
-@TeX{} Live packaging is still very much work in progress, but you can
-help!  @xref{Contributing}, for more information.
-@end quotation
+@noindent
+The file is available in the @TeX{} Live @code{helvetic} package, which
+is known in Guix as @code{texlive-helvetic}.  Quite a ride, but you
+found it!
 
 @node Security Updates
 @chapter Security Updates
diff --git a/doc/local.mk b/doc/local.mk
index 9d1e3ff7e4..97f0c3a92a 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -230,7 +230,7 @@ $(srcdir)/%D%/guix.1: scripts/guix.in $(sub_commands_mans)
 # source script (the first prerequisite) has been changed.  The $(GOBJECTS)
 # prerequisite is solely meant to force these docs to be made only after all
 # Guile modules have been compiled.  We also need the guix script to exist.
-$(srcdir)/%D%/guix-%.1: scripts/guix guix/scripts/%.scm $(GOBJECTS)
+$(srcdir)/%D%/guix-%.1: guix/scripts/%.scm $(GOBJECTS) scripts/guix
 	-@case '$?' in \
 	  *$<*) $(AM_V_P) && set -x || echo "  HELP2MAN $@"; \
 	        $(gen_man) --output="$@" "guix $*";; \