Re: doc: Removing much of Binary Installation (was: Feedback of the GNU Guix manual)

[Matt]

 ---- On Wed, 06 Mar 2024 18:15:05 +0100  pelzflorian (Florian Pelz)  wrote ---
 > Thank you Matt for the suggested diff.

Thank you for taking the time to review it!

 > > - Places directions for 'guix-install.sh' after directions to use 
 > > distribution-specific package managers, giving preference to those simpler 
 > > install processes over the more manual 'guix-install.sh' process
 >
 > I don’t feel qualified to judge, but is this the preference?  Arch wiki 
 > advises against the Arch AUR package: “Therefore, after updating Guix once, 
 > the AUR advantage really turns into a disadvantage, as there will be many 
 > unnecessary files in the /usr file tree that are part of the Guix AUR 
 > package but that are never used by Guix anymore.  Therefore, consider using 
 > the manual installation.” [0]
 >
 > [0] https://wiki.archlinux.org/title/Guix

Good question, I wondered about this after I submitted.

The current manual has instructions for using the Debian, Ubuntu, and openSUSE 
package managers.  These instructions are given after the recommendation for 
=guix-install.sh= along with the transition:

"If you’re running Debian or a derivative such as Ubuntu, you can instead 
install the package..."

"Instead" means "in place of something previously mentioned."  So, as written, 
installing with =guix-install.sh= and installing with those specific package 
managers have equal levels of recommendation.

Since users of foreign systems are likely familiar with the corresponding 
foreign package managers, in addition to their use being one step versus four, 
I vote that they appear first.

This is good information about the situation with Arch.  Maybe this is why Arch 
isn't mentioned?

I wonder if we should have similar concerns about the Debian and openSUSE 
packages?

 > The reason of existence for these distribution packages is probably similar 
 > to the reason why the Binary Installation section exists.
 >
 > As for the suggested diff where much of Binary Installation gets removed,
 >
 > > -@item
 > > -@cindex substitutes, authorization thereof
 > > -To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
 > > -@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
 > > -authorize them:
 > > -
 > > -@example
 > > -# guix archive --authorize < \
 > > -     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
 > > -# guix archive --authorize < \
 > > -     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
 > > -@end example
 > > -
 > > -@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
 >
 > I disagree with this chunk.  This must stay.  Not enabling substitutes is an 
 > option in guix-install.sh and the Guix System installer.  Users might want 
 > to enable substitutes later on.

Excellent point.

I have updated the patch with the following:

- Add commas in appropriate places; after "For...Ubuntu-based systems", 
"Likewise", and the 'or' within the list of substitutes
- Remove ')' from after 'guix pull'
- Clarify that 'guix-install.sh' guides users through the steps.  Previously, 
it was unclear if the script ran without user input.
- Add the substitute server setup with the following changes:
  + Make explicit that the default for binary installations is to build 
everything
  + Change "for a discussion of reasons why one might want do disable 
substitutes" (note the 'do' typo) to "for a discussion why this is the 
default".  This aims to state it positively and encourage people to consider 
the reasons.
- Emphasize that the substitute authorization code is an example and may need 
modification

v02-refactor-binary-installation-section.diff
Description: Binary data