chore: Edit chapters: ch00-00, ch01-00, ch02-00

.envrc

@@ -0,0 +1 @@
+use flake

.gitignore

@@ -1,4 +1,5 @@
 result*
+.direnv/
 
 # This is the output directory of mdbook
 book

README.md

@@ -3,13 +3,15 @@ The Nix Package Manager
 
 Rendered book can be found at https://book.divnix.com/
 
-This book is heavily inspired by the [rust-lang/book](https://doc.rust-lang.org/stable/book/) and serves to provide new nix users a quick introduction to fundamental nix concepts.
+This book is heavily inspired by the [rust-lang/book](https://doc.rust-lang.org/stable/book/) and serves to provide new Nix users a quick introduction to fundamental Nix concepts.
 
 It's recommended to use this resource as a precursor to [nix-pills](https://nixos.org/guides/nix-pills/) which is much more in-depth on details, but a much longer read.
 
 ## Contributing
 
-Use `nix develop` to have `mdbook` on your shell.
+For a dev environment with `mdbook` on your shell:
+
+Use `nix develop` or `direnv allow`
 
 Run `mdbook serve` to launch a local webserver hosting the contents
 

flake.nix

@@ -1,5 +1,5 @@
 {
-  description = "Nix-book";
+  description = "Nix-Book: The Nix Package Manager";
 
   inputs = {
     utils.url = "github:numtide/flake-utils";
@@ -8,23 +8,21 @@
 
   outputs = { self, nixpkgs, utils }:
     let
+      systems = ["x86_64-linux" "aarch64-linux" "x86_64-darwin"];
       localOverlay = import ./nix/overlay.nix;
-      pkgsForSystem = system: import nixpkgs {
-        overlays = [
-          localOverlay
-        ];
-        inherit system;
+      forSystem = system: rec {
+        legacyPackages = import nixpkgs {
+          inherit system;
+          overlays = [localOverlay];
+        };
+        packages = utils.lib.flattenTree {
+          inherit (legacyPackages) devShell nix-book;
+        };
+        defaultPackage = packages.nix-book;
+        apps.nix-book = utils.lib.mkApp {drv = packages.nix-book;};
+        hydraJobs = {inherit (legacyPackages) nix-book;};
+        checks = {inherit (legacyPackages) nix-book;};
       };
-    in utils.lib.eachSystem [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" ] (system: rec {
-      legacyPackages = pkgsForSystem system;
-      packages = utils.lib.flattenTree {
-        inherit (legacyPackages) devShell nix-book;
-      };
-      defaultPackage = packages.nix-book;
-      apps.nix-book = utils.lib.mkApp { drv = packages.nix-book; };
-      hydraJobs = { inherit (legacyPackages) nix-book; };
-      checks = { inherit (legacyPackages) nix-book; };
-  }) // {
-    overlay = localOverlay;
-  };
+    in
+      utils.lib.eachSystem systems forSystem // { overlay = localOverlay; };
 }

src/ch00-00-the-nix-package-manager.md

@@ -2,8 +2,10 @@
 
 *by Jonathan Ringer and Tim Deherra*
 
-This book assumes usage of the nix 3.0 cli. Which can be enabled in nix 2.4+
-[following these instructions](https://nixos.wiki/wiki/Flakes#Enable_flakes).
+This book assumes usage of the nix 3.0 cli.
+
+This can be enabled in nix 2.4 by [following these instructions](https://nixos.wiki/wiki/Flakes#Enable_flakes).
 
 This book is available on the web at [https://book.divnix.com/](https://book.divnix.com/).
+
 For changes to the book, please see the [https://github.com/divnix/nix-book](https://github.com/divnix/nix-book).

src/ch01-00-preface.md

@@ -1,22 +1,20 @@
 # Preface
 
-My journey to learn nix was only possible by my extreme desire to master it.
+My journey to learn Nix was only made possible by my extreme desire to master it.
 The path was anything but easy and predictable. And it is still a considerable
-hurdle for many trying to learn nix.
+hurdle for many who try to learn Nix.
 
 The goal of this book is to provide newcomers with a more approachable
 document than the [nix-pills series](https://nixos.org/guides/nix-pills).
-Although nix-pills is still a very good resource
+Although nix-pills is a very good resource
 with many years of refinement, it is extensive and hard to follow without
-some prior knowledge of nix. This book hopes to 
-provide a more recent account of nix with more of a focus on giving the user
-intuition around what nix is doing rather than a deep understanding like nix-pills.
+some prior knowledge of Nix. This book hopes to
+provide a more recent account of Nix with more of a focus on giving the user
+intuition around what Nix is doing rather than a deep understanding like nix-pills.
 
-The goal is not to replace any existing nix guides or documentation, but rather
-provide a good starting place for new users. Motivation for writing
-this is to provide a "nix equilavent of the [rust-lang book](https://doc.rust-lang.org/book/)".
-Where there is one resource which can be read end-to-end in an afternoon and
-able to equip the reader with the knowledge necessary
-to thrive in the nix ecosystem.
+The motivation for writing this is to provide a "Nix equivalent of the [rust-lang book](https://doc.rust-lang.org/book/)":
+one resource that can be read end-to-end in an afternoon that is able to equip the reader with the
+knowledge necessary to thrive in the Nix ecosystem. The goal is not to replace any existing Nix
+guides or documentation, but rather provide a good starting place for new users.
 
--- Jonathan Ringer
+<div style="text-align: right">– Jonathan Ringer</div>

src/ch02-00-introduction.md

@@ -2,114 +2,126 @@
 
 # The Nix Package Manager
 
-Nix is a package manager which focuses on
-caputuring all inputs which contribute to building software.
+Nix is a package manager that focuses on
+capturing all inputs which contribute to building software.
 The result of factoring all of the information about building
-the software is called a derivation. This aggregated information includes where
-the source code is pulled, configuration flags, patches,
+the software is called a *derivation*. This information includes from where
+the source code is downloaded, configuration flags, patches,
 dependencies, build steps, installation steps, and many other potential inputs.
 
-This information is aggregated through hashing, and allows nix to
+This information is hashed, which allows Nix to
 describe and reference the exact software which is intended to use.
-This enables nix to be used on any system because it's assumptions
-do not collide with the assumptions of a host system. This also means that
-nix does not adhere to the traditional [File Hierarchical System(FHS)](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard)
+This enables Nix to be used on any system because its assumptions
+do not collide with the assumptions of a host system. This means that
+Nix does not adhere to the traditional [File Hierarchical System (FHS)][fhs]
 but it also means that it's not limited to FHS's restriction of only having
-a single variant of a piece of software.
+a single variant of a piece of software: You can have multiple versions of
+the same software installed, or the same version installed twice compiled with
+two different set of compile flags without conflict.
+
+[fhs]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
 
 # Who is Nix For
 
 ## Teams of Developers
 
-Development needs to have similar tooling across every individual. Having divergent
-development environments and productions environments is a major cause of regressions
-in software development. Nix can help mitigate this by allowing development environments
-to be version controlled and maintained along with a project.
+Each developer on a team needs access to the same development environment.
+
+Development environments need to reflect the build and production environments.
+
+When these diverge, software may fail to build or run properly after a software delivery was made.
+Having divergent development, build and production environments is a major cause of regressions
+in software development. Nix can help mitigate this by allowing environments to be version
+controlled and maintained along with a project. Nix can also lower the onboarding time of new
+developers by automating installation instructions.
 
-## DevOps (Operations)
+## DevOps
 
-Nix allows you to precisely describe the software you intended to use. Nix packages
+Nix allows you to precisely describe the software you intend to use. Nix packages
 are defined by their dependencies, so they inherently retain their SBOM (Software Bill of Materials)
 by default. By leveraging NixOS modules, one can also create configurable services and compose
-it into coherent systems. The combination of Nix + NixOS allows you to have declarative configuration
-of both services and systems.
+them into coherent systems. The combination of Nix + NixOS allows you to have declarative configuration
+of both services and systems of multiple machines and architectures.
 
 ## System Administrators (home to enterprise)
 
-Ever have to maintain a few systems to a few hundred systems? The ability to version control and manipulate
-systems-as-code enables a new paradigm of system configuration management. Atomically apply or rollback
-system updates for each system. Nixpkgs can also be freely extended to include personal or private additions
-of software; this allows you to leverage all other Nix tooling as though your application-specific software
-was a first-class citizen.
+Nix allows you to maintain dozens to hundreds of systems: Placing a system's configuration as code
+in version control enables a new paradigm of system configuration management. Atomically apply or
+rollback system updates for each system. Nixpkgs can be freely extended to include private additions
+to software.
 
-Also, Nix largely invalidates the need for docker. However, nix can also be used to produce docker images
-if there is a downstream technology which consumes oci images as an interface (E.g. kubernetes).
+Nix largely replaces the need for Docker. However, Nix can also be used to produce Docker images
+if there is a downstream technology which consumes OCI images as an interface (e.g. Kubernetes).
 
 ## Power Users
 
-Do you have incredible specific or opinated environments? Nix allows you to declaratively create
-project (flakes), user (home-manager), or system (NixOS) environments with the exact software
-and configuration you desired. Whether you're building software or ricing a desktop, nix will allow
-you to version control and specify your configuration exactly how you intended.
+Nix allows for incredibly specific or opinionated environments. Nix allows you to declare projects
+(flakes), user directory configuration ([home-manager][hm]), or system environments (NixOS) with the exact
+same software. Whether you're a software developer, or you're tweaking the appearance of your desktop
+system, Nix will allow you to control and specify configuration exactly as you intend, and persist
+this across multiple machines.
+
+[hm]: https://github.com/nix-community/home-manager
 
 # The Nix Ecosystem
 
-There's roughly four layers of abstractions in the official nix ecosystem, these are:
+There's roughly four layers of abstractions in the official Nix ecosystem, these are:
 
-- Nix - The domain-specifc language used to write nix expressions
+- Nix - The domain-specifc language used to write Nix expressions
 - Nix - The package manager
 - Nixpkgs - The official Nix package repository
-- NixOS - A linux distribution built upon nixpkgs
+- NixOS - A Linux distribution built on Nixpkgs
+
+There are also a several unofficial projects commonly used within the community. Some of these are:
 
-There are also a few unofficial projects which are commonly used within the community:
-- [Home-manager](https://github.com/nix-community/home-manager) - NixOS-like user configuration for linux or MacOS built upon nixpkgs
+- [home-manager][hm] - NixOS-like user configuration for Linux or MacOS built on Nixpkgs
 - [Nix-darwin](https://github.com/LnL7/nix-darwin) - NixOS-like configuration, but for MacOS
 
-All of these topics will be discussed in greater detail in later sections, but a 
+These topics will be discussed in greater detail in later sections, but a
 quick summary of official projects are provided below.
 
-## The Nix Language
+## Nix: The Language
 
 The Nix language is a Domain-Specific Language (DSL) which is designed to
-handle package configuration. Nix can be thought of [JSON](https://en.wikipedia.org/wiki/JSON) + functions +
-some syntax sugar. It's main goal is to provide effect-free evaluation of
-package configuration, to this point Nix is restricted in many ways and lacks
+handle package configuration. Nix can be thought of [JSON](https://en.wikipedia.org/wiki/JSON) +
+functions + imports + some syntax sugar. Its main goal is to provide *effect-free evaluation* of
+package configuration. For that reason, Nix is restricted in many ways and lacks
 many features from generic programming languages. There is very limited input and
 output possible to the system, there are no loops, no concurrency primitives, and
-no types. What is left is a small functional-oriented programming language. After all,
+no types. What is left is a small functional programming language. After all,
 Nix's goal is to take a few inputs such as a system platform, and produce a build
-graph which can be used to build software.
+graph which can be used as a recipe to build software.
 
-## Nix the Package Manager
+## Nix: The Package Manager
 
 The Nix Package Manager began its life as the [PhD thesis work](https://edolstra.github.io/pubs/phd-thesis.pdf)
 of Eelco Dolstra. The goal was to bring discipline to the software landscape. Similar to
 how structured programming helped tame the complexity of goto through introducing constructs such
-as loops and logic flow; so too does nix attempt to tame the chaos of package management
-through explicit descriptions of software and their dependencies. The truely novel idea
+as loops and logic flow; so too does Nix attempt to tame the chaos of package management
+through explicit descriptions of software and their dependencies. The truly novel idea
 of Nix is that of the *derivation*. It encapsulates everything about a piece of software,
-and these derivations can be referenced from other derivations constituting a Directed-Acyclic-Graph
-of how to built that software from source.
+and these derivations can be referenced from other derivations constituting a *directed, acyclic
+graph* (DAG) of how to built that software from source.
 
-## Nixpkgs
+## Nixpkgs: The Package Repository
 
 Nixpkgs is the official package repository for the Nix community. It contains the logic
 on how to build over 60,000+ software packages. Nixpkgs can be thought of as an
 expert body-of-knowledge on the subject of how to build software. When a user
-asks for the "firefox" package, the nix package manager is able to input the user's computer
-platform into nixpkgs, and nixpkgs is then able to produce a build graph on
-how to build firefox and all of it's dependencies down to the C compiler.
-This allows for a great deal of freedom in how nix is leveraged, and nix can be used on any Linux distribution and MacOS as
-first class supported OS's, and to a much lesser degree on many other UNIX-like OS's.
+asks for the "firefox" package, the Nix package manager is able to query Nixpkgs
+and produce a build graph on how to build Firefox and all of its dependencies down
+to the C compiler, for that user's platform.
+This allows for a great deal of freedom: Nix can be used on any Linux distribution and MacOS as
+first class supported OS'es, and to a lesser degree on many other UNIX-like OS'es.
 
 Nixpkgs is also supported by [Hydra](https://hydra.nixos.org/), which provides
 pre-built binaries of libre software for Linux and MacOS.
 
-## NixOS
+## NixOS: The Operating System
 
-NixOS is a non-FHS Linux distribution which leverages nixpkgs to provide a wealth
-of software ready to be combined into a system environment. The concept of a nix
+NixOS is a [non-FHS][fhs] Linux distribution which leverages Nixpkgs to provide a wealth
+of software ready to be combined into a system environment. The concept of a Nix
 derivation is extended here to include service configuration and system creation.
-The entirity of the system is represented as a derivation which gives it many of
-it's defining qualities such as atomic rollbacks, system-as-a-configuration-file,
+The entirety of the system is represented as a derivation which gives it many of
+its defining qualities such as atomic rollbacks, system-as-a-configuration-file, and
 extensive user configuration potential.