The Web manual situation is still needlessly confusing

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.

Kind regards,

T G-R

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

On Mon, Oct 04, 2021 at 12:12:55AM +0200, Tobias Geerinckx-Rice via Bug reports for GNU Guix wrote:

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>

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

static-website-service-type services to change the locations of the

generated guix manuals.

nginx-location-configuration for the manual locations.

---

hydra/berlin.scm | 7 ++++---

hydra/nginx/berlin.scm | 10 +++++-----

2 files changed, 9 insertions(+), 8 deletions(-)

Hi,

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

Good idea. :-)

Cheers,

simon

Hi,

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

[1] https://guix.gnu.org/manual/en/guix.html

[2] https://guix.gnu.org/en/manual/devel/en/guix.html

[3] https://guix.gnu.org/en/manual/en/guix.html#Multiple-Patches-1

Hi,

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

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

https://issues.guix.gnu.org//66189

https://issues.guix.gnu.org/msgid/rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0@rt.gnu.org

https://yhetil.org/guix/rt-4.2.16-14-g9a593ee-17542-1695629143-1144.1975364-8-0@rt.gnu.org

Quoting:

> https://ftp.gnu.org/gnu/guix/guix-system-vm-image-e5f7c14.x86_64-linux.qcow2

> in

> https://guix.gnu.org/manual/devel/en/html_node/Running-Guix-in-a-VM.html

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

https://ftp.gnu.org/gnu/guix/guix-system-vm-image-fafd3ca.x86_64-linux.qcow2

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

Cheers,

simon