Re: Feedback of the GNU Guix manual

[Matt <matt@excalamus.com>]

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


 ---- On Sun, 18 Feb 2024 14:55:46 +0100  Josselin Poiret  wrote --- 

 > Matt matt@excalamus.com> writes:
 > 
 > > Specific mention of installing Guix's dependencies was removed.  Guix being installed implies that its dependencies are also installed.
 > 
 > I don't agree here: it's often the case in Linux-land that binary
 > archives are provided without their dependencies included, assuming that
 > the user already has them, often by installing them via their own
 > package manager.  Keeping the mention that it is self-contained and that
 > the dependencies are also included might clarify the situation for some
 > users.

Thank you for the feedback.

I opted for only "self-contained" which seems to imply that dependencies are available, in addition to other things, perhaps like setting an environment or pathing.  If "self-contained" is distinct from "includes dependencies," we could append something like "...and includes all dependencies" to the last sentence.

I also tried to distinguish that it's the installation *process* which requires GNU-tar and Xz and not the final installation, since that's self-contained.

Otherwise, I tried to simplify the language:

- archived binaries -> a binary archive
- are often quicker -> often go faster
- which is described in the next sections -> described later

This version has fewer words and one more sentence.  However, each sentence has a single, hopefully clear, point:

1. What this section is about? Installing from a binary archive.
2. Why you might want this section? It's faster than building.
3. What's needed?  A Linux or Hurd-system with GNU-tar and Xz.
4. What do you get?  A self-contained Guix installation.

Original: Region has 5 lines, 3 sentences, 51 words, and 301 characters
v2:       Region has 5 lines, 4 sentences, 45 words, and 292 characters

If this is good, I can write up a commit message and format the change as a patch.

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

diff --git a/doc/guix.texi b/doc/guix.texi
index 9966a8e697..a5558300fa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,17 @@ 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 a binary archive.  Such
+installations often go faster than building from source, described
+later.  Guix requires a Linux or Hurd-based system and unpacking the
+archive requires GNU@tie{}tar and Xz.  The resulting installation is
+self-contained.
+
+@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