Re: Feedback of the GNU Guix manual

[Matt]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed an item and are ready to work on the next one:

#+begin_quote
,** Binary Installation L88 and L95

~root is weird. Should be root or simply ~ for the user profile which would be 
root as root user.
#+end_quote

I agree.  I found it weird at first, too.

Two thoughts:

1. The use of "~root" is intentional
2. Section 2.1 Binary Install can be refactored to remove the reported 
confusion as well as the tarpit of shell related details

*1. The use of "~root" is intentional*

According to the Bash info and man pages, "~root" is a TILDE-PREFIX with "root" 
as the LOGIN NAME.  The TILDE-PREFIX is replaced with the home directory 
associated with the specified LOGIN NAME.

Using "~root" solves the problem of operations happening in the wrong location. 
 It ensures that commands reference the 'root' user's home directory.

- (original issue) 
https://lists.gnu.org/archive/html/guix-devel/2015-06/msg00085.html
- (separate issue) https://bugs.gnu.org/30728

*2. Section 2.1 Binary Install needs refactoring*

The Binary Installation section tries to solve the problem of guiding readers 
to install Guix as quickly and painlessly as possible.  This began as a 
step-by-step process which was later automated by 'guix-install.sh'.  Over 6 
years, 12 people have worked to make 'guix-install.sh' robust.  Because of 
these efforts, Section 2.1 Binary Installation has effectively become high 
level documentation for how 'guix-install.sh' works.

Like any code comment tends to drift out of sync with the source code, the 
current presentation of binary installations has become inconsistent and 
redundant.  Using 'guix-install.sh' is the recommended method for binary 
installation.  It's the first thing mentioned by Section 2 Installation and one 
of the first things mentioned by Section 2.1 Binary Installation.  It's 
inconsistent to say, "This is how to do it" and then proceed to explain how to 
*not* use the recommended method.

Key information, like the recommended installation method and the definition of 
"foreign distro", are improperly hidden inside notes.  Note blocks act as 
comments which, by definition, are secondary to the main point.  The main point 
is to use 'guix-install.sh' on foreign distros which don't provide their own 
packages for Guix.

The attached diff addresses these issues.  It fixes the root issue (pun 
intended) of whether or not to expect readers to understand '~root', as well as 
unmentioned issues also related to shell-specific knowledge like, "What does it 
mean to 'source'?"  Readers interested in those details may read the code for 
'guix-install.sh'.

The diff does the following:

- Clarifies at the top level that installing on a foreign distro has two 
methods: using packaged binaries and building from source
- Places the overwrite warning at the top level node and binary installation 
level node
- Moves the definition of "foreign distro" out of quotation
- Moves the foreign distro installation instructions out of quotation
- Summarizes the steps 'guix-install.sh' follows rather than trying to detail 
them
- Splits the requirements between system requirements for binary installations, 
GNU/Linux or GNU/Hurd, and requirements for running 'guix-install.sh', tar, 
wget, Xz
- Removes redundant instructions to use 'guix-install.sh'
- Places directions for 'guix-install.sh' after directions to use 
distribution-specific package managers, giving preference to those simpler 
install processes over the more manual 'guix-install.sh' process

v01-refactor-binary-installation-section.diff
Description: Binary data