Feedback of the GNU Guix cookbook manual

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

Hello,

I read the cookbook on revision
ee7c9d254117fa470686210ad2ef5e7f1ba4fefc using Emacs in TTY mode.

It seems kinda messy.  Some descriptions are read like a temporarily
note that should have been rewritten for the cookbook manual.  There
are even lines that exceed the 80 column limit.

Though, it was still very useful for me as a beginner.  It made the
entrance way easier than Emacs since I had actually code I could use
(this is also true for the normal manual).

Here are some things I noticed:

*** 2.1.3.2 Snippets
"the code in only" should probably be "the code is only"

Snippets are quoted (i.e.  non-evaluated) Scheme code that are a means
of patching the source.  They are a Guix-y alternative to the
traditional ‘.patch’ files.  Because of the quote, the code in only
evaluated when passed to the Guix daemon for building.  There can be as
many snippets as needed.

*** 2.1.3.3 Inputs
Seems like a copy paste error.  It says "using the style above
instead" but there is none since it is missing.  In the guix manual
both code snippets are present.

     This is the “old style”, where each input in the list is explicitly
     given a label (a string).  It is still supported but we recommend
     using the style above instead.  *Note (guix)package Reference::,
     for more info.
     
*** 2.1.3.5 Build system arguments
Use the new style with gexpr.

L216
     #:make-flags (list (string-append "prefix=" (assoc-ref %outputs "out"))
                        "CC=gcc")


L315
     (lambda* (#:key inputs outputs #:allow-other-keys)
       (let ((bash-directory (assoc-ref inputs "bash"))
             (output-directory (assoc-ref outputs "out"))
             (doc-directory (assoc-ref outputs "doc")))
         ;; ...
         #true))
         
*** 3.1 Auto-Login to a Specific TTY
Whitespace ( see

While the Guix manual explains auto-login one user to _all_ TTYs ( *note
(guix)auto-login to TTY::), some might prefer a situation, in which one

*** 3.2 Customizing the kernel
6 is current.  Maybe just say current as of the time of writing

   The current ‘linux-libre’ package is for the 5.15.x series, and is
declared like this:

Also it does use the old style syntax for code.

*** 3.7.1 StumpWM
Guix system instead of Guix System and uses old style syntax for code.

*** Running Guix on a Kimsufi server
Maybe use local file to be consistent with Linode guide.

     	      (authorized-keys
     	       `(("guix" ,(plain-file "SSH-KEY-NAME.PUB"
                                           "SSH-PUBLIC-KEY-CONTENT"))))))

Just give the actual commands and don't assume user knows it.

   Transfer your operating system declaration ‘os.scm’ file on the
server via the ‘scp’ or ‘sftp’ commands.

   Now all that is left is to install Guix with a ‘guix system init’ and
restart.

*** Guix Containers
What?

             ;; Common command line tools lest the container is too empty.
             
*** The benefits of manifest
guix environment on the first step and on the third step it is guix
shell.  guix environment is superseded by guix shell and should
therefore not be mentioned.

  1. We have an environment for hacking on a project for which there
     isn’t a Guix package yet.  We build the environment using a
     manifest, and then run ‘guix environment -m manifest.scm’.  So far
     so good.

  2. Many weeks pass and we have run a couple of ‘guix pull’ in the mean
     time.  Maybe a dependency from our manifest has been updated; or we
     may have run ‘guix gc’ and some packages needed by our manifest
     have been garbage-collected.

  3. Eventually, we set to work on that project again, so we run ‘guix
     shell -m manifest.scm’.  But now we have to wait for Guix to build
     and install stuff!
     
*** Guix environment via direnv
guix environment should be replaced with guix shell.  Also exceeding 80 columns

         eval "$(guix environment --search-paths --root="$gcroot" --pure guix --ad-hoc ${PACKAGES[@]} ${PACKAGES_MAINTENANCE[@]} "$@")"
*** 7.3 Network Access
Replace white list with allow list?

-- 
Christian Miller