WIP: workspace prep for jj

.github/workflows/ci.yml

@@ -10,9 +10,9 @@ jobs:
     name: ${{ matrix.os }} build
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v2
-    - uses: cachix/install-nix-action@v17
-    - uses: cachix/cachix-action@v10
+    - uses: actions/checkout@v4
+    - uses: cachix/install-nix-action@v27
+    - uses: cachix/cachix-action@v15
       with:
         name: shajra
         signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}'

doc/internal/nix-introduction-compat.org

@@ -6,58 +6,60 @@ project-dependent.
 
 * Helping non-flakes users
 
-A few users make work in organizations or contribute to projects that disallow
+A few users work in organizations or contribute to projects that disallow
 experimental features such as flakes.
 
-To buffer this compromise, this project uses and encourages the use of the
-[[nix-flake-compat][flake-compat]] project, which enables an end user who has opted not to enable
-flakes to at least access the flake's contents, packages or otherwise.
+For these users, this project uses and encourages the use of the [[nix-flake-compat][flake-compat]]
+project, which enables an end user who has opted not to enable flakes to at
+least access the flake's contents, packages or otherwise.
 
-With flake-compat, end users will have a normal (non-flake) Nix expression they
+With flake-compat, end users will have a regular (non-flake) Nix expression they
 can evaluate. However, since dependencies are managed with flakes, the project
 maintainer must have flakes enabled to manage dependencies (for example,
 updating to the latest dependencies with =nix flake update=).
 
-* Documenting an end user experience
+* Documenting an end-user experience
 
 To deal with the transition of the Nix community to flake, this project provides
 two user guides:
 
 - [[file:nix-usage-flakes.org][Nix Usage with Flakes (Recommended) ]]
 - [[file:nix-usage-noflakes.org][Nix Usage without Flakes]]
 
-Links generally steer users to the recommended guide, which then links users to
-the non-flakes guide if they have the interest or need.
+Links generally steer users to the recommended flakes guide, which then links
+users to the non-flakes guide if they have the interest or need.
 
 The non-flakes guide intentionally avoids commands like =nix-shell= and
-=nix-channel=. These commands lead users to setting the =NIX_PATH= environment
-variable, which can lead to unreliable builds.
+=nix-channel=. These commands lead users to set the =NIX_PATH= environment
+variable, which can lead to unreliable builds.  These are the pitfalls that
+motivated the design of flakes.
 
-Though this guide avoid the =flakes= experimental feature, it still invites end
-users to use the experimental =nix-command= to get the following subcommands:
+Though this non-flakes guide avoids the =flakes= experimental feature, it still
+invites end users to use the experimental =nix-command= to get the following
+subcommands:
 - =nix search=
 - =nix shell=
 - =nix run=
 
-In general, the non-flakes guide only explains usage of experimental =nix=
-subcommands when there exist no other alternatives, or when the alternatives are
+In general, the non-flakes guide only explains the usage of experimental =nix=
+subcommands when there exist no other alternatives or when the alternatives are
 considered worse for new users.
 
-=nix search= simply has no good alternative within the set of non-experimental
-Nix tools, but it's too useful to not tell users about. Again, this is an
+For example, =nix search= has no alternative within the set of non-experimental
+Nix tools, and it's too helpful not to tell users about it. Again, this is an
 example of the Nix community leading users to experimental features.
 
-=nix shell= and =nix run= are shown as improved alternatives to =nix-shell=.
-=nix-shell= is a complicated tool that has been historically used for a lot of
-different purposes:
+Additionally, =nix shell= and =nix run= are shown as improved alternatives to
+=nix-shell=.  =nix-shell= is a complicated tool that has been historically used
+for a lot of different purposes:
 - debugging the build environments of packages
 - creating a developer environment for a package (=nix develop= does this
-  better, but for only for flakes)
+  better, but only for flakes)
 - entering a shell with Nix-build executables on the path (=nix shell= does this
   better)
 - running arbitrary commands with Nix-build executables on the path (=nix run=
   does this better)
 
 To cover all of these scenarios, =nix-shell= became so complex it is hard to
-explain to new users. =nix-shell= is really only best for debugging builds,
-which is beyond the scope of the documentation provided by this project.
+explain to new users. =nix-shell= is only best for debugging builds, which is
+beyond the scope of the documentation provided by this project.

doc/internal/nix-usage-flakes-optional.org

@@ -5,12 +5,12 @@ project-dependent.
 #+end_comment
 
 This project supports a still-experimental feature of Nix called /flakes/, which
-this guide shows users how to use. [[file:../nix-usage-noflakes.org][Another guide]] explains how to do
-everything illustrated in this document, but without flakes.
+this guide shows users how to use. [[file:nix-usage-noflakes.org][Another guide]] explains how to do everything
+illustrated in this document, but without flakes.
 
 #+begin_quote
-*_NOTE:_* If you're new to flakes, please read the provided [[file:../nix-introduction.org][supplemental
+*_NOTE:_* If you're new to flakes, please read the provided [[file:nix-introduction.org][supplemental
 introduction to Nix]] to understand the experimental nature of flakes and how it
-may or may not affect you. Hopefully you'll find these trade-offs acceptable so
-you can take advantage of the improved experience flakes offer.
+may or may not affect you. Hopefully, you'll find these trade-offs acceptable to
+take advantage of the improved experience flakes offer.
 #+end_quote

doc/internal/params.el

@@ -10,8 +10,8 @@
  ;; run-type must be "executable"
  (run-target-short     . "direnv")
  (run-target-long      . "bin/direnv")
- (nix-latest           . "2.14")
- (nixos-latest         . "22.11")
+ (nix-latest           . "2.21")
+ (nixos-latest         . "23.11")
  (platforms            . "\n\
 - Linux on x86-64 machines\n\
 - MacOS on x86-64 machines\n\

doc/nix-installation.org

@@ -3,7 +3,7 @@
 
 * Org-mode setup :noexport:
 
-This document is written in a project-agnostic way so it can be copied to other
+This document is written in a project-agnostic way to be copied to other
 projects that use Nix.
 
 ** Variables
@@ -42,23 +42,23 @@ installed in Windows via the Windows Subsystem for Linux (WSL). Installation on
 WSL may involve steps not covered in this documentation, though.
 
 Note, some users may be using [[nixos][NixOS]], a Linux operating system built on top of
-Nix. Those users already have Nix and don't need to install it separately. To
-use this project, you don't need to use NixOS as well.
+Nix. Those users already have Nix and don't need to install it separately. You
+don't need to use NixOS to use this project.
 
 * Level of commitment/risk
 
 Unless you're on NixOS, you're likely already using another package manager for
-your operating system already (APT, DNF, etc.). You don't have to worry about
-Nix or packages installed by Nix conflicting with anything already on your
-system. Running Nix along side other package managers is safe.
+your operating system (APT, DNF, etc.). You don't have to worry about Nix or
+packages installed by Nix conflicting with anything already on your system.
+Running Nix alongside other package managers is safe.
 
-All the files of a Nix package are located under =/nix= a directory, well
-isolated from any other package manager. Nix won't touch critical directories
-under =/usr= or =/var=. Nix then symlinks files under =/nix= to your home
-directory under dot-files like =~/.nix-profile=. There is also some light
-configuration under =/etc/nix=.
+All the files of a Nix package are located under =/nix= a directory, isolated
+from any other package manager. Nix won't touch critical directories under
+=/usr= or =/var=. Nix then symlinks files under =/nix= to your home directory
+under dot-files like =~/.nix-profile=. There is also some light configuration
+under =/etc/nix=.
 
-Hopefully this alleviates any worry about installing a complex program on your
+Hopefully, this alleviates any worry about installing a complex program on your
 machine. Uninstallation is not too much more than deleting everything under
 =/nix=.
 
@@ -93,9 +93,9 @@ the Nix manual]].
 
 This project pushes built Nix packages to [[cachix][Cachix]] as part of its [[github-actions][continuous
 integration]]. It's recommended to configure Nix to use shajra.cachix.org as a
-Nix /substituter/. Once configured, Nix will pull down pre-built packages from
-Cachix, instead of building them locally (potentially saving a lot of time).
-This augments Nix's default substituter that pulls from cache.nixos.org.
+Nix /substituter/. Once configured, Nix can pull down pre-built packages from
+Cachix, instead of building them locally (potentially saving time). Cachix will
+augment Nix's default substituter that pulls from cache.nixos.org.
 
 You can configure shajra.cachix.org as a supplemental substituter with the
 following command:
@@ -115,7 +115,7 @@ If you've just run a multi-user Nix installation and are not yet a trusted user
 in =/etc/nix/nix.conf=, this command may not work. But it will report back some
 options to proceed.
 
-One option sets you up as a trusted user, and installs Cachix configuration for
+One option sets you up as a trusted user and installs Cachix configuration for
 Nix locally at =~/.config/nix/nix.conf=. This configuration will be available
 immediately, and any subsequent invocation of Nix commands will take advantage
 of the Cachix cache.
@@ -139,18 +139,18 @@ As you can guess, the =flakes= feature enables flakes functionality in Nix. The
 command-line tool, some of which allow us to work with flakes.
 
 If you don't enable experimental features globally, there is a switch to enable
-features local to just a single command-line invocation. For example, too use
-flakes-related commands we call ~nix --extra-experimental-features 'nix-command
-flakes' …~. For users not enabling these features globally, this can be useful
-to set to a shell alias. Here's an example that works in most POSIX-compliant
-shells:
+features local to just a single command-line invocation. For example, to use
+flakes-related commands, we call ~nix --extra-experimental-features 'nix-command
+flakes' …~.  When not configuring globally, setting an alias for this can be
+useful. The following command illustrates setting an alias in most
+POSIX-compliant shells:
 
 #+begin_src sh :eval no
 alias nix-flakes = nix --extra-experimental-features 'nix-command flakes'
 #+end_src
 
-As discussed in the introduction, =nix-command= is actually enabled by default.
-You don't need to enable it explicitly (though you could disable it).
+As discussed in the introduction, =nix-command= is enabled by default.  You
+don't need to enable it explicitly (though you could disable it).
 
 To use flakes there are two things we need to do:
 1. make sure the version of Nix we're on is at least 2.4
@@ -166,10 +166,10 @@ nix --version
 #+end_src
 
 #+RESULTS: nix-version
-: nix (Nix) 2.11.1
+: nix (Nix) 2.18.1
 
 The easiest way to turn on experimental features is to create a file
-=~/.config/nix/nix.conf= if it doesn't already exist, and in it put the
+=~/.config/nix/nix.conf= if it doesn't already exist, and in it, put the
 following line:
 
 #+begin_src text :eval no