Tweak documentation

README.md

@@ -5,6 +5,8 @@
 
 [![img](https://github.com/shajra/nix-project/workflows/CI/badge.svg)](https://github.com/shajra/nix-project/actions)
 
+[![img](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fshajra%2Fnix-project%3Fbranch%3Dmain)](https://garnix.io)
+
 # About this project<a id="sec-1"></a>
 
 This project, Nix-project, assists the setup of other projects with the [Nix package manager](https://nixos.org/nix) leaning on [flakes](https://nixos.wiki/wiki/Flakes), an experimental Nix feature.

README.org

@@ -1,7 +1,10 @@
 #+title: Nix-based Project Tools
 #+setupfile: doc/internal/links.org
 
+#+ATTR_HTML: :alt built with GitHub Actions
 [[https://github.com/shajra/nix-project/actions][https://github.com/shajra/nix-project/workflows/CI/badge.svg]]
+#+ATTR_HTML: :alt built with Garnix
+[[https://garnix.io][https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fshajra%2Fnix-project%3Fbranch%3Dmain]]
 
 * About this project
 

doc/internal/links.org

@@ -1,6 +1,7 @@
 #+link: cachix https://cachix.org
 #+link: docstring https://en.wikipedia.org/wiki/Docstring
 #+link: fhs https://www.pathname.com/fhs/
+#+link: garnix https://garnix.io/docs/caching
 #+link: gfm https://github.github.com/gfm/
 #+link: github-actions https://github.com/shajra/nix-project/actions
 #+link: litprog https://en.wikipedia.org/wiki/Literate_programming

doc/nix-introduction.md

@@ -104,13 +104,13 @@ What makes Nix unique is that these expressions specify a way to build that's
 -   repeatable
 -   guaranteed not to conflict with anything already installed
 
-For some, it's easy to miss the degree to which Nix-built packages are precise and repeatable. If you build a package from a Nix expression on one system and then build the same expression on a system of the same architecture, you should get the same result. In most cases, the built artifacts will be identical bit-for-bit.
+For some, it's easy to miss the degree to which Nix-built packages are precise and repeatable. Nix builds in highly controlled sandbox environments. If you build a package from a Nix expression on one system and then build the same expression on a system of the same architecture, you should get the same result. In many cases, the built artifacts will be identical bit-for-bit.
 
 A system of thorough hashing accomplishes this degree of precision. In Nix, the dependencies needed to build packages are also themselves Nix packages. Every Nix expression has an associated hash calculated from the hashes of the package's dependencies and build instructions. When we change this dependency (even if only by a single bit), the hash for the Nix expression changes. This new hash cascades to a different calculated hash for any package relying on this dependency. But if nothing changes, all systems will calculate identical hashes.
 
 The repeatability and precision of Nix form the basis of how substituters are trusted as caching services across the world. It also allows us to trust remote builds more easily without worrying about deviations in environment configuration.
 
-Nix has a central substituter at <https://cache.nixos.org>, but there are third-party ones as well, like [Cachix](https://cachix.org). Before building a package, the hash for the package is calculated. If any configured substituter has a build for the hash, it's pulled down as a substitute. A certificate-based protocol is used to establish the trust of substituters. Between this protocol and the algorithm for calculating hashes in Nix, you can have confidence that a package pulled from a substituter will be identical to what you would have built locally.
+Nix has a central substituter at <https://cache.nixos.org>, but there are third-party ones as well, like [Cachix](https://cachix.org) and [Garnix](https://garnix.io/docs/caching). Before building a package, the hash for the package is calculated. If any configured substituter has a build for the hash, it's pulled down as a substitute. A certificate-based protocol is used to establish the trust of substituters. Between this protocol and the algorithm for calculating hashes in Nix, you can have confidence that a package pulled from a substituter will be equivalent to what you would have built locally.
 
 Finally, all packages are stored in `/nix/store` by their hash. This simple scheme allows us to install multiple versions of the same package without conflicts. References to dependencies all point back to the desired version in `/nix/store` they need. Though Nix has not eliminated the risk of concurrently running different versions of the same program, at least the flexibility to do so is in the user's hands.
 

doc/nix-introduction.org

@@ -152,10 +152,10 @@ What makes Nix unique is that these expressions specify a way to build that's
 - guaranteed not to conflict with anything already installed
 
 For some, it's easy to miss the degree to which Nix-built packages are precise
-and repeatable. If you build a package from a Nix expression on one system and
-then build the same expression on a system of the same architecture, you should
-get the same result. In most cases, the built artifacts will be identical
-bit-for-bit.
+and repeatable. Nix builds in highly controlled sandbox environments. If you
+build a package from a Nix expression on one system and then build the same
+expression on a system of the same architecture, you should get the same result.
+In many cases, the built artifacts will be identical bit-for-bit.
 
 A system of thorough hashing accomplishes this degree of precision. In Nix, the
 dependencies needed to build packages are also themselves Nix packages.  Every
@@ -171,12 +171,13 @@ builds more easily without worrying about deviations in environment
 configuration.
 
 Nix has a central substituter at https://cache.nixos.org, but there are
-third-party ones as well, like [[cachix][Cachix]]. Before building a package, the hash for
-the package is calculated. If any configured substituter has a build for the
-hash, it's pulled down as a substitute. A certificate-based protocol is used to
-establish the trust of substituters. Between this protocol and the algorithm for
-calculating hashes in Nix, you can have confidence that a package pulled from a
-substituter will be identical to what you would have built locally.
+third-party ones as well, like [[cachix][Cachix]] and [[garnix][Garnix]]. Before building a package, the
+hash for the package is calculated. If any configured substituter has a build
+for the hash, it's pulled down as a substitute. A certificate-based protocol is
+used to establish the trust of substituters. Between this protocol and the
+algorithm for calculating hashes in Nix, you can have confidence that a package
+pulled from a substituter will be equivalent to what you would have built
+locally.
 
 Finally, all packages are stored in =/nix/store= by their hash. This simple
 scheme allows us to install multiple versions of the same package without

doc/nix-usage-noflakes.md

@@ -305,6 +305,7 @@ nix-env --install --file . --attr packages.x86_64-linux.org2gfm 2>&1
 ```
 
     installing 'org2gfm'
+    building '/nix/store/hs9xz17vlb2m4qn6kxfmccgjq4jyrvqg-user-environment.drv'...
 
 We can see this installation by querying what's been installed:
 

doc/nix-usage-noflakes.org

@@ -557,6 +557,7 @@ nix-env --profile /tmp/nix-profile \
 
 #+RESULTS: nix-env-install
 : installing 'org2gfm'
+: building '/nix/store/hs9xz17vlb2m4qn6kxfmccgjq4jyrvqg-user-environment.drv'...
 
 We can see this installation by querying what's been installed: