I've just re-installed Guix from a 0.16 image.  My first time in a year,
and I've had the opportunity to have a fresh look at the installation
manual.  I've taken note of a few confusing points that gave me a hard
time installing Guix (even the 2nd time :p) so here they are.  I'll send
a patch to address them if you people agree.


- From the manual, 6.1.4 Preparing for Installation:

--8<---------------cut here---------------start------------->8---
   If you instead wish to use EFI-based GRUB, a FAT32 “EFI System
Partition” (ESP) is required.  This partition should be mounted at
‘/boot/efi’ and must have the ‘esp’ flag set.  E.g., for ‘parted’:
--8<---------------cut here---------------end--------------->8---

Actually the EFI partition can be mounted anywhere (/efi or /boot are also
customary), it's up to the users to make sure they are pointed at the right
mounted location.


--8<---------------cut here---------------start------------->8---
   Also mount any other file systems you would like to use on the target
system relative to this path.  If you have ‘/boot’ on a separate
partition for example, mount it at ‘/mnt/boot’ now so it is found by
‘guix system init’ afterwards.
--8<---------------cut here---------------end--------------->8---

That's not consistent with /mnt/boot/efi that was just mentioned above.
Besides, I think we should mention the word "EFI" in this paragraph so that
people find this paragraph when they search for the EFI term to make sure
they've covered everything

- From 6.1.5 Proceeding with the Installation
--8<---------------cut here---------------start------------->8---
   • Make sure the ‘bootloader-configuration’ form refers to the target
     you want to install GRUB on.  It should mention ‘grub-bootloader’
     if you are installing GRUB in the legacy way, or
     ‘grub-efi-bootloader’ for newer UEFI systems.  For legacy systems,
     the ‘target’ field names a device, like ‘/dev/sda’; for UEFI
     systems it names a path to a mounted EFI partition, like
     ‘/boot/efi’, and do make sure the path is actually mounted.
--8<---------------cut here---------------end--------------->8---

At the end, it's unclear whether the EFI partition must be _currently_ mounted
or if the config.scm must have a mount point declaration.  Actually, it's both,
and that be made explicit I think.  Also see the next point:

- From gnu/system/examples/desktop.tmpl:

--8<---------------cut here---------------start------------->8---
  ;; Use the UEFI variant of GRUB with the EFI System
  ;; Partition mounted on /boot/efi.
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")))
  ;...

  (file-systems (cons (file-system
                        (device (file-system-label "my-root"))
                        (mount-point "/")
                        (type "ext4")
                        (dependencies mapped-devices))
                      %base-file-systems))
--8<---------------cut here---------------end--------------->8---

The EFI partition is missing from the file-systems declaration!!


- All templates:
I remember this was discussed before, but shouldn't we replace (cons* ...) with
(list ...)?  It's easier to grok for users new to Lisp.

- In the operating-system record, what's the default value of home-directory (in
  (users (list (user-account (home-directory ...)))))?  Shouldn't default to
  (string-append "/home/" name)?  That could also spare us some potential
  mistakes at install-time.

- I was surprised to see that from the install image, curl, git, etc. would fail
  with an SSL error.  It's annoying because I really needed to get my config.scm
  from an online source.

  I only briefly investigated: the environment has

--8<---------------cut here---------------start------------->8---
SSL_CERT_DIR=/etc/ssl/certs
SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
--8<---------------cut here---------------end--------------->8---

  but the install image only has a /etc/ssl file.

--
Pierre Neidhardt
https://ambrevar.xyz/