Feedback of the GNU Guix manual

[Christian Miller <christian.miller@dadoes.de>]

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