improve installation instructions

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 Lirzin@*
 Copyright @copyright{} 2014 Pierre-Antoine Rault@*
 Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
 Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
 Copyright @copyright{} 2016 Ben Woodcroft@*
 Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
 Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
@@ -394,29 +394,32 @@ garbage collection of packages (@pxref{Features}).
 @chapter Installation
 
 @cindex installing Guix
-@cindex official website
-GNU Guix is available for download from its website at
-@url{http://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,
-@pxref{System Installation}.
+We recommend the use of this
+@uref{https://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 distro}.@footnote{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, @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
-@dfn{foreign distro}---GNU@tie{}Guix 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, GNU@tie{}Guix 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
 GNU@tie{}tar and Xz.
 
-We provide a
-@uref{https://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.
 
+@cindex official website
+GNU Guix is available for download from its website at
+@url{https://www.gnu.org/software/guix/}.
+
 GNU Guix depends on the following packages:
 
 @itemize
--8<---------------cut here---------------end--------------->8---


--
Ricardo

Re: improve installation instructions

[Amirouche Boubekki]

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

Le sam. 5 janv. 2019 17:59, Ricardo Wurmus <rekado@elephly.net> a écrit :

> 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 Lirzin@*
>  Copyright @copyright{} 2014 Pierre-Antoine Rault@*
>  Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
>  Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
> -Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@*
> +Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
>  Copyright @copyright{} 2016 Ben Woodcroft@*
>  Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
>  Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
> @@ -394,29 +394,32 @@ garbage collection of packages (@pxref{Features}).
>  @chapter Installation
>
>  @cindex installing Guix
> -@cindex official website
> -GNU Guix is available for download from its website at
> -@url{http://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,
> -@pxref{System Installation}.
> +We recommend the use of this
> +@uref{
> https://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 distro}.@footnote{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, @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
> -@dfn{foreign distro}---GNU@tie{}Guix 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, GNU@tie{}Guix 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
>  GNU@tie{}tar and Xz.
>
> -We provide a
> -@uref{
> https://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.
>
> +@cindex official website
> +GNU Guix is available for download from its website at
> +@url{https://www.gnu.org/software/guix/}.
> +
>  GNU Guix depends on the following packages:
>
>  @itemize
> --8<---------------cut here---------------end--------------->8---
>

LGTM

>

[-- Attachment #2: Type: text/html, Size: 6077 bytes --]

Re: improve installation instructions

[Kyle Meyer]

Ricardo Wurmus <rekado@elephly.net> writes:

> 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.

I've installed Guix on a foreign distro a few times and didn't realize
that that script existed, so I must have skipped past it each time.

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

Looks good.  I think it would certainly help hasty readers like me.

Thanks.

-- 
Kyle

Re: improve installation instructions

[Ludovic Courtès]

Hello!

Ricardo Wurmus <rekado@elephly.net> skribis:

> 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?

Good idea.

> +We recommend the use of this
> +@uref{https://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 distro}.@footnote{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, @pxref{System Installation}.} The script automates the
> +download, installation, and initial configuration of Guix.  It should be run
> +as the root user.

Perhaps you could wrap this paragraph in “@quotation Note” to make it
even more visible.

Thanks,
Ludo’.

Re: improve installation instructions

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

>> What do you think about mentioning the script in the Installation
>> section and only asking users to look in the subsections for details?
>
> Good idea.
>
>> +We recommend the use of this
>> +@uref{https://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 distro}.@footnote{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, @pxref{System Installation}.} The script automates the
>> +download, installation, and initial configuration of Guix.  It should be run
>> +as the root user.
>
> Perhaps you could wrap this paragraph in “@quotation Note” to make it
> even more visible.

Done.  Thanks for the comments!

-- 
Ricardo