On Ludo's recommendation, I'm submitting this patch set. It fixes issues of
confusion raised in feedback on the manual. See this discussion:
https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html
I will reply to points raised in that thread here and have CC'd people who have
previously shown interest.
---- On Sat, 16 Mar 2024 15:05:13 +0100 pelzflorian (Florian Pelz) wrote ---
> 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.
See attached.
> >> > Matt matt@excalamus.com> writes:
> >> > +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.)
Thank you for your feedback. Reading the suggested changes again with fresh
eyes, I think I now see your concerns. I see you raise two concerns:
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..."
This is based off the Section 1: Introduction which calls Guix System a
distribution, "...or you can use [Guix] as a standalone operating system
distribution, 'Guix System'" and Section 1.2: GNU Distribution which says, "we
refer to the standalone distribution as Guix System."
I'm not sure if I've responded to all of your concerns here. Have I missed any?
> 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.
You say, "I would not address Hurd *here*" which implies it's valid to address
Hurd elsewhere. What's the criteria for deciding whether to address Hurd and
how are the reasons I inadequate?
Here are the reasons I gave previously for why we should continue documenting
Hurd support:
- The manual already documents Hurd support
- Core developers have published the statement, "running on the Hurd was always
a goal for Guix"
- Guix can run on Hurd
- Code exists in the main branch for Hurd support
> > No mention of 'guix-install.sh' is made on that page.
>
> I wanted to give an example what I mean, not a suggestion.
I don't understand what you mean then. The exchange quoted here was part of
the "Guix" versus "Guix System" discussion above. Have the updates I've made
there addressed this point?
> >> 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.
What I ask myself is, "Is this a problem or a detail?" I know that probably
sounds stupid. However, the question is whether Guix can be installed on Hurd.
The answer is, Guix can be installed on Hurd. Everything else, therefore,
including guile-fibers or which Hurd, while important in other contexts, is not
important to this issue.
> > […]
> >> >> 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.
Ensuring fairness is everyone's responsiblity. I respect you for accepting
this and speaking up. I understand that you're concerned about proper
attribution.
AFAIK, Ubuntu gives clear credit to Debian. For example, the Ubuntu website
says, "Debian is the rock on which Ubuntu is built."
https://ubuntu.com/community/governance/debian They give similarly clear
statements elsewhere, too.
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. That adds value also deserving of credit
and which is separate from the value added by Debian. Also, we must not
overlook that Debian is itself built upon the work of others, many of whom are
not associated with Debian and may not even be aware Debian packages or
distributes their work. This is all possible and just because of Free
Software. One of the four freedoms is the right to distribute unmodified
copies. It depends on the license terms, or lack thereof, whether explicit
credit needs to be given. I've not heard of Ubuntu violating any license terms
or other legal restrictions requiring attribution.
Am I missing something?
> >> Better not change the wording? I believe enabling substitutes is not
> >> the default.
You are correct! I misunderstood the current manual and wrote that
misunderstanding into my suggested changes. I have updated the suggested
changes. Thank you for catching this!
> 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.
The term "substitute" is given in the Section 1 Introduction. However, since
it's jargon and this is a different chapter, I think it prudent to repeat the
definition again as a reminder.
The 'guix-install.sh' script uses the term "pre-built package binaries" instead
of "substitute":
"Permit downloading pre-built package binaries from the project's build farms?
[Y/n]"
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.
> Otherwise LGTM. Could you send another diff?
Gladly. I reviewed our past messages and tried to document all the relevant
changes in the commit messages.
0001-doc-Simplify-installation-instructions.patch
Description: Binary data
--- End Message ---