Update dependencies and documentation

README.md

@@ -242,27 +242,27 @@ If you want to check that everything builds before flashing your keyboard, you c
 tree $(nix build --no-link --print-out-paths) 2>/dev/null
 ```
 
-    /nix/store/f6h841a2lw0g6yp6l3z0mnbz17q3ibg2-shajra-keyboards-ci
+    /nix/store/1cvs7slmj8131i05w837i1y35lfdzkhi-shajra-keyboards-ci
     ├── build-ergodoxez-builtin-shajra-flash -> /nix/store/xnrj344dc9l06jqn304ishbxdgpwa4b2-ergodoxez-builtin-shajra-flash
     ├── build-ergodoxez-builtin-shajra-hex -> /nix/store/dqhsjba9qna2k7g2ac21sbsa025jy021-ergodoxez-builtin-shajra.hex
     ├── build-ergodoxez-factory-flash -> /nix/store/8lgc4cl3am3a5ajh9iiyrmvhni0fkhnm-ergodoxez-factory-flash
     ├── build-ergodoxez-factory-hex -> /nix/store/al7pcqv436p7w116729nfmma29izxwip-ergodoxez-factory.hex
-    ├── build-model01-builtin-shajra-flash -> /nix/store/nwd9dw8b4c405ikx39jwf7r3axxygpbr-model01-builtin-shajra-flash
-    ├── build-model01-builtin-shajra-hex -> /nix/store/qa0bhay93i0hyvwf7pikf17j7xpxr1il-model01-builtin-shajra-hex
-    ├── build-model01-factory-flash -> /nix/store/1qmacxmrwx5l8malmprf389n57w3fr1s-model01-factory-flash
-    ├── build-model01-factory-hex -> /nix/store/bsvxmm8f5nfhmqr4knr5asf09a6p7i0i-model01-factory-hex
-    ├── build-model100-builtin-shajra-flash -> /nix/store/ryf4kalbv46ky0n591xy3194b1ppv1jd-model100-builtin-shajra-flash
-    ├── build-model100-builtin-shajra-hex -> /nix/store/ingfzbahcxy80drklhgxjd4204n1haab-model100-builtin-shajra-hex
-    ├── build-model100-factory-flash -> /nix/store/vk6mpawwgrrg7lyigwzn0wmj37wm94j1-model100-factory-flash
-    ├── build-model100-factory-hex -> /nix/store/9bm06gvn5h21gk1hxwn89hbd220fwvkw-model100-factory-hex
+    ├── build-model01-builtin-shajra-flash -> /nix/store/92mdwd12v03azygy6x0k3k99xcil5idq-model01-builtin-shajra-flash
+    ├── build-model01-builtin-shajra-hex -> /nix/store/kvik2b3r96d3g3sfxzl2fppkq6afin7f-model01-builtin-shajra-hex
+    ├── build-model01-factory-flash -> /nix/store/8h7idnxnk6lqxfdk599iggfz8a47k7hn-model01-factory-flash
+    ├── build-model01-factory-hex -> /nix/store/pb8ivna4nbdhzpf4xss0j3hfvay8qfcj-model01-factory-hex
+    ├── build-model100-builtin-shajra-flash -> /nix/store/s7i74bc9h6qk0i5x7q5sslqbsprpyhy0-model100-builtin-shajra-flash
+    ├── build-model100-builtin-shajra-hex -> /nix/store/c67gyphcghhqv2hhbnvwl5fvjdwavrys-model100-builtin-shajra-hex
+    ├── build-model100-factory-flash -> /nix/store/l7nwf0afsw6z2k06w13pnzldaazvag4z-model100-factory-flash
+    ├── build-model100-factory-hex -> /nix/store/lfgm06rj71hq5brfljyw845a5gpxjfn1-model100-factory-hex
     ├── build-moonlander-builtin-shajra-flash -> /nix/store/ybfqxcp7m0ah44l16fhlighqh9sa8msv-moonlander-builtin-shajra-flash
     ├── build-moonlander-builtin-shajra-hex -> /nix/store/qiznnlymwh7wn5pdc0b87i527carcalk-moonlander-builtin-shajra.bin
     ├── build-moonlander-factory-flash -> /nix/store/m349s0ml89pfmaxp2swzs5d5zqxd60p3-moonlander-factory-flash
     ├── build-moonlander-factory-hex -> /nix/store/5136516h4jqlwij63kn4y4fzdb7bjjgs-moonlander-factory.bin
-    ├── flash-ergodoxez -> /nix/store/zm3ym7p85sclsc41h0plaz8ffli7b1i3-flash-ergodoxez
-    ├── flash-model01 -> /nix/store/nz2dad9c4i2dsj5w4gf088iza4hn6lb4-flash-model01
-    ├── flash-model100 -> /nix/store/bwwklv5d0iz4ln1znvyjadg0h13qkxib-flash-model100
-    ├── flash-moonlander -> /nix/store/54wyh4kbsb1vmkpgjx0m65wxi1v1l5vd-flash-moonlander
+    ├── flash-ergodoxez -> /nix/store/in8mcv0adj19f3k41wmfbxf9y4clrixp-flash-ergodoxez
+    ├── flash-model01 -> /nix/store/xmpdcg42yfbp1vmwgy0l1mgn29jagynk-flash-model01
+    ├── flash-model100 -> /nix/store/dk7p44k58wk7c6y5037cixa20hvfzlam-flash-model100
+    ├── flash-moonlander -> /nix/store/1cw5qz47apslk9438mdic03rz9avqyal-flash-moonlander
     └── licenses -> /nix/store/cbb8gmijyrrcp89r8c4z9z3a041aq183-shajra-keyboards-licenses
 
     18 directories, 4 files

README.org

@@ -308,27 +308,27 @@ tree $(nix build --no-link --print-out-paths) 2>/dev/null
 
 #+results: nix-build
 #+begin_example
-/nix/store/f6h841a2lw0g6yp6l3z0mnbz17q3ibg2-shajra-keyboards-ci
+/nix/store/1cvs7slmj8131i05w837i1y35lfdzkhi-shajra-keyboards-ci
 ├── build-ergodoxez-builtin-shajra-flash -> /nix/store/xnrj344dc9l06jqn304ishbxdgpwa4b2-ergodoxez-builtin-shajra-flash
 ├── build-ergodoxez-builtin-shajra-hex -> /nix/store/dqhsjba9qna2k7g2ac21sbsa025jy021-ergodoxez-builtin-shajra.hex
 ├── build-ergodoxez-factory-flash -> /nix/store/8lgc4cl3am3a5ajh9iiyrmvhni0fkhnm-ergodoxez-factory-flash
 ├── build-ergodoxez-factory-hex -> /nix/store/al7pcqv436p7w116729nfmma29izxwip-ergodoxez-factory.hex
-├── build-model01-builtin-shajra-flash -> /nix/store/nwd9dw8b4c405ikx39jwf7r3axxygpbr-model01-builtin-shajra-flash
-├── build-model01-builtin-shajra-hex -> /nix/store/qa0bhay93i0hyvwf7pikf17j7xpxr1il-model01-builtin-shajra-hex
-├── build-model01-factory-flash -> /nix/store/1qmacxmrwx5l8malmprf389n57w3fr1s-model01-factory-flash
-├── build-model01-factory-hex -> /nix/store/bsvxmm8f5nfhmqr4knr5asf09a6p7i0i-model01-factory-hex
-├── build-model100-builtin-shajra-flash -> /nix/store/ryf4kalbv46ky0n591xy3194b1ppv1jd-model100-builtin-shajra-flash
-├── build-model100-builtin-shajra-hex -> /nix/store/ingfzbahcxy80drklhgxjd4204n1haab-model100-builtin-shajra-hex
-├── build-model100-factory-flash -> /nix/store/vk6mpawwgrrg7lyigwzn0wmj37wm94j1-model100-factory-flash
-├── build-model100-factory-hex -> /nix/store/9bm06gvn5h21gk1hxwn89hbd220fwvkw-model100-factory-hex
+├── build-model01-builtin-shajra-flash -> /nix/store/92mdwd12v03azygy6x0k3k99xcil5idq-model01-builtin-shajra-flash
+├── build-model01-builtin-shajra-hex -> /nix/store/kvik2b3r96d3g3sfxzl2fppkq6afin7f-model01-builtin-shajra-hex
+├── build-model01-factory-flash -> /nix/store/8h7idnxnk6lqxfdk599iggfz8a47k7hn-model01-factory-flash
+├── build-model01-factory-hex -> /nix/store/pb8ivna4nbdhzpf4xss0j3hfvay8qfcj-model01-factory-hex
+├── build-model100-builtin-shajra-flash -> /nix/store/s7i74bc9h6qk0i5x7q5sslqbsprpyhy0-model100-builtin-shajra-flash
+├── build-model100-builtin-shajra-hex -> /nix/store/c67gyphcghhqv2hhbnvwl5fvjdwavrys-model100-builtin-shajra-hex
+├── build-model100-factory-flash -> /nix/store/l7nwf0afsw6z2k06w13pnzldaazvag4z-model100-factory-flash
+├── build-model100-factory-hex -> /nix/store/lfgm06rj71hq5brfljyw845a5gpxjfn1-model100-factory-hex
 ├── build-moonlander-builtin-shajra-flash -> /nix/store/ybfqxcp7m0ah44l16fhlighqh9sa8msv-moonlander-builtin-shajra-flash
 ├── build-moonlander-builtin-shajra-hex -> /nix/store/qiznnlymwh7wn5pdc0b87i527carcalk-moonlander-builtin-shajra.bin
 ├── build-moonlander-factory-flash -> /nix/store/m349s0ml89pfmaxp2swzs5d5zqxd60p3-moonlander-factory-flash
 ├── build-moonlander-factory-hex -> /nix/store/5136516h4jqlwij63kn4y4fzdb7bjjgs-moonlander-factory.bin
-├── flash-ergodoxez -> /nix/store/zm3ym7p85sclsc41h0plaz8ffli7b1i3-flash-ergodoxez
-├── flash-model01 -> /nix/store/nz2dad9c4i2dsj5w4gf088iza4hn6lb4-flash-model01
-├── flash-model100 -> /nix/store/bwwklv5d0iz4ln1znvyjadg0h13qkxib-flash-model100
-├── flash-moonlander -> /nix/store/54wyh4kbsb1vmkpgjx0m65wxi1v1l5vd-flash-moonlander
+├── flash-ergodoxez -> /nix/store/in8mcv0adj19f3k41wmfbxf9y4clrixp-flash-ergodoxez
+├── flash-model01 -> /nix/store/xmpdcg42yfbp1vmwgy0l1mgn29jagynk-flash-model01
+├── flash-model100 -> /nix/store/dk7p44k58wk7c6y5037cixa20hvfzlam-flash-model100
+├── flash-moonlander -> /nix/store/1cw5qz47apslk9438mdic03rz9avqyal-flash-moonlander
 └── licenses -> /nix/store/cbb8gmijyrrcp89r8c4z9z3a041aq183-shajra-keyboards-licenses
 
 18 directories, 4 files

doc/nix-installation.md

@@ -145,3 +145,7 @@ Then you should see that the appropriate features are enabled:
 ```sh
 nix show-config experimental-features
 ```
+
+    fetch-tree flakes nix-command
+
+Note that the `fetch-tree` experimental feature is required and automatically enabled with the enablement of `flakes`.

doc/nix-installation.org

@@ -212,9 +212,12 @@ experimental-features = nix-command flakes
 Then you should see that the appropriate features are enabled:
 
 #+name: nix-show-config
-#+begin_src sh :results output :export both
+#+begin_src sh :results output :exports both
 nix show-config experimental-features
 #+end_src
 
 #+RESULTS: nix-show-config
-: flakes nix-command
+: fetch-tree flakes nix-command
+
+Note that the =fetch-tree= experimental feature is required and automatically
+enabled with the enablement of =flakes=.

doc/nix-language.md

@@ -105,10 +105,8 @@ nix eval --expr 'let a = 1; a = 2; in a' 2>&1 || true
 ```
 
     error: attribute 'a' already defined at «string»:1:5
-
            at «string»:1:12:
-
-                1| let a = 1; a = 2;
+                1| let a = 1; a = 2; in a
                  |            ^
 
 Note that semicolons are mandatory in all Nix forms that have them, including let-expressions. Because of Nix's strict parsing, you can neither elide semicolons nor put extra ones.
@@ -138,14 +136,12 @@ nix eval --expr '
 
     error:
            … while evaluating a path segment
-
              at «string»:3:9:
-
                 2|     let a_number = 42;
                 3|     in "${a_number} is a terrible number"
                  |         ^
 
-           error: cannot coerce an integer to a string
+           error: cannot coerce an integer to a string: 42
 
 We can use a builtin `toString` function to coerce types to strings:
 
@@ -176,9 +172,7 @@ nix eval --expr "''In $FROM_SHELL expansion still happens.''" 2>&1 || true
 ```
 
     error: undefined variable 'EXPANDED_BY_NIX'
-
            at «string»:1:8:
-
                 1| ''In ${EXPANDED_BY_NIX} expansion still happens.''
                  |        ^
 
@@ -271,9 +265,7 @@ nix eval --expr '{ a = b; b = 2; }.a' 2>&1 || true
 ```
 
     error: undefined variable 'b'
-
            at «string»:1:7:
-
                 1| { a = b; b = 2; }.a
                  |       ^
 
@@ -293,16 +285,12 @@ nix eval --expr '({ a }: a + 2 ) { a = 3; b = 4; }' 2>&1 || true
 
     error:
            … from call site
-
              at «string»:1:1:
-
                 1| ({ a }: a + 2 ) { a = 3; b = 4; }
                  | ^
 
            error: function 'anonymous lambda' called with unexpected argument 'b'
-
            at «string»:1:2:
-
                 1| ({ a }: a + 2 ) { a = 3; b = 4; }
                  |  ^
            Did you mean a?

doc/nix-language.org

@@ -132,10 +132,8 @@ nix eval --expr 'let a = 1; a = 2; in a' 2>&1 || true
 
 #+RESULTS:
 : error: attribute 'a' already defined at «string»:1:5
-: 
 :        at «string»:1:12:
-: 
-:             1| let a = 1; a = 2;
+:             1| let a = 1; a = 2; in a
 :              |            ^
 
 Note that semicolons are mandatory in all Nix forms that have them, including
@@ -170,18 +168,14 @@ nix eval --expr '
 #+end_src
 
 #+RESULTS:
-#+begin_example
-error:
-       … while evaluating a path segment
-
-         at «string»:3:9:
-
-            2|     let a_number = 42;
-            3|     in "${a_number} is a terrible number"
-             |         ^
-
-       error: cannot coerce an integer to a string
-#+end_example
+: error:
+:        … while evaluating a path segment
+:          at «string»:3:9:
+:             2|     let a_number = 42;
+:             3|     in "${a_number} is a terrible number"
+:              |         ^
+: 
+:        error: cannot coerce an integer to a string: 42
 
 We can use a builtin =toString= function to coerce types to strings:
 
@@ -223,9 +217,7 @@ nix eval --expr "''In $FROM_SHELL expansion still happens.''" 2>&1 || true
 
 #+RESULTS:
 : error: undefined variable 'EXPANDED_BY_NIX'
-: 
 :        at «string»:1:8:
-: 
 :             1| ''In ${EXPANDED_BY_NIX} expansion still happens.''
 :              |        ^
 
@@ -341,9 +333,7 @@ nix eval --expr '{ a = b; b = 2; }.a' 2>&1 || true
 
 #+RESULTS:
 : error: undefined variable 'b'
-: 
 :        at «string»:1:7:
-: 
 :             1| { a = b; b = 2; }.a
 :              |       ^
 
@@ -368,16 +358,12 @@ nix eval --expr '({ a }: a + 2 ) { a = 3; b = 4; }' 2>&1 || true
 #+begin_example
 error:
        … from call site
-
          at «string»:1:1:
-
             1| ({ a }: a + 2 ) { a = 3; b = 4; }
              | ^
 
        error: function 'anonymous lambda' called with unexpected argument 'b'
-
        at «string»:1:2:
-
             1| ({ a }: a + 2 ) { a = 3; b = 4; }
              |  ^
        Did you mean a?

doc/nix-usage-flakes.md

@@ -171,7 +171,7 @@ For commands accepting installables as an argument, if none are provided, then `
 We can use the `nix search` command to see what package derivations a flake contains. For example, from the root directory of this project, we can execute:
 
 ```sh
-nix search .
+nix search . ^
 ```
 
     * packages.x86_64-linux.default
@@ -185,7 +185,7 @@ nix search .
     * packages.x86_64-linux.flash-model100
     …
 
-If a flake has a lot of packages, you can pass regexes to prune down the search. Returned values will match all the regexes provided.
+We're required to pass regexes as final arguments to prune down the search. Above we've passed `^` to match everything and return all results.
 
 We can also search a remote repository for packages to install. For example, Nixpkgs is a central repository for Nix, providing several thousand packages. We can search the “nixpkgs-unstable” branch of [Nixpkgs' GitHub repository](https://github.com/NixOS/nixpkgs) for packages that match both “gpu|opengl|accel” and “terminal” as follows:
 
@@ -222,7 +222,7 @@ nix search nixpkgs 'gpu|opengl|accel' terminal | ansifilter
 If we're curious about what version of WezTerm is available in NixOS's latest release, we can specialize the installable we're searching as follows:
 
 ```sh
-nix search nixpkgs/nixos-24.11#wezterm
+nix search nixpkgs/nixos-24.11#wezterm ^
 ```
 
     * legacyPackages.x86_64-linux.wezterm (20240203-110809-5046fc22)
@@ -363,7 +363,7 @@ nix run .#licenses-thirdparty  -- --help
 We can see some of the metadata of this package with the `--json` switch of `nix search`:
 
 ```sh
-nix search --json .#licenses-thirdparty | jq .
+nix search --json .#licenses-thirdparty ^ | jq .
 ```
 
     {
@@ -424,22 +424,16 @@ We can see this installation by querying what's been installed:
 nix profile list
 ```
 
-    Index:              0
+    Name:               licenses-thirdparty
     Flake attribute:    packages.x86_64-linux.licenses-thirdparty
     Original flake URL: git+file:///home/shajra/src/shajra-keyboards
     Locked flake URL:   git+file:///home/shajra/src/shajra-keyboards
     Store paths:        /nix/store/cbb8gmijyrrcp89r8c4z9z3a041aq183-shajra-keyboards-licenses
 
-If we want to uninstall a program from our profile, we do so by the index from this list:
+If we want to uninstall a program from our profile, we can reference it by name:
 
 ```sh
-nix profile remove 0
-```
-
-We can also provide a regex matching the full attribute path of the flake:
-
-```sh
-nix profile remove '.*licenses-thirdparty'
+nix profile remove licenses-thirdparty
 ```
 
 Also, if you look at the symlink-resolved location for your profile, you'll see that Nix retains the symlink trees of previous generations of your profile. You can even roll back to an earlier profile with the `nix profile rollback` subcommand. You can delete old generations of your profile with the `nix profile wipe-history` subcommand.

doc/nix-usage-flakes.org

@@ -290,12 +290,12 @@ We can use the =nix search= command to see what package derivations a flake
 contains. For example, from the root directory of this project, we can execute:
 
 #+begin_src sh :eval no
-nix search .
+nix search . ^
 #+end_src
 
 #+name: nix-search-local
 #+begin_src sh :dir .. :results output :exports results :post crop(text=*this*, first-n=9, last-n=0)
-nix search . | ansifilter
+nix search . ^ | ansifilter
 #+end_src
 
 #+results: nix-search-local
@@ -312,8 +312,8 @@ nix search . | ansifilter
 …
 #+end_example
 
-If a flake has a lot of packages, you can pass regexes to prune down the search.
-Returned values will match all the regexes provided.
+We're required to pass regexes as final arguments to prune down the search.
+Above we've passed =^= to match everything and return all results.
 
 We can also search a remote repository for packages to install.  For example,
 Nixpkgs is a central repository for Nix, providing several thousand packages. We
@@ -360,12 +360,12 @@ If we're curious about what version of WezTerm is available in NixOS's latest
 release, we can specialize the installable we're searching as follows:
 
 #+begin_src sh :eval no :noweb yes
-nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm
+nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm ^
 #+end_src
 
 #+name: nix-search-remote-wezterm
 #+begin_src sh :dir .. :results output :exports results :noweb yes
-nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm | ansifilter
+nix search nixpkgs/nixos-<<get("nixos-latest")>>#wezterm ^ | ansifilter
 #+end_src
 
 #+RESULTS: nix-search-remote-wezterm
@@ -584,7 +584,7 @@ search=:
 
 #+name: nix-search-details
 #+begin_src sh :dir .. :results output :exports both :noweb yes :post crop(text=*this*, first-n=5, last-n=0)
-nix search --json .#<<get("run-attr-short")>> | jq .
+nix search --json .#<<get("run-attr-short")>> ^ | jq .
 #+end_src
 
 #+RESULTS: nix-search-details
@@ -683,29 +683,21 @@ nix profile list --profile /tmp/nix-profile | ansifilter
 #+end_src
 
 #+RESULTS: nix-profile-list
-: Index:              0
+: Name:               licenses-thirdparty
 : Flake attribute:    packages.x86_64-linux.licenses-thirdparty
 : Original flake URL: git+file:///home/shajra/src/shajra-keyboards
 : Locked flake URL:   git+file:///home/shajra/src/shajra-keyboards
 : Store paths:        /nix/store/cbb8gmijyrrcp89r8c4z9z3a041aq183-shajra-keyboards-licenses
 
-If we want to uninstall a program from our profile, we do so by the index from
-this list:
-
-#+name: nix-profile-remove
-#+begin_src sh :eval no :noweb yes
-nix profile remove 0
-#+end_src
-
-We can also provide a regex matching the full attribute path of the flake:
+If we want to uninstall a program from our profile, we can reference it by name:
 
 #+begin_src sh :eval no :noweb yes
-nix profile remove '.*<<get("package-attr-short")>>'
+nix profile remove <<get("package-attr-short")>>
 #+end_src
 
 #+name: nix-profile-remove
 #+begin_src sh :dir .. :results silent :exports none :noweb yes
-nix profile remove --profile /tmp/nix-profile '.*<<get("package-attr-short")>>'
+nix profile remove --profile /tmp/nix-profile <<get("package-attr-short")>>
 #+end_src
 
 Also, if you look at the symlink-resolved location for your profile, you'll see