The Web manual situation is still needlessly confusing

  • Open
  • quality assurance status badge
Details
5 participants
  • Efraim Flashner
  • Felix Lechner
  • John Kehayias
  • Tobias Geerinckx-Rice
  • zimoun
Owner
unassigned
Submitted by
Tobias Geerinckx-Rice
Severity
normal
T
T
Tobias Geerinckx-Rice wrote on 4 Oct 2021 00:12
(name . Bug reports for GNU Guix)(address . bug-guix@gnu.org)
87ilydycps.fsf@nckx
Good evening Guix!

Nary a literal week goes by that someone doesn't post confusion
about this or that not being in ‘the manual’, where the manual
of the one actually shipped with their Guix.

The current solution is pointing them to
timer.

Instead:

‘devel’ version, and move the stable version to to a versioned

- Both manuals should have a gorgeous CSS box at the very top
clearly explaining their nature.

Kind regards,

T G-R
-----BEGIN PGP SIGNATURE-----

iIMEARYKACsWIQT12iAyS4c9C3o4dnINsP+IT1VteQUCYVosIA0cbWVAdG9iaWFz
LmdyAAoJEA2w/4hPVW15uOkA/jrtFZbSAv+twHdy3r7sIFZ3POJPJm+kQOahb2zk
VOgCAP4pumzKl5gVxn3VvAnFxhx9L37AC8LByXyHLqtCmv3/CA==
=yHWb
-----END PGP SIGNATURE-----

J
J
John Kehayias wrote on 4 Oct 2021 06:19
(name . 51000@debbugs.gnu.org)(address . 51000@debbugs.gnu.org)
susz0kTIZduiBm3i-bxbWioXd1-7m0GKVQJHBNMOHlb7o-yzcFfKyFS77l1TZEZuag_GtYjhtIJmZflLEbZNZbTMIYwNbX6Rgluz0O6KEuA=@protonmail.com
Hi everyone,

Definitely agree with needing this to be clearer than it is currently. As a new user I was a bit confused over the different manual versions on the website (which is still how I prefer to read the manual). As a side note, when searching online with Guix questions, I think I only see the 'stable' version come up in results.

We could perhaps be clearer in what is meant by the 'stable'/1.3.0 documentation. Seems this is mostly needed in preparing for installation (with the 1.3.0 image, not if building a current install image, of course) and during installation. Afterward, users will probably run a guix pull very soon (as in Getting Started, or as recommended by the guix command itself) and thus no longer be on the 1.3.0 manual. I'm not sure how best to communicate this on the website, but to me it is related to the next point:

I think we need something describing what we mean by Guix versions and releases, perhaps in the Intro and/or Getting Started sections (and on an About type page?). I was confused by this starting out, as I'm used to rolling distros like Arch (or, a long time ago, distros like Debian). While Guix is mostly 'rolling', we also have releases with certain package changes (like core-updates) and Guix changes. Just a simple description would I think help new users and give better context for the manual versions, however we label or make them available.

I'm happy to take a stab and making either of these points clearer, especially as one newer to Guix with these questions and assumptions nearer to mind.

John
E
E
Efraim Flashner wrote on 4 Oct 2021 08:31
Re: bug#51000: The Web manual situation is still needlessly confusing
(name . Tobias Geerinckx-Rice)(address . me@tobias.gr)(address . 51000@debbugs.gnu.org)
YVqf32IHhqhf/RDr@3900XT
On Mon, Oct 04, 2021 at 12:12:55AM +0200, Tobias Geerinckx-Rice via Bug reports for GNU Guix wrote:
Toggle quote (19 lines)
> Good evening Guix!
>
> Nary a literal week goes by that someone doesn't post confusion about this
> or that not being in ‘the manual’, where the manual turns out to be
> <https://guix.gnu.org/manual/en/guix.html> instead of the one actually
> shipped with their Guix.
>
> The current solution is pointing them to
> <https://guix.gnu.org/manual/devel/en/guix.html> and resetting the timer.
>
> Instead:
>
> - We should make <https://guix.gnu.org/manual/en/guix.html> the ‘devel’
> version, and move the stable version to to a versioned URL like
> <https://guix.gnu.org/manual/1.3.0/en/guix.html>.
>
> - Both manuals should have a gorgeous CSS box at the very top clearly
> explaining their nature.

Here is an untested patch against guix-maintenance to change the manual
locations. It doesn't take into account any changes needed in the
website itself to add a pointer to the 1.3.0 manual.


--
Efraim Flashner <efraim@flashner.co.il> ????? ?????
GPG key = A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted
From 5ae07d5d8db78d3f190a8780ba2eeaa5ce2c1be1 Mon Sep 17 00:00:00 2001
Message-Id: <5ae07d5d8db78d3f190a8780ba2eeaa5ce2c1be1.1633329044.git.efraim@flashner.co.il>
From: Efraim Flashner <efraim@flashner.co.il>
Date: Mon, 4 Oct 2021 09:28:20 +0300
Subject: [PATCH] hydra: Move guix-manual URLs.

This is likely to remove some ambiguity for which manual to use.

* hydra/berlin.scm (operating-system)[services]: Adjust
static-website-service-type services to change the locations of the
generated guix manuals.
* hydra/nginx/berlin.scm (guix.gnu.org-other-locations): Adjust
nginx-location-configuration for the manual locations.
---
hydra/berlin.scm | 7 ++++---
hydra/nginx/berlin.scm | 10 +++++-----
2 files changed, 9 insertions(+), 8 deletions(-)

Toggle diff (60 lines)
diff --git a/hydra/berlin.scm b/hydra/berlin.scm
index 146173b..44324cf 100644
--- a/hydra/berlin.scm
+++ b/hydra/berlin.scm
@@ -300,7 +300,8 @@ Happy hacking!\n"))
(static-web-site-configuration
(git-url "https://git.savannah.gnu.org/git/guix.git")
(git-ref '(branch . "version-1.3.0"))
- (directory "/srv/guix-manual")
+ (directory "/srv/guix-manual-1.3.0")
+ (cache-directory "guix-manual-1.3.0")
(build-file "doc/build.scm")
(environment-variables
'(("GUIX_MANUAL_VERSION" . "1.3.0")
@@ -310,7 +311,7 @@ Happy hacking!\n"))
(service static-web-site-service-type
(static-web-site-configuration
(git-url "https://git.savannah.gnu.org/git/guix.git")
- (directory "/srv/guix-manual-devel")
+ (directory "/srv/guix-manual")
;; XXX: Use a different cache directory to work around
;; the fact that (guix git) would use a same-named
@@ -318,7 +319,7 @@ Happy hacking!\n"))
;; above. Since both mcron jobs run at the same time,
;; they would end up using one branch or the other, in
;; a non-deterministic way.
- (cache-directory "guix-master-manual")
+ (cache-directory "guix-manual")
(build-file "doc/build.scm")
(environment-variables
diff --git a/hydra/nginx/berlin.scm b/hydra/nginx/berlin.scm
index 44ff28e..14a94fe 100644
--- a/hydra/nginx/berlin.scm
+++ b/hydra/nginx/berlin.scm
@@ -768,14 +768,14 @@ PUBLISH-URL."
"alias /srv/guix.gnu.org/static;")))
;; These rules take precedence over the '.pdf' and '.html' rules below.
- (nginx-location-configuration
- (uri "~ /manual/devel/(.*)$")
- (body (list "expires 4h;"
- "alias /srv/guix-manual-devel/$1;")))
(nginx-location-configuration
(uri "~ /manual/(.*)$")
- (body (list "expires 1d;"
+ (body (list "expires 4h;"
"alias /srv/guix-manual/$1;")))
+ (nginx-location-configuration
+ (uri "~ /manual/1.3.0/(.*)$")
+ (body (list "expires 1d;"
+ "alias /srv/guix-manual-1.3.0/$1;")))
(nginx-location-configuration
(uri "~ /cookbook/(.*)$")
(body (list "expires 4h;"

base-commit: 3069d5e8c8b00162af1d6e7705c8d235f2e3b56a
--
2.33.0
-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAmFan98ACgkQQarn3Mo9
g1FWHQ/7BSr3r7g4nYE0ihSWgPLZAWHZDN1jWUvMkQjzmMR0UMrm2++9oRtv/6sa
td19oK8hHxXoGVkVlshsGBmP6Oe0KLnvwOkNprMRh/lBspqt00F3t7g2cBjiitGX
sV42yiBCpzUyBi5jaBSJcH6uRpPC9x+c74jPqouvsnrcm0TIL0zStAF15Re/y5gk
M5vN5pryorSvfzW7WwOFV+xOoiRlZsqNI3AUuxrvCAf8ecTUqJYJbblMj9ZnRhz2
yqFEFSg63UPbpbRyoADxyF+yRrcc81S5CtURBRtgLtoKpB0OsAnstWrnTDsekmqC
4Ce2nBPyS5SfAr0YlLA9EL7gpibqs83BKH8g5Kif8in3TmmQqAx6pZjAbMjK0wCg
UU/T8MLsf0D9zL2ll0YZlCbGhaX6/gsHZL4SztyJytRSSKNUbj60O1FSevK2a3iI
+ZZ1aE7YRgIgHCOCAV+9rPkdJUn9jaQQzVQN3bgSy18/xWWZiG5KUZRYVIy3umaR
Rrkl8nFPa2paStQIck8UhNvSX+RO58kYEruytS3JULsAZesqOmqYicOgOSOJ3oDP
2prWGGPBrjb9LK5haU+H4G+svK4tMBHqoP4DNS3gjoC2C75iGvZxFQyDz8SNEbrv
XVUitay3kfC9AclPyLnXbmitt8Q5ilRaE4Jte75xU+2qUuw2Yxo=
=o7iz
-----END PGP SIGNATURE-----


Z
Z
zimoun wrote on 4 Oct 2021 08:58
864k9xff98.fsf@gmail.com
Hi,

On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice via Bug reports for GNU Guix <bug-guix@gnu.org> wrote:

Toggle quote (7 lines)
> ‘devel’ version, and move the stable version to to a versioned
> URL like <https://guix.gnu.org/manual/1.3.0/en/guix.html>.
>
> - Both manuals should have a gorgeous CSS box at the very top
> clearly explaining their nature.

Good idea. :-)

Cheers,
simon
F
F
Felix Lechner wrote on 22 May 2023 03:59
Please drop web manuals for released versions
(address . 51000@debbugs.gnu.org)
CAFHYt549HO9d1W_=pZoMEQyQZS1iE25AAk2JUcoYKpmQmqY2ww@mail.gmail.com
Hi,

Toggle quote (2 lines)
> Here is an untested patch

Guix suffers from an unhelpful anachronism that search engines
consistently rank historical versions of the Reference Manual [1]
above the latest edition. [2] It's probably because third-parties link
to historical versions more often than they do to the current version.
Please drop the historical versions.

Historical versions are irrelevant for current users and should only
be shipped on installation media. The current edition is only a 'guix
pull' away—a command we encourage widely.

As an example for the grave but unnecessary confusion, the manual
generally perceived as official lists the incorrect email address
guix-patches@debbugs.gnu.org as a way to contribute to Guix. [3]

Let's not put stumbling blocks before the blind, please. I beg you,
let's think of our fellow human beings. Thanks!

Kind regards,
Felix Lechner

S
S
Simon Tournier wrote on 27 Sep 2023 11:26
Re: bug#51000: The Web manual situation is still needlessly confusing
(name . Tobias Geerinckx-Rice)(address . me@tobias.gr)(address . 51000@debbugs.gnu.org)
86pm24hspt.fsf@gmail.com
Hi,

On Mon, 04 Oct 2021 at 00:12, Tobias Geerinckx-Rice <me@tobias.gr> wrote:

Toggle quote (6 lines)
> Instead:
>
> - We should make <https://guix.gnu.org/manual/en/guix.html> the ‘devel’
> version, and move the stable version to to a versioned URL like
> <https://guix.gnu.org/manual/1.3.0/en/guix.html>.

Considering this hypothetical change, please note issue as reported by:

bug#66189: [gnu.org #1975364] Broken link in Guix manual.
"Therese Godefroy via RT" <webmasters-comment@gnu.org>
Mon, 25 Sep 2023 04:05:43 -0400
id:rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0@rt.gnu.org

Quoting:

> in
> is broken.

Yes, the link is automatically generated by,

@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}

For instance, today the last manual correspond to Guix revision faf3ca
and the link in this development manual reads,


To my knowledge, no one is pushing to FTP all these images.

Cheers,
simon
?
Your comment

Commenting via the web interface is currently disabled.

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

To respond to this issue using the mumi CLI, first switch to it
mumi current 51000
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch