Docs: Clarify use-cases of `guix-for-channels`?

[45mg <45mg.writes@gmail.com>]

Hi Tomas,

I finally understand that it's my use of `guix-for-channels` that's
making it pull when I reconfigure. So, my issue is solved by removing
the `(guix)` field from the `(guix-configuration)` form in the
configuration I posted.

All I was trying to do was specify additional channels in my system
configuration, without having to write anything in
~/.config/guix/channels.scm (I prefer for everything related to my
system configuration to be tracked by git in a single root-owned
directory). It looks like I only need the `(channels)` field of
`(guix-configuration)` for that. Is that correct?

This would have been obvious to me if I had understood what
`guix-for-channels` is actually /for/ from the start. The only reason I
ended up using it in the first place is that I was reading through
'(guix) Channels' to understand how to configure additional ones, and
then I saw this in '(guix) Customizing the System-Wide Guix':

> If you’re running Guix System or building system images with it, maybe
> you will want to customize the system-wide ‘guix’ it
> provides—specifically, ‘/run/current-system/profile/bin/guix’.  For
> example, you might want to provide additional channels or to pin its
> revision.
> 
>    This can be done using the ‘guix-for-channels’ procedure, which
> returns a package for the given channels, and using it as part of your
> operating system configuration, as in this example:
> 
>      (use-modules (gnu packages package-management)
>                   (guix channels))
> 
>      (define my-channels
>        ;; Channels that should be available to
>        ;; /run/current-system/profile/bin/guix.
>        (append
>         (list (channel
>                (name 'guix-science)
>                (url "https://github.com/guix-science/guix-science")
>                (branch "master")))
>         %default-channels))
> 
>      (operating-system
>        ;; ...
>        (services
>          ;; Change the package used by 'guix-service-type'.
>          (modify-services %base-services
>            (guix-service-type
>             config => (guix-configuration
>                        (inherit config)
>                        (channels my-channels)
>                        (guix (guix-for-channels my-channels)))))))
> 
>    The resulting operating system will have both the ‘guix’ and the
> ‘guix-science’ channels visible by default.  The ‘channels’ field of
> ‘guix-configuration’ above further ensures that
> ‘/etc/guix/channels.scm’, which is used by ‘guix pull’, specifies the
> same set of channels (*note ‘channels’ field of ‘guix-configuration’:
> guix-configuration-channels.).

If I had really been paying close attention, I would have noticed
phrasing like '/maybe/ you will want', and realised that using
`guix-for-channels` is /optional/. But since this subsection is under
the 'Channels' section of the manual, which explains the basics of using
channels - and does not provide any other snippet explaining how to
configure channels in the system configuration file - I assumed that the
code snippet quoted above is THE Official Way™ to configure additional
channels directly in the system configuration, without using
~/.config/guix/channels.scm; and copied it near-verbatim.

I think this could be clarified a little, so that other people who are
in a hurry to set things up for the first time don't make the same
mistake as me, and then think that Guix needs an internet connection
just to reconfigure the system.

I could write a patch to the manual for this. Here's what I'm proposing
to do:

- Add a snippet to '(guix) Specifying Additional Channels', explaining
  how to configure additional channels within the system configuration
  file (as per the second paragraph of this message).

- In '(guix) Customizing the System-Wide Guix', explain more clearly
  where `guix-for-channels` would be useful. As I understand it, the
  main use-case is for fresh system installations where running `guix
  pull` would be a hassle, such as on an installer ISO. Are there other
  significant use-cases? Any other reasons why one might want to use it
  on their main system, despite the hassle of it pulling every time and
  not caching the derivation? (We should also document that limitation,
  unless it's likely to change in the near future.)