bug#54711: Bad Documentation Series: 6.1 Specifying Additional Channels

[Marek Paśnikowski]

In light of the above replies and my own experiences, I propose the
following to be the text of the chapter. Formatted in CommonMark.

## 6.1 Specifying Additional Channels

You can specify _additional channels_ to pull from. To use a channel,
write `~/.config/guix/channels.scm` to instruct `guix pull` to pull
from it _in addition to_ or _instead of_ the default Guix channel:

```
;; Use the literal default.
%default-channels
```

```
;; Add a channel to the default.
(cons
  (channel
    (name 'additional-channel)
    (url "https://example.org/additional-channel.git";))
  %default-channels)
```

```
;; Replace Guix repository with a local copy.
(list
  (channel
    (name 'guix)
    (url "/home/user/src/guix")))
```

Note that the snippets above are (as always!) Scheme code; we use
`cons` to add a channel to the list of channels that the variable
`%default-channels` is bound to (see [`cons` and lists](link target) in
GNU Guile Reference Manual). With this file in place, `guix pull`
builds not only Guix, but also the package modules from the added
repositories. The result in `~/.config/guix/current` is the union of
Guix with the added package modules:

```
$ guix pull --list generations
... Example output ...
```

The output of `guix pull` above shows that Generation 19 includes both
Guix and packages from the `additional-channel` channel. Among the new
and upgraded packages that are listed, some like `variant-gimp` and
`variant-emacs-with-cool-features` might come from `additional-
channel`, while others come from the Guix default channel.

Don't forget, that the channels can have more options specified, such
as authentication. Read the following chapters to learn more about the
options.

***

PS: (url "file://path/to/local/repository") was not accepted by Guix
during my experiments this week. Should I report is as a separate bug?