improve installation instructions

[Ricardo Wurmus]

Hey,

I just installed Guix as a package manager on an aarch64 box.  The
manual makes it a little difficult to perform all these steps, because
the commands cannot be easily copied.  We do have the shell script, but
the manual mentions it only in passing – as a user I skipped over the
introduction and went straight to step 1, right past the script.

What do you think about mentioning the script in the Installation
section and only asking users to look in the subsections for details?

Here’s a draft patch:

--8<---------------cut here---------------start------------->8---
diff --git a/doc/guix.texi b/doc/guix.texi
index fcb5b8c08..f9afe2bc3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -25,7 +25,7 @@ Copyright @copyright{} 2015, 2016 Mathieu address@hidden
 Copyright @copyright{} 2014 Pierre-Antoine address@hidden
 Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/address@hidden
 Copyright @copyright{} 2015, 2016, 2017 Leo address@hidden
-Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo address@hidden
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo address@hidden
 Copyright @copyright{} 2016 Ben address@hidden
 Copyright @copyright{} 2016, 2017, 2018 Chris address@hidden
 Copyright @copyright{} 2016, 2017, 2018 Efraim address@hidden
@@ -394,29 +394,32 @@ garbage collection of packages (@pxref{Features}).
 @chapter Installation
 
 @cindex installing Guix
address@hidden official website
-GNU Guix is available for download from its website at
address@hidden://www.gnu.org/software/guix/}.  This section describes the
-software requirements of Guix, as well as how to install it and get
-ready to use it.
 
-Note that this section is concerned with the installation of the package
-manager, which can be done on top of a running GNU/Linux system.  If,
-instead, you want to install the complete GNU operating system,
address@hidden Installation}.
+We recommend the use of this
address@hidden://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
+shell installer script} to install Guix on top of a running GNU/Linux system,
+thereafter called a @dfn{foreign address@hidden section is concerned
+with the installation of the package manager, which can be done on top of a
+running GNU/Linux system.  If, instead, you want to install the complete GNU
+operating system, @pxref{System Installation}.} The script automates the
+download, installation, and initial configuration of Guix.  It should be run
+as the root user.
 
 @cindex foreign distro
 @cindex directories related to foreign distro
-
-When installed on a running GNU/Linux system---thereafter called a
address@hidden address@hidden complements the available tools
-without interference.  Its data lives exclusively in two directories,
-usually @file{/gnu/store} and @file{/var/guix}; other files on your
-system, such as @file{/etc}, are left untouched.
+When installed on a foreign distro, address@hidden complements the available
+tools without interference.  Its data lives exclusively in two directories,
+usually @file{/gnu/store} and @file{/var/guix}; other files on your system,
+such as @file{/etc}, are left untouched.
 
 Once installed, Guix can be updated by running @command{guix pull}
 (@pxref{Invoking guix pull}).
 
+If you prefer to perform the installation steps manually or want to tweak
+them, you may find the following subsections useful.  They describe the
+software requirements of Guix, as well as how to install it manually and get
+ready to use it.
+
 @menu
 * Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
@@ -437,11 +440,6 @@ dependencies.  This is often quicker than installing from 
source, which
 is described in the next sections.  The only requirement is to have
 address@hidden and Xz.
 
-We provide a
address@hidden://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script}, which automates the download, installation, and
-initial configuration of Guix.  It should be run as the root user.
-
 Installing goes along these lines:
 
 @enumerate
@@ -638,6 +636,10 @@ build procedure for Guix is the same as for other GNU 
software, and is
 not covered here.  Please see the files @file{README} and @file{INSTALL}
 in the Guix source tree for additional details.
 
address@hidden official website
+GNU Guix is available for download from its website at
address@hidden://www.gnu.org/software/guix/}.
+
 GNU Guix depends on the following packages:
 
 @itemize
--8<---------------cut here---------------end--------------->8---


--
Ricardo