Re: Feedback of the GNU Guix manual

[Matt <matt@excalamus.com>]

[-- Attachment #1: Type: text/plain, Size: 3689 bytes --]

Friendly bump.

Attached is a suggested diff.

A previous suggestion was made to change "system" to the proper noun "System", as in the "Guix System", within the Binary Installation section.  The change would occur in a warning that moving unpacked binary tarballs as directed on existing Guix installations will overwrite system files.

The suggested capitalization would be improper since the "system" referred to is "an arbitrary system" and not specifically the Guix System.

The broader context is that the change suggested occurs within the Binary Installation section.  Since, there is no apparent reason why a user of an existing Guix installation would need to perform a binary installation, this patch removes the warning sentence (containing the confusing usage of "system") and moves it to the beginning of the section so that readers may understand the risk at the start and to decide whether this section applies to them before reading further.

The change also corrects the overly broad term "arbitrary system" to the specific "Linux or Hurd-based system."  Guix does not work with BSD, Haiku, Windows, or Darwin systems.  While installing Guix on these systems may be possible, by some definitions of "install", doing so for an end-user would be silly, since it wouldn't function as expected.

The change also more accurately lists the requirements.  Previously, it was stated that only tar and Xz are required.  This is false since Guix requires a Linux or Hurd-based system.

The explanation of "a self-contained tarball providing binaries for Guix and for all its dependencies" was reduced to the simpler "archived binaries."  Generally, "tarball" is imprecise, hence the need to explain what it contains in this context.  Further, it's jargon, may not be familiar to some readers, and isn't relevant to the point of the introduction, that Guix may be installed without needing to compile and why that might be desirable.

Specific mention of installing Guix's dependencies was removed.  Guix being installed implies that its dependencies are also installed.

The warning line was added in commit:
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=5dc3ce5f6c7990f44143f8e9bb9a873a014a82e4.
The warning orginates from this commit:
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=09722b11e5e618028051d5f6d14eb13529dc7100

I see no associated issue referenced in the commits.  I assume the warning is simply being cautious.

#+begin_src diff
diff --git a/doc/guix.texi b/doc/guix.texi
index 4af830aed7..16349d4ec1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,16 @@ ready to use it.

 @cindex installing Guix from binaries
 @cindex installer script
-This section describes how to install Guix on an arbitrary system from a
-self-contained tarball providing binaries for Guix and for all its
-dependencies.  This is often quicker than installing from source, which
-is described in the next sections.  The only requirement is to have
-GNU@tie{}tar and Xz.
+This section describes how to install Guix from archived binaries.  Such
+installations are often quicker than building from source, which is
+described in the next sections.  Binary installations require a Linux or
+Hurd-based system with GNU@tie{}tar and Xz.
+
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.

 @c Note duplicated from the ``Installation'' node.
-@quotation Note
 We recommend the use of this
 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
 shell installer script}.  The script automates the download, installation, and
#+end_src

[-- Attachment #2: 0001-binary-installation.diff --]
[-- Type: application/octet-stream, Size: 1213 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 4af830aed7..16349d4ec1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,16 @@ ready to use it.
 
 @cindex installing Guix from binaries
 @cindex installer script
-This section describes how to install Guix on an arbitrary system from a
-self-contained tarball providing binaries for Guix and for all its
-dependencies.  This is often quicker than installing from source, which
-is described in the next sections.  The only requirement is to have
-GNU@tie{}tar and Xz.
+This section describes how to install Guix from archived binaries.  Such
+installations are often quicker than building from source, which is
+described in the next sections.  Binary installations require a Linux or
+Hurd-based system with GNU@tie{}tar and Xz.
+
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 
 @c Note duplicated from the ``Installation'' node.
-@quotation Note
 We recommend the use of this
 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
 shell installer script}.  The script automates the download, installation, and