aboutsummaryrefslogtreecommitdiff
path: root/gnu
diff options
context:
space:
mode:
Diffstat (limited to 'gnu')
-rw-r--r--gnu/packages/emacs.scm12
1 files changed, 3 insertions, 9 deletions
diff --git a/gnu/packages/emacs.scm b/gnu/packages/emacs.scm
index 94d08244d1..9a5ec2ad0d 100644
--- a/gnu/packages/emacs.scm
+++ b/gnu/packages/emacs.scm
@@ -462,16 +462,10 @@ languages.")
(arguments
(substitute-keyword-arguments (package-arguments emacs-next)
((#:configure-flags flags #~'())
- #~(cons* "--with-pgtk" "--with-xwidgets" #$flags))))
- (propagated-inputs
- (list gsettings-desktop-schemas glib-networking))
- (inputs
- (modify-inputs (package-inputs emacs-next)
- (prepend webkitgtk-with-libsoup2)))
- (home-page "https://github.com/masm11/emacs")
- (synopsis "Emacs text editor with @code{pgtk} and @code{xwidgets} support")
+ #~(cons* "--with-pgtk" #$flags))))
+ (synopsis "Emacs text editor with @code{pgtk} support")
(description "This Emacs build implements graphical UI purely in terms of
-GTK and also enables xwidgets.")))
+GTK.")))
(define-public emacs-minimal
;; This is the version that you should use as an input to packages that just
generated by cgit
tr>-rw-r--r--doc/local.mk2
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