Feedback of the GNU Guix manual

Feedback of the GNU Guix manual

[Christian Miller]

Hello,

I read through the GNU Guix manual on revision
ee7c9d254117fa470686210ad2ef5e7f1ba4fefc with Emacs in TTY mode.

As a beginner, the manual was helpful and I learned lot's of stuff.
Though it felt heartless.  No consistency and sometimes the structure
is confusing (especially the contributing part, since it tries to get
GNU Guix System and GNU Guix under one section and it was kinda
confusing for me).

Overall it was a better experience than reading the Emacs manual.  The
Emacs manual may have a better consistent style but it was hard to
understand.  Felt like it assumed people would know stuff which I did
not do.

It seems that there is no style guide.  Sometimes default values are
mentioned and sometimes not.  Also some use uppercase and other use
lowercase for type of variable.  There is also Scheme code which is
most of the time in the old style notation.  For me as a beginner,
this was confusing.

I will mention lot's of style issues since at that time I did not know
it is in such a bad state.

Here are some things I noticed:

** Binary installation L73
Guix system should be Guix System

** Binary Installation L88 and L95
~root is weird.  Should be root or simply ~ for the user profile which
would be root as root user.

** 2.4 Setting up the deamon
Seems like an issue with info.  Have seen this in the Emacs manual as
well.  There is also sometimes see see (doc)

L15 See also see Substitutes.

** 3.7 After System Installation
L27 Libera_Chat, why the underscore.  It is colored as well for me so
I guess this is a special char.  Should be anways just Libera Chat

** 3.8 Installing Guix in a Virtual Machine
L25 in an vm should be in a vm

** 6.4 L60 packages should be package
The outputs of a packages are listed in the third column of the output
of ‘guix package --list-available’ (*note Invoking guix package::).

** 6.7 L37 true for Guix System as well?
   The result of running ‘guix pull’ is a “profile” available under
‘~/.config/guix/current’ containing the latest Guix.  Thus, make sure to
add it to the beginning of your search path so that you use the latest
version, and similarly for the Info manual (*note Documentation::):

     export PATH="$HOME/.config/guix/current/bin:$PATH"
     export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
     
** 6.8 Maybe just mention the actual movie for people that never have seen or heard of it
   (1) If you don’t know what a DeLorean is, consider traveling back to
the 1980’s. (Back to the Future (1985))

** 7.1 should be variant-packages (not sure anymore, those notices I made are several weeks old)
The output of ‘guix describe’ above shows that we’re now running
Generation 19 and that it includes both Guix and packages from the
‘variant-personal-packages’ channel (*note Invoking guix describe::).

** 8.1
See https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?h=v6.7&id=6eb3c3d0a52dca337e327ae8868ca1f44a712e02

     You may pass any ‘guix shell’ option, but there’s one caveat: the
     Linux kernel has a limit of 127 bytes on shebang length.

** 8.1
this is done automatically on Guix System.  Should be mentioned?

   ‘guix shell’ defines the ‘GUIX_ENVIRONMENT’ variable in the shell it
spawns; its value is the file name of the profile of this environment.
This allows users to, say, define a specific prompt for development
environments in their ‘.bashrc’ (*note (bash)Bash Startup Files::):

     if [ -n "$GUIX_ENVIRONMENT" ]
     then
         export PS1="\u@\h \w [dev]\$ "
     fi

... or to browse the profile:

     $ ls "$GUIX_ENVIRONMENT/bin"
     
** 8.2
Time to remove?

     Being deprecated, ‘guix environment’ is slated for eventual
     removal, but the Guix project is committed to keeping it until May
     1st, 2023.  Please get in touch with us at <guix-devel@gnu.org> if
     you would like to discuss it.
     
** 8.3
L47 they they
   What if the recipient of your pack does not have root privileges on
their machine, and thus cannot unpack it in the root file system?  In
that case, you will want to use the ‘--relocatable’ option (see below).
This option produces “relocatable binaries”, meaning they they can be
placed anywhere in the file system hierarchy: in the example above,
users can unpack your tarball in their home directory and directly run

** 9
missing application word for apis.

GNU Guix provides several Scheme programming interfaces (APIs) to
define, build, and query packages.  The first interface allows users to
write high-level package definitions.  These definitions refer to
familiar packaging concepts, such as the name and version of a package,
its build system, and its dependencies.  These definitions can then be
turned into concrete build actions.

** 9.5 build system
texlive-build-system

located in located in

     It also generates font metrics (i.e., ‘.tfm’ files) out of Metafont
     files whenever possible.  Likewise, it can also create TeX formats
     (i.e., ‘.fmt’ files) listed in the ‘#:create-formats’ argument, and
     generate a symbolic link from ‘bin/’ directory to any script
     located in located in ‘texmf-dist/scripts/’, provided its file name
     is listed in ‘#:link-scripts’ argument.
     
** 10.1.3 bottom
shouldn't this be on "a" instead of "an" x86 machine?

     So for instance, imagine you want to see the build log of GDB on
     ‘aarch64’, but you are actually on an ‘x86_64’ machine:

          $ guix build --log-file gdb -s aarch64-linux
          https://ci.guix.gnu.org/log/...-gdb-7.10
          
** 10.1.4 L38
remove word "run" for easier understanding

   In such cases, you may need to run inspect the build process from
within a container similar to the one the build daemon creates:

** 10.3
Someone on IRC mentioned that using guix downloaded could be abused as
of it sees (the website) the user agent and returns a different source.

** 10.4 L141
command command

     The command command below imports metadata for the Cairo R package:
     
** 10.4 L195
command command
     The command command below imports metadata for the ‘fontspec’ TeX
     package:
     
** 10.4 L373
package repository urls is mentioned twice

‘elm’
     Import metadata from the Elm package repository
     package.elm-lang.org (https://package.elm-lang.org), as in this
     example:
     
** 10.4 L433
package repo url mentioned twice (name missing)

‘go’
     Import metadata for a Go module using proxy.golang.org
     (https://proxy.golang.org).

** 10.9 L59
it possible it to

This makes it possible it to profile disk usage of store items that are
not even on disk, only available remotely.

** 10.16 L34
guix shell not guix environment

   In this example we see that ‘guix-daemon’ has three clients: ‘guix
environment’, ‘guix publish’, and the Cuirass continuous integration

** Emacs info next using space
On chapter "Conecpt Index" at the bottom, it should jump to the next
node called "Programming Index" but instead it goes to "12.12 Name
Service Switch L21"

** 12.1
mention that generations are linear just like guix package roll-back
did it.

   Although the ‘guix system reconfigure’ command will not modify
previous generations, you must take care when the current generation is
not the latest (e.g., after invoking ‘guix system roll-back’), since the
operation might overwrite a later generation (*note Invoking guix
system::).

** 12.9.1 Base Services L933
Here is AN example sounds better

     Here is example of switching from ‘mingetty-service-type’ to
     ‘greetd-service-type’, and how different terminals could be:

** 12.9.1 Base Services L561
This is a list but it is interpreted as a footnotes

 Suppose you would like to fetch substitutes from
          ‘guix.example.org’ in addition to ‘ci.guix.gnu.org’.  You will
          need to do two things: (1) add ‘guix.example.org’ to
          ‘substitute-urls’, and (2) authorize its signing key, having

** 12.9.4 Networking Setup L283
It's value must be a [...]

 -- Variable: connman-service-type
     This is the service type to run Connman (https://01.org/connman), a
     network connection manager.

     Its value must be an ‘connman-configuration’ record as in this
     example:
     
** 12.9.5 Networking Services L89
why the #?

     ‘driver’ (default: ‘"nl80211"’)
          The driver interface type.  ‘"nl80211"’ is used with all Linux
          mac80211 drivers.  Use ‘"none"’ if building hostapd as a
          standalone RADIUS server that does # not control any
          wireless/wired driver.
          
** 12.9.5 L109
Uppercase for new sentences (rearange text, make it look more clean)

same for nftables as well

     This is the service type to set up an iptables configuration.
     iptables is a packet filtering framework supported by the Linux
     
** 12.9.5
normally this is always the first entry and not the last

     ‘ntp’ (default: ‘ntp’)
          The NTP package to use.

** 12.9.5 233
gnu is not highlighted as URL

            (constraint-from '("www.gnu.org"))
            (constraints-from '("https://www.google.com/"))))
            
** 12.9.5 L611
default are in uppercase as #F instead of #f.

same for webssh

** 12.9.5 L1078
[...] for the configuration of Avahi.

 -- Data Type: avahi-configuration
     Data type representation the configuration for Avahi.

** 12.9.5 L1216
adynamic? probably meant a dynamic

     ‘autoconf?’ (default: ‘#f’)
          Whether to use automatic mode.  Enabling it makes Yggdrasil
          use adynamic IP and peer with IPv6 neighbors.

is HJSON correct?
	  
     ‘config-file’ (default: ‘"/etc/yggdrasil-private.conf"’)
          What HJSON file to load sensitive data from.  This is where

** 12.9.5
expect gnu lsh, there is no type information

** 12.9.7 x window
double space


"  -SecurityTypes None"))


** 12.9.9 Desktop Services L694
quote in value
             • ‘"15c0a148-c273-11ea-b3de-0242ac130004’: BlueZ
               Experimental LL privacy,
               
** 12.9.10 Sound Services L26
uppercase letter instead of lowercase

     ‘pulseaudio?’ (default: #T)

** 12.9.11 L79
Which other methods do exist?

     ‘method’ (default: ‘'store’)
          Indexing method for ‘guix locate’.  The default value,
          ‘'store’, yields a more complete database but is relatively
          expensive in terms of CPU and input/output.
          
** 12.9.12 L37
missing default

     ‘postgresql’
          PostgreSQL package to use for the service.

** 12.9.13 L1275
valid values are passwd and static but the default is someting else.
How?

           -- getmail-retriever-configuration parameter: string type
               The type of mail retriever to use.  Valid values include
               ‘passwd’ and ‘static’.

               Defaults to ‘"SimpleIMAPSSLRetriever"’.
               
** 12.9.13 Dovecot
Dovecot has many entries "same as [...]" "defaults to [...]".  I don't
know if this is good since if one would change the defaults of a
variable the docs would be wrong (except it does it automatically).

** 12.9.14 L379
is just AN empty string

   For example, if your ‘prosody.cfg.lua’ is just the empty string, you
could instantiate a prosody service like this:

** 12.9.19 LDAP L207
connection weird symbol.

 -- nslcd-configuration parameter: maybe-number idle-timelimit
     Specifies the period if inactivity (in seconds) after which the
     con‐ nection to the LDAP server will be closed.  The default is not
     to time out connections.

     Defaults to ‘disabled’.
     
** 12.9.19 LDAP L237
authentication weird symbol

 -- nslcd-configuration parameter: maybe-string tls-cacertdir
     Specifies the directory containing X.509 certificates for peer
     authen‐ tication.  This parameter is ignored when using GnuTLS.

     Defaults to ‘disabled’.
     
** 12.9.19 LDAP L434
Normally booleans are #f or #t

     ‘selinux’ (default: ‘#false’) (type: boolean)
          Enables SELinux detection and integration during the
          installation of this instance.  If set to ‘#true’, ‘dscreate’
          auto-detects whether SELinux is enabled.
          
** 12.9.20 Web Services L29 and L155
formatting of string-join elements

          (simple-service 'www.example.com-server httpd-service-type
                          (list
                            (httpd-virtualhost
                              "*:80"
                              (list (string-join '("ServerName www.example.com"
                                                    "DocumentRoot /srv/http/www.example.com")
                                                 "\n")))))
                                                 
** 12.9.20 Web Services NGINX
Sometimes it is called NGinx.  But isn't it either NGINX or nginx?  It
was also named as Nginx.  Sometimes it is 'nginx'.

** 12.9.20 Web Services Mumi
#true instead of #t

     ‘mailer?’ (default: ‘#true’)
          Whether to enable or disable the mailer component.
** 12.9.23 VNC Services L125
should be #t instead of #true in the description.

     ‘localhost?’ (default: ‘#t’) (type: boolean)
          Only allow connections from the same machine.  It is set to
          #true by default for security, which means SSH or another
          secure means should be used to expose the remote port.
          
** 12.9.27 Continous Integretation L135
before argument is a weird symbol.

   To enable this build mode a ‘cuirass-remote-server-configuration’
record must be passed as ‘remote-server’ argument of the
‘cuirass-configuration’ record.  The
‘cuirass-remote-server-configuration’ record is described below.
** 12.9.29 Audio Services L75
two different variables that do the same thing.

     ‘music-directory’ (type: maybe-string)
          The directory to scan for music files.

     ‘music-dir’ (type: maybe-string)
          The directory to scan for music files.

     ‘playlist-directory’ (type: maybe-string)
          The directory to store playlists.

     ‘playlist-dir’ (type: maybe-string)
          The directory to store playlists.

** 12.9.29 Audio Services L289
missing new line

     ‘user’ (default: ‘%mympd-user’) (type: user-account)
          Owner of the ‘mympd’ process.

          The default ‘%mympd-user’ is a system user with the name
          “mympd”, who is a part of the group GROUP (see below).
     ‘group’ (default: ‘%mympd-group’) (type: user-group)
          Owner group of the ‘mympd’ process.

          The default ‘%mympd-group’ is a system group with name
          “mympd”.
     ‘work-directory’ (default: ‘"/var/lib/mympd"’) (type: string)
          Where myMPD will store its data.
          
** 12.9.30 Virtualization Services L969
#true instead of #t

               (ganeti-os
                (name "guix")
                (variants (local-file "ganeti-guix-variants"
                                      #:recursive? #true)))
                                      
** 12.9.31 Version Control Services L385
config- file weird syntax

 -- cgit-configuration parameter: file-object include
     Name of a configfile to include before the rest of the current
     config- file is parsed.

     Defaults to ‘""’.

 
Just an empty string instead of the empty string L858    

   For example, if your ‘cgitrc’ is just the empty string, you could
instantiate a cgit service like this:

     (service cgit-service-type
              (opaque-cgit-configuration
               (cgitrc "")))

Default values are in UPPERCASE L859     

 -- Data Type: gitolite-configuration
     Data type representing the configuration for
     ‘gitolite-service-type’.
     
** 12.9.32 PAM Mount Service
Uses old style.

** 12.9.37 Misc Services
Dictionary Service UPPERCASE values for default variables.


Shouldn't this be gets banned instead of get banned? L574

     ‘max-retry’ (type: maybe-integer)
          The number of failures before a host get banned (e.g.
          ‘(max-retry 5)’).

** 12.11 Bootloader Configuration L74
Instead of tftp info detects ftp.

          If you plan to use an NFS root file system as well (actually
          if you mount the store from an NFS share), then the TFTP
          server needs to serve the file ‘/boot/grub/grub.cfg’ and other
          files from the store (like GRUBs background image, the kernel
          (*note ‘kernel’: operating-system Reference.) and the initrd
          (*note ‘initrd’: operating-system Reference.)), too.  All
          these files from the store will be accessed by GRUB through
          TFTP with their normal store path, for example as
          ‘tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz’.

Uppercase default value L171

     ‘theme’ (default: #F)
          The bootloader theme object describing the theme to use.  If
          no theme is provided, some bootloaders might use a default
          theme, that’s true for GRUB.


random + at the end L271
	  
	       ‘multiboot-arguments’ (default: ‘'()’)
          The list of extra command-line arguments for the
          multiboot-kernel.

          For example, when running in QEMU it can be useful to use a
          text-based console (use options ‘--nographic’ ‘--serial
          mon:stdio’):

               '("console=com0")

          To use the new and still experimental rumpdisk user-level disk
          driver (https://darnassus.sceen.net/~hurd-web/rump_kernel/)
          instead of GNU Mach’s in-kernel IDE driver, set
          ‘kernel-arguments’ to:

               '("noide")

          Of course, these options can be combined:

               '("console=com0" "noide")

          +
          
** 12.12 Invoking Guix system L88
, -unless

     It also adds a bootloader menu entry for the new OS configuration,
     —unless ‘--no-bootloader’ is passed.  For GRUB, it moves entries
     for older configurations to a submenu, allowing you to choose an
     older system generation at boot time should you need it.
** Service Reference L177
It lists some services that were already mentioned in the Services
chapter.  Wouldn't it be better to just reference to this, to have one
source of truth?

   At the core of the service abstraction lies the ‘fold-services’
procedure, which is responsible for “compiling” a list of services down
to a single directory that contains everything needed to boot and run
the system—the directory shown by the ‘guix system build’ command (*note
Invoking guix system::).  In essence, it propagates service extensions
down the service graph, updating each node parameters on the way, until
it reaches the root node.

** Guix home
it is called "dotfiles" and on the next chapter it is called "dot
files".

** Essential Home Server L85
Explain DAG acronym.

-- Variable: home-service-type
     The root of home services DAG, it generates a folder, which later
     will be symlinked to ‘~/.guix-home’, it contains configurations,
     profile with binaries and libraries, and some necessary scripts to
     glue things together.

** Shells Home Services
Add the code as well.  Was the case for system services.

   You would then add ‘bash-fancy-prompt-service’ to the list in the
‘services’ field of your ‘home-environment’.  The reference of
‘home-bash-extension’ follows.

Inputrc Profile Service

The example code uses the old style.

          (service home-inputrc-service-type
                   (home-inputrc-configuration
                     (key-bindings
                      `(("Control-l" . "clear-screen")))
                     (variables
                      `(("bell-style" . "visible")
                        ("colored-completion-prefix" . #t)
                        ("editing-mode" . "vi")
                        ("show-mode-in-prompt" . #t)))
                     (conditional-constructs
                      `(("$if mode=vi" .
                         ,(home-inputrc-configuration
                            (variables
                             `(("colored-stats" . #t)
                               ("enable-bracketed-paste" . #t)))))
                        ("$else" .
                         ,(home-inputrc-configuration
                            (variables
                             `(("show-all-if-ambiguous" . #t)))))
                        ("endif" . #t)
                        ("$include" . "/etc/inputrc")
                        ("$include" . ,(file-append
                                         (specification->package "readline")
                                         "/etc/inputrc"))))))


** Secure Shell
Weird syntax.  Can't we just have 'no, 'confirm, 'ask or 'yes?

     ‘add-keys-to-agent’ (default: ‘``no''’)
          This string specifies whether keys should be automatically
          added to a running ssh-agent.  If this option is set to
          ‘``yes''’ and a key is loaded from a file, the key and its
          passphrase are added to the agent with the default lifetime,
          as if by ‘ssh-add’.  If this option is set to ‘``ask''’, ‘ssh’
          will require confirmation.  If this option is set to
          ‘``confirm''’, each use of the key must be confirmed.  If this
          option is set to ‘``no''’, no keys are added to the agent.
          Alternately, this option may be specified as a time interval
          to specify the key’s lifetime in ‘ssh-agent’, after which it
          will automatically be removed.  The argument must be ‘``no''’,
          ‘``yes''’, ‘``confirm''’ (optionally followed by a time
          interval), ‘``ask''’ or a time interval.
          
** Desktop Home Services L32
Geolocation provider— why the hyphen.

     ‘location-provider’ (default: ‘geoclue2’) (type: symbol)
          Geolocation provider—‘'manual’ or ‘'geoclue2’.  In the former
          case, you must also specify the ‘latitude’ and ‘longitude’
          fields so Redshift can determine daytime at your place.  In
          the latter case, the Geoclue system service must be running;
          it will be queried for location information.
          
** Mail Home Services L101
cmd should be CMD, since it as a parameter.

     ‘password-eval’ (type: maybe-string)
          Set the password for authentication to the output (stdout) of
          the command cmd.
          
** 17.1
should be is that IT takes up a fair

The problem with debugging information is that is takes up a fair amount
of disk space.  For example, debugging information for the GNU C Library

** Full Source Bootstrap L68
to to

   Work is ongoing to to bring these bootstraps to the ‘arm-linux’ and
‘aarch64-linux’ architectures and to the Hurd.

** Preparitng to use Bootstrap binaries L152
of of

Our first major achievement is the replacement of of GCC, the GNU C
Library and Binutils by MesCC-Tools (a simple hex linker and macro

** 22 Contributing
There is a weird symbol after Libera.

This project is a cooperative effort, and we need your help to make it
grow!  Please get in touch with us on <guix-devel@gnu.org> and ‘#guix’
on the Libera Chat IRC network.  We welcome ideas, bug reports, patches,
and anything that may be helpful to the project.  We particularly
welcome help on packaging (*note Packaging Guidelines::).

** Version Numers L59
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?h=v6.7&id=6eb3c3d0a52dca337e327ae8868ca1f44a712e02

   It is a good idea to strip commit identifiers in the ‘version’ field
to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
aesthetics have a role to play here) as well as problems related to OS
limits such as the maximum shebang length (127 bytes for the Linux
kernel).  There are helper functions for doing this for packages using
‘git-fetch’ or ‘hg-fetch’ (see below).  It is best to use the full
commit identifiers in ‘origin’s, though, to avoid ambiguities.  A
typical package definition may look like this:

** Elm Packages
It says it is not required but at the same time it says it is
required, or do I understand this wrong? (I like those prefixes
anyways, they keep it organized and makes finding packages easier.)

Elm applications can be named like other software: their names need not
mention Elm.

   To form the Guix package name from the upstream name, we follow a
convention similar to Python packages (*note Python Modules::), adding
an ‘elm-’ prefix unless the name would already begin with ‘elm-’.

** Formatting Code L18
Shouldn't it be know?

   If you do not use Emacs, please make sure to let your editor knows
these rules.





Also, I read in the manual this:

‘create-mount-point?’ (default: ‘#f’)
          When true, the mount point is created if it does not exist
          yet.

and my config is this:

(file-system
  (mount-point "/home/cm/entertainment")
  (device (uuid
            "8112eb2f-5a42-4bb9-b097-501a468c1573"
            'btrfs))
  (type "btrfs"))

though if I reinstall my system on a new drive, the /entertainment
directory is automatically created as root and therefore whole
/home/cm is owned by root which breaks the shell of the home user.

-- 
Christian Miller

Re: Feedback of the GNU Guix manual

[Matt]

I care about this.  How can I help?

- Convert the notes into patches?
- Proofread any patches that derive from Christian's efforts?
 
 ---- On Sun, 14 Jan 2024 16:01:58 +0100  Christian Miller  wrote --- 

 > I read through the GNU Guix manual on revision
 > ee7c9d254117fa470686210ad2ef5e7f1ba4fefc with Emacs in TTY mode.

What's TTY mode?  M-x tty <tab> reveals nothing for me.
 
 > As a beginner, the manual was helpful and I learned lot's of stuff.
 > Though it felt heartless.  No consistency and sometimes the structure
 > is confusing (especially the contributing part, since it tries to get
 > GNU Guix System and GNU Guix under one section and it was kinda
 > confusing for me).

Thank you for sharing your experience.  I'm sorry it wasn't more positive.  I've found it challenging to read as well.

 > It seems that there is no style guide.  Sometimes default values are
 > mentioned and sometimes not.  Also some use uppercase and other use
 > lowercase for type of variable.  There is also Scheme code which is
 > most of the time in the old style notation.  For me as a beginner,
 > this was confusing.

The GNU project has several:

- https://www.gnu.org/prep/standards/html_node/Documentation.html
- https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf

 > I will mention lot's of style issues since at that time I did not know
 > it is in such a bad state.

I respectfully disagree that it's in bad taste to mention them.  I find such feedback helpful towards correcting the problems you experience.  I appreciate you taking the time to write them all up.  It's nice to know someone reads the manual! :)

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Feedback of the GNU Guix manual

[Christian Miller]

> I care about this.  How can I help?

I don't know.  I would also create patches but don't know if it should
be a huge patch or multiple ones, or maybe even it's own branch.

> What's TTY mode?  M-x tty <tab> reveals nothing for me.

Mode is probably the wrong word.  It basically is just running
"emacsclient --tty".  I sometimes use Emacs in a Linux console, since
I like how it looks (also helps in learning the keybindings and
actually using them, since it forces me to not use the mouse).  I
mentioned it, since it changes how the documentation is rendered.  For
example, there will be no pictures since there is no graphics in a
Linux console.

> I appreciate you taking the time to write them all up.
Thanks.

-- 
Christian Miller

Re: Feedback of the GNU Guix manual

[Maxim Cournoyer]

Hi Matt!

Matt <matt@excalamus.com> writes:

> I care about this.  How can I help?
>
> - Convert the notes into patches?
> - Proofread any patches that derive from Christian's efforts?

That would be a good way to help, yes!  It'll be easier to review if
each distinct problem is fixed in its own commit (patch).

-- 
Thanks,
Maxim

Re: Feedback of the GNU Guix manual

[Matt]

 ---- On Thu, 18 Jan 2024 20:44:53 +0100  Maxim Cournoyer  wrote --- 

 > That would be a good way to help, yes!  It'll be easier to review if
 > each distinct problem is fixed in its own commit (patch).

Now that I've looked more closely at it, I completely agree.

I suggest we take them point-by-point and move on only after we've completed each one in turn. 

** Binary installation L73
Guix system should be Guix System

*** Comment
Line 73 in the info file, section "Binary Installation" corresponds to
line 825 in =doc/guix.texi=.

=15efd5a7f4:doc/guix.texi= reads,

#+begin_quote
Do _not_ unpack the tarball on a working Guix system since that would
overwrite its own essential files.
#+end_quote

I see several issues with this sentence.  In order of severity:

1. the sentence isn't necessary
2. the problem is moving, not unpacking
3. the sentence confuses the subject
4. (reported) the word "system" is unclear

At this point in the manual, the reader has downloaded a Guix tarball
and has just been instructed to unpack and move the extracted files.
The sentence warns that moving =/tmp/var/guix= to =/var/= and
=/tmp/gnu= to =/= will overwrite files already there from an existing
Guix installation.

**** 1. the sentence isn't necessary
Is there ever a circumstance where a Guix installation, from a binary
or as a System, would need to install Guix from the tarball?

Unless there's a reason for a Guix user to follow the steps in "Binary
Installation," I suggest we remove this sentence and revise the
introduction paragraph to make sure current Guix users skip this
section.

--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode

Re: Feedback of the GNU Guix manual

[Matt]

[-- Attachment #1: Type: text/plain, Size: 3689 bytes --]

Friendly bump.

Attached is a suggested diff.

A previous suggestion was made to change "system" to the proper noun "System", as in the "Guix System", within the Binary Installation section.  The change would occur in a warning that moving unpacked binary tarballs as directed on existing Guix installations will overwrite system files.

The suggested capitalization would be improper since the "system" referred to is "an arbitrary system" and not specifically the Guix System.

The broader context is that the change suggested occurs within the Binary Installation section.  Since, there is no apparent reason why a user of an existing Guix installation would need to perform a binary installation, this patch removes the warning sentence (containing the confusing usage of "system") and moves it to the beginning of the section so that readers may understand the risk at the start and to decide whether this section applies to them before reading further.

The change also corrects the overly broad term "arbitrary system" to the specific "Linux or Hurd-based system."  Guix does not work with BSD, Haiku, Windows, or Darwin systems.  While installing Guix on these systems may be possible, by some definitions of "install", doing so for an end-user would be silly, since it wouldn't function as expected.

The change also more accurately lists the requirements.  Previously, it was stated that only tar and Xz are required.  This is false since Guix requires a Linux or Hurd-based system.

The explanation of "a self-contained tarball providing binaries for Guix and for all its dependencies" was reduced to the simpler "archived binaries."  Generally, "tarball" is imprecise, hence the need to explain what it contains in this context.  Further, it's jargon, may not be familiar to some readers, and isn't relevant to the point of the introduction, that Guix may be installed without needing to compile and why that might be desirable.

Specific mention of installing Guix's dependencies was removed.  Guix being installed implies that its dependencies are also installed.

The warning line was added in commit:
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=5dc3ce5f6c7990f44143f8e9bb9a873a014a82e4.
The warning orginates from this commit:
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=09722b11e5e618028051d5f6d14eb13529dc7100

I see no associated issue referenced in the commits.  I assume the warning is simply being cautious.

#+begin_src diff
diff --git a/doc/guix.texi b/doc/guix.texi
index 4af830aed7..16349d4ec1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,16 @@ ready to use it.

 @cindex installing Guix from binaries
 @cindex installer script
-This section describes how to install Guix on an arbitrary system from a
-self-contained tarball providing binaries for Guix and for all its
-dependencies.  This is often quicker than installing from source, which
-is described in the next sections.  The only requirement is to have
-GNU@tie{}tar and Xz.
+This section describes how to install Guix from archived binaries.  Such
+installations are often quicker than building from source, which is
+described in the next sections.  Binary installations require a Linux or
+Hurd-based system with GNU@tie{}tar and Xz.
+
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.

 @c Note duplicated from the ``Installation'' node.
-@quotation Note
 We recommend the use of this
 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
 shell installer script}.  The script automates the download, installation, and
#+end_src

[-- Attachment #2: 0001-binary-installation.diff --]
[-- Type: application/octet-stream, Size: 1213 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 4af830aed7..16349d4ec1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,16 @@ ready to use it.
 
 @cindex installing Guix from binaries
 @cindex installer script
-This section describes how to install Guix on an arbitrary system from a
-self-contained tarball providing binaries for Guix and for all its
-dependencies.  This is often quicker than installing from source, which
-is described in the next sections.  The only requirement is to have
-GNU@tie{}tar and Xz.
+This section describes how to install Guix from archived binaries.  Such
+installations are often quicker than building from source, which is
+described in the next sections.  Binary installations require a Linux or
+Hurd-based system with GNU@tie{}tar and Xz.
+
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 
 @c Note duplicated from the ``Installation'' node.
-@quotation Note
 We recommend the use of this
 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
 shell installer script}.  The script automates the download, installation, and

Re: Feedback of the GNU Guix manual

[Matt]

Friendly bump.  Awaiting feedback or guidance.

Re: Feedback of the GNU Guix manual

[Josselin Poiret]

[-- Attachment #1: Type: text/plain, Size: 1037 bytes --]

Hi Matt,

Matt <matt@excalamus.com> writes:

> The explanation of "a self-contained tarball providing binaries for Guix and for all its dependencies" was reduced to the simpler "archived binaries."  Generally, "tarball" is imprecise, hence the need to explain what it contains in this context.  Further, it's jargon, may not be familiar to some readers, and isn't relevant to the point of the introduction, that Guix may be installed without needing to compile and why that might be desirable.
>
> Specific mention of installing Guix's dependencies was removed.  Guix being installed implies that its dependencies are also installed.

I don't agree here: it's often the case in Linux-land that binary
archives are provided without their dependencies included, assuming that
the user already has them, often by installing them via their own
package manager.  Keeping the mention that it is self-contained and that
the dependencies are also included might clarify the situation for some
users.

Best,
-- 
Josselin Poiret

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 682 bytes --]

Re: Feedback of the GNU Guix manual

[Matt]

[-- Attachment #1: Type: text/plain, Size: 1914 bytes --]


 ---- On Sun, 18 Feb 2024 14:55:46 +0100  Josselin Poiret  wrote --- 

 > Matt matt@excalamus.com> writes:
 > 
 > > Specific mention of installing Guix's dependencies was removed.  Guix being installed implies that its dependencies are also installed.
 > 
 > I don't agree here: it's often the case in Linux-land that binary
 > archives are provided without their dependencies included, assuming that
 > the user already has them, often by installing them via their own
 > package manager.  Keeping the mention that it is self-contained and that
 > the dependencies are also included might clarify the situation for some
 > users.

Thank you for the feedback.

I opted for only "self-contained" which seems to imply that dependencies are available, in addition to other things, perhaps like setting an environment or pathing.  If "self-contained" is distinct from "includes dependencies," we could append something like "...and includes all dependencies" to the last sentence.

I also tried to distinguish that it's the installation *process* which requires GNU-tar and Xz and not the final installation, since that's self-contained.

Otherwise, I tried to simplify the language:

- archived binaries -> a binary archive
- are often quicker -> often go faster
- which is described in the next sections -> described later

This version has fewer words and one more sentence.  However, each sentence has a single, hopefully clear, point:

1. What this section is about? Installing from a binary archive.
2. Why you might want this section? It's faster than building.
3. What's needed?  A Linux or Hurd-system with GNU-tar and Xz.
4. What do you get?  A self-contained Guix installation.

Original: Region has 5 lines, 3 sentences, 51 words, and 301 characters
v2:       Region has 5 lines, 4 sentences, 45 words, and 292 characters

If this is good, I can write up a commit message and format the change as a patch.

[-- Attachment #2: v2-0001-binary-installation.diff --]
[-- Type: application/octet-stream, Size: 1249 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 9966a8e697..a5558300fa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -732,14 +732,17 @@ ready to use it.
 
 @cindex installing Guix from binaries
 @cindex installer script
-This section describes how to install Guix on an arbitrary system from a
-self-contained tarball providing binaries for Guix and for all its
-dependencies.  This is often quicker than installing from source, which
-is described in the next sections.  The only requirement is to have
-GNU@tie{}tar and Xz.
+This section describes how to install Guix from a binary archive.  Such
+installations often go faster than building from source, described
+later.  Guix requires a Linux or Hurd-based system and unpacking the
+archive requires GNU@tie{}tar and Xz.  The resulting installation is
+self-contained.
+
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 
 @c Note duplicated from the ``Installation'' node.
-@quotation Note
 We recommend the use of this
 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
 shell installer script}.  The script automates the download, installation, and

Re: Feedback of the GNU Guix manual

[Maxim Cournoyer]

Hi Matt,

Thanks for the follow-up.

Matt <matt@excalamus.com> writes:

[...]

> #+begin_src diff
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 4af830aed7..16349d4ec1 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -732,14 +732,16 @@ ready to use it.
>
>  @cindex installing Guix from binaries
>  @cindex installer script
> -This section describes how to install Guix on an arbitrary system from a
> -self-contained tarball providing binaries for Guix and for all its
> -dependencies.
>
>  This is often quicker than installing from source, which
> -is described in the next sections.  The only requirement is to have
> -GNU@tie{}tar and Xz.
> +This section describes how to install Guix from archived binaries.  Such
> +installations are often quicker than building from source, which is
> +described in the next sections.  Binary installations require a Linux or
> +Hurd-based system with GNU@tie{}tar and Xz.

Like Josselin, I prefer to keep the mention that the tarball archive
includes the transitive dependencies of Guix (it's explicit; "archived
binaries" is a bit vague to my taste).

As for the Linux or Hurd-based system, that seems like a good idea to
make things explicit.

I've pushed your adjusted suggestions with commit ec9c8b0c1a.

Thank you!

-- 
Maxim

Re: Feedback of the GNU Guix manual

[Matt]

 ---- On Wed, 21 Feb 2024 18:20:19 +0100  Maxim Cournoyer  wrote --- 

 > Thanks for the follow-up.

Thank you!  Seems like we were looking at it at about the same time :)

 > Like Josselin, I prefer to keep the mention that the tarball archive
 > includes the transitive dependencies of Guix (it's explicit; "archived
 > binaries" is a bit vague to my taste).

I tried to address that in the diff I wrote up before I saw your message.  I agree, "archived binaries" is awkward.  I changed it in my update.

 > I've pushed your adjusted suggestions with commit ec9c8b0c1a.
 
Cool.  I'll work on the next item in the list.  Please let me know if there's something more regarding this item based on the v2 update.

Re: Feedback of the GNU Guix manual

[Maxim Cournoyer]

Hi Matt,

Matt <matt@excalamus.com> writes:

>  ---- On Wed, 21 Feb 2024 18:20:19 +0100  Maxim Cournoyer  wrote --- 
>
>  > Thanks for the follow-up.
>
> Thank you!  Seems like we were looking at it at about the same time :)
>
>  > Like Josselin, I prefer to keep the mention that the tarball archive
>  > includes the transitive dependencies of Guix (it's explicit; "archived
>  > binaries" is a bit vague to my taste).
>
> I tried to address that in the diff I wrote up before I saw your message.  I agree, "archived binaries" is awkward.  I changed it in my update.
>
>  > I've pushed your adjusted suggestions with commit ec9c8b0c1a.
>  
> Cool.  I'll work on the next item in the list.  Please let me know if there's something more regarding this item based on the v2 update.

Great, sounds good.  I've checked your v2 update, but opted to keep
things as they are (following my own edition of your initial work, which
was committed).

Thank you for your efforts!

-- 
Maxim

Re: Feedback of the GNU Guix manual

[Matt]

 ---- On Fri, 23 Feb 2024 03:46:29 +0100  Maxim Cournoyer  wrote --- 

 > Great, sounds good.  I've checked your v2 update, but opted to keep
 > things as they are (following my own edition of your initial work, which
 > was committed).

No problem, I think what you did looks good.

 > Thank you for your efforts!
 
Likewise, excited to be working on this.

Re: Feedback of the GNU Guix manual

[Matt]

[-- Attachment #1: Type: text/plain, Size: 3623 bytes --]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed an item and are ready to work on the next one:

#+begin_quote
,** Binary Installation L88 and L95

~root is weird. Should be root or simply ~ for the user profile which would be root as root user.
#+end_quote

I agree.  I found it weird at first, too.

Two thoughts:

1. The use of "~root" is intentional
2. Section 2.1 Binary Install can be refactored to remove the reported confusion as well as the tarpit of shell related details

*1. The use of "~root" is intentional*

According to the Bash info and man pages, "~root" is a TILDE-PREFIX with "root" as the LOGIN NAME.  The TILDE-PREFIX is replaced with the home directory associated with the specified LOGIN NAME.

Using "~root" solves the problem of operations happening in the wrong location.  It ensures that commands reference the 'root' user's home directory.

- (original issue) https://lists.gnu.org/archive/html/guix-devel/2015-06/msg00085.html
- (separate issue) https://bugs.gnu.org/30728

*2. Section 2.1 Binary Install needs refactoring*

The Binary Installation section tries to solve the problem of guiding readers to install Guix as quickly and painlessly as possible.  This began as a step-by-step process which was later automated by 'guix-install.sh'.  Over 6 years, 12 people have worked to make 'guix-install.sh' robust.  Because of these efforts, Section 2.1 Binary Installation has effectively become high level documentation for how 'guix-install.sh' works.

Like any code comment tends to drift out of sync with the source code, the current presentation of binary installations has become inconsistent and redundant.  Using 'guix-install.sh' is the recommended method for binary installation.  It's the first thing mentioned by Section 2 Installation and one of the first things mentioned by Section 2.1 Binary Installation.  It's inconsistent to say, "This is how to do it" and then proceed to explain how to *not* use the recommended method.

Key information, like the recommended installation method and the definition of "foreign distro", are improperly hidden inside notes.  Note blocks act as comments which, by definition, are secondary to the main point.  The main point is to use 'guix-install.sh' on foreign distros which don't provide their own packages for Guix.

The attached diff addresses these issues.  It fixes the root issue (pun intended) of whether or not to expect readers to understand '~root', as well as unmentioned issues also related to shell-specific knowledge like, "What does it mean to 'source'?"  Readers interested in those details may read the code for 'guix-install.sh'.

The diff does the following:

- Clarifies at the top level that installing on a foreign distro has two methods: using packaged binaries and building from source
- Places the overwrite warning at the top level node and binary installation level node
- Moves the definition of "foreign distro" out of quotation
- Moves the foreign distro installation instructions out of quotation
- Summarizes the steps 'guix-install.sh' follows rather than trying to detail them
- Splits the requirements between system requirements for binary installations, GNU/Linux or GNU/Hurd, and requirements for running 'guix-install.sh', tar, wget, Xz
- Removes redundant instructions to use 'guix-install.sh'
- 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

[-- Attachment #2: v01-refactor-binary-installation-section.diff --]
[-- Type: application/octet-stream, Size: 11940 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index f6476e0d81..6322cc6fe9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -690,20 +690,25 @@ to join!  @xref{Contributing}, for information about how you can help.
 @chapter Installation
 
 @cindex installing Guix
+@cindex foreign distro
+@cindex Guix System
+You can install the Guix package management tool on top of an existing
+GNU/Linux or GNU/Hurd system, referred to as a @dfn{foreign distro}, or
+as a standalone operating system distribution, the
+@dfn{Guix@tie{}System}.  This section is concerned with the installation
+of Guix on a foreign distro.  If, instead, you want to install the
+complete GNU operating system, @pxref{System Installation}.
 
-@quotation Note
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script} to install Guix on top of a running GNU/Linux system,
-thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
-with the installation of the package manager, which can be done on top of a
-running GNU/Linux system.  If, instead, you want to install the complete GNU
-operating system, @pxref{System Installation}.} The script automates the
-download, installation, and initial configuration of Guix.  It should be run
-as the root user.
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 @end quotation
 
-@cindex foreign distro
+The following sections describe two methods of installation, binary
+installation and building from source.  They describe the software
+requirements of Guix, as well as how to install it manually and get
+ready to use it.
+
 @cindex directories related to foreign distro
 When installed on a foreign distro, GNU@tie{}Guix complements the available
 tools without interference.  Its data lives exclusively in two directories,
@@ -713,11 +718,6 @@ such as @file{/etc}, are left untouched.
 Once installed, Guix can be updated by running @command{guix pull}
 (@pxref{Invoking guix pull}).
 
-If you prefer to perform the installation steps manually or want to tweak
-them, you may find the following subsections useful.  They describe the
-software requirements of Guix, as well as how to install it manually and get
-ready to use it.
-
 @menu
 * Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
@@ -736,254 +736,57 @@ ready to use it.
 This section describes how to install Guix from a self-contained tarball
 providing binaries for Guix and for all its dependencies.  This is often
 quicker than installing from source, which is described in the next
-sections.  Binary installation requires a system using a Hurd or Linux
-kernel; the GNU@tie{}tar and Xz commands must also be available.
+sections.
 
 @quotation Important
 This section only applies to systems without Guix.  Following it for
 existing Guix installations will overwrite important system files.
+@end quotation
 
-@c Note duplicated from the ``Installation'' node.
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script}.  The script automates the download, installation, and
-initial configuration steps described below.  It should be run as the root
-user.  As root, you can thus run this:
-
-@example
-cd /tmp
-wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
-chmod +x guix-install.sh
-./guix-install.sh
-@end example
+Some distributions, such as Debian, Ubuntu, and openSUSE, provide Guix
+through their own package managers.  The version of Guix may be older
+than @value{VERSION} but you can update it afterwards by running
+@samp{guix pull}).
 
-If you're running Debian or a derivative such as Ubuntu, you can instead
-install the package (it might be a version older than @value{VERSION}
-but you can update it afterwards by running @samp{guix pull}):
+For Debian and Ubuntu-based systems call:
 
 @example
 sudo apt install guix
 @end example
 
-Likewise on openSUSE:
+Likewise on openSUSE run:
 
 @example
 sudo zypper install guix
 @end example
 
-When you're done, @pxref{Application Setup} for extra configuration you
-might need, and @ref{Getting Started} for your first steps!
-@end quotation
-
-Installing goes along these lines:
-
-@enumerate
-@item
-@cindex downloading Guix binary
-Download the binary tarball from
-@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
-where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
-@code{i686} (32-bits) machine already running the kernel Linux, and so on
-(@pxref{GNU Distribution}).
-
-@c The following is somewhat duplicated in ``System Installation''.
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the tarball against it, along these lines:
-
-@example
-$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-@end example
+The Guix project also provides a shell script, @file{guix-install.sh},
+which automates the binary installation process without use of a foreign
+distro package
+manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}.
+Use of @file{guix-install.sh} requires Bash, GNU@tie{}tar, wget, and Xz.
 
-If that command fails because you do not have the required public key,
-then run this command to import it:
+The script does the following:
 
-@example
-$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-      -qO - | gpg --import -
-@end example
-
-@noindent
-and rerun the @code{gpg --verify} command.
-
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
-
-@c end authentication part
+@itemize
+@item Downloads and extracts the binary tarball
+@item Sets up the build daemon
+@item Makes the ‘guix’ command available to non-root users
+@item Configures substitute servers
+@end itemize
 
-@item
-Now, you need to become the @code{root} user.  Depending on your distribution,
-you may have to run @code{su -} or @code{sudo -i}.  As @code{root}, run:
+As root, run:
 
 @example
 # cd /tmp
-# tar --warning=no-timestamp -xf \
-     /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
-# mv var/guix /var/ && mv gnu /
-@end example
-
-This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
-The latter contains a ready-to-use profile for @code{root} (see next
-step).
-
-Do @emph{not} unpack the tarball on a working Guix system since that
-would overwrite its own essential files.
-
-The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
-not emit warnings about ``implausibly old time stamps'' (such
-warnings were triggered by GNU@tie{}tar 1.26 and older; recent
-versions are fine).
-They stem from the fact that all the
-files in the archive have their modification time set to 1 (which
-means January 1st, 1970).  This is done on purpose to make sure the
-archive content is independent of its creation time, thus making it
-reproducible.
-
-@item
-Make the profile available under @file{~root/.config/guix/current}, which is
-where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
-
-@example
-# mkdir -p ~root/.config/guix
-# ln -sf /var/guix/profiles/per-user/root/current-guix \
-         ~root/.config/guix/current
-@end example
-
-Source @file{etc/profile} to augment @env{PATH} and other relevant
-environment variables:
-
-@example
-# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
-  source $GUIX_PROFILE/etc/profile
-@end example
-
-@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}).
-
-@item
-Run the daemon, and set it to automatically start on boot.
-
-If your host distro uses the systemd init system, this can be achieved
-with these commands:
-
-@c Versions of systemd that supported symlinked service files are not
-@c yet widely deployed, so we should suggest that users copy the service
-@c files into place.
-@c
-@c See this thread for more information:
-@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
-     ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
-     /etc/systemd/system/
-# systemctl enable --now gnu-store.mount guix-daemon
-@end example
-
-You may also want to arrange for @command{guix gc} to run periodically:
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
-     ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
-     /etc/systemd/system/
-# systemctl enable --now guix-gc.timer
-@end example
-
-You may want to edit @file{guix-gc.service} to adjust the command line
-options to fit your needs (@pxref{Invoking guix gc}).
-
-If your host distro uses the Upstart init system:
-
-@example
-# initctl reload-configuration
-# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
-     /etc/init/
-# start guix-daemon
-@end example
-
-Otherwise, you can still start the daemon manually with:
-
-@example
-# ~root/.config/guix/current/bin/guix-daemon \
-       --build-users-group=guixbuild
-@end example
-
-@item
-Make the @command{guix} command available to other users on the machine,
-for instance with:
-
-@example
-# mkdir -p /usr/local/bin
-# cd /usr/local/bin
-# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
-@end example
-
-It is also a good idea to make the Info version of this manual available
-there:
-
-@example
-# mkdir -p /usr/local/share/info
-# cd /usr/local/share/info
-# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
-  do ln -s $i ; done
-@end example
-
-That way, assuming @file{/usr/local/share/info} is in the search path,
-running @command{info guix} will open this manual (@pxref{Other Info
-Directories,,, texinfo, GNU Texinfo}, for more details on changing the
-Info search path).
-
-@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
-
-@item
-Each user may need to perform a few additional steps to make their Guix
-environment ready for use, @pxref{Application Setup}.
-@end enumerate
-
-Voilà, the installation is complete!
-
-You can confirm that Guix is working by installing a sample package into
-the root profile:
-
-@example
-# guix install hello
-@end example
-
-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
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @end example
 
-@xref{Invoking guix pack}, for more info on this handy tool.
+When you're done installing Guix, @pxref{Application Setup} for extra
+configuration you might need, and @ref{Getting Started} for your first
+steps!
 
 @node Requirements
 @section Requirements

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

[pelzflorian (Florian Pelz)]

Thank you Matt for the suggested diff.

Yes, I agree some simplification as you suggested would be beneficial,
so that the description of Binary Installation looks as simple as it
really is.  (In particular, I have witnessed people, to whom I had
suggested Guix, fail at trying Guix because they tried Guix System on a
not libre-friendly laptop, when they could/should have tried Binary
Installation.)

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

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.

Regards,
Florian

[0] https://wiki.archlinux.org/title/Guix

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

[Matt]

[-- Attachment #1: Type: text/plain, Size: 3905 bytes --]

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

[-- Attachment #2: v02-refactor-binary-installation-section.diff --]
[-- Type: application/octet-stream, Size: 12248 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 87fe9f803c..cc9b07c152 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -691,20 +691,25 @@ to join!  @xref{Contributing}, for information about how you can help.
 @chapter Installation
 
 @cindex installing Guix
+@cindex foreign distro
+@cindex Guix System
+You can install the Guix package management tool on top of an existing
+GNU/Linux or GNU/Hurd system, referred to as a @dfn{foreign distro}, or
+as a standalone operating system distribution, the
+@dfn{Guix@tie{}System}.  This section is concerned with the installation
+of Guix on a foreign distro.  If, instead, you want to install the
+complete GNU operating system, @pxref{System Installation}.
 
-@quotation Note
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script} to install Guix on top of a running GNU/Linux system,
-thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
-with the installation of the package manager, which can be done on top of a
-running GNU/Linux system.  If, instead, you want to install the complete GNU
-operating system, @pxref{System Installation}.} The script automates the
-download, installation, and initial configuration of Guix.  It should be run
-as the root user.
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 @end quotation
 
-@cindex foreign distro
+The following sections describe two methods of installation, binary
+installation and building from source.  They describe the software
+requirements of Guix, as well as how to install it manually and get
+ready to use it.
+
 @cindex directories related to foreign distro
 When installed on a foreign distro, GNU@tie{}Guix complements the available
 tools without interference.  Its data lives exclusively in two directories,
@@ -714,11 +719,6 @@ such as @file{/etc}, are left untouched.
 Once installed, Guix can be updated by running @command{guix pull}
 (@pxref{Invoking guix pull}).
 
-If you prefer to perform the installation steps manually or want to tweak
-them, you may find the following subsections useful.  They describe the
-software requirements of Guix, as well as how to install it manually and get
-ready to use it.
-
 @menu
 * Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
@@ -737,209 +737,63 @@ ready to use it.
 This section describes how to install Guix from a self-contained tarball
 providing binaries for Guix and for all its dependencies.  This is often
 quicker than installing from source, which is described in the next
-sections.  Binary installation requires a system using a Hurd or Linux
-kernel; the GNU@tie{}tar and Xz commands must also be available.
+sections.
 
 @quotation Important
 This section only applies to systems without Guix.  Following it for
 existing Guix installations will overwrite important system files.
+@end quotation
 
-@c Note duplicated from the ``Installation'' node.
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script}.  The script automates the download, installation, and
-initial configuration steps described below.  It should be run as the root
-user.  As root, you can thus run this:
-
-@example
-cd /tmp
-wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
-chmod +x guix-install.sh
-./guix-install.sh
-@end example
+Some distributions, such as Debian, Ubuntu, and openSUSE provide Guix
+through their own package managers.  The version of Guix may be older
+than @value{VERSION} but you can update it afterwards by running
+@samp{guix pull}.
 
-If you're running Debian or a derivative such as Ubuntu, you can instead
-install the package (it might be a version older than @value{VERSION}
-but you can update it afterwards by running @samp{guix pull}):
+For Debian and Ubuntu-based systems, call:
 
 @example
 sudo apt install guix
 @end example
 
-Likewise on openSUSE:
+Likewise, on openSUSE:
 
 @example
 sudo zypper install guix
 @end example
 
-When you're done, @pxref{Application Setup} for extra configuration you
-might need, and @ref{Getting Started} for your first steps!
-@end quotation
-
-Installing goes along these lines:
-
-@enumerate
-@item
-@cindex downloading Guix binary
-Download the binary tarball from
-@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
-where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
-@code{i686} (32-bits) machine already running the kernel Linux, and so on
-(@pxref{GNU Distribution}).
-
-@c The following is somewhat duplicated in ``System Installation''.
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the tarball against it, along these lines:
-
-@example
-$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-@end example
-
-If that command fails because you do not have the required public key,
-then run this command to import it:
-
-@example
-$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-      -qO - | gpg --import -
-@end example
-
-@noindent
-and rerun the @code{gpg --verify} command.
+The Guix project also provides a shell script, @file{guix-install.sh},
+which automates the binary installation process without use of a foreign
+distro package
+manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}.
+Use of @file{guix-install.sh} requires Bash, GNU@tie{}tar, wget, and Xz.
 
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
+The script guides you through the following:
 
-@c end authentication part
+@itemize
+@item Download and extract the binary tarball
+@item Set up the build daemon
+@item Make the ‘guix’ command available to non-root users
+@item Configure substitute servers
+@end itemize
 
-@item
-Now, you need to become the @code{root} user.  Depending on your distribution,
-you may have to run @code{su -} or @code{sudo -i}.  As @code{root}, run:
+As root, run:
 
 @example
 # cd /tmp
-# tar --warning=no-timestamp -xf \
-     /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
-# mv var/guix /var/ && mv gnu /
-@end example
-
-This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
-The latter contains a ready-to-use profile for @code{root} (see next
-step).
-
-Do @emph{not} unpack the tarball on a working Guix system since that
-would overwrite its own essential files.
-
-The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
-not emit warnings about ``implausibly old time stamps'' (such
-warnings were triggered by GNU@tie{}tar 1.26 and older; recent
-versions are fine).
-They stem from the fact that all the
-files in the archive have their modification time set to 1 (which
-means January 1st, 1970).  This is done on purpose to make sure the
-archive content is independent of its creation time, thus making it
-reproducible.
-
-@item
-Make the profile available under @file{~root/.config/guix/current}, which is
-where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
-
-@example
-# mkdir -p ~root/.config/guix
-# ln -sf /var/guix/profiles/per-user/root/current-guix \
-         ~root/.config/guix/current
-@end example
-
-Source @file{etc/profile} to augment @env{PATH} and other relevant
-environment variables:
-
-@example
-# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
-  source $GUIX_PROFILE/etc/profile
-@end example
-
-@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}).
-
-@item
-Run the daemon, and set it to automatically start on boot.
-
-If your host distro uses the systemd init system, this can be achieved
-with these commands:
-
-@c Versions of systemd that supported symlinked service files are not
-@c yet widely deployed, so we should suggest that users copy the service
-@c files into place.
-@c
-@c See this thread for more information:
-@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
-     ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
-     /etc/systemd/system/
-# systemctl enable --now gnu-store.mount guix-daemon
-@end example
-
-You may also want to arrange for @command{guix gc} to run periodically:
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
-     ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
-     /etc/systemd/system/
-# systemctl enable --now guix-gc.timer
-@end example
-
-You may want to edit @file{guix-gc.service} to adjust the command line
-options to fit your needs (@pxref{Invoking guix gc}).
-
-If your host distro uses the Upstart init system:
-
-@example
-# initctl reload-configuration
-# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
-     /etc/init/
-# start guix-daemon
-@end example
-
-Otherwise, you can still start the daemon manually with:
-
-@example
-# ~root/.config/guix/current/bin/guix-daemon \
-       --build-users-group=guixbuild
-@end example
-
-@item
-Make the @command{guix} command available to other users on the machine,
-for instance with:
-
-@example
-# mkdir -p /usr/local/bin
-# cd /usr/local/bin
-# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @end example
 
-It is also a good idea to make the Info version of this manual available
-there:
-
-@example
-# mkdir -p /usr/local/share/info
-# cd /usr/local/share/info
-# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
-  do ln -s $i ; done
-@end example
-
-That way, assuming @file{/usr/local/share/info} is in the search path,
-running @command{info guix} will open this manual (@pxref{Other Info
-Directories,,, texinfo, GNU Texinfo}, for more details on changing the
-Info search path).
+@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.
 
-@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:
+@code{@value{SUBSTITUTE-SERVER-2}}, or a mirror (@pxref{Substitutes}),
+you must authorize them.  For example,
 
 @example
 # guix archive --authorize < \
@@ -947,44 +801,11 @@ authorize them:
 # 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
 
-@item
-Each user may need to perform a few additional steps to make their Guix
-environment ready for use, @pxref{Application Setup}.
-@end enumerate
-
-Voilà, the installation is complete!
-
-You can confirm that Guix is working by installing a sample package into
-the root profile:
-
-@example
-# guix install hello
-@end example
-
-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.
+When you're done installing Guix, @pxref{Application Setup} for extra
+configuration you might need, and @ref{Getting Started} for your first
+steps!
 
 @node Requirements
 @section Requirements

Re: doc: Removing much of Binary Installation

[Suhail Singh]

Matt <matt@excalamus.com> writes:

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

FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who
don't care if there is an easy way to uninstall Guix would be better
served by using =guix-install.sh= as opposed to =zypper=.  The issues of
"unnecessary files" applies to Tumbleweed as well (and I believe the
same would be true for Debian as well).

In addition, the manpages can get out of sync.  The reason for the
latter is that doing =sudo -i guix pull --fallback= doesn't generate
manpages.  However, the version of Guix installed via =zypper= does
install manpages (presumably generated via =help2man=).  As such, after
updating Guix, running something like =man guix= results in outdated
manpage being shown.  If Guix installation is done via
=guix-install.sh=, no manpage is shown which, in my opinion, is the
lesser evil.

On a related note, it would help if Guix would install manpages in
addition to infopages.  Not sure if this omission constitutes a bug or a
missing feature.

-- 
Suhail

Re: doc: Removing much of Binary Installation

[Suhail Singh]

Suhail Singh <suhailsingh247@gmail.com> writes:

> FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who
> don't care if there is an easy way to uninstall Guix would be better
> served by using =guix-install.sh= as opposed to =zypper=.

Btw, for completeness, on Tumbleweed, the user needs to take some
additional steps to ensure that restoring a previous Tumbleweed snapshot
doesn't revert Guix state.  Unless I'm misremembering, these steps are
needed regardless of whether =zypper= or =guix-install.sh= was used to
install Guix.

-- 
Suhail

Re: doc: Removing much of Binary Installation

[pelzflorian (Florian Pelz)]

Hello Matt and all.  As a more proper review, I first tried
guix-install.sh on a Debian GNU/Hurd VM.  It fails, telling me:

[1709825168.049]: [ INFO ] init system is: sysv-init
[1709825168.059]: [ FAIL ] Unsupported CPU type: i686-AT386

The script guix-install.sh cannot be used on any GNU/Hurd system.
Vagrant’s guix package is missing on Debian GNU/Hurd as well, which is
fine of course, but we should not claim otherwise.  Therefore, could you
change it like the old instructions and only talk about GNU/Linux?

> If, instead, you want to install the complete GNU operating system,
> @pxref{System Installation}.

Maybe better say “complete Guix operating system”?  *complete* GNU
operating system maybe should only be used for GNU/Hurd.

You suggested in your mail:

Matt <matt@excalamus.com> writes:
> Readers interested
> in those details may read the code for 'guix-install.sh'.

Could you add this suggestion to your diff?

Further:

IIRC, you are removing the manual installation.  Therefore, the sentence
would have to be removed: “The following sections describe two methods
of installation, binary installation and building from source.”

Also,

Matt <matt@excalamus.com> writes:
> - Add commas in appropriate places; after "For...Ubuntu-based
> systems", "Likewise", and the 'or' within the list of substitutes

I’m not a native speaker, but I believe the commas are not necessary.
There particularly does not need to be an Oxford comma before ‘or’.
There could be, but there is no reason to change it.

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”.

At the beginning, “You can install the Guix package management tool on
top of an existing” makes it appear as if Guix were not a distribution.
It is both a tool and a distro.  A distro does not need to be an OS.
For example, MSYS2 is a distribution.  I therefore nitpickingly prefer
“You can install Guix”.  Admittedly, the wording was vague before,
perhaps deliberately.

“Use of @file{guix-install.sh} requires Bash, GNU@tie{}tar, wget, and
Xz.” is incomplete when applied to guix-install.sh, which also requires
GnuPG.

Regards,
Florian

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

[Matt]

[-- Attachment #1: Type: text/plain, Size: 8581 bytes --]

I realigned the subject.  It was previously changed to "doc: Removing much of Binary Installation" which is misleading.  The topic is how to clarify installation based on reported confusion, not about removing text.  The reported confusion was on the use of '~root'.  Explicit mention of '~root' is only necessary when the manual details how 'guix-install.sh' works.  Since 'guix-install.sh' is the recommended method of installation, such level of detail is unnecessary, inappropriate, and impractical.  The suggested changes address the issue, only incidentally, by removing text.

I respond to Suhail Singh, Vagrant Cascadian, and pelzflorian in order.

---- On Wed, 06 Mar 2024 22:18:33 +0100  Suhail Singh  wrote ---
> Suhail Singh suhailsingh247@gmail.com> writes:
>
> > FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who don't care if there is an easy way to uninstall Guix would be better served by using =guix-install.sh= as opposed to =zypper=.
> Btw, for completeness, on Tumbleweed, the user needs to take some additional steps to ensure that restoring a previous Tumbleweed snapshot doesn't revert Guix state.  Unless I'm misremembering, these steps are needed regardless of whether =zypper= or =guix-install.sh= was used to install Guix.

Thank you for this.  I want to follow up with Vagrant and Florian first before responding more fully.

---- On Wed, 06 Mar 2024 22:29:23 +0100  Vagrant Cascadian  wrote ---
> As the one who packaged and maintains guix in Debian...

Thank you for doing this work!

> The guix-daemon should continue to work from the packaged version, although as guix develops more and more features; how long an old version can be expected to continue to work remains an open question.

I was under the impression that Guix installed through a foreign package manager is able to update with 'guix pull'.  This is what the current documentation says,

"If you’re running Debian or a derivative such as Ubuntu, you can instead install the package (it might be a version older than 0.0-git but you can update it afterwards by running ‘guix pull’):"

Is this correct?  Does 'guix pull' update Guix when installed through a foreign package manager?

---- On Thu, 07 Mar 2024 18:03:50 +0100  pelzflorian (Florian Pelz)  wrote ---

> I first tried guix-install.sh on a Debian GNU/Hurd VM.  It fails, telling me:
>
> [1709825168.049]: [ INFO ] init system is: sysv-init
> [1709825168.059]: [ FAIL ] Unsupported CPU type: i686-AT386
>
> The script guix-install.sh cannot be used on any GNU/Hurd system.

Thanks for taking the time to test 'guix-install.sh' on Hurd.  This looks like a bug.

> Vagrant’s guix package is missing on Debian GNU/Hurd as well, which is fine of course, but we should not claim otherwise.

Updated to specify "distributions" as "GNU/Linux distributions".

> Therefore, could you change it like the old instructions and only talk about GNU/Linux?

I don't think that's appropriate.  Guix supports GNU/Linux and GNU/Hurd and the installation section needs to cover both.

There are two issues here:

1) Up to this point, the manual doesn't make clear that current GNU/Hurd support is limited

I've duplicated the footnote from the 'operating-system Reference' section which explains the current status of GNU/Hurd support: https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html

2) 'guix-install.sh' has a bug preventing installation on GNU/Hurd

Any takers?

> > If, instead, you want to install the complete GNU operating system, @pxref{System Installation}.
>
> Maybe better say “complete Guix operating system”?  *complete* GNU operating system maybe should only be used for GNU/Hurd.

That line is directly copied from the current manual: https://guix.gnu.org/en/manual/en/html_node/Installation.html#FOOT4

I saw this and I agree with you.  It would be better stated as something like you suggest.  My intent was to do this in a separate patch.

> You suggested in your mail:
>
> Matt matt@excalamus.com> writes:
> > Readers interested in those details may read the code for 'guix-install.sh'.
>
> Could you add this suggestion to your diff?

I don't see that as relevant to the reader.  The ability to read the source is implicit in it being provided, which it is.

> IIRC, you are removing the manual installation.

Yes? No? I'm not sure how to respond.

The suggested changes remove superfluous commentary on the recommended binary installation process which create confusion.

The challenge in directly responding to your statement is there's not a clear cut-off between "install" and "configure."  To install, generally, means something like "situate artifacts so the user can make use of them".  Often, this is simply adding a directory to PATH.  Guix isn't that simple.  It requires setting up the store, var/guix, configuring the demon, setting up profiles, and other things.  That's all part of "so the user can make use of them" which is more "configuration" than "installation".  Which specific configuration is necessary, however, depends on the system and the user.  Detailing that at the level of "type this, type that" requires many caveats, explanations, and updates that don't really address the core topic: get Guix on a reader's system so that they can use it.  That, as far as I can tell, is the fundamental reason why 'guix-install.sh' exists.

What do you think is lost that isn't captured by the following bulleted list?

+The script guides you through the following:
+@itemize
+@item Download and extract the binary tarball
+@item Set up the build daemon
+@item Make the ‘guix’ command available to non-root users
+@item Configure substitute servers
+@end itemize

> Therefore, the sentence would have to be removed: “The following sections describe two methods of installation, binary installation and building from source.”

I've removed that sentence for a different reason.  I also revised the sentence, "This is often quicker than installing from source, which is described in the next sections", to simply, "described later".

The reason is that Chapter 2 doesn't currently explain building or installing from source.  Building and installing from source is currently covered much later in Section 22.1.  Whether or not the Installation section should cover building from source is a separate issue and shouldn't be part of this discussion.

> Also,
>
> Matt matt@excalamus.com> writes:
> > - Add commas in appropriate places; after "For...Ubuntu-based systems", "Likewise", and the 'or' within the list of substitutes
>
> I’m not a native speaker, but I believe the commas are not necessary.  There particularly does not need to be an Oxford comma before ‘or’.  There could be, but there is no reason to change it.

Ah, the One True Brace Style of natural language :)

I think there's already enough controversy in this thread.  I've changed it back :)

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

> At the beginning, “You can install the Guix package management tool on top of an existing” makes it appear as if Guix were not a distribution.  It is both a tool and a distro.  A distro does not need to be an OS.  For example, MSYS2 is a distribution.  I therefore nitpickingly prefer “You can install Guix”.  Admittedly, the wording was vague before, perhaps deliberately.

I don't follow you.  The complete sentence is:

"You can install the Guix package management tool on top of an existing GNU/Linux or GNU/Hurd system, referred to as a foreign distro, or as a standalone operating system distribution, the Guix System."

What about that is unclear?

> “Use of @file{guix-install.sh} requires Bash, GNU@tie{}tar, wget, and Xz.” is incomplete when applied to guix-install.sh, which also requires GnuPG.

Added! Thank you.

An updated diff is included.  I tried to split it into separate commits but couldn't.  That's very, very hard and probably impossible to do in an independent way.  My hope is that we can settle on language for this topic and try for a more step-wise approach on the next feedback item.

[-- Attachment #2: v03-refactor-binary-installation-section.diff --]
[-- Type: application/octet-stream, Size: 12622 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 858d5751bf..9113cd0152 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -691,20 +691,23 @@ to join!  @xref{Contributing}, for information about how you can help.
 @chapter Installation
 
 @cindex installing Guix
+@cindex foreign distro
+@cindex Guix System
+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.  Using GNU@tie{}mach with the GNU@tie{}Hurd
+is experimental and only available when building a virtual machine disk
+image.}, referred to as a @dfn{foreign distro}, or as a standalone
+operating system distribution, the @dfn{Guix@tie{}System}.  This section
+is concerned with the installation of Guix on a foreign distro.  If,
+instead, you want to install the complete GNU operating system,
+@pxref{System Installation}.
 
-@quotation Note
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script} to install Guix on top of a running GNU/Linux system,
-thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
-with the installation of the package manager, which can be done on top of a
-running GNU/Linux system.  If, instead, you want to install the complete GNU
-operating system, @pxref{System Installation}.} The script automates the
-download, installation, and initial configuration of Guix.  It should be run
-as the root user.
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 @end quotation
 
-@cindex foreign distro
 @cindex directories related to foreign distro
 When installed on a foreign distro, GNU@tie{}Guix complements the available
 tools without interference.  Its data lives exclusively in two directories,
@@ -714,11 +717,6 @@ such as @file{/etc}, are left untouched.
 Once installed, Guix can be updated by running @command{guix pull}
 (@pxref{Invoking guix pull}).
 
-If you prefer to perform the installation steps manually or want to tweak
-them, you may find the following subsections useful.  They describe the
-software requirements of Guix, as well as how to install it manually and get
-ready to use it.
-
 @menu
 * Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
@@ -736,210 +734,64 @@ ready to use it.
 @cindex installer script
 This section describes how to install Guix from a self-contained tarball
 providing binaries for Guix and for all its dependencies.  This is often
-quicker than installing from source, which is described in the next
-sections.  Binary installation requires a system using a Hurd or Linux
-kernel; the GNU@tie{}tar and Xz commands must also be available.
+quicker than installing from source, described later.
 
 @quotation Important
 This section only applies to systems without Guix.  Following it for
 existing Guix installations will overwrite important system files.
+@end quotation
 
-@c Note duplicated from the ``Installation'' node.
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script}.  The script automates the download, installation, and
-initial configuration steps described below.  It should be run as the root
-user.  As root, you can thus run this:
-
-@example
-cd /tmp
-wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
-chmod +x guix-install.sh
-./guix-install.sh
-@end example
+Some GNU/Linux distributions, such as Debian, Ubuntu, and openSUSE
+provide Guix through their own package managers.  The version of Guix
+may be older than @value{VERSION} but you can update it afterwards by
+running @samp{guix pull}.
 
-If you're running Debian or a derivative such as Ubuntu, you can instead
-install the package (it might be a version older than @value{VERSION}
-but you can update it afterwards by running @samp{guix pull}):
+For Debian and Ubuntu-based systems, call:
 
 @example
 sudo apt install guix
 @end example
 
-Likewise on openSUSE:
+Likewise, on openSUSE:
 
 @example
 sudo zypper install guix
 @end example
 
-When you're done, @pxref{Application Setup} for extra configuration you
-might need, and @ref{Getting Started} for your first steps!
-@end quotation
-
-Installing goes along these lines:
+The Guix project also provides a shell script, @file{guix-install.sh},
+which automates the binary installation process without use of a foreign
+distro package
+manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}.
+Use of @file{guix-install.sh} requires Bash, GnuPG, GNU@tie{}tar, wget,
+and Xz.
 
-@enumerate
-@item
-@cindex downloading Guix binary
-Download the binary tarball from
-@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
-where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
-@code{i686} (32-bits) machine already running the kernel Linux, and so on
-(@pxref{GNU Distribution}).
-
-@c The following is somewhat duplicated in ``System Installation''.
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the tarball against it, along these lines:
-
-@example
-$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-@end example
+The script guides you through the following:
 
-If that command fails because you do not have the required public key,
-then run this command to import it:
-
-@example
-$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-      -qO - | gpg --import -
-@end example
-
-@noindent
-and rerun the @code{gpg --verify} command.
-
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
-
-@c end authentication part
+@itemize
+@item Download and extract the binary tarball
+@item Set up the build daemon
+@item Make the ‘guix’ command available to non-root users
+@item Configure substitute servers
+@end itemize
 
-@item
-Now, you need to become the @code{root} user.  Depending on your distribution,
-you may have to run @code{su -} or @code{sudo -i}.  As @code{root}, run:
+As root, run:
 
 @example
 # cd /tmp
-# tar --warning=no-timestamp -xf \
-     /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
-# mv var/guix /var/ && mv gnu /
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @end example
 
-This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
-The latter contains a ready-to-use profile for @code{root} (see next
-step).
-
-Do @emph{not} unpack the tarball on a working Guix system since that
-would overwrite its own essential files.
-
-The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
-not emit warnings about ``implausibly old time stamps'' (such
-warnings were triggered by GNU@tie{}tar 1.26 and older; recent
-versions are fine).
-They stem from the fact that all the
-files in the archive have their modification time set to 1 (which
-means January 1st, 1970).  This is done on purpose to make sure the
-archive content is independent of its creation time, thus making it
-reproducible.
-
-@item
-Make the profile available under @file{~root/.config/guix/current}, which is
-where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
-
-@example
-# mkdir -p ~root/.config/guix
-# ln -sf /var/guix/profiles/per-user/root/current-guix \
-         ~root/.config/guix/current
-@end example
-
-Source @file{etc/profile} to augment @env{PATH} and other relevant
-environment variables:
-
-@example
-# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
-  source $GUIX_PROFILE/etc/profile
-@end example
-
-@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}).
-
-@item
-Run the daemon, and set it to automatically start on boot.
-
-If your host distro uses the systemd init system, this can be achieved
-with these commands:
-
-@c Versions of systemd that supported symlinked service files are not
-@c yet widely deployed, so we should suggest that users copy the service
-@c files into place.
-@c
-@c See this thread for more information:
-@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
-     ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
-     /etc/systemd/system/
-# systemctl enable --now gnu-store.mount guix-daemon
-@end example
-
-You may also want to arrange for @command{guix gc} to run periodically:
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
-     ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
-     /etc/systemd/system/
-# systemctl enable --now guix-gc.timer
-@end example
-
-You may want to edit @file{guix-gc.service} to adjust the command line
-options to fit your needs (@pxref{Invoking guix gc}).
-
-If your host distro uses the Upstart init system:
-
-@example
-# initctl reload-configuration
-# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
-     /etc/init/
-# start guix-daemon
-@end example
-
-Otherwise, you can still start the daemon manually with:
-
-@example
-# ~root/.config/guix/current/bin/guix-daemon \
-       --build-users-group=guixbuild
-@end example
-
-@item
-Make the @command{guix} command available to other users on the machine,
-for instance with:
-
-@example
-# mkdir -p /usr/local/bin
-# cd /usr/local/bin
-# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
-@end example
-
-It is also a good idea to make the Info version of this manual available
-there:
-
-@example
-# mkdir -p /usr/local/share/info
-# cd /usr/local/share/info
-# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
-  do ln -s $i ; done
-@end example
-
-That way, assuming @file{/usr/local/share/info} is in the search path,
-running @command{info guix} will open this manual (@pxref{Other Info
-Directories,,, texinfo, GNU Texinfo}, for more details on changing the
-Info search path).
+@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.
 
-@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:
+you must authorize them.  For example,
 
 @example
 # guix archive --authorize < \
@@ -947,44 +799,11 @@ authorize them:
 # 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
 
-@item
-Each user may need to perform a few additional steps to make their Guix
-environment ready for use, @pxref{Application Setup}.
-@end enumerate
-
-Voilà, the installation is complete!
-
-You can confirm that Guix is working by installing a sample package into
-the root profile:
-
-@example
-# guix install hello
-@end example
-
-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.
+When you're done installing Guix, @pxref{Application Setup} for extra
+configuration you might need, and @ref{Getting Started} for your first
+steps!
 
 @node Requirements
 @section Requirements
@@ -17643,6 +17462,7 @@ configuration (@pxref{Using the Configuration System}).
 
 @table @asis
 @item @code{kernel} (default: @code{linux-libre})
+@c footnote duplicated in @pxref{Installation}
 The package object of the operating system kernel to
 use@footnote{Currently only the Linux-libre kernel is fully supported.
 Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only

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

[Vagrant Cascadian]

[-- Attachment #1: Type: text/plain, Size: 1655 bytes --]

On 2024-03-10, matt@excalamus.com wrote:
> ---- On Wed, 06 Mar 2024 22:29:23 +0100  Vagrant Cascadian  wrote ---
>> As the one who packaged and maintains guix in Debian...
>
> Thank you for doing this work!
>
>> The guix-daemon should continue to work from the packaged version, although as guix develops more and more features; how long an old version can be expected to continue to work remains an open question.
>
> I was under the impression that Guix installed through a foreign package manager is able to update with 'guix pull'.  This is what the current documentation says,
>
> "If you’re running Debian or a derivative such as Ubuntu, you can instead install the package (it might be a version older than 0.0-git but you can update it afterwards by running ‘guix pull’):"
>
> Is this correct?  Does 'guix pull' update Guix when installed through a foreign package manager?

Yes, with the guix packages provided by Debian, generally I would
recommend doing "guix pull" to get current packages (a lot has changed
since guix 1.4!) ... but "guix pull" does not update the running
guix-daemon; that is not the responsibility of "guix pull".

There is also the classic issue of updating PATH and other environment
variables after the first "guix pull" but that is not unique to the
packages from Debian.

A newly pulled guix should continue to remain compatible with older
guix-daemon to some extent, but it may be missing new guix-daemon
features (and possibly security updates, though those are grounds for
getting it fixed in the package), and possibly someday may no longer be
compatible.

live well,
  vagrant

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

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

[Suhail Singh]

Vagrant Cascadian <vagrant@debian.org> writes:

> but "guix pull" does not update the running guix-daemon;

Just to be clear, however, if one were to do =sudo -i guix pull=
instead, followed by =systemctl restart guix-daemon.service= it /would/
update the running guix-daemon on Debian, correct?  Or is that not the
case?  In other words, on Debian, does the systemd unit reference
=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?

-- 
Suhail

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

[Vagrant Cascadian]

[-- Attachment #1: Type: text/plain, Size: 877 bytes --]

On 2024-03-10, Suhail Singh wrote:
> Vagrant Cascadian <vagrant@debian.org> writes:
>> but "guix pull" does not update the running guix-daemon;
>
> Just to be clear, however, if one were to do =sudo -i guix pull=
> instead, followed by =systemctl restart guix-daemon.service= it /would/
> update the running guix-daemon on Debian, correct?  Or is that not the
> case?

No, out of the box guix-daemon is provided by the Debian guix package.


> In other words, on Debian, does the systemd unit reference
> =/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?

But you could provide an override pointing at whatever guix-daemon you
want, of course! :)

Once you do that, you may as well remove the Debian packaged guix,
although users that have not yet run "guix pull" would need to guess
where to find guix, as there will be no guix on PATH.


live well,
  vagrant

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

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

[John Kehayias]

Hi vagrant,


On Sunday, March 10th, 2024 at 9:58 PM, Vagrant Cascadian <vagrant@debian.org> wrote:

> 
> 
> On 2024-03-10, Suhail Singh wrote:
> 
> > Vagrant Cascadian vagrant@debian.org writes:
> > 
> > > but "guix pull" does not update the running guix-daemon;
> > 
> > Just to be clear, however, if one were to do =sudo -i guix pull=
> > instead, followed by =systemctl restart guix-daemon.service= it /would/
> > update the running guix-daemon on Debian, correct? Or is that not the
> > case?
> 
> 
> No, out of the box guix-daemon is provided by the Debian guix package.
> 

That means the instructions to update the guix daemon in the manual, <https://guix.gnu.org/en/manual/devel/en/html_node/Upgrading-Guix.html> is incorrect or doesn't work? Or am I misunderstanding what you meant here?

(I know in the past some discussions have come up about older guix-daemon on foreign distros, presumably because the packages there don't get updated and a user wouldn't think to upgrade guix separately? But it seems you are saying you can't upgrade without modifying the e.g. systemd service definition? This is also important for security updates to guix itself, of course.)

> > In other words, on Debian, does the systemd unit reference
> > =/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?
> 
> 
> But you could provide an override pointing at whatever guix-daemon you
> want, of course! :)
> 
> Once you do that, you may as well remove the Debian packaged guix,
> although users that have not yet run "guix pull" would need to guess
> where to find guix, as there will be no guix on PATH.
> 
> 
> live well,
> vagrant

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

[Vagrant Cascadian]

[-- Attachment #1: Type: text/plain, Size: 2536 bytes --]

On 2024-03-11, John Kehayias wrote:
> On Sunday, March 10th, 2024 at 9:58 PM, Vagrant Cascadian <vagrant@debian.org> wrote:
>> On 2024-03-10, Suhail Singh wrote:
>> 
>> > Vagrant Cascadian vagrant@debian.org writes:
>> > 
>> > > but "guix pull" does not update the running guix-daemon;
>> > 
>> > Just to be clear, however, if one were to do =sudo -i guix pull=
>> > instead, followed by =systemctl restart guix-daemon.service= it /would/
>> > update the running guix-daemon on Debian, correct? Or is that not the
>> > case?
>> 
>> 
>> No, out of the box guix-daemon is provided by the Debian guix package.
>> 
>
> That means the instructions to update the guix daemon in the manual,
> <https://guix.gnu.org/en/manual/devel/en/html_node/Upgrading-Guix.html>
> is incorrect or doesn't work? Or am I misunderstanding what you meant
> here?

I presume it works fine if you install from the GNU Guix binary tarball,
but not with the Debian guix packages without configuring systemd or
whatever init system to use the guix daemon provided by "guix pull".


> (I know in the past some discussions have come up about older
> guix-daemon on foreign distros, presumably because the packages there
> don't get updated and a user wouldn't think to upgrade guix
> separately? But it seems you are saying you can't upgrade without
> modifying the e.g. systemd service definition? This is also important
> for security updates to guix itself, of course.)

As with other packages in Debian, security updates would, at least in
theory, be uploaded via Debian's security update process, like any other
package in Debian... unless you actually configure it to work like the
instructions above (e.g. add a systemd override).

At least once, I pulled patches from guix upstream into the Debian
package to resolve security issues in the Debian packages.

Just to be absolutely clear here, "guix pull" and whatnot works fine;
that part of upgrading is no different than Guix System or Guix Binary
installation on a foreign distro.


live well,
  vagrant

>> > In other words, on Debian, does the systemd unit reference
>> > =/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?
>> 
>> 
>> But you could provide an override pointing at whatever guix-daemon you
>> want, of course! :)
>> 
>> Once you do that, you may as well remove the Debian packaged guix,
>> although users that have not yet run "guix pull" would need to guess
>> where to find guix, as there will be no guix on PATH.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

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

[pelzflorian (Florian Pelz)]

Hi Matt.  I would almost want to push your changes, but we still
disagree on some wordings.

Also,

Matt <matt@excalamus.com> writes:
> I realigned the subject.  It was previously changed to "doc: Removing
> much of Binary Installation" which is misleading.  The topic is how to
> clarify installation based on reported confusion, not about removing
> text.  The reported confusion was on the use of '~root'.  Explicit
> mention of '~root' is only necessary when the manual details how
> 'guix-install.sh' works.  Since 'guix-install.sh' is the recommended
> method of installation, such level of detail is unnecessary,
> inappropriate, and impractical.  The suggested changes address the
> issue, only incidentally, by removing text.

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.


> +@cindex foreign distro
> +@cindex Guix System

“@cindex Guix System” is inappropriate, because instructions on Guix
System are not here.


> +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”.

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.  Additionally “only the
Linux-libre kernel” is incorrect, because running Guix on non-libre
Linux is fully supported.  Running Guix System there is not supported
(by us).


>> You suggested in your mail:
>>
>> Matt matt@excalamus.com> writes:
>> > Readers interested in those details may read the code for 'guix-install.sh'.
>>
>> Could you add this suggestion to your diff?
>
> I don't see that as relevant to the reader.  The ability to read the
> source is implicit in it being provided, which it is.

Yes, you are right.


> The suggested changes remove superfluous commentary on the recommended
> binary installation process which create confusion.

“remove superfluous commentary” could be part of a commit message for
your changes, if you agree.


> What do you think is lost that isn't captured by the following bulleted list?
>
> +The script guides you through the following:
> +@itemize
> +@item Download and extract the binary tarball
> +@item Set up the build daemon
> +@item Make the ‘guix’ command available to non-root users
> +@item Configure substitute servers
> +@end itemize

The list is fine.


>> Therefore, the sentence would have to be removed: “The following
>> sections describe two methods of installation, binary installation
>> and building from source.”
>
> I've removed that sentence for a different reason.  I also revised the
> sentence, "This is often quicker than installing from source, which is
> described in the next sections", to simply, "described later".
>
> The reason is that Chapter 2 doesn't currently explain building or
> installing from source.  Building and installing from source is
> currently covered much later in Section 22.1.  Whether or not the
> Installation section should cover building from source is a separate
> issue and shouldn't be part of this discussion.

This could be:

described later (@pxref{Building from Git}).


>> Matt matt@excalamus.com> writes:
>> > - Add commas in appropriate places; after "For...Ubuntu-based
>> > systems", "Likewise", and the 'or' within the list of substitutes
>>
>> I’m not a native speaker, but I believe the commas are not
>> necessary.  There particularly does not need to be an Oxford comma
>> before ‘or’.  There could be, but there is no reason to change it.
>
> Ah, the One True Brace Style of natural language :)
>
> I think there's already enough controversy in this thread.  I've changed it back :)

:D  However, please also do not change:

> -Likewise on openSUSE:
> +Likewise, on openSUSE:



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


> +@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.


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.

Regards,
Florian

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

[Matt]

[-- Attachment #1: Type: text/plain, Size: 10598 bytes --]

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), 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 ---
> Hi Matt.  I would almost want to push your changes, but we still
> disagree on some wordings.

I'm glad to hear the suggested changes are more acceptable than not.
Let's do what we need to get things right.

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

> > +@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.  No
mention of 'guix-install.sh' is made on that page.

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.  This is
exactly what the suggested changes say, minus the emphasis.  As far as
I know, it's true:

1. https://guix.gnu.org/en/blog/2020/a-hello-world-virtual-machine-running-the-hurd/
2. https://guix.gnu.org/en/blog/2020/childhurds-and-substitutes/

Further, the manual already mentions Hurd support:
https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html

Beyond the manual, there are two blog posts (linked above) which have explicit
sections about why it makes sense to develop for Hurd.  Code for Hurd
is mainlined with 80 files in the master branch providing Hurd
support.

I get it, it's the Hurd.  Running Guix on Hurd was part of a joke.
Correct me if I'm wrong, though: Hurd support wasn't the punchline,
ending support for Linux was.  The part that said, "running on the
Hurd was always a goal for Guix" is sincere.

So, what should be said is that Hurd support is limited.  Any errors
are bugs, either for Guix or for upstream.

I've updated the footnote to warn that Hurd support is currently
limited.

> Additionally “only the Linux-libre kernel” is incorrect, because
> running Guix on non-libre Linux is fully supported.  Running Guix
> System there is not supported (by us).

Excellent point: the package manager is indeed supported on non-free
distros.  I had carelessly copied the footnote, and the text containing this
issue, from another section.  The update on the previous point,
regarding Hurd support, removes this issue by removing mention of
Linux.

> >> Therefore, the sentence would have to be removed: “The following
> >> sections describe two methods of installation, binary installation
> >> and building from source.”
> >
> > I've removed that sentence for a different reason.  I also revised the
> > sentence, "This is often quicker than installing from source, which is
> > described in the next sections", to simply, "described later".
> >
> > The reason is that Chapter 2 doesn't currently explain building or
> > installing from source.  Building and installing from source is
> > currently covered much later in Section 22.1.  Whether or not the
> > Installation section should cover building from source is a separate
> > issue and shouldn't be part of this discussion.
>
> This could be:
>
> described later (@pxref{Building from Git}).

Updated.

> >> Matt matt@excalamus.com> writes:
> >> > - Add commas in appropriate places; after "For...Ubuntu-based
> >> > systems", "Likewise", and the 'or' within the list of substitutes
> >>
> >> I’m not a native speaker, but I believe the commas are not
> >> necessary.  There particularly does not need to be an Oxford comma
> >> before ‘or’.  There could be, but there is no reason to change it.
> >
> > Ah, the One True Brace Style of natural language :)
> >
> > I think there's already enough controversy in this thread.  I've changed it back :)
>
> :D  However, please also do not change:
>
> > -Likewise on openSUSE:
> > +Likewise, on openSUSE:

Corrected.

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

> > +@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 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.

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

[-- Attachment #2: v04-refactor-binary-installation-section.diff --]
[-- Type: application/octet-stream, Size: 12451 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 796ac0028f..844e8df135 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -691,20 +691,20 @@ to join!  @xref{Contributing}, for information about how you can help.
 @chapter Installation
 
 @cindex installing Guix
+@cindex foreign distro
+You can install the Guix package management tool on top of an existing
+GNU/Linux or GNU/Hurd system@footnote{Hurd support is currently
+limited.}, referred to as a @dfn{foreign distro}, or as a standalone
+operating system distribution, the @dfn{Guix@tie{}System}.  This section
+is concerned with the installation of Guix on a foreign distro.  If,
+instead, you want to install the complete GNU operating system,
+@pxref{System Installation}.
 
-@quotation Note
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script} to install Guix on top of a running GNU/Linux system,
-thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
-with the installation of the package manager, which can be done on top of a
-running GNU/Linux system.  If, instead, you want to install the complete GNU
-operating system, @pxref{System Installation}.} The script automates the
-download, installation, and initial configuration of Guix.  It should be run
-as the root user.
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 @end quotation
 
-@cindex foreign distro
 @cindex directories related to foreign distro
 When installed on a foreign distro, GNU@tie{}Guix complements the available
 tools without interference.  Its data lives exclusively in two directories,
@@ -714,11 +714,6 @@ such as @file{/etc}, are left untouched.
 Once installed, Guix can be updated by running @command{guix pull}
 (@pxref{Invoking guix pull}).
 
-If you prefer to perform the installation steps manually or want to tweak
-them, you may find the following subsections useful.  They describe the
-software requirements of Guix, as well as how to install it manually and get
-ready to use it.
-
 @menu
 * Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
@@ -736,31 +731,20 @@ ready to use it.
 @cindex installer script
 This section describes how to install Guix from a self-contained tarball
 providing binaries for Guix and for all its dependencies.  This is often
-quicker than installing from source, which is described in the next
-sections.  Binary installation requires a system using a Hurd or Linux
-kernel; the GNU@tie{}tar and Xz commands must also be available.
+quicker than installing from source, described later (@pxref{Building
+from Git}).
 
 @quotation Important
 This section only applies to systems without Guix.  Following it for
 existing Guix installations will overwrite important system files.
+@end quotation
 
-@c Note duplicated from the ``Installation'' node.
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script}.  The script automates the download, installation, and
-initial configuration steps described below.  It should be run as the root
-user.  As root, you can thus run this:
-
-@example
-cd /tmp
-wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
-chmod +x guix-install.sh
-./guix-install.sh
-@end example
+Some GNU/Linux distributions, such as Debian, Ubuntu, and openSUSE
+provide Guix through their own package managers.  The version of Guix
+may be older than @value{VERSION} but you can update it afterwards by
+running @samp{guix pull}.
 
-If you're running Debian or a derivative such as Ubuntu, you can instead
-install the package (it might be a version older than @value{VERSION}
-but you can update it afterwards by running @samp{guix pull}):
+For Debian and Ubuntu-based systems, call:
 
 @example
 sudo apt install guix
@@ -772,174 +756,40 @@ Likewise on openSUSE:
 sudo zypper install guix
 @end example
 
-When you're done, @pxref{Application Setup} for extra configuration you
-might need, and @ref{Getting Started} for your first steps!
-@end quotation
-
-Installing goes along these lines:
-
-@enumerate
-@item
-@cindex downloading Guix binary
-Download the binary tarball from
-@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
-where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
-@code{i686} (32-bits) machine already running the kernel Linux, and so on
-(@pxref{GNU Distribution}).
-
-@c The following is somewhat duplicated in ``System Installation''.
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the tarball against it, along these lines:
-
-@example
-$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-@end example
-
-If that command fails because you do not have the required public key,
-then run this command to import it:
-
-@example
-$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-      -qO - | gpg --import -
-@end example
-
-@noindent
-and rerun the @code{gpg --verify} command.
+The Guix project also provides a shell script, @file{guix-install.sh},
+which automates the binary installation process without use of a foreign
+distro package
+manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}.
+Use of @file{guix-install.sh} requires Bash, GnuPG, GNU@tie{}tar, wget,
+and Xz.
 
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
+The script guides you through the following:
 
-@c end authentication part
+@itemize
+@item Download and extract the binary tarball
+@item Set up the build daemon
+@item Make the ‘guix’ command available to non-root users
+@item Configure substitute servers
+@end itemize
 
-@item
-Now, you need to become the @code{root} user.  Depending on your distribution,
-you may have to run @code{su -} or @code{sudo -i}.  As @code{root}, run:
+As root, run:
 
 @example
 # cd /tmp
-# tar --warning=no-timestamp -xf \
-     /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
-# mv var/guix /var/ && mv gnu /
-@end example
-
-This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
-The latter contains a ready-to-use profile for @code{root} (see next
-step).
-
-Do @emph{not} unpack the tarball on a working Guix system since that
-would overwrite its own essential files.
-
-The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
-not emit warnings about ``implausibly old time stamps'' (such
-warnings were triggered by GNU@tie{}tar 1.26 and older; recent
-versions are fine).
-They stem from the fact that all the
-files in the archive have their modification time set to 1 (which
-means January 1st, 1970).  This is done on purpose to make sure the
-archive content is independent of its creation time, thus making it
-reproducible.
-
-@item
-Make the profile available under @file{~root/.config/guix/current}, which is
-where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
-
-@example
-# mkdir -p ~root/.config/guix
-# ln -sf /var/guix/profiles/per-user/root/current-guix \
-         ~root/.config/guix/current
-@end example
-
-Source @file{etc/profile} to augment @env{PATH} and other relevant
-environment variables:
-
-@example
-# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
-  source $GUIX_PROFILE/etc/profile
-@end example
-
-@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}).
-
-@item
-Run the daemon, and set it to automatically start on boot.
-
-If your host distro uses the systemd init system, this can be achieved
-with these commands:
-
-@c Versions of systemd that supported symlinked service files are not
-@c yet widely deployed, so we should suggest that users copy the service
-@c files into place.
-@c
-@c See this thread for more information:
-@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
-     ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
-     /etc/systemd/system/
-# systemctl enable --now gnu-store.mount guix-daemon
-@end example
-
-You may also want to arrange for @command{guix gc} to run periodically:
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
-     ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
-     /etc/systemd/system/
-# systemctl enable --now guix-gc.timer
-@end example
-
-You may want to edit @file{guix-gc.service} to adjust the command line
-options to fit your needs (@pxref{Invoking guix gc}).
-
-If your host distro uses the Upstart init system:
-
-@example
-# initctl reload-configuration
-# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
-     /etc/init/
-# start guix-daemon
-@end example
-
-Otherwise, you can still start the daemon manually with:
-
-@example
-# ~root/.config/guix/current/bin/guix-daemon \
-       --build-users-group=guixbuild
-@end example
-
-@item
-Make the @command{guix} command available to other users on the machine,
-for instance with:
-
-@example
-# mkdir -p /usr/local/bin
-# cd /usr/local/bin
-# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @end example
 
-It is also a good idea to make the Info version of this manual available
-there:
-
-@example
-# mkdir -p /usr/local/share/info
-# cd /usr/local/share/info
-# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
-  do ln -s $i ; done
-@end example
-
-That way, assuming @file{/usr/local/share/info} is in the search path,
-running @command{info guix} will open this manual (@pxref{Other Info
-Directories,,, texinfo, GNU Texinfo}, for more details on changing the
-Info search path).
+@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.
 
-@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:
+you must authorize them.  For example,
 
 @example
 # guix archive --authorize < \
@@ -947,44 +797,11 @@ authorize them:
 # 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
 
-@item
-Each user may need to perform a few additional steps to make their Guix
-environment ready for use, @pxref{Application Setup}.
-@end enumerate
-
-Voilà, the installation is complete!
-
-You can confirm that Guix is working by installing a sample package into
-the root profile:
-
-@example
-# guix install hello
-@end example
-
-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.
+When you're done installing Guix, @pxref{Application Setup} for extra
+configuration you might need, and @ref{Getting Started} for your first
+steps!
 
 @node Requirements
 @section Requirements
@@ -17643,6 +17460,7 @@ configuration (@pxref{Using the Configuration System}).
 
 @table @asis
 @item @code{kernel} (default: @code{linux-libre})
+@c footnote duplicated in @pxref{Installation}
 The package object of the operating system kernel to
 use@footnote{Currently only the Linux-libre kernel is fully supported.
 Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only

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

[pelzflorian (Florian Pelz)]

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

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

[Ludovic Courtès]

Hi,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

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

I’d recommend sending it to guix-patches to make it more visible.

Ludo’.

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

[Vagrant Cascadian]

[-- Attachment #1: Type: text/plain, Size: 1831 bytes --]

On 2024-03-06, pelzflorian (Florian Pelz) wrote:
> 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]
>
> The reason of existence for these distribution packages is probably
> similar to the reason why the Binary Installation section exists.

Indeed, after the first guix pull, most of the packaged files are no
longer used.

As the one who packaged and maintains guix in Debian, my main motivation
was and is to have a trust path from debian; mainly not having to
manually verify the signatures of the manual installation method (I
would hazard to guess that the percentage of people who actually do
manually verify signatures is disturbingly small).

The guix-daemon should continue to work from the packaged version,
although as guix develops more and more features; how long an old
version can be expected to continue to work remains an open question.

I cannot say I have done a *great* job at maintaining guix in Debian,
but hopefully at least a passable job. Although there are some annoying
things that probably need to be fixed:

  https://bugs.debian.org/1064748
  a.k.a.
  https://issues.guix.gnu.org/69518

... or backported to Debian stable:

  https://bugs.debian.org/1036304
  https://bugs.debian.org/1038916


I have found a fair number of issues (especially typos!) to fix in
upstream guix as a result of packaging it for Debian, so if nothing
else, it is some quality assurance! :)


live well,
  vagrant

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

[-- Attachment #1: Type: text/plain, Size: 2300 bytes --]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first two items.

The next item reported is:

#+begin_quote
2.4 Setting up the deamon

Seems like an issue with info.  Have seen this in the Emacs manual as well.  There is also sometimes see see (doc)

L15 See also see Substitutes.
#+end_quote

This sounds like the use of an @xref instead of @ref.  However, I can't find it in the current version (5a95cf76) of the documentation, nor the reported version (ee7c9d25).  The last change to doc/guix.texi at that the reported time was in e5ed1712 (git log -n 1 ee7c9d25 -- doc/guix.texi).

The full reported sentence currently reads,

#+begin_quote
See also @ref{Substitutes}, for information on how to allow the daemon to download pre-built binaries.
#+end_quote

The use of the comma after "Substitutes" is inappropriate, if I have the terminology correct, because "See also Substitutes" is not a participial phrase.  "Also" and "information on" are also unnecessary.  I suggest the following:

#+begin_quote
See @ref{Substitutes} for how to allow the daemon to download pre-built binaries.
#+end_quote

Searching for "see also" turns up the following in 'Mail Services':

#+begin_quote
See also ssl=required setting.
#+end_quote

This needs "the" before "ssl=required" as it refers to a specific setting.  It should probably use the @option or @samp markup:

#+begin_quote
See also the @samp{ssl=required} setting.
#+end_quote

I have opted for @samp because it's used elsewhere for similar items.  In the same section is:

#+begin_quote
NOTE: See also @samp{disable-plaintext-auth} setting.
#+end_quote

This too should have "the" before the setting.  The "NOTE:" designation is also unnecessary.  I suggest:

#+begin_quote
See also the @samp{disable-plaintext-auth} setting.
#+end_quote

Included is a patch which makes these suggested changes.

It was advised to submit the previous patch to guix-patches.  I opted to submit this next patch here to keep the thread connected since it's part of a larger discussion (I suppose).  If we're agreed that guix-patches is more appropriate, I can submit the next item in a new thread there using the same message format I've been following.  Thoughts?

[-- Attachment #2: 0001-doc-Fix-grammar-and-markup.patch --]
[-- Type: application/octet-stream, Size: 1986 bytes --]

From 880264a6887621891a35e637788ddcd63c5bcb54 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Wed, 10 Apr 2024 15:44:36 +0200
Subject: [PATCH] doc: Fix grammar and markup

doc/guix.texi (Setting Up the Daemon): Remove comma and extra words.

doc/guix.texi (Mail Services): Add definite article to setting.  Use
@samp markup on setting.
---
 doc/guix.texi | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5827e0de14..5efbd00984 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -848,8 +848,8 @@ goes through the daemon.  For instance, command-line tools such as
 daemon (@i{via} remote procedure calls) to instruct it what to do.
 
 The following sections explain how to prepare the build daemon's
-environment.  See also @ref{Substitutes}, for information on how to allow
-the daemon to download pre-built binaries.
+environment.  See @ref{Substitutes} for how to allow the daemon to
+download pre-built binaries.
 
 @menu
 * Build Environment Setup::     Preparing the isolated build environment.
@@ -26641,7 +26641,7 @@ Disable LOGIN command and all other plaintext authentications unless
 SSL/TLS is used (LOGINDISABLED capability).  Note that if the remote IP
 matches the local IP (i.e.@: you're connecting from the same computer),
 the connection is considered secure and plaintext authentication is
-allowed.  See also ssl=required setting.
+allowed.  See also the @samp{ssl=required} setting.
 Defaults to @samp{#t}.
 @end deftypevr
 
@@ -26781,7 +26781,7 @@ Defaults to @samp{#f}.
 List of wanted authentication mechanisms.  Supported mechanisms are:
 @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
 @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
-@samp{otp}, @samp{skey}, and @samp{gss-spnego}.  NOTE: See also
+@samp{otp}, @samp{skey}, and @samp{gss-spnego}.  See also the
 @samp{disable-plaintext-auth} setting.
 @end deftypevr
 
-- 
2.41.0

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Christian Miller]

Hello,

I just want to mention that I am still in CC and my mail server is going 
offline. Need to optimize my budget and don't have any time for GNU 
anymore because of university.

--

Christian Miller

Am 10/04/2024 um 16:05 schrieb Matt:
> We're working through a list of feedback one item at a time:
> https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html
>
> We have completed the first two items.
>
> The next item reported is:
>
> #+begin_quote
> 2.4 Setting up the deamon
>
> Seems like an issue with info.  Have seen this in the Emacs manual as well.  There is also sometimes see see (doc)
>
> L15 See also see Substitutes.
> #+end_quote
>
> This sounds like the use of an @xref instead of @ref.  However, I can't find it in the current version (5a95cf76) of the documentation, nor the reported version (ee7c9d25).  The last change to doc/guix.texi at that the reported time was in e5ed1712 (git log -n 1 ee7c9d25 -- doc/guix.texi).
>
> The full reported sentence currently reads,
>
> #+begin_quote
> See also @ref{Substitutes}, for information on how to allow the daemon to download pre-built binaries.
> #+end_quote
>
> The use of the comma after "Substitutes" is inappropriate, if I have the terminology correct, because "See also Substitutes" is not a participial phrase.  "Also" and "information on" are also unnecessary.  I suggest the following:
>
> #+begin_quote
> See @ref{Substitutes} for how to allow the daemon to download pre-built binaries.
> #+end_quote
>
> Searching for "see also" turns up the following in 'Mail Services':
>
> #+begin_quote
> See also ssl=required setting.
> #+end_quote
>
> This needs "the" before "ssl=required" as it refers to a specific setting.  It should probably use the @option or @samp markup:
>
> #+begin_quote
> See also the @samp{ssl=required} setting.
> #+end_quote
>
> I have opted for @samp because it's used elsewhere for similar items.  In the same section is:
>
> #+begin_quote
> NOTE: See also @samp{disable-plaintext-auth} setting.
> #+end_quote
>
> This too should have "the" before the setting.  The "NOTE:" designation is also unnecessary.  I suggest:
>
> #+begin_quote
> See also the @samp{disable-plaintext-auth} setting.
> #+end_quote
>
> Included is a patch which makes these suggested changes.
>
> It was advised to submit the previous patch to guix-patches.  I opted to submit this next patch here to keep the thread connected since it's part of a larger discussion (I suppose).  If we're agreed that guix-patches is more appropriate, I can submit the next item in a new thread there using the same message format I've been following.  Thoughts?

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Pushed as cd557e2d1c83839dd587016279900d31f053efc8.

Matt <matt@excalamus.com> writes:
> The next item reported is:
>
> #+begin_quote
> 2.4 Setting up the deamon
>
> Seems like an issue with info.  Have seen this in the Emacs manual as well.  There is also sometimes see see (doc)
>
> L15 See also see Substitutes.
> #+end_quote
>
>
> This sounds like the use of an @xref instead of @ref.  However, I
> can't find it in the current version (5a95cf76) of the documentation,
> nor the reported version (ee7c9d25).  […]

I believe the rendering of @ref was an issue with Emacs that is gone in
latest Emacs.


> It was advised to submit the previous patch to guix-patches.  I opted
> to submit this next patch here to keep the thread connected since it's
> part of a larger discussion (I suppose).  If we're agreed that
> guix-patches is more appropriate, I can submit the next item in a new
> thread there using the same message format I've been following.
> Thoughts?

I believe guix-devel is OK for such changes.

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

[-- Attachment #1: Type: text/plain, Size: 942 bytes --]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first three items.

The next item reported is:

#+begin_quote
3.7 After System Installation
L27 Libera_Chat, why the underscore. It is colored as well for me so
I guess this is a special char. Should be anways just Libera Chat
#+end_quote

"Libera_Chat" is not, or no longer, in the docs (d3fe763fe3).  However, there are two variations present: "Libera Chat" and "Libera.Chat".

The attached change updates "Libera Chat" to the "Libera.Chat" stylization.

The network itself is inconsistent in self-reference and provides no guideline I could find on which form to use.  I opted for the "dot" version to make things consistent.  Because the URL is https://libera.chat, someone searching for the network by copy-paste may arrive at the homepage more directly than with the non-dot version.

[-- Attachment #2: 0001-doc-Standardize-IRC-stylization.patch --]
[-- Type: application/octet-stream, Size: 839 bytes --]

From a3b8fd62c499325cc2a0127e5e5d4f82cf71492b Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Fri, 12 Apr 2024 21:00:05 +0200
Subject: [PATCH] doc: Standardize IRC stylization

* doc/guix.texi (After System Installation): make references to Libera.Chat
consistent.
---
 doc/guix.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5efbd00984..4c8d55f492 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2548,7 +2548,7 @@ This builds a new system @dfn{generation} with the latest packages and
 services.
 
 Now, @pxref{Getting Started with the System}, and
-join us on @code{#guix} on the Libera Chat IRC network or on
+join us on @code{#guix} on the Libera.Chat IRC network or on
 @email{guix-devel@@gnu.org} to share your experience!
 
 
-- 
2.41.0

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Matt <matt@excalamus.com> writes:
> #+begin_quote
> 3.7 After System Installation
> L27 Libera_Chat, why the underscore. It is colored as well for me so
> I guess this is a special char. Should be anways just Libera Chat
> #+end_quote
>
> "Libera_Chat" is not, or no longer, in the docs (d3fe763fe3).
> However, there are two variations present: "Libera Chat" and
> "Libera.Chat".

Currently Libera Chat is written using a non-breaking space.  We could
also use @tie{} instead of the special char  .  I do agree with your
Libera.Chat stylization, will push it later.  It will not matter to
search engines, I think.

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Matt <matt@excalamus.com> writes:
> The attached change updates "Libera Chat" to the "Libera.Chat" stylization.

Pushed as df7b569b464c05036871f23d37ba319be78e5f64.

Thanks!

Regards,
Florian

Creating a documentation team?

[Ludovic Courtès]

[-- Attachment #1: Type: text/plain, Size: 426 bytes --]

Hi Florian and all,

I figure you’ve been doing a lot of review and writing of the manual.
Should we create a documentation team, of which you could be a honorary
member?  :-)

I feel like ensuring doc consistency, be it regarding the content,
terminology, typography, or use of markup, is a job in its own that
could be best reviewed by people familiar with and interested in those
issues.

WDYT?

Ludo’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 770 bytes --]

diff --git a/etc/teams.scm b/etc/teams.scm
index d537e83efc..4d65a5476e 100755
--- a/etc/teams.scm
+++ b/etc/teams.scm
@@ -434,6 +434,16 @@ (define-team core
               (make-regexp* "^guix/scripts/")
               (make-regexp* "^guix/store/"))))
 
+(define-team documentation
+  (team 'documentation
+        #:name "Documentation"
+        #:description "Documentation: the manual and cookbook."
+        #:scope (list (make-regexp* "\\.texi$")
+                      "doc/build.scm"
+                      "gnu/system/examples/bare-bones.tmpl"
+                      "gnu/system/examples/lightweight-desktop.tmpl"
+                      "gnu/system/examples/desktop.tmpl")))
+
 (define-team core-packages
   (team 'core-packages
         #:name "Core packages"

Re: Creating a documentation team?

[Maxim Cournoyer]

Hi,

Ludovic Courtès <ludo@gnu.org> writes:

> Hi Florian and all,
>
> I figure you’ve been doing a lot of review and writing of the manual.
> Should we create a documentation team, of which you could be a honorary
> member?  :-)
>
> I feel like ensuring doc consistency, be it regarding the content,
> terminology, typography, or use of markup, is a job in its own that
> could be best reviewed by people familiar with and interested in those
> issues.
>
> WDYT?
>
> Ludo’.
>
> diff --git a/etc/teams.scm b/etc/teams.scm
> index d537e83efc..4d65a5476e 100755
> --- a/etc/teams.scm
> +++ b/etc/teams.scm
> @@ -434,6 +434,16 @@ (define-team core
>                (make-regexp* "^guix/scripts/")
>                (make-regexp* "^guix/store/"))))
>  
> +(define-team documentation
> +  (team 'documentation
> +        #:name "Documentation"
> +        #:description "Documentation: the manual and cookbook."
> +        #:scope (list (make-regexp* "\\.texi$")
> +                      "doc/build.scm"
> +                      "gnu/system/examples/bare-bones.tmpl"
> +                      "gnu/system/examples/lightweight-desktop.tmpl"
> +                      "gnu/system/examples/desktop.tmpl")))
> +
>  (define-team core-packages
>    (team 'core-packages
>          #:name "Core packages"

I second this.  I'd be happy to be added to it.

-- 
Thanks,
Maxim

Re: Creating a documentation team?

[pelzflorian (Florian Pelz)]

Ludovic Courtès <ludo@gnu.org> writes:
> Hi Florian and all,
>
> I figure you’ve been doing a lot of review and writing of the manual.
> Should we create a documentation team, of which you could be a honorary
> member?  :-)

Yes, please add this team for documentation.  I agree and would like to
be in that team.  (Although I am already not able to keep up with all
outstanding doc patches like bug#70202.)

Regards,
Florian

Re: Creating a documentation team?

[Matt]

 ---- On Fri, 19 Apr 2024 16:09:53 +0200  Ludovic Courtès  wrote --- 
 > Hi Florian and all,
 > 
 > I figure you’ve been doing a lot of review and writing of the manual.
 > Should we create a documentation team, of which you could be a honorary
 > member?  :-)
 > 
 > I feel like ensuring doc consistency, be it regarding the content,
 > terminology, typography, or use of markup, is a job in its own that
 > could be best reviewed by people familiar with and interested in those
 > issues.
 
I'm in favor of this and would enjoy continuing to help with the docs.

Re: Creating a documentation team?

[Ludovic Courtès]

Hello!

Thanks Florian, Maxime, and Matt for your feedback.

I’ve added the documentation team locally.  I’ll push shortly and let
you add yourselves.

Ludo’.

Re: Creating a documentation team?

[pelzflorian (Florian Pelz)]

Thank you for creating the team for documentation,

Ludovic Courtès <ludo@gnu.org> writes:
> I’ll push shortly and let
> you add yourselves.

I’ve added myself.

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Ludovic Courtès]

Hi,

Matt <matt@excalamus.com> skribis:

> See @ref{Substitutes} for how to allow the daemon to download pre-built binaries.

Nitpick: this works but I believe the recommended approach is
“@xref{Substitutes} for how…”.

  https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html

Thanks for reporting these issues!

Ludo’.

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

[-- Attachment #1: Type: text/plain, Size: 599 bytes --]

 ---- On Fri, 12 Apr 2024 22:16:39 +0200  Ludovic Courtès  wrote --- 

 > > See @ref{Substitutes} for how to allow the daemon to download pre-built binaries.
 > 
 > Nitpick: this works but I believe the recommended approach is
 > “@xref{Substitutes} for how…”.
 > 
 >   https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html
 
Good catch!  I took the opportunity and found several similar issues elsewhere.  The attached patch tries to correct them.

 > Thanks for reporting these issues!

I appreciate your assistance with these details :)

[-- Attachment #2: 0001-doc-Fix-cross-references.patch --]
[-- Type: application/octet-stream, Size: 3111 bytes --]

From bc8d3654f8c1d3271596d0eafb48b02421236e1c Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Sat, 13 Apr 2024 10:12:05 +0200
Subject: [PATCH] doc: Fix cross-references

* doc/guix.texi (Setting Up the Daemon): use @xref to start sentence.
(Build Systems): capitalize "python" and start parenthesized reference with
@pxref.
(Linux Services): use @xref to start phrase.
(Configuring the Shell): use @xref to start phrase.
---
 doc/guix.texi | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5efbd00984..b117a2d03c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -848,8 +848,8 @@ goes through the daemon.  For instance, command-line tools such as
 daemon (@i{via} remote procedure calls) to instruct it what to do.
 
 The following sections explain how to prepare the build daemon's
-environment.  See @ref{Substitutes} for how to allow the daemon to
-download pre-built binaries.
+environment.  @xref{Substitutes} for how to allow the daemon to download
+pre-built binaries.
 
 @menu
 * Build Environment Setup::     Preparing the isolated build environment.
@@ -9086,7 +9086,7 @@ package name should be prefixed with the lisp implementation, such as
 @code{sbcl-} for @code{asdf-build-system/sbcl}.
 
 Additionally, the corresponding source package should be labeled using
-the same convention as python packages (see @ref{Python Modules}), using
+the same convention as Python packages (@pxref{Python Modules}), using
 the @code{cl-} prefix.
 
 In order to create executable programs and images, the build-side
@@ -39603,9 +39603,9 @@ The package providing the @command{fstrim} command.
 
 @item @code{schedule} (default: @code{"0 0 * * 0"}) (type: mcron-time)
 Schedule for launching @command{fstrim}.  This can be a procedure, a
-list or a string.  For additional information, see @ref{Guile
-Syntax,,Job specification,mcron,the mcron manual}.  By default this is
-set to run weekly on Sunday at 00:00.
+list or a string.  For additional information, @xref{Guile Syntax,,Job
+specification,mcron,the mcron manual}.  By default this is set to run
+weekly on Sunday at 00:00.
 
 @item @code{listed-in} (default: @code{'("/etc/fstab" "/proc/self/mountinfo")}) (type: maybe-list-of-strings)
 List of files in fstab or kernel mountinfo format.  All missing or empty
@@ -44229,9 +44229,9 @@ Guix Home.  Otherwise, read it carefully.
 There are a few scripts that must be evaluated by a login shell to
 activate the home environment.  The shell startup files only read by
 login shells often have @code{profile} suffix.  For more information
-about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
-Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
-Reference Manual}.
+about login shells, @xref{Invoking Bash,,, bash, The GNU Bash Reference
+Manual} and @xref{Bash Startup Files,,, bash, The GNU Bash Reference
+Manual}.
 
 The first script that needs to be sourced is @file{setup-environment},
 which sets all the necessary environment variables (including variables
-- 
2.41.0

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Hello Matt.  Thank you for fixing the oversight.  However:

Matt <matt@excalamus.com> writes:
> From: Matthew Trzcinski <matt@excalamus.com>
> Date: Sat, 13 Apr 2024 10:12:05 +0200
> Subject: [PATCH] doc: Fix cross-references
>
> * doc/guix.texi (Setting Up the Daemon): use @xref to start sentence.
> (Build Systems): capitalize "python" and start parenthesized reference with
> @pxref.
> (Linux Services): use @xref to start phrase.

@xref produces a capital See instead of see.  This should be @pxref.
See the Texinfo manual “info texinfo” or the Web manual Ludo points to.

In info, this will use the word *note instead of *see, but it’s still
right, if Matt you agree.

> (Configuring the Shell): use @xref to start phrase.

This should be @pxref.

Additionally, the commit message’s first sentence should end with a
period.  The sentences in the commit message describing a section should
start with a capital letter.

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

 ---- On Sat, 13 Apr 2024 13:26:39 +0200  pelzflorian (Florian Pelz)  wrote --- 

 > @xref produces a capital See instead of see.  This should be @pxref.
 > See the Texinfo manual “info texinfo” or the Web manual Ludo points to.
 > 
 > In info, this will use the word *note instead of *see, but it’s still
 > right, if Matt you agree.

Yes, rereading the linked docs, it is as you say.  

The problem is that the Emacs Info reader incorrectly renders cross-references by default.  I was reading the Texinfo documentation in Emacs.

The default Emacs rendering of the Texinfo info file looks like:

#+begin_src info
‘@xref’
     Used to start a sentence with an Info cross-reference saying ‘see
     NAME.’ or with 'See ...' in other output formats.

‘@ref’
     Used within or, more often, at the end of a sentence; produces an
     Info cross-reference saying ‘see NAME.’, and just the
     reference in other output formats, without the preceding 'See'.    
#+end_src

Specifically, it misleadingly replaces info file instances of "*Note", which correspond to @xref, with (lowercase 's') "see ".

A workaround is use (setq Info-hide-note-references nil)

I was unable to fix the issue in Emacs and have filed a bug report.

 > Additionally, the commit message’s first sentence should end with a
 > period.  The sentences in the commit message describing a section should
 > start with a capital letter.

Thank you for the reminder.  I have made a note to check this for my future submissions.

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Matt <matt@excalamus.com> writes:
> The problem is that the Emacs Info reader incorrectly renders
> cross-references by default.  I was reading the Texinfo documentation
> in Emacs.

I believe the Emacs errors are historical; looking at Emacs 29.3 as
packaged in Guix, Emacs-Info displays xref properly as See.  Display
errors had existed, but in the past only.

Again thank you for tediously working through deficiencies in Guix’ docs.

Do you agree that I should commit your docs correction with @pxref?
I believe it is an improvement over current “see @ref”, even though it
looks different in the info reader.

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

 ---- On Mon, 15 Apr 2024 14:58:50 +0200  pelzflorian (Florian Pelz)  wrote --- 

 > Do you agree that I should commit your docs correction with @pxref?
 > I believe it is an improvement over current “see @ref”, even though it
 > looks different in the info reader.
 
Yes, I agree and thank you for double checking.  Sorry for not answering you more clearly before!  @pxref is the correct command to use within parentheses.

 > I believe the Emacs errors are historical; looking at Emacs 29.3 as
 > packaged in Guix, Emacs-Info displays xref properly as See.  Display
 > errors had existed, but in the past only.

I reported it to emacs-devel (it's addressed now) and the issue isn't technically @xrefs; it's the compilation of @xref and @ref, '*Note' and '*note' respectively.  Emacs looks at the context around these and renders them as 'See' or 'see' according to what's nearby.  The trouble is that the Texinfo documentation intends to show '*Note' and '*note' literally which is an exception to the Emacs logic.
                                                                          
I looked it up and the related Emacs code had been there for like 18 years...I have a knack for finding these kinds of dumb things.  I can't decide if it's a superpower or a super-curse. :)

 > Again thank you for tediously working through deficiencies in Guix’ docs.

Like Richard Hamming asks, "If what you're working on is not important and it's not likely to lead to important things, why are you working on it?"  I think Guix is important!  Thanks for sticking with me :)

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Hi Matt.  When triple checking, I read in “info "(texinfo)@pxref"”:

   In past versions of Texinfo, it was not allowed to write punctuation
after a '@pxref', so it could be used _only_ before a right parenthesis.
This is no longer the case.  The effect of '@pxref{NODE-NAME}' is
similar to that of 'see @ref{NODE-NAME}'.  However, in many circumstance
the latter is preferrable, as this makes it clear in the Info output
that the word "see" should be present.

Because of this last sentence, my tendency would now be to use @pxref
only for parentheses.  (Texinfo is really confusing.)  Should I just cut
these changes:

(Linux Services): Use @pxref to start phrase.
(Configuring the Shell): Use @pxref to start phrase.

or is there more that should go in this patch?

Matt <matt@excalamus.com> writes:
>  ---- On Mon, 15 Apr 2024 14:58:50 +0200  pelzflorian (Florian Pelz)  wrote --- 
>  > I believe the Emacs errors are historical; looking at Emacs 29.3 as
>  > packaged in Guix, Emacs-Info displays xref properly as See.  Display
>  > errors had existed, but in the past only.
>
> I reported it to emacs-devel (it's addressed now) and the issue isn't
> technically @xrefs; it's the compilation of @xref and @ref, '*Note'
> and '*note' respectively.  Emacs looks at the context around these and
> renders them as 'See' or 'see' according to what's nearby.  […]

Ohh thank you and them for the fix.

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

 ---- On Tue, 16 Apr 2024 08:43:23 +0200  pelzflorian (Florian Pelz)  wrote --- 
 > Hi Matt.  When triple checking, I read in “info "(texinfo)@pxref"”:
 > 
 >    In past versions of Texinfo, it was not allowed to write punctuation
 > after a '@pxref', so it could be used _only_ before a right parenthesis.
 > This is no longer the case.  The effect of '@pxref{NODE-NAME}' is
 > similar to that of 'see @ref{NODE-NAME}'.  However, in many circumstance
 > the latter is preferrable, as this makes it clear in the Info output
 > that the word "see" should be present.
 > 
 > Because of this last sentence, my tendency would now be to use @pxref
 > only for parentheses.  (Texinfo is really confusing.)  Should I just cut
 > these changes:
 > 
 > (Linux Services): Use @pxref to start phrase.
 > (Configuring the Shell): Use @pxref to start phrase.

Yes, I agree that cutting those, and using the original "see @ref{}", is what the Texinfo manual says is correct.  We should also cut this change:

(Setting Up the Daemon): use @xref to start sentence.

The original was also correct.

The only change that should remain is:

(Build Systems): capitalize "python" and start parenthesized reference with
@pxref.

Thanks for checking that.  I had it wrong and I learned something!

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Hello Matt, pushed as 86fb0e039bf30cf85e2066401f9a384427c47ea8.

I was bold enough to retain the xref change in (Setting Up the Daemon)
prompted by Ludo, because starting a sentence with @xref is recommended
in the Texinfo manual and its examples, while @pxref at the start of a
phrase is not preferrable, according to the “info "(texinfo)@pxref"”.

Again, Texinfo cross-references are complicated.

(In the German translations, I always wrote only @ref, but only because
@xref is not properly translated; Emacs in particular is not
internationalized at all.)

Regards,
Florian

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt]

 ---- On Fri, 19 Apr 2024 22:56:13 +0200  pelzflorian (Florian Pelz)  wrote --- 
 > Hello Matt, pushed as 86fb0e039bf30cf85e2066401f9a384427c47ea8.
 > 
 > I was bold enough to retain the xref change in (Setting Up the Daemon)
 > prompted by Ludo, because starting a sentence with @xref is recommended
 > in the Texinfo manual and its examples, while @pxref at the start of a
 > phrase is not preferrable, according to the “info "(texinfo)@pxref"”.
 > 
 > Again, Texinfo cross-references are complicated.
 > 
 > (In the German translations, I always wrote only @ref, but only because
 > @xref is not properly translated; Emacs in particular is not
 > internationalized at all.)
 
Sounds good, thank you!

Re: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Maxim Cournoyer]

Hi Matt,

Matt <matt@excalamus.com> writes:

>  ---- On Mon, 15 Apr 2024 14:58:50 +0200  pelzflorian (Florian Pelz)  wrote --- 
>
>  > Do you agree that I should commit your docs correction with @pxref?
>  > I believe it is an improvement over current “see @ref”, even though it
>  > looks different in the info reader.
>  
> Yes, I agree and thank you for double checking.  Sorry for not
> answering you more clearly before!  @pxref is the correct command to
> use within parentheses.
>
>  > I believe the Emacs errors are historical; looking at Emacs 29.3 as
>  > packaged in Guix, Emacs-Info displays xref properly as See.  Display
>  > errors had existed, but in the past only.
>
> I reported it to emacs-devel (it's addressed now) and the issue isn't
> technically @xrefs; it's the compilation of @xref and @ref, '*Note'
> and '*note' respectively.  Emacs looks at the context around these and
> renders them as 'See' or 'see' according to what's nearby.  The
> trouble is that the Texinfo documentation intends to show '*Note' and
> '*note' literally which is an exception to the Emacs logic.
>                                                                           
> I looked it up and the related Emacs code had been there for like 18
> years...I have a knack for finding these kinds of dumb things.  I
> can't decide if it's a superpower or a super-curse. :)

Awesome!  Definitely a superpower in my book.  Thanks for following it
through with the Emacs folks!  I'm sure I was bothered by that
inconsistency before but couldn't put my finger on the culprit.

-- 
Thanks,
Maxim

[PATCH] Fix typo (Re: Feedback of the GNU Guix manual)

[Matt]

[-- Attachment #1: Type: text/plain, Size: 390 bytes --]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first four items.

The next item reported is:

#+begin_quote
3.8 Installing Guix in a Virtual Machine

L25 in an vm should be in a vm
#+end_quote

This is a nice, easy fix, good for me to practice getting the commit formatting correct :)

[-- Attachment #2: 0001-doc-Fix-typo.patch --]
[-- Type: application/octet-stream, Size: 784 bytes --]

From d853c2eb0fea153ac6f6540b3fa4343cd486c5c0 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Mon, 22 Apr 2024 19:56:26 +0200
Subject: [PATCH] doc: Fix typo.

* doc/guix.texi (Installing Guix in a VM): Change indefinite article.
---
 doc/guix.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 65af136e61..04e33da1a9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2583,7 +2583,7 @@ The resulting file will be much smaller than 50 GB (typically less than
 1 MB), but it will grow as the virtualized storage device is filled up.
 
 @item
-Boot the USB installation image in an VM:
+Boot the USB installation image in a VM:
 
 @example
 qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
-- 
2.41.0

Re: [PATCH] Fix typo (Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Pushed as b8ccbc942e0ec7baf695d383e575991289c6e033.

Thank you for trudging on through the list.

Regards,
Florian

[PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Matt]

[-- Attachment #1: Type: text/plain, Size: 1380 bytes --]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first five items.  The sixth item was fixed already in
https://git.savannah.gnu.org/cgit/guix.git/commit/?id=cb3f833aaa5326e653b128bfd7b13d553f7c2a47

The next item reported is:

#+begin_quote
6.7 L37 true for Guix System as well?
The result of running ‘guix pull’ is a “profile” available under
‘~/.config/guix/current’ containing the latest Guix. Thus, make sure to
add it to the beginning of your search path so that you use the latest
version, and similarly for the Info manual (*note Documentation::):

export PATH="$HOME/.config/guix/current/bin:$PATH"
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
#+end_quote

As far as I know, exporting like this is only necessary on foreign distros.

The attached patch makes this explicit.  It also provides information for people unfamiliar with the concept of a "search path" or how shells work by suggesting the exports be added to .bashrc and tries to clarify the consequences of not doing this.

Unnecessary words were struck to reduce the overall word count.  According to M-x count-words-region, the patch adds only 6 words (which is less than the 7 needed for "users of Guix on a foreign distro", itself hard to reduce).

[-- Attachment #2: 0001-doc-Clarify-need-to-update-search-paths-on-foreign-d.patch --]
[-- Type: application/octet-stream, Size: 1564 bytes --]

From 61d7fd377f428bf228e77f9e64b9e55e903a63f3 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Tue, 7 May 2024 21:30:28 +0200
Subject: [PATCH] doc: Clarify need to update search paths on foreign distro.

* doc/guix.texi (Invoking guix pull): Make explicit the need to update PATH
and INFOPATH on foreign distros after running 'guix pull'.  Give example of
where users may make the updates, as well as clearify the explanation why.
---
 doc/guix.texi | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1c1e0164e7..af08dd4046 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4403,11 +4403,12 @@ instance, when user @code{root} runs @command{guix pull}, this has no
 effect on the version of Guix that user @code{alice} sees, and vice
 versa.
 
-The result of running @command{guix pull} is a @dfn{profile} available
-under @file{~/.config/guix/current} containing the latest Guix.  Thus,
-make sure to add it to the beginning of your search path so that you use
-the latest version, and similarly for the Info manual
-(@pxref{Documentation}):
+@command{guix pull} creates a new @dfn{profile} in
+@file{~/.config/guix/current} containing the latest Guix.  Users of Guix
+on a foreign distro should add this profile to the beginning of their
+search path (for example in @file{.bashrc}) to ensure that
+@command{guix} and @command{info guix} (@pxref{Documentation}) reference
+the latest versions:
 
 @example
 export PATH="$HOME/.config/guix/current/bin:$PATH"
-- 
2.41.0

Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Vagrant Cascadian]

[-- Attachment #1: Type: text/plain, Size: 1488 bytes --]

On 2024-05-07, matt@excalamus.com wrote:
> #+begin_quote
> 6.7 L37 true for Guix System as well?
> The result of running ‘guix pull’ is a “profile” available under
> ‘~/.config/guix/current’ containing the latest Guix. Thus, make sure to
> add it to the beginning of your search path so that you use the latest
> version, and similarly for the Info manual (*note Documentation::):
>
> export PATH="$HOME/.config/guix/current/bin:$PATH"
> export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
> #+end_quote
>
> As far as I know, exporting like this is only necessary on foreign distros.
>
> The attached patch makes this explicit.  It also provides information
> for people unfamiliar with the concept of a "search path" or how
> shells work by suggesting the exports be added to .bashrc and tries to
> clarify the consequences of not doing this.

If the foreign distro has /etc/profile.d/*guix.sh installed, as
implemented in the binary guix-install.sh script and also implemented in
the Debian packaging, manually adding this is also arguably not
necessary, unless they are using a shell that does not respect
/etc/profile.d ... which, to my knowledge, is no different from Guix
System really.

There is also the issue of logging out and back in again (or manually
adding the variables for one session), but that seems a little
tangential, and again, is no different for Guix System than on foreign
distros.

live well,
  vagrant

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Matt]

<div>
<br /> ---- On Tue, 07 May 2024 22:41:33 +0200  Vagrant Cascadian  wrote --- 
<br /> &gt; On 2024-05-07, matt@excalamus.com wrote:
<br /> &gt; &gt; #+begin_quote
<br /> &gt; &gt; 6.7 L37 true for Guix System as well?
<br /> &gt; &gt; The result of running ‘guix pull’ is a “profile” available under
<br /> &gt; &gt; ‘~/.config/guix/current’ containing the latest Guix. Thus, make sure to
<br /> &gt; &gt; add it to the beginning of your search path so that you use the latest
<br /> &gt; &gt; version, and similarly for the Info manual (*note Documentation::):
<br /> &gt; &gt;
<br /> &gt; &gt; export PATH="$HOME/.config/guix/current/bin:$PATH"
<br /> &gt; &gt; export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
<br /> &gt; &gt; #+end_quote
<br /> &gt; &gt;
<br /> &gt; &gt; As far as I know, exporting like this is only necessary on foreign distros.
<br /> &gt; &gt;
<br /> &gt; &gt; The attached patch makes this explicit.  It also provides information
<br /> &gt; &gt; for people unfamiliar with the concept of a "search path" or how
<br /> &gt; &gt; shells work by suggesting the exports be added to .bashrc and tries to
<br /> &gt; &gt; clarify the consequences of not doing this.
<br /> &gt; 
<br /> &gt; If the foreign distro has /etc/profile.d/*guix.sh installed, as
<br /> &gt; implemented in the binary guix-install.sh script and also implemented in
<br /> &gt; the Debian packaging, manually adding this is also arguably not
<br /> &gt; necessary, unless they are using a shell that does not respect
<br /> &gt; /etc/profile.d ... which, to my knowledge, is no different from Guix
<br /> &gt; System really.
<br /> &gt; 
<br /> &gt; There is also the issue of logging out and back in again (or manually
<br /> &gt; adding the variables for one session), but that seems a little
<br /> &gt; tangential, and again, is no different for Guix System than on foreign
<br /> &gt; distros.
<br />
<br />Should we remove the advice to update search paths and instead explain (IIUC) how guix.sh is added to /etc/profile.d?  Basically, does the reader need to take some action or is there some information about the system that would be relevant for  the reader regarding its use or maintenance?</div>

Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[pelzflorian (Florian Pelz)]

Hello Matt, Vagrant and all.  As I understand, we should not advice all
users to add these exports to .bashrc, because users with
guix-install.sh’s sys_create_init_profile or Debian’s
/etc/profile.d/guix.sh do not need it.

Instead, there already is advice for .config/guix/current documented in
the Guix manual’s Getting Started section.  The advice should be a
cross-reference that users should follow the steps from Getting Started,
so search paths are set up properly instead of advising to set PATH and
INFOPATH.

The advice of setting PATH really should go away.

Regards,
Florian

Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual)

[Matt]

---- On Sat, 11 May 2024 10:14:15 +0200  pelzflorian (Florian Pelz)  wrote ---
> Instead, there already is advice for .config/guix/current documented in
> the Guix manual’s Getting Started section.  The advice should be a
> cross-reference that users should follow the steps from Getting Started,
> so search paths are set up properly instead of advising to set PATH and
> INFOPATH.
>
> The advice of setting PATH really should go away.

Sorry for the late and lengthy reply.  Life is life and when I returned to the issue I noticed that the problem is really that the concept of profiles could use some revision within the manual.  That will make for a rather complex change set.  I hoped to have one ready yet, again, life is life.  So, here are my thoughts and, after hearing yours, I can put together  the necessary changes if my points hold.

I see two fundamental issues:

1. should there be a single point of reference for the concept of "profile" and where should it be?

2. what information about profiles is relevant to addressing the reported issue and where is it?

We'll need to discuss possible solutions because, unfortunately, the concept of "profiles" isn't conveniently documented.

ISSUE 1 - should there be a single point of reference for the concept of "profile" and where should it be?

tl;dr create a new subsection for the profile concept

I find your suggestion reasonable; document concepts in a single place and then favor references to that place.  Unfortunately, there is currently no single place of reference for the concept of "profile".

Important facts about profiles are spread across the following sections (a list is given at the end of this section):

- Section 4: Getting Started (1)
- Section 5.1: Features (and isn't indexed there) (1)
- Section 5.2: Invoking 'guix package' (13)
- Section 5.7: Invoking 'guix pull' (3)
- Section 8.8: Search Paths (1)
- Section 9.1: Invoking 'guix build' (1)
- Section 11.3: operating-system Reference (2), and
- Section 11.19.3: Service Reference (1)

Should we make Section 4: Getting Started the common reference point?

I say no.  The Getting Started section is intended to help readers get started with Guix and get a feel of what it's like.  Therefore, it should contain a simple how-to with minimal explanation.  As the GNU Press Styleguide[1] advises,

"Move slowly. Do not impose too much of a cognitive load at once on the reader."

I think the Getting Started section has too much profile information in it as is.  For example, GUIX_PYTHONPATH is a convention, hard-coded into package definitions whereas GUIX_PROFILE is a literary shorthand for the concept that multiple profiles may exist and that the profile is the $HOME/.guix-profile in this case.

Of all the sections that discuss profiles, Invoking 'guix package' contains the most information (13 facts).  It's also given as the point of reference by 5 other sections:

1. Invoking 'guix pull' (twice)
2. Invoking 'guix shell'
3. Invoking 'guix environment'
4. Invoking 'guix build'
5. operating-system Reference

Should we make Invoking 'guix package' be the common reference point for profiles?

Again, I say no. AFAIU, profiles have two forms: a system profile, sometimes called the global profile, which manages Guix itself and user profiles, including "default" or "current", which dictate package accessibility.  While system and user profiles "work exactly" like each other (see Invoking guix pull), there are separate commands for each: 'guix package' is for user profiles and 'guix pull' is for the system profile.  It's easy to confuse all this.  Therefore, it would be better to have a separate section that explains profiles and let Invoking 'guix package' and Invoking 'guix pull' focus on the command options.

The best common reference point for profiles is in a new section just below Section 5.1: Features. As the Styleguide[1] says,

"Put important notes to the reader in subsections of their own. This tells the reader the notes really are important."

Profiles are first introduced in Section 4: Getting Started.  It does a good job introducing the idea and could actually provide less information.  The concept, however, is first explained in Section 5.1: Features.  The majority of Features is about how profiles are useful and a core concept of Guix.  I think we could switch the focus of Features to be about the benefits of the store, the symlink forest, transactions, control of the build environment, and provenance tracking and move the explanation and details of profiles to a new subsection.

Information about profiles grouped by section:

- Getting Started
  + A profile is a directory containing installed packages
- Features (not indexed)
  + A profile is a reference to the store kept in each user's home
    directory managed by 'guix package'
- Invoking 'guix package'
  + a profile is a directory of installed packages
  + profiles exist per user
  + there exists a "default" profile
  + guix package operations create and modify profiles
  + profiles are created in $HOME/.guix-profile
  + $HOME/.guix-profile is a symlink
  + In a multi-user setup, user profiles are stored in a place
    registered as a "garbage-collector root"
  + there is a notion of "current profile"
  + profiles have generations
  + generations within a profile are linear, starting with a "zeroth
    generation", which contains no files apart from its own metadata.
  + multiple profiles may be referenced at a time
  + removing a profile means removing the symlink previously specified
    by "guix project --profile" as well as any corresponding '-*-link'
    suffixed symlinks
  + profiles are handles on state (that is, the state of which
    software is installed and available)
- Invoking guix pull
  + the latest Guix is determined by a profile
  + 'guix pull' and 'guix package' both create profiles and how these
    profiles work is similar
  + there are two types of profiles; those managed by 'guix pull' and
    those managed by 'guix package'
- Search Paths
  + installing packages in the default profile creates the file
    '~/.guix-profile/etc/profile' which defines search path
    environment variables
- Invoking 'guix build'
  + modifying the user's profile is the job of 'guix package'
- operating-system Reference
  + the global profile is accessible at '/run/current-system/profile'
  + it is good practice to install non-core utilities in user profiles
- Service Reference
  + the "system profile" is the programs under
    '/run/current-system/profile'

ISSUE 2- what information about profiles is relevant to addressing the reported issue and where is it?

tldr; we should create a new subsection rather than expand Getting Started

I'm able to reduce the information necessary to address the reported issue to:

1. the user environment must be configured so that the shell and other applications can find software installed with Guix
2. Guix provides a file, $GUIX_PROFILE/etc/profile, to configure the user environment
3. $GUIX_PROFILE/etc/profile is created for *each* profile
4. $GUIX_PROFILE/etc/profile must be sourced

Section 4: Getting Started explicitly states the first and forth points and implies the second.  AFAICT, the third isn't actually in the manual (although it is in the Cookbook)!

I think explaining $GUIX_PROFILE/etc/profile in more detail within Getting Started wouldn't make sense.  Therefore, because of this, and the points I made above, we should consider breaking out profiles into their own section.

[1] https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf

(No) new profiles section in the manual (was Re: [PATCH] doc: Clarify need to update search paths on foreign distro (was Re: Feedback of the GNU Guix manual))

[pelzflorian (Florian Pelz)]

Hello Matt.  It was wrong of me not to react for so long.

And now, I want to state my disagreement to [1].  You propose / ask
(kind of a wishlist bug) to collect the information about profiles in
one, new section.  But because profiles are core Guix behavior and not a
functionality, it seems right to me to keep the information where it is
and just reference it from the concept index, as is the status quo?

In particular, “guix package” is not “for user profiles” and not one
more command supporting profiles.  It really is the fundamental CLI
interface of profiles.  Therefore the “Invoking guix package” section
should remain the go-to place.

But I would still like to address your patch [2] “[PATCH] doc: Clarify
need to update search paths on foreign distro” by just removing the
duplicate, unnecessary, incomplete instructions.  I will send a patch to
the guix-patches mailing list.

Regards,
Florian

[1] https://mail.gnu.org/archive/html/guix-devel/2024-05/msg00200.html
[2] https://mail.gnu.org/archive/html/guix-devel/2024-05/msg00058.html