[bug#69977] [PATCH] doc: doc-Simplify installation instructions

[pelzflorian (Florian Pelz)]

Hi Matt, mostly looks good to me.

Matt <matt@excalamus.com> writes:
>---- On Sat, 16 Mar 2024 15:05:13 +0100  pelzflorian (Florian Pelz)  wrote ---
>>>> Either
>>>> say “You can install the Guix package management tool and distribution”
>>>> or “You can install Guix”.
>>> You can install the Guix package management tool on top of an
>> Precisely this terminology is the issue.  Nix is a package manager;
>> Nixpkgs is a distribution.  For Guix, Guix is both a package manager and
>> distribution.[…]
> You can install the package management tool Guix on top of an

Looking at it with fresh eyes myself, your wording is OK.  Even though I
still think you have a misunderstanding of the term distribution, there
is no reason for me to insist the term distribution must be explained
here.


> 1. A clear distinction between Guix and the Guix System was not made
>
> I have split the suggested sentence, whose current version (v04) is
> given above, into two. One sentence has the subject of "the package
> management tool Guix" and the other "the Guix System".  You were
> correct in observing that the suggestion confused the meaning of
> "Guix".  Good catch!
>
> 2. The use of "operating system" is inappropriate
>
> The v04 suggestion used "operating system" only because the current
> manual (bf53001) says in Section 1: Introduction, "If, instead, you
> want to install the complete GNU operating system..." before linking
> to "...how to install Guix System on a machine."
>
> I have changed the patch set to say,
>
> "If, instead, you want to install the complete, standalone GNU system
> distribution..."

I like that you added the word “standalone”.  But I prefer the old
ordering where this sentence comes after “This section +is concerned
with the installation of Guix on a foreign distro.”


Looking at how to make an install tarball for Hurd, I noticed that you
removed these important instructions for building the tarball:

> -The binary installation tarball can be (re)produced and verified simply
> -by running the following command in the Guix source tree:
> -
> -@example
> -make guix-binary.@var{system}.tar.xz
> -@end example
> -
> -@noindent
> -...@: which, in turn, runs:
> -
> -@example
> -guix pack -s @var{system} --localstatedir \
> -  --profile-name=current-guix guix
> -@end example
> -
> -@xref{Invoking guix pack}, for more info on this handy tool.
> -
>  @node Requirements
>  @section Requirements

The tarball is needed by guix-install.sh, so the instructions for
building it should stay, because it is what your recommended
guix-install.sh uses.  Please keep the instructions for this reason.

No such tarball is released for GNU Hurd yet, and when I tried to build
it for GNU Hurd, it fails, because guile-git cannot be built.  Note that
it is possible to instead cross-compile a pack for Hurd, using
“--target=i586-pc-gnu” instead of “-s i586-gnu”, even though I have not
tested if it can be used.  Also note that Hurd is quite crashy.  Better
just not mention it here.



>> Ubuntu should not get the credits for what Debian is doing.  The current
>> wording “Debian or a derivative such as Ubuntu” is fairer and equally
>> clear.
> […]
> My understanding is that many distros call themselves "based on
> Ubuntu", "built upon Ubuntu", or list Ubuntu as "upstream" because
> they use packages that are, at minimum, distributed by Ubuntu.

I believe “Debian or a derivative such as Ubuntu” is a better wording
than “Debian and Ubuntu-based systems”, despite some Ubuntu derivatives
not mentioning Debian or users being aware only of Ubuntu.


> I propose the following.  The intent is to match the script's language
> so that readers may understand the consequences of a 'Y' or 'n'
> choice.  The best place to do this would be in the prompt.  However,
> documenting consequences in the manual seems a reasonable compromise
> which makes the prompt concise and allows us to link to the "On
> Trusting Binaries" section.
>
> +By default, 'guix-install.sh' will configure Guix to download pre-built
> +package binaries, called @dfn{substitutes} (@pxref{Substitutes}), from
> +the project's build farms.  If you choose not to permit this, Guix will
> +build @emph{everything} from source, making each installation and
> +upgrade very expensive.  @xref{On Trusting Binaries} for a discussion of
> +why you may want to build packages from source.

Good!


> * doc/guix.texi (Installation):
> - Move the definition of "foreign distro" out of quotation
> - Repeat overwrite warning
> - Remove superfluous commentary
> 
> * doc/guix.texi (Binary Installation):
> - Clarify that installing on a foreign distro has two methods: using
>   packaged binaries and building from source
> - Add cross reference to "Building from Git"
> - Move the foreign distro installation instructions out of quotation
> - Move directions for 'guix-install.sh' after instructions to use
>   distribution-specific package managers
> - Specify "distributions" as "GNU/Linux distributions"
> - Add GnuPG as a requirement for 'guix-install.sh'
> - Add comma after "Likewise"

I think this comma (“Likewise, on openSUSE:”) should not be added, since
it does not improve understanding, but it is not really important.


> - Remove redundant instructions to use 'guix-install.sh'
> - Split the requirements between system requirements for binary
>   installations, GNU/Linux or GNU/Hurd, and requirements for running
>   'guix-install.sh'
> - Clarify that 'guix-install.sh' guides users through the steps
> - Summarize the steps 'guix-install.sh' follows rather than try to
>   detail them
> - Make explicit that the 'guix-install.sh' default is to download
>   substitutes
> - Emphasize that the substitute authorization code is an example and
>   may need modification

Well these details are good for reviewers, but the commit message is
intended for readers of “git log”.  Better keep it short like the other
commits you can view with “cd ~/src/guix; git log doc”.

Could you send another patch without mentioning the Hurd, or do you see
a way to actually run Guix on a foreign GNU/Hurd distribution that you
can document?

Regards,
Florian