[PATCH] doc: Use existing URLs and file names in installation instructions.

DoneSubmitted by Julien Lepiller.
Details
4 participants
  • Julien Lepiller
  • Leo Famulari
  • Marius Bakke
  • Tobias Geerinckx-Rice
Owner
unassigned
Severity
normal
J
J
Julien Lepiller wrote on 27 May 2020 17:30
(address . guix-patches@gnu.org)
20200527173013.36a11a54@tachikoma.lepiller.eu
Some users seem to be confused by the fact that our URLs in the manualdon't work for them. This is most likely because they copy themwithout reading the rest of the text which clearly says they shouldreplace @var{system} with one of the supported values. One example ofthis confusion is this conversation:https://mastodon.social/@Nixfreak/104224784493287104
Since our current approach doesn't seem to be very effective, I proposeto change the URLs and file names with actual ones, using x86_64-linuxas the system because this is the most popular platform that we supportnowadays. I keep mentioning the other architectures as alternatives,hoping that users will notice the x86_64 in the URL and keep reading tolearn how to install Guix for another architecture if they want to.
Wdyt?
From 5be064d009e3e45029fe8c5b9a7cc0c8275bec50 Mon Sep 17 00:00:00 2001From: Julien Lepiller <julien@lepiller.eu>Date: Wed, 27 May 2020 16:52:53 +0200Subject: [PATCH] doc: Use existing URLs and file names in installation instructions.
Some users are confused that these URLs and file names don't work, sochange them to the most popular architecture, while still mentioningalternatives.
* doc/guix.texi (USB Stick and DVD Installation): Use x86_64-linux URLsby default.--- doc/guix.texi | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-)
Toggle diff (97 lines)diff --git a/doc/guix.texi b/doc/guix.texiindex 4dbbf96db9..695b0c4485 100644--- a/doc/guix.texi+++ b/doc/guix.texi@@ -567,17 +567,18 @@ Installing goes along these lines: @item @cindex downloading Guix binary Download the binary tarball from-@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz},-where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine-already running the kernel Linux, and so on.+@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},+where @code{x86_64-linux} can be replaced with @code{xi686-linux} for an+@code{i686} (32-bits) machine already running the kernel Linux, and so on+(@pxref{GNU Distribution}). @c The following is somewhat duplicated in ``System Installation''. Make sure to download the associated @file{.sig} file and to verify the authenticity of the tarball against it, along these lines: @example-$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig-$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig+$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig+$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig @end example If that command fails because you do not have the required public key,@@ -603,7 +604,7 @@ you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run: @example # cd /tmp # tar --warning=no-timestamp -xf \- /path/to/guix-binary-@value{VERSION}.@var{system}.tar.xz+ /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz # mv var/guix /var/ && mv gnu / @end example @@ -1917,8 +1918,8 @@ about their support in GNU/Linux. An ISO-9660 installation image that can be written to a USB stick or burnt to a DVD can be downloaded from-@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz},-where @var{system} is one of:+@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz},+where you can replace @code{x86_64-linux} with one of: @table @code @item x86_64-linux@@ -1933,8 +1934,8 @@ Make sure to download the associated @file{.sig} file and to verify the authenticity of the image against it, along these lines: @example-$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig-$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig+$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig+$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig @end example If that command fails because you do not have the required public key,@@ -1965,7 +1966,7 @@ To copy the image to a USB stick, follow these steps: Decompress the image using the @command{xz} command: @example-xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz+xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz @end example @item@@ -1974,7 +1975,7 @@ its device name. Assuming that the USB stick is known as @file{/dev/sdX}, copy the image with: @example-dd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdX+dd if=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX sync @end example @@ -1990,7 +1991,7 @@ To copy the image to a DVD, follow these steps: Decompress the image using the @command{xz} command: @example-xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz+xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz @end example @item@@ -1999,7 +2000,7 @@ its device name. Assuming that the DVD drive is known as @file{/dev/srX}, copy the image with: @example-growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{system}.iso+growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso @end example Access to @file{/dev/srX} usually requires root privileges.-- 2.26.2
T
T
Tobias Geerinckx-Rice wrote on 27 May 2020 17:50
(name . Julien Lepiller)(address . julien@lepiller.eu)(address . 41565@debbugs.gnu.org)
87v9kh4bse.fsf@nckx
Julien,
Julien Lepiller 写道:
Toggle quote (2 lines)> https://mastodon.social/@Nixfreak/104224784493287104
Sigh :-)
Toggle quote (13 lines)> Since our current approach doesn't seem to be very effective, I > propose> to change the URLs and file names with actual ones, using > x86_64-linux> as the system because this is the most popular platform that we > support> nowadays. I keep mentioning the other architectures as > alternatives,> hoping that users will notice the x86_64 in the URL and keep > reading to> learn how to install Guix for another architecture if they want > to.
I like it!
Kind regards,
T G-R
-----BEGIN PGP SIGNATURE-----
iHUEARYKAB0WIQT12iAyS4c9C3o4dnINsP+IT1VteQUCXs6MUQAKCRANsP+IT1VteTUuAP48O37oIZvwkCN1+ZSgoedbe9+C9QqIXzmjQQQZlVu7/wD/XnZYQ5SsOW8WJ9jIWNLYtsljWr9a4LmxN9pUU3hUcQc==QYN4-----END PGP SIGNATURE-----
L
L
Leo Famulari wrote on 27 May 2020 19:17
(name . Julien Lepiller)(address . julien@lepiller.eu)(address . 41565@debbugs.gnu.org)
20200527171730.GC28889@jasmine.lan
On Wed, May 27, 2020 at 05:30:13PM +0200, Julien Lepiller wrote:
Toggle quote (14 lines)> Some users seem to be confused by the fact that our URLs in the manual> don't work for them. This is most likely because they copy them> without reading the rest of the text which clearly says they should> replace @var{system} with one of the supported values. One example of> this confusion is this conversation:> https://mastodon.social/@Nixfreak/104224784493287104> > Since our current approach doesn't seem to be very effective, I propose> to change the URLs and file names with actual ones, using x86_64-linux> as the system because this is the most popular platform that we support> nowadays. I keep mentioning the other architectures as alternatives,> hoping that users will notice the x86_64 in the URL and keep reading to> learn how to install Guix for another architecture if they want to.
I agree, it's a common mistake for new users. Your patch seems like theright thing to do...
M
M
Marius Bakke wrote on 27 May 2020 22:44
87tv013y6b.fsf@gnu.org
Julien Lepiller <julien@lepiller.eu> writes:
Toggle quote (2 lines)> Wdyt?
Sgtm.
[...]
Toggle quote (5 lines)> -@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz},> -where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine> -already running the kernel Linux, and so on.> +@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},> +where @code{x86_64-linux} can be replaced with @code{xi686-linux} for an
^^^ stray 'x'
-----BEGIN PGP SIGNATURE-----
iQEzBAEBCgAdFiEEu7At3yzq9qgNHeZDoqBt8qM6VPoFAl7O0TwACgkQoqBt8qM6VPoSvAgA1FjNPFjyc/yJo1TqpLae0GfAoy9FIP1+tBtTWUeet9Lgu6INhUX3gZSUEFP9IDQufm9c02IZqk+Pv92f0S8gCTKOS3iDKpF20wqRjY73CPNXKfSm80zinVRDOPtoOy9cvV8jfS09PkYzduWOq3jIvTShu5jS9GmG/wMHH3X1DSWl1s/3J6KsH4bxzJiSgvGC5TnH4DtJdoovuACtiPhEQxI3rUt686KYHLg3MnlG8PGO0JmQlu9MlsJPolZnbQ/i7e3DfCyGaHRiNO8D8vWh9KZExfR+THZ8I+1XVjcWF6ubNOOuk41htAmbhPba2ORvKkdpLkXQR+4uszEdYt64Dw===aVwV-----END PGP SIGNATURE-----
J
J
Julien Lepiller wrote on 27 May 2020 23:29
(address . 41565-done@debbugs.gnu.org)
20200527232911.74e8c406@tachikoma.lepiller.eu
Le Wed, 27 May 2020 22:44:44 +0200,Marius Bakke <marius@gnu.org> a écrit :
Toggle quote (17 lines)> Julien Lepiller <julien@lepiller.eu> writes:> > > Wdyt? > > Sgtm.> > [...]> > > -@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz},> > -where @var{system} is @code{x86_64-linux} for an @code{x86_64}> > machine -already running the kernel Linux, and so on.> > +@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},> > +where @code{x86_64-linux} can be replaced with @code{xi686-linux}> > for an > ^^^ stray 'x'

Pushed as f18d5d75979f5374962c03a8f3c266054a489e11 with this fix, acopyright line for me and an improved commit message.
Thank you!
Closed
?
Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send email to 41565@debbugs.gnu.org