Re: Feedback of the GNU Guix manual

[Matt]

 ---- On Thu, 18 Jan 2024 20:44:53 +0100  Maxim Cournoyer  wrote --- 

 > That would be a good way to help, yes!  It'll be easier to review if
 > each distinct problem is fixed in its own commit (patch).

Now that I've looked more closely at it, I completely agree.

I suggest we take them point-by-point and move on only after we've completed 
each one in turn. 

** Binary installation L73
Guix system should be Guix System

*** Comment
Line 73 in the info file, section "Binary Installation" corresponds to
line 825 in =doc/guix.texi=.

=15efd5a7f4:doc/guix.texi= reads,

#+begin_quote
Do _not_ unpack the tarball on a working Guix system since that would
overwrite its own essential files.
#+end_quote

I see several issues with this sentence.  In order of severity:

1. the sentence isn't necessary
2. the problem is moving, not unpacking
3. the sentence confuses the subject
4. (reported) the word "system" is unclear

At this point in the manual, the reader has downloaded a Guix tarball
and has just been instructed to unpack and move the extracted files.
The sentence warns that moving =/tmp/var/guix= to =/var/= and
=/tmp/gnu= to =/= will overwrite files already there from an existing
Guix installation.

**** 1. the sentence isn't necessary
Is there ever a circumstance where a Guix installation, from a binary
or as a System, would need to install Guix from the tarball?

Unless there's a reason for a Guix user to follow the steps in "Binary
Installation," I suggest we remove this sentence and revise the
introduction paragraph to make sure current Guix users skip this
section.

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode