01/04: website: package-channel: Fix more typos and wording issues.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix-artwork.

commit f1d33624e3fe24af5acd0cd909fa632773c5f1bd
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Mon Jun 5 15:03:40 2023 +0200

    website: package-channel: Fix more typos and wording issues.
    
    Suggested by Ricardo Wurmus.
    
    * website/drafts/package-channel.md: Fix typos and wording issues.
---
 website/drafts/package-channel.md | 63 ++++++++++++++++++++-------------------
 1 file changed, 32 insertions(+), 31 deletions(-)

diff --git a/website/drafts/package-channel.md 
b/website/drafts/package-channel.md
index c9e2950..5ce44b6 100644
--- a/website/drafts/package-channel.md
+++ b/website/drafts/package-channel.md
@@ -6,7 +6,7 @@ date: 2023-06-02 15:00:00
 ---
 
 Guix is a handy tool for developers; [`guix
-shell`](https://guix.gnu.org/manual/en/html_node/Invoking-guix-shell.html),
+shell`](https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-shell.html),
 in particular, gives a standalone development environment for your
 package, no matter what language(s) it’s written in.  To benefit from
 it, you have to initially write a package definition and have it either
@@ -14,26 +14,26 @@ in Guix proper, in a channel, or directly upstream as a 
`guix.scm` file.
 This last option is appealing: all developers have to do to get set up
 is clone the project's repository and run `guix shell`, with no
 arguments—we looked at the rationale for `guix shell` in [an earlier
-missive](https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/).
+article](https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/).
 
 Development needs go beyond development environments though.  How can
 developers perform continuous integration of their code in Guix build
 environments?  How can they deliver their code straight to adventurous
-users?  This post describes a set of files and conventions developers
-can follow in their repository to set up Guix-based development
+users?  This post describes a set of files developers can add
+to their repository to set up Guix-based development
 environments, continuous integration, and continuous delivery—all at
 once.
 
 # Getting started
 
 How do we go about “Guixifying” a repository?  The first step, as we’ve
-seen, will be to add a `guix.scm` at the root of the repository we’re
-interested in.  We’ll take [Guile](https://www.gnu.org/software/guile)
+seen, will be to add a `guix.scm` at the root of the repository in
+question.  We’ll take [Guile](https://www.gnu.org/software/guile)
 as an example in this post: it’s written in Scheme (mostly) and C, and
 has a number of dependencies—a C compilation tool chain, C libraries,
 Autoconf and its friends, LaTeX, and so on.  The resulting `guix.scm`
 looks like the usual [package
-definition](https://guix.gnu.org/manual/en/html_node/Defining-Packages.html),
+definition](https://guix.gnu.org/manual/devel/en/html_node/Defining-Packages.html),
 just without the `define-public` bit:
 
 ```scheme
@@ -163,7 +163,7 @@ field, along these lines:
 
 Here’s what we changed:
 
-  1. We add `(guix git-download)` to our set of imported modules, so we
+  1. We added `(guix git-download)` to our set of imported modules, so we
      can use its `git-predicate` procedure.
   2. We defined `vcs-file?` as a procedure that returns true when passed
      a file that is under version control.  For good measure, we add a
@@ -200,7 +200,7 @@ guix build -f guix.scm --target=x86_64-w64-mingw32
 ```
 
 You can also use [package transformation
-options](https://guix.gnu.org/manual/en/html_node/Package-Transformation-Options.html)
+options](https://guix.gnu.org/manual/devel/en/html_node/Package-Transformation-Options.html)
 to test package variants:
 
 ```
@@ -221,9 +221,7 @@ We now have a Git repository containing (among other 
things) a package
 definition.  Can’t we turn it into a
 [*channel*](https://guix.gnu.org/manual/devel/en/html_node/Channels.html)?
 After all, channels are designed to ship package definitions to users,
-and that’s exactly what we’re doing with our `guix.scm`.  Granted, our
-Git repository is one package definition lost in a sea of code—in this
-case, Guile—, but still.
+and that’s exactly what we’re doing with our `guix.scm`.
 
 Turns out we can indeed turn it into a channel, but with one caveat: we
 must create a separate directory for the `.scm` file(s) of our channel
@@ -289,14 +287,14 @@ To recap, we now have these files:
 
 And that’s it: we have a channel!  (We could do better and support
 [*channel
-authentication*](https://guix.gnu.org/manual/en/html_node/Specifying-Channel-Authorizations.html)
+authentication*](https://guix.gnu.org/manual/devel/en/html_node/Specifying-Channel-Authorizations.html)
 so users know they’re pulling genuine code.  We’ll spare you the details
 here but it’s worth considering!)  Users can pull from this channel by
 [adding it to
 
`~/.config/guix/channels.scm`](https://guix.gnu.org/manual/devel/en/html_node/Specifying-Additional-Channels.html),
 along these lines:
 
-```
+```scheme
 (append (list (channel
                 (name 'guile)
                 (url "https://git.savannah.gnu.org/git/guile.git";)
@@ -329,12 +327,12 @@ $ guix build guile@3.0.99-git
 /gnu/store/r34gsij7f0glg2fbakcmmk0zn4v62s5w-guile-3.0.99-git
 ```
 
-That’s how, as a developer, you get your software delivered directly in
+That’s how, as a developer, you get your software delivered directly into
 the hands of users!  No intermediaries, yet no loss of transparency and
 provenance tracking.
 
 With that in place, it also becomes trivial for anyone to create Docker
-images, Deb/RPM packages, or plain tarball of the software with [`guix
+images, Deb/RPM packages, or a plain tarball with [`guix
 pack`](https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-pack.html):
 
 ```
@@ -368,28 +366,28 @@ transformation options.  We can add them like so:
   (package/inherit p
     (arguments
      (substitute-keyword-arguments (package-arguments p)
-       ((#:configure-flags original-flags #~'())
+       ((#:configure-flags original-flags #~(list))
         #~(append #$original-flags #$flags))))))
 
 (define-public guile-without-threads
   (package
     (inherit (package-with-configure-flags guile
-                                           #~'("--without-threads")))
+                                           #~(list "--without-threads")))
     (name "guile-without-threads")))
 
 (define-public guile-without-networking
   (package
     (inherit (package-with-configure-flags guile
-                                           #~'("--disable-networking")))
+                                           #~(list "--disable-networking")))
     (name "guile-without-networking")))
 
 
-;; Return the package object define above at the end of the module.
+;; Return the package object defined above at the end of the module.
 guile
 ```
 
 We can build these variants as regular packages once we’ve pulled the
-channel, or, if we have a checkout of Guile, we can run a command like
+channel.  Alternatively, from a checkout of Guile, we can run a command like
 this one from the top level:
 
 ```
@@ -404,7 +402,7 @@ 
integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI).
 There are several ways to do that.
 
 You can use one of the mainstream continuous integration tools, such as
-GitLab-CI.  To do that, you need to make sure you run jobs into a Docker
+GitLab-CI.  To do that, you need to make sure you run jobs     n a Docker
 image or virtual machine that has Guix installed.  If we were to do that
 in the case of Guile, we’d have a job that runs a shell command like
 this one:
@@ -457,14 +455,16 @@ evaluation is a combination of commits of the `guix` and 
`guile`
 channels providing a number of *jobs*—one job per package defined in
 `guile-package.scm` times the number of target architectures.
 
-As for substitutes, they come for free!  As an example, our `guile`
-jobset being built on ci.guix.gnu.org, one automatically gets
-substitutes for it from ci.guix.gnu.org.  It’s as simple as that.
+As for substitutes, they come for free!  As an example, since our
+`guile` jobset is built on ci.guix.gnu.org, which runs [`guix
+publish`](https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-publish.html)
+in addition to Cuirass, one automatically gets substitutes for `guile`
+builds from ci.guix.gnu.org; no additional work is needed for that.
 
 # Bonus: Build manifest
 
 The Cuirass spec above is convenient: it builds every package in our
-channel, which includes a few variants.  However, this might may be
+channel, which includes a few variants.  However, this might be
 insufficiently expressive in some cases: one might want specific
 cross-compilation jobs, transformations, Docker images, RPM/Deb
 packages, or even system tests.
@@ -549,7 +549,9 @@ previous one:
                  %default-channels))))
 ```
 
-This is it!
+We changed the `(build …)` part of the spec to `'(manifest
+".guix/manifest.scm")` so that it would pick our manifest, and that’s
+it!
 
 # Wrapping up
 
@@ -561,7 +563,7 @@ result here:
     with the top-level `guix.scm` symlink;
   - 
[`.guix/manifest.scm`](https://git.savannah.gnu.org/cgit/guile.git/tree/.guix/manifest.scm?id=cd57379b3df636198d8cd8e76c1bfbc523762e79).
 
-These days, repositories are commonly splattered with dot files for
+These days, repositories are commonly peppered with dot files for
 various tools: `.envrc`, `.gitlab-ci.yml`, `.github/workflows`,
 `Dockerfile`, `.buildpacks`, `Aptfile`, `requirements.txt`, and whatnot.
 It may sound like we’re proposing a bunch of *additional* files, but in
@@ -580,7 +582,6 @@ With a couple of files, we get support for:
     Deb/RPM packages (`guix pack`).
 
 At the Guix headquarters, we’re quite happy about the result.  We’ve
-been building a unified tool set for reproducible software deployment
-when all the rage is on specialized tools building on one another;
-hopefully this is an illustration of how you as a developer can benefit
+been building a unified tool set for reproducible software deployment;
+this is an illustration of how you as a developer can benefit
 from it!