Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation)

["pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de>]

Hello Matt and thank you for your precise wording.  You have made clear
the differences:

Matt <matt@excalamus.com> writes:
> There are several actions which we have deferred and other topics
> which still need to be addressed, such as those raised by Vagrant and
> Suhail.  My hope is to 1) resolve and merge this immediate patch, as
> we appear to be converging on a consensus, 2) discuss how we could
> better handle documentation changes than how I've handled them here
> (that is, in one ever evolving diff),

I think the diff was quite appropriate.  You could make a patch via “git
format-patch” or “git send-email”, which would include a commit message
and which could include a move of sections 2.2 and 2.3 to the
contributing.texi.  But it is not necessary for documentation changes.


> 3) compile a list of deferred
> actions, 4) compile a list of deferred topics, and 5) address points 3
> and 4 according to 2.
>
> ---- On Mon, 11 Mar 2024 16:54:01 +0100  pelzflorian (Florian Pelz)  wrote ---
>> Yes, however the removal means that we should move the sections
>>
>> * 2.2 Requirements
>> * 2.3 Running the Test Suite
>>
>> to the Contributing manual in doc/contributing.texi.  WDYT?  You said,
>> it could be a separate discussion, but in my opinion it would be part of
>> the same patch.
>
> I was thinking of the opposite, of moving "Building from Git" into
> Installation.  What you say makes more sense and I agree.  Since the
> suggested patch is already quite complex, I have not added moving
> Sections 2.2 and 2.3 to the changes.  I propose we make the move in a
> separate commit.

Yes, it should probably be a separate commit, to make it possible to
revert it separately.


>> > +@cindex foreign distro
>> > +@cindex Guix System
>>
>> “@cindex Guix System” is inappropriate, because instructions on Guix
>> System are not here.
>
> Removed.  Good catch!
>
>> > +You can install the Guix package management tool on top of an existing
>> > +GNU/Linux or GNU/Hurd system@footnote{Currently only the Linux-libre
>> > +kernel is fully supported. […]
>>
>> No.
>>
>> First of all, using guix-install.sh as per your instructions, one
>> installs the Guix distribution *and* package management tool.  Either
>> say “You can install the Guix package management tool and distribution”
>> or “You can install Guix”.
>
> I'm afraid I don't follow.  Where do you see the suggested changes
> confusing the installation process for Guix as a distribution and Guix
> as a package management tool?
>
> The sentence you quote is the suggested first sentence for the Chapter
> 2: Installation.  The complete sentence reads,
>
> "You can install the Guix package management tool on top of an
> existing GNU/Linux or GNU/Hurd system(1), referred to as a "foreign
> distro", or as a standalone operating system distribution, the "Guix
> System"."
>
> It literally says Guix is a package manager or a distribution.

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.  Guix System is not a distribution in this sense; Guix is
the distribution.  I am aware that some people expect distribution to
mean a self-sufficient operating system, but we should not subscribe to
one side of terminology.  (Actually, the term operating system is
complex as well, for example GNU is an operating system and the people
from Robot Operating System call ROS an operating system.)

I would not address Hurd here at all.  Hurd support would be important
and is promising, but documentation for it should come after it works on
more than a Childhurd.



> No
> mention of 'guix-install.sh' is made on that page.

I wanted to give an example what I mean, not a suggestion.


>
> The current "introduction" to Chapter 2: Installation is this:
>
> "Note: We recommend the use of this <shell installer script> to
> install Guix on top of a running GNU/Linux system, thereafter called a
> foreign distro. The script automates the download, installation, and
> initial configuration of Guix. It should be run as the root user."
>
> https://guix.gnu.org/en/manual/devel/en/html_node/Installation.html
>
> Maybe the diff didn't apply correctly?  Maybe it's confusing how the
> Texinfo syntax puts the footnote markup in the middle of the source
> sentence, even though footnotes render at the bottom of the page?
>
>> Next, I believe Guix cannot currently be built on existing GNU/Hurd
>> systems, because guile-fibers does not work.  I do not really know
>> enough, but I would not mention Hurd support.
>
> The are two issues here, what is said and what should be said.
>
> Regarding what is said, the section we're talking about is for
> installing not building.  You *can* install the Guix package
> management tool on top of an existing GNU/Hurd system.

Probably a guix pack of the guix package would run, but Debian’s
guile-fibers is not accepted, if I don’t misunderstand.


> […]
>> >> Similarly, IMO the nuances are more appropriate in the old wording
>> >> “For Debian or a derivative such as Ubuntu,” rather than your change
>> >> “For Debian and Ubuntu-based systems”.
>> >
>> > The current wording is, "If you're running Debian or a derivative such
>> > as Ubuntu..."  None of the suggested changes include the wording you
>> > give.
>> >
>> > What are the nuances?  If they matter, we should probably make them explicit.
>>
>> The nuance is that Ubuntu is a derivative of Debian.  It can be
>> bootstrapped with Debian’s dpkg, although I did not follow a recent
>> e-mail thread on how to do this from a Guix-provided dpkg.
>
> Unless there's something about this nuance which directly affects the
> installation process, I don't think the distinction warrants mention.
>
> I opted to ignore the distinction and use "Debian and Ubuntu-based
> systems" because many popular distros, such as Ubuntu, Linux Mint,
> Zorin OS, Elementary OS, Linux Lite, and Pop!_OS, are known for being
> "based on Ubuntu."  The relevant information for users of these
> systems is not that they're derivatives of Debian, it's that this is
> the installation process for such systems.

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.


>> > +@quotation Note
>> > +By default, binary installations of Guix build @emph{everything} from
>> > +source.  This makes each installation and upgrade very expensive.
>> > +@xref{On Trusting Binaries} for a discussion of why this is the default.
>> > […]
>> > -
>> > -@quotation Note
>> > -If you do not enable substitutes, Guix will end up building
>> > -@emph{everything} from source on your machine, making each installation
>> > -and upgrade very expensive.  @xref{On Trusting Binaries}, for a
>> > -discussion of reasons why one might want do disable substitutes.
>> >  @end quotation
>>
>> Better not change the wording?  I believe enabling substitutes is not
>> the default.
>
> My assumption is that the vast majority of readers are not installing
> Guix on distros whose default is to compile from source.  The concept
> and jargon of substitutes, let alone the idea of compiling from
> source, is likely completely unknown to most readers.  Readers likely
> expect, what we would call, substitutes to be enabled.
>
> As far as I understand, the default behavior is opposite what most
> readers would expect: substitutes are *not* enabled by default for
> binary installations of Guix.
>
> The suggested wording avoids the jargon of "substitutes" in favor of
> simpler language which directly addresses what the reader likely cares
> about: the default Guix behavior is to compile from source which takes
> a long time.  It also frames the discussion of "On Trusting Binaries"
> from the perspective of "the expensive default was decided by careful
> consideration."  The current wording, "why one might want to disable
> substitutes," involves jargon (substitutes) and a negative (disable)
> which requires understanding what a substitute is, what the default
> is, and whether "disabling" is contrary to the default.  That
> complexity is unnecessary, as I believe the suggested changes
> demonstrate.

I just tried now and I had not expected the install script to say:

Permit downloading pre-built package binaries from the project's build
farms? [Y/n]

Getting substitutes unexpectedly is the default (also unlike what you
write) and users can complete the installation without knowing the term,
but they do get asked.

I agree with you now that the wording can be simplified, except it must
be rewritten to that disabling substitutes is an option that is not the
default.



>
> I think a valid critique of the suggested changes is "why say 'very
> expensive' instead of 'takes a long time'?"  The suggestion uses the
> phrase "very expensive" instead of "takes a long time" because 1)
> "very expensive" is the current language and 2) wall time is only one
> of several expenses; others are energy and CPU cycles.  This is a
> situation where I think it's okay to be non-specific.  The point is
> "the default behavior may seem undesirable" and the word "expensive"
> is typically considered undesirable.

I agree that “expensive” is sufficiently understandable.


>> IMHO The discussion about whether Upgrading Guix should recommend to
>> edit the systemd service of the Debian guix package is for a
>> separate second patch.
>
> Agreed.


Otherwise LGTM.  Could you send another diff?  Would a commit message
like this be okay:

doc: Simplify installation instructions.

* doc/guix.texi (Installation): Direct readers towards the installation
script.  Remove superfluous commentary.


Regards,
Florian