From 2799fe4cdbe77e017544f2fe61ae9baef650dbe6 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Tue, 21 Dec 2021 19:34:40 +0100
Subject: enable LTO in optimized builds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

gives 2-5% performance improvement across a board of tests.
LTO is broken when using clang; some libs link fine while others crash
the linker with a segfault in the llvm linker plugin. 🙁
---
 doc/manual/src/release-notes/rl-next.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7dd8387d8..d81e54e49 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -26,3 +26,6 @@
 
 * Templates can now define a `welcomeText` attribute, which is printed out by
   `nix flake {init,new} --template <template>`.
+
+* Nix can now be built with LTO by passing `--enable-lto` to `configure`.
+  LTO is currently only supported when building with GCC.
-- 
cgit v1.2.3


From fda2224b591c2667d18fb815f117f48b45a54cb1 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 7 Apr 2022 19:45:38 +0000
Subject: Add release notes mark experimental

---
 doc/manual/src/release-notes/rl-next.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 8c8c0fd41..97627cc96 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -40,3 +40,6 @@
 
   As before, the old output will continue to work, but `nix flake check` will
   issue a warning about it.
+
+* Add experimental *indexed store derivations* installable syntax, part of the
+  the `computed-derivations` experimental feature.
-- 
cgit v1.2.3


From 0e2b01b14e77dfb9a6f1748dec353273f91d1609 Mon Sep 17 00:00:00 2001
From: ckie <git-525ff67@ckie.dev>
Date: Mon, 18 Apr 2022 20:21:47 +0300
Subject: nix repl: make symlinks with the :bl command

Requested by ppepino on the Matrix:
https://matrix.to/#/!KqkRjyTEzAGRiZFBYT:nixos.org/$Tb32BS3rVE2BSULAX4sPm0h6CDewX2hClOTGzTC7gwM?via=nixos.org&via=matrix.org&via=nixos.dev

This adds a new command, :bl, which works like :b but also creates
a GC root symlink to the various derivation outputs.

ckie@cookiemonster ~/git/nix -> ./outputs/out/bin/nix repl
Welcome to Nix 2.6.0. Type :? for help.

nix-repl> :l <nixpkgs>
Added 16118 variables.

nix-repl> :b runCommand "hello" {} "echo hi > $out"

This derivation produced the following outputs:
  ./repl-result-out -> /nix/store/kidqq2acdpi05c4a9mlbg2baikmzik44-hello
[1 built, 0.0 MiB DL]
ckie@cookiemonster ~/git/nix -> cat ./repl-result-out
hi
---
 doc/manual/src/release-notes/rl-next.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index c869b5e2f..3e2998c6c 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1 +1,4 @@
 # Release X.Y (202?-??-??)
+
+* `nix repl` has a new build-'n-link (`:bl`) command that builds a derivation
+  while creating GC root symlinks.
-- 
cgit v1.2.3


From 51cfea8bb05d3f284534b2486cc29bb0ebf17ade Mon Sep 17 00:00:00 2001
From: Artturin <Artturin@artturin.com>
Date: Sat, 19 Mar 2022 20:16:05 +0200
Subject: nix build: add --print-out-paths flag

has the same functionality as default nix-build

$ nix-build . -A "bash" -A "bash.dev" -A "tinycc"
/nix/store/4nmqxajzaf60yjribkgvj5j54x9yvr1r-bash-5.1-p12
/nix/store/c49i1ggnr5cc8gxmk9xm0cn961z104dn-bash-5.1-p12-dev
/nix/store/dbapb08862ajgaax3621fz8hly9fdah3-tcc-0.9.27+date=2022-01-11

$ nix-build . -A "bash"
/nix/store/4nmqxajzaf60yjribkgvj5j54x9yvr1r-bash-5.1-p12

$ $HOME/nixgits/nix/result/bin/nix build "nixpkgs#bash" "nixpkgs#bash.dev" "nixpkgs#tinycc" --print-out-paths
/nix/store/4nmqxajzaf60yjribkgvj5j54x9yvr1r-bash-5.1-p12
/nix/store/c49i1ggnr5cc8gxmk9xm0cn961z104dn-bash-5.1-p12-dev
/nix/store/dbapb08862ajgaax3621fz8hly9fdah3-tcc-0.9.27+date=2022-01-11

$ $HOME/nixgits/nix/result/bin/nix build "nixpkgs#bash" --print-out-paths
/nix/store/4nmqxajzaf60yjribkgvj5j54x9yvr1r-bash-5.1-p12
---
 doc/manual/src/release-notes/rl-next.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 3e2998c6c..452002dca 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -2,3 +2,6 @@
 
 * `nix repl` has a new build-'n-link (`:bl`) command that builds a derivation
   while creating GC root symlinks.
+
+* `nix build` has a new `--print-out-paths` flag to print the resulting output paths.
+  This matches the default behaviour of `nix-build`.
-- 
cgit v1.2.3


From f25112d3832b93a2bc8abe7936e6355dae9a25d5 Mon Sep 17 00:00:00 2001
From: Tom Bereknyei <tomberek@gmail.com>
Date: Thu, 21 Apr 2022 16:41:37 -0400
Subject: fix: builtins.toFile adds path to allowedPaths

The produced path is then allowed be imported or utilized elsewhere:
```
assert (43 == import (builtins.toFile "source" "43")); "good"
```

This will still fail on write-only stores.
---
 doc/manual/src/release-notes/rl-next.md | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 3e2998c6c..f16ae901c 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -2,3 +2,7 @@
 
 * `nix repl` has a new build-'n-link (`:bl`) command that builds a derivation
   while creating GC root symlinks.
+
+* The path produced by `builtins.toFile` is now allowed to be imported or read
+  even with restricted evaluation. Note that this will not work with a
+  read-only store.
-- 
cgit v1.2.3


From c67d8876c34bdcfbc0d3ea9e68e68dc90fbdaeac Mon Sep 17 00:00:00 2001
From: midchildan <git@midchildan.org>
Date: Mon, 25 Apr 2022 01:23:49 +0900
Subject: feat: add integration with zsh's run-help

---
 doc/manual/src/release-notes/rl-next.md | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 06c2583c9..7b3ad4e58 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,5 +1,10 @@
 # Release X.Y (202?-??-??)
 
+* Nix now provides better integration with zsh's run-help feature. It is now
+  included in the Nix installation in the form of an autoloadable shell
+  function, run-help-nix. It picks up Nix subcommands from the currently typed
+  in command and directs the user to the associated man pages.
+
 * `nix repl` has a new build-'n-link (`:bl`) command that builds a derivation
   while creating GC root symlinks.
 
-- 
cgit v1.2.3


From 9ff892aad4ee13532ea84cb6e4a2a53d70945efe Mon Sep 17 00:00:00 2001
From: Guillaume Maudoux <guillaume.maudoux@tweag.io>
Date: Fri, 29 Apr 2022 11:24:48 +0200
Subject: Add release notes for error traces revamp

---
 doc/manual/src/release-notes/rl-next.md | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7b3ad4e58..f312f2f86 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -14,3 +14,7 @@
 
 * `nix build` has a new `--print-out-paths` flag to print the resulting output paths.
   This matches the default behaviour of `nix-build`.
+
+* Error traces have been reworked to provide detailed explanations and more
+  accurate error locations. A short excerpt of the trace is now shown by
+  default when an error occurs.
-- 
cgit v1.2.3


From 4a79cba5118f29b896f3d50164beacd4901ab01f Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 22 Apr 2022 15:17:01 +0200
Subject: Allow selecting derivation outputs using 'installable!outputs'

E.g. 'nixpkgs#glibc^dev,static' or 'nixpkgs#glibc^*'.
---
 doc/manual/src/release-notes/rl-next.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7b3ad4e58..efd893662 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -14,3 +14,13 @@
 
 * `nix build` has a new `--print-out-paths` flag to print the resulting output paths.
   This matches the default behaviour of `nix-build`.
+
+* You can now specify which outputs of a derivation `nix` should
+  operate on using the syntax `installable^outputs`,
+  e.g. `nixpkgs#glibc^dev,static` or `nixpkgs#glibc^*`. By default,
+  `nix` will use the outputs specified by the derivation's
+  `meta.outputsToInstall` attribute if it exists, or all outputs
+  otherwise.
+
+  Selecting derivation outputs using the attribute selection syntax
+  (e.g. `nixpkgs#glibc.dev`) no longer works.
-- 
cgit v1.2.3


From 7c75f1d52b3078608be29cbe0b009875829cc03f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?=
 <theophane.hufschmitt@tweag.io>
Date: Tue, 10 May 2022 11:56:47 +0200
Subject: Expand the testing section of the hacking docs

- Make it clear what the different kind of tests are, where they live
  and how they can be ran
- Ask people to primarily write unit tests
---
 doc/manual/src/contributing/hacking.md | 41 ++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 12 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 90a8f1f94..7ce8d8de6 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -71,18 +71,6 @@ To install it in `$(pwd)/outputs` and test it:
 nix (Nix) 3.0
 ```
 
-To run a functional test:
-
-```console
-make tests/test-name-should-auto-complete.sh.test
-```
-
-To run the unit-tests for C++ code:
-
-```
-make check
-```
-
 If you have a flakes-enabled Nix you can replace:
 
 ```console
@@ -94,3 +82,32 @@ by:
 ```console
 $ nix develop
 ```
+
+## Testing
+
+Nix comes with three different flavors of tests: unit, functional and integration.
+
+Most tests are currently written as functional tests.
+**However**, it is preferable (as much as it makes sense) to primarily test new code with unit tests.
+
+### Unit-tests
+
+The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined
+under `src/{library_name}/tests` using the
+[googletest](https://google.github.io/googletest/) framework.
+
+You can run the whole testsuite with `make check`, or the tests for a specific component with `make libfoo-tests_RUN`. Finer-grained filtering is also possible using the [--gtest_filter](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) command-line option.
+
+### Functional tests
+
+The functional tests reside under the `tests` directory and are listed in `tests/local.mk`.
+The whole testsuite can be run with `make install && make installcheck`.
+Individual tests can be run with `make tests/{testName}.sh.test`.
+
+### Integration tests
+
+The integration tests are defined in the Nix flake under the `hydraJobs.tests` attribute.
+These tests include everything that needs to interact with external services or run Nix in a non-trivial distributed setup.
+Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on <https://hydra.nixos.org/jobset/nix/master>).
+
+You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}`
-- 
cgit v1.2.3


From 65a913d29be7305b2c743fb92c93f0e6bb12d610 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?=
 <theophane.hufschmitt@tweag.io>
Date: Thu, 12 May 2022 12:02:31 +0200
Subject: =?UTF-8?q?Don=E2=80=99t=20recommend=20writing=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As asked in <https://github.com/NixOS/nix/pull/6517#discussion_r869416905>
---
 doc/manual/src/contributing/hacking.md | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 7ce8d8de6..59ce5cac7 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -87,9 +87,6 @@ $ nix develop
 
 Nix comes with three different flavors of tests: unit, functional and integration.
 
-Most tests are currently written as functional tests.
-**However**, it is preferable (as much as it makes sense) to primarily test new code with unit tests.
-
 ### Unit-tests
 
 The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined
-- 
cgit v1.2.3


From 1ca3f6035da4e82647382405c774e43e02de3fa1 Mon Sep 17 00:00:00 2001
From: Tom Bereknyei <tomberek@gmail.com>
Date: Fri, 11 Mar 2022 13:52:08 -0500
Subject: repl: update docs with installables

---
 doc/manual/src/release-notes/rl-next.md | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index efd893662..096499bc3 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -24,3 +24,8 @@
 
   Selecting derivation outputs using the attribute selection syntax
   (e.g. `nixpkgs#glibc.dev`) no longer works.
+
+* `nix repl` now takes installables on the command line, unifying the usage
+  with other commands that use `--file` and `--expr`. Primary breaking change
+  is for the common usage of `nix repl '<nixpkgs>'` which can be recovered with
+  `nix repl nixpkgs` or `nix repl --expr 'import <nixpkgs>{}'`
-- 
cgit v1.2.3


From 5b8c1deb18e0e6fc7a83fb8101cf5fc8dba38843 Mon Sep 17 00:00:00 2001
From: Tony Olagbaiye <me@fron.io>
Date: Fri, 16 Oct 2020 00:35:24 +0100
Subject: fetchTree: Allow fetching plain files

Add a new `file` fetcher type, which will fetch a plain file over
http(s), or from the local file.

Because plain `http(s)://` or `file://` urls can already correspond to
`tarball` inputs (if the path ends-up with a know archive extension),
the URL parsing logic is a bit convuluted in that:

- {http,https,file}:// urls will be interpreted as either a tarball or a
  file input, depending on the extensions of the path part (so
  `https://foo.com/bar` will be a `file` input and
  `https://foo.com/bar.tar.gz` as a `tarball` input)
- `file+{something}://` urls will be interpreted as `file` urls (with
  the `file+` part removed)
- `tarball+{something}://` urls will be interpreted as `tarball` urls (with
  the `tarball+` part removed)

Fix #3785

Co-Authored-By: Tony Olagbaiye <me@fron.io>
---
 doc/manual/src/release-notes/rl-next.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index efd893662..9f00893fd 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -24,3 +24,6 @@
 
   Selecting derivation outputs using the attribute selection syntax
   (e.g. `nixpkgs#glibc.dev`) no longer works.
+
+* `builtins.fetchTree` (and flake inputs) can now be used to fetch plain files
+  over the `http(s)` and `file` protocols in addition to directory tarballs.
-- 
cgit v1.2.3


From 82c4af41e3348a87ebc9fb583df09070beadc019 Mon Sep 17 00:00:00 2001
From: Tom Bereknyei <tomberek@gmail.com>
Date: Fri, 20 May 2022 01:49:49 -0400
Subject: repl: clarify change and usage of <nixpkgs>

---
 doc/manual/src/release-notes/rl-next.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 096499bc3..6dbf6adae 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -28,4 +28,4 @@
 * `nix repl` now takes installables on the command line, unifying the usage
   with other commands that use `--file` and `--expr`. Primary breaking change
   is for the common usage of `nix repl '<nixpkgs>'` which can be recovered with
-  `nix repl nixpkgs` or `nix repl --expr 'import <nixpkgs>{}'`
+  `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`
-- 
cgit v1.2.3


From 6031a36208dd174f05f094898d8ad35e5366106f Mon Sep 17 00:00:00 2001
From: Ben Burdette <bburdette@protonmail.com>
Date: Wed, 25 May 2022 10:38:13 -0600
Subject: add --debugger to rl-next list

---
 doc/manual/src/release-notes/rl-next.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index efd893662..a808e145a 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -24,3 +24,16 @@
 
   Selecting derivation outputs using the attribute selection syntax
   (e.g. `nixpkgs#glibc.dev`) no longer works.
+
+* Running nix with the new `--debugger` flag will cause it to start a repl session if
+  there is an exception thrown during eval, or if `builtins.break` is called.  From
+  there one can inspect symbol values and evaluate nix expressions.  In debug mode
+  the following new repl commands are available:
+  ```
+  :env          Show env stack
+  :bt           Show trace stack
+  :st           Show current trace
+  :st <idx>     Change to another trace in the stack
+  :c            Go until end of program, exception, or builtins.break().
+  :s            Go one step
+  ```
-- 
cgit v1.2.3


From 8f4548d40147b735035fcf454c487ebf4bc1ddfe Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 25 May 2022 17:14:45 +0200
Subject: Tweak IN_NIX_SHELL description

---
 doc/manual/src/command-ref/env-common.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 6e2403461..0b28a85ba 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -4,7 +4,7 @@ Most Nix commands interpret the following environment variables:
 
   - `IN_NIX_SHELL`\
     Indicator that tells if the current environment was set up by
-    `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"`
+    `nix-shell`. It can have the values `pure` or `impure`.
 
   - `NIX_PATH`\
     A colon-separated list of directories used to look up Nix
-- 
cgit v1.2.3


From 7708a34a514ddeb1420886309ae9870d8757f7ce Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Wed, 25 May 2022 12:36:46 +0200
Subject: doc: Add anchors to long lists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added using the following sed scripts:

- For command-ref/opt-common.md:

    s~- `(--?)([^`]+)`~- [`\1\2`]{#opt-\2}~g

- For expressions/builtin-constants.md:

    s~- `(builtins\.?)([^`]+)`~- [`\1\2`]{#builtins-\2}~g

- For expressions/advanced-attributes.md

    s~^  - `([^`]+)`~  - [`\1`]{#adv-attr-\1}~g

  and manually adjusted outputHashAlgo & outputHashMode.

- For glossary.md

    s~^  - (`([^`]+)`|(.+)) ?\\~  - [\1]{#gloss-\2\3}\\~g;
    s~(gloss-\w+) ~\1-~g

  and manually adjusted anchors for Nix expression, user environment, NAR, ∅ and ε.

- For command-ref/env-common.md

    s~^  - `([^`]+)`~  - [`\1`]{#env-\1}~g'
---
 doc/manual/src/command-ref/env-common.md          | 30 ++++++++--------
 doc/manual/src/command-ref/nix-build.md           |  6 ++--
 doc/manual/src/command-ref/opt-common.md          | 42 +++++++++++------------
 doc/manual/src/expressions/advanced-attributes.md | 22 ++++++------
 doc/manual/src/expressions/builtin-constants.md   |  2 +-
 doc/manual/src/glossary.md                        | 36 +++++++++----------
 6 files changed, 69 insertions(+), 69 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 6e2403461..ab048074a 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -2,11 +2,11 @@
 
 Most Nix commands interpret the following environment variables:
 
-  - `IN_NIX_SHELL`\
+  - [`IN_NIX_SHELL`]{#env-IN_NIX_SHELL}\
     Indicator that tells if the current environment was set up by
     `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"`
 
-  - `NIX_PATH`\
+  - [`NIX_PATH`]{#env-NIX_PATH}\
     A colon-separated list of directories used to look up Nix
     expressions enclosed in angle brackets (i.e., `<path>`). For
     instance, the value
@@ -44,7 +44,7 @@ Most Nix commands interpret the following environment variables:
     The Nix search path can also be extended using the `-I` option to
     many Nix commands, which takes precedence over `NIX_PATH`.
 
-  - `NIX_IGNORE_SYMLINK_STORE`\
+  - [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
     Normally, the Nix store directory (typically `/nix/store`) is not
     allowed to contain any symlink components. This is to prevent
     “impure” builds. Builders sometimes “canonicalise” paths by
@@ -66,41 +66,41 @@ Most Nix commands interpret the following environment variables:
 
     Consult the mount 8 manual page for details.
 
-  - `NIX_STORE_DIR`\
+  - [`NIX_STORE_DIR`]{#env-NIX_STORE_DIR}\
     Overrides the location of the Nix store (default `prefix/store`).
 
-  - `NIX_DATA_DIR`\
+  - [`NIX_DATA_DIR`]{#env-NIX_DATA_DIR}\
     Overrides the location of the Nix static data directory (default
     `prefix/share`).
 
-  - `NIX_LOG_DIR`\
+  - [`NIX_LOG_DIR`]{#env-NIX_LOG_DIR}\
     Overrides the location of the Nix log directory (default
     `prefix/var/log/nix`).
 
-  - `NIX_STATE_DIR`\
+  - [`NIX_STATE_DIR`]{#env-NIX_STATE_DIR}\
     Overrides the location of the Nix state directory (default
     `prefix/var/nix`).
 
-  - `NIX_CONF_DIR`\
+  - [`NIX_CONF_DIR`]{#env-NIX_CONF_DIR}\
     Overrides the location of the system Nix configuration directory
     (default `prefix/etc/nix`).
 
-  - `NIX_CONFIG`\
+  - [`NIX_CONFIG`]{#env-NIX_CONFIG}\
     Applies settings from Nix configuration from the environment.
     The content is treated as if it was read from a Nix configuration file.
     Settings are separated by the newline character.
 
-  - `NIX_USER_CONF_FILES`\
+  - [`NIX_USER_CONF_FILES`]{#env-NIX_USER_CONF_FILES}\
     Overrides the location of the user Nix configuration files to load
     from (defaults to the XDG spec locations). The variable is treated
     as a list separated by the `:` token.
 
-  - `TMPDIR`\
+  - [`TMPDIR`]{#env-TMPDIR}\
     Use the specified directory to store temporary files. In particular,
     this includes temporary build directories; these can take up
     substantial amounts of disk space. The default is `/tmp`.
 
-  - `NIX_REMOTE`\
+  - [`NIX_REMOTE`]{#env-NIX_REMOTE}\
     This variable should be set to `daemon` if you want to use the Nix
     daemon to execute Nix operations. This is necessary in [multi-user
     Nix installations](../installation/multi-user.md). If the Nix
@@ -108,16 +108,16 @@ Most Nix commands interpret the following environment variables:
     should be set to `unix://path/to/socket`. Otherwise, it should be
     left unset.
 
-  - `NIX_SHOW_STATS`\
+  - [`NIX_SHOW_STATS`]{#env-NIX_SHOW_STATS}\
     If set to `1`, Nix will print some evaluation statistics, such as
     the number of values allocated.
 
-  - `NIX_COUNT_CALLS`\
+  - [`NIX_COUNT_CALLS`]{#env-NIX_COUNT_CALLS}\
     If set to `1`, Nix will print how often functions were called during
     Nix expression evaluation. This is useful for profiling your Nix
     expressions.
 
-  - `GC_INITIAL_HEAP_SIZE`\
+  - [`GC_INITIAL_HEAP_SIZE`]{#env-GC_INITIAL_HEAP_SIZE}\
     If Nix has been configured to use the Boehm garbage collector, this
     variable sets the initial size of the heap in bytes. It defaults to
     384 MiB. Setting it to a low value reduces memory consumption, but
diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index 43de7a6e6..aacb32a25 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -47,16 +47,16 @@ All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
 `nix-instantiate`.
 
-  - `--no-out-link`\
+  - [`--no-out-link`]{#opt-no-out-link}\
     Do not create a symlink to the output path. Note that as a result
     the output does not become a root of the garbage collector, and so
     might be deleted by `nix-store
                     --gc`.
 
-  - `--dry-run`\
+  - [`--dry-run`]{#opt-dry-run}\
     Show what store paths would be built or downloaded.
 
-  - `--out-link` / `-o` *outlink*\
+  - [`--out-link`]{#opt-out-link} / `-o` *outlink*\
     Change the name of the symlink to the output path created from
     `result` to *outlink*.
 
diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md
index 7ee1a26bc..51d7de18a 100644
--- a/doc/manual/src/command-ref/opt-common.md
+++ b/doc/manual/src/command-ref/opt-common.md
@@ -2,13 +2,13 @@
 
 Most Nix commands accept the following command-line options:
 
-  - `--help`\
+  - [`--help`]{#opt-help}\
     Prints out a summary of the command syntax and exits.
 
-  - `--version`\
+  - [`--version`]{#opt-version}\
     Prints out the Nix version number on standard output and exits.
 
-  - `--verbose` / `-v`\
+  - [`--verbose`]{#opt-verbose} / `-v`\
     Increases the level of verbosity of diagnostic messages printed on
     standard error. For each Nix operation, the information printed on
     standard output is well-defined; any diagnostic information is
@@ -37,14 +37,14 @@ Most Nix commands accept the following command-line options:
       - 5\
         “Vomit”: print vast amounts of debug information.
 
-  - `--quiet`\
+  - [`--quiet`]{#opt-quiet}\
     Decreases the level of verbosity of diagnostic messages printed on
     standard error. This is the inverse option to `-v` / `--verbose`.
 
     This option may be specified repeatedly. See the previous verbosity
     levels list.
 
-  - `--log-format` *format*\
+  - [`--log-format`]{#opt-log-format} *format*\
     This option can be used to change the output of the log format, with
     *format* being one of:
 
@@ -66,14 +66,14 @@ Most Nix commands accept the following command-line options:
       - bar-with-logs\
         Display the raw logs, with the progress bar at the bottom.
 
-  - `--no-build-output` / `-Q`\
+  - [`--no-build-output`]{#opt-no-build-output} / `-Q`\
     By default, output written by builders to standard output and
     standard error is echoed to the Nix command's standard error. This
     option suppresses this behaviour. Note that the builder's standard
     output and error are always written to a log file in
     `prefix/nix/var/log/nix`.
 
-  - `--max-jobs` / `-j` *number*\
+  - [`--max-jobs`]{#opt-max-jobs} / `-j` *number*\
     Sets the maximum number of build jobs that Nix will perform in
     parallel to the specified number. Specify `auto` to use the number
     of CPUs in the system. The default is specified by the `max-jobs`
@@ -83,7 +83,7 @@ Most Nix commands accept the following command-line options:
     Setting it to `0` disallows building on the local machine, which is
     useful when you want builds to happen only on remote builders.
 
-  - `--cores`\
+  - [`--cores`]{#opt-cores}\
     Sets the value of the `NIX_BUILD_CORES` environment variable in
     the invocation of builders. Builders can use this variable at
     their discretion to control the maximum amount of parallelism. For
@@ -94,18 +94,18 @@ Most Nix commands accept the following command-line options:
     means that the builder should use all available CPU cores in the
     system.
 
-  - `--max-silent-time`\
+  - [`--max-silent-time`]{#opt-max-silent-time}\
     Sets the maximum number of seconds that a builder can go without
     producing any data on standard output or standard error. The
     default is specified by the `max-silent-time` configuration
     setting. `0` means no time-out.
 
-  - `--timeout`\
+  - [`--timeout`]{#opt-timeout}\
     Sets the maximum number of seconds that a builder can run. The
     default is specified by the `timeout` configuration setting. `0`
     means no timeout.
 
-  - `--keep-going` / `-k`\
+  - [`--keep-going`]{#opt-keep-going} / `-k`\
     Keep going in case of failed builds, to the greatest extent
     possible. That is, if building an input of some derivation fails,
     Nix will still build the other inputs, but not the derivation
@@ -113,13 +113,13 @@ Most Nix commands accept the following command-line options:
     for builds of substitutes), possibly killing builds in progress (in
     case of parallel or distributed builds).
 
-  - `--keep-failed` / `-K`\
+  - [`--keep-failed`]{#opt-keep-failed} / `-K`\
     Specifies that in case of a build failure, the temporary directory
     (usually in `/tmp`) in which the build takes place should not be
     deleted. The path of the build directory is printed as an
     informational message.
 
-  - `--fallback`\
+  - [`--fallback`]{#opt-fallback}\
     Whenever Nix attempts to build a derivation for which substitutes
     are known for each output path, but realising the output paths
     through the substitutes fails, fall back on building the derivation.
@@ -134,12 +134,12 @@ Most Nix commands accept the following command-line options:
     failure in obtaining the substitutes to lead to a full build from
     source (with the related consumption of resources).
 
-  - `--readonly-mode`\
+  - [`--readonly-mode`]{#opt-readonly-mode}\
     When this option is used, no attempt is made to open the Nix
     database. Most Nix operations do need database access, so those
     operations will fail.
 
-  - `--arg` *name* *value*\
+  - [`--arg`]{#opt-arg} *name* *value*\
     This option is accepted by `nix-env`, `nix-instantiate`,
     `nix-shell` and `nix-build`. When evaluating Nix expressions, the
     expression evaluator will automatically try to call functions that
@@ -170,13 +170,13 @@ Most Nix commands accept the following command-line options:
     since the argument is a Nix string literal, you have to escape the
     quotes.)
 
-  - `--argstr` *name* *value*\
+  - [`--argstr`]{#opt-argstr} *name* *value*\
     This option is like `--arg`, only the value is not a Nix
     expression but a string. So instead of `--arg system
     \"i686-linux\"` (the outer quotes are to keep the shell happy) you
     can say `--argstr system i686-linux`.
 
-  - `--attr` / `-A` *attrPath*\
+  - [`--attr`]{#opt-attr} / `-A` *attrPath*\
     Select an attribute from the top-level Nix expression being
     evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
     `nix-shell` only.) The *attribute path* *attrPath* is a sequence
@@ -191,7 +191,7 @@ Most Nix commands accept the following command-line options:
     attribute of the fourth element of the array in the `foo` attribute
     of the top-level expression.
 
-  - `--expr` / `-E`\
+  - [`--expr`]{#opt-expr} / `-E`\
     Interpret the command line arguments as a list of Nix expressions to
     be parsed and evaluated, rather than as a list of file names of Nix
     expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.)
@@ -202,17 +202,17 @@ Most Nix commands accept the following command-line options:
     use, give your expression to the `nix-shell -p` convenience flag
     instead.
 
-  - `-I` *path*\
+  - [`-I`]{#opt-I} *path*\
     Add a path to the Nix expression search path. This option may be
     given multiple times. See the `NIX_PATH` environment variable for
     information on the semantics of the Nix search path. Paths added
     through `-I` take precedence over `NIX_PATH`.
 
-  - `--option` *name* *value*\
+  - [`--option`]{#opt-option} *name* *value*\
     Set the Nix configuration option *name* to *value*. This overrides
     settings in the Nix configuration file (see nix.conf5).
 
-  - `--repair`\
+  - [`--repair`]{#opt-repair}\
     Fix corrupted or missing store paths by redownloading or rebuilding
     them. Note that this is slow because it requires computing a
     cryptographic hash of the contents of every path in the closure of
diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md
index 000595815..2e7e80ed0 100644
--- a/doc/manual/src/expressions/advanced-attributes.md
+++ b/doc/manual/src/expressions/advanced-attributes.md
@@ -2,7 +2,7 @@
 
 Derivations can declare some infrequently used optional attributes.
 
-  - `allowedReferences`\
+  - [`allowedReferences`]{#adv-attr-allowedReferences}\
     The optional attribute `allowedReferences` specifies a list of legal
     references (dependencies) of the output of the builder. For example,
 
@@ -17,7 +17,7 @@ Derivations can declare some infrequently used optional attributes.
     booting Linux don’t have accidental dependencies on other paths in
     the Nix store.
 
-  - `allowedRequisites`\
+  - [`allowedRequisites`]{#adv-attr-allowedRequisites}\
     This attribute is similar to `allowedReferences`, but it specifies
     the legal requisites of the whole closure, so all the dependencies
     recursively. For example,
@@ -30,7 +30,7 @@ Derivations can declare some infrequently used optional attributes.
     runtime dependency than `foobar`, and in addition it enforces that
     `foobar` itself doesn't introduce any other dependency itself.
 
-  - `disallowedReferences`\
+  - [`disallowedReferences`]{#adv-attr-disallowedReferences}\
     The optional attribute `disallowedReferences` specifies a list of
     illegal references (dependencies) of the output of the builder. For
     example,
@@ -42,7 +42,7 @@ Derivations can declare some infrequently used optional attributes.
     enforces that the output of a derivation cannot have a direct
     runtime dependencies on the derivation `foo`.
 
-  - `disallowedRequisites`\
+  - [`disallowedRequisites`]{#adv-attr-disallowedRequisites}\
     This attribute is similar to `disallowedReferences`, but it
     specifies illegal requisites for the whole closure, so all the
     dependencies recursively. For example,
@@ -55,7 +55,7 @@ Derivations can declare some infrequently used optional attributes.
     dependency on `foobar` or any other derivation depending recursively
     on `foobar`.
 
-  - `exportReferencesGraph`\
+  - [`exportReferencesGraph`]{#adv-attr-exportReferencesGraph}\
     This attribute allows builders access to the references graph of
     their inputs. The attribute is a list of inputs in the Nix store
     whose references graph the builder needs to know. The value of
@@ -84,7 +84,7 @@ Derivations can declare some infrequently used optional attributes.
     with a Nix store containing the closure of a bootable NixOS
     configuration).
 
-  - `impureEnvVars`\
+  - [`impureEnvVars`]{#adv-attr-impureEnvVars}\
     This attribute allows you to specify a list of environment variables
     that should be passed from the environment of the calling user to
     the builder. Usually, the environment is cleared completely when the
@@ -112,7 +112,7 @@ Derivations can declare some infrequently used optional attributes.
     > environmental variables come from the environment of the
     > `nix-build`.
 
-  - `outputHash`; `outputHashAlgo`; `outputHashMode`\
+  - [`outputHash`]{#adv-attr-outputHash}; [`outputHashAlgo`]{#adv-attr-outputHashAlgo}; [`outputHashMode`]{#adv-attr-outputHashMode}\
     These attributes declare that the derivation is a so-called
     *fixed-output derivation*, which means that a cryptographic hash of
     the output is already known in advance. When the build of a
@@ -208,7 +208,7 @@ Derivations can declare some infrequently used optional attributes.
     [`nix-hash` command](../command-ref/nix-hash.md) for information
     about converting to and from base-32 notation.)
     
-  - `__contentAddressed`
+  - [`__contentAddressed`]{#adv-attr-__contentAddressed}
     If this **experimental** attribute is set to true, then the derivation
     outputs will be stored in a content-addressed location rather than the
     traditional input-addressed one.
@@ -216,7 +216,7 @@ Derivations can declare some infrequently used optional attributes.
     
     Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above).
 
-  - `passAsFile`\
+  - [`passAsFile`]{#adv-attr-passAsFile}\
     A list of names of attributes that should be passed via files rather
     than environment variables. For example, if you have
 
@@ -234,7 +234,7 @@ Derivations can declare some infrequently used optional attributes.
     builder, since most operating systems impose a limit on the size
     of the environment (typically, a few hundred kilobyte).
 
-  - `preferLocalBuild`\
+  - [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
     If this attribute is set to `true` and [distributed building is
     enabled](../advanced-topics/distributed-builds.md), then, if
     possible, the derivation will be built locally instead of forwarded
@@ -242,7 +242,7 @@ Derivations can declare some infrequently used optional attributes.
     where the cost of doing a download or remote build would exceed
     the cost of building locally.
 
-  - `allowSubstitutes`\
+  - [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
     If this attribute is set to `false`, then Nix will always build this
     derivation; it will not try to substitute its outputs. This is
     useful for very trivial derivations (such as `writeText` in Nixpkgs)
diff --git a/doc/manual/src/expressions/builtin-constants.md b/doc/manual/src/expressions/builtin-constants.md
index 1404289e5..78d066a82 100644
--- a/doc/manual/src/expressions/builtin-constants.md
+++ b/doc/manual/src/expressions/builtin-constants.md
@@ -14,7 +14,7 @@ Here are the constants built into the Nix expression evaluator:
     This allows a Nix expression to fall back gracefully on older Nix
     installations that don’t have the desired built-in function.
 
-  - `builtins.currentSystem`\
+  - [`builtins.currentSystem`]{#builtins-currentSystem}\
     The built-in value `currentSystem` evaluates to the Nix platform
     identifier for the Nix installation on which the expression is being
     evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 71ff13275..3448b971b 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -1,48 +1,48 @@
 # Glossary
 
-  - derivation\
+  - [derivation]{#gloss-derivation}\
     A description of a build action. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
     using the [`derivation` primitive](expressions/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
-  - store\
+  - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
     `/nix/store`.
 
-  - store path\
+  - [store path]{#gloss-store-path}\
     The location in the file system of a store object, i.e., an
     immediate child of the Nix store directory.
 
-  - store object\
+  - [store object]{#gloss-store-object}\
     A file that is an immediate child of the Nix store directory. These
     can be regular files, but also entire directory trees. Store objects
     can be sources (objects copied from outside of the store),
     derivation outputs (objects produced by running a build action), or
     derivations (files describing a build action).
 
-  - substitute\
+  - [substitute]{#gloss-substitute}\
     A substitute is a command invocation stored in the Nix database that
     describes how to build a store object, bypassing the normal build
     mechanism (i.e., derivations). Typically, the substitute builds the
     store object by downloading a pre-built version of the store object
     from some server.
 
-  - purity\
+  - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
     the same output. This cannot be guaranteed in general (e.g., a
     builder can rely on external inputs such as the network or the
     system time) but the Nix model assumes it.
 
-  - Nix expression\
+  - [Nix expression]{#gloss-nix-expression}\
     A high-level description of software packages and compositions
     thereof. Deploying software using Nix entails writing Nix
     expressions for your packages. Nix expressions are translated to
     derivations that are stored in the Nix store. These derivations can
     then be built.
 
-  - reference\
+  - [reference]{#gloss-reference}\
     A store path `P` is said to have a reference to a store path `Q` if
     the store object at `P` contains the path `Q` somewhere. The
     *references* of a store path are the set of store paths to which it
@@ -52,11 +52,11 @@
     output paths), whereas an output path only references other output
     paths.
 
-  - reachable\
+  - [reachable]{#gloss-reachable}\
     A store path `Q` is reachable from another store path `P` if `Q`
     is in the *closure* of the *references* relation.
 
-  - closure\
+  - [closure]{#gloss-closure}\
     The closure of a store path is the set of store paths that are
     directly or indirectly “reachable” from that store path; that is,
     it’s the closure of the path under the *references* relation. For
@@ -71,34 +71,34 @@
     to path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
     references `R` then `R` is also in the closure of `P`.
 
-  - output path\
+  - [output path]{#gloss-output-path}\
     A store path produced by a derivation.
 
-  - deriver\
+  - [deriver]{#gloss-deriver}\
     The deriver of an *output path* is the store
     derivation that built it.
 
-  - validity\
+  - [validity]{#gloss-validity}\
     A store path is considered *valid* if it exists in the file system,
     is listed in the Nix database as being valid, and if all paths in
     its closure are also valid.
 
-  - user environment\
+  - [user environment]{#gloss-user-env}\
     An automatically generated store object that consists of a set of
     symlinks to “active” applications, i.e., other store paths. These
     are generated automatically by
     [`nix-env`](command-ref/nix-env.md). See *profiles*.
 
-  - profile\
+  - [profile]{#gloss-profile}\
     A symlink to the current *user environment* of a user, e.g.,
     `/nix/var/nix/profiles/default`.
 
-  - NAR\
+  - [NAR]{#gloss-nar}\
     A *N*ix *AR*chive. This is a serialisation of a path in the Nix
     store. It can contain regular files, directories and symbolic
     links.  NARs are generated and unpacked using `nix-store --dump`
     and `nix-store --restore`.
-  - `∅` \
+  - [`∅`]{#gloss-emtpy-set}\
     The empty set symbol. In the context of profile history, this denotes a package is not present in a particular version of the profile.
-  - `ε` \
+  - [`ε`]{#gloss-epsilon}\
     The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute.
-- 
cgit v1.2.3


From a793863b97efde14189b031326e48ac0f448fafc Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Wed, 25 May 2022 13:53:07 +0200
Subject: doc: Manually insert some anchors

---
 doc/manual/src/advanced-topics/diff-hook.md      | 2 +-
 doc/manual/src/command-ref/nix-store.md          | 2 +-
 doc/manual/src/expressions/derivations.md        | 2 +-
 doc/manual/src/installation/installing-binary.md | 3 ++-
 4 files changed, 5 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/advanced-topics/diff-hook.md b/doc/manual/src/advanced-topics/diff-hook.md
index 7a2622b3d..161e64b2a 100644
--- a/doc/manual/src/advanced-topics/diff-hook.md
+++ b/doc/manual/src/advanced-topics/diff-hook.md
@@ -101,7 +101,7 @@ In particular, notice the
 `/nix/store/krpqk0l9ib0ibi1d2w52z293zw455cap-unstable.check` output. Nix
 has copied the build results to that directory where you can examine it.
 
-> **Note**
+> []{#check-dirs-are-unregistered} **Note**
 > 
 > Check paths are not protected against garbage collection, and this
 > path will be deleted on the next garbage collection.
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index 7db9f0c1c..dc8faba68 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -22,7 +22,7 @@ This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
 have an effect.
 
-  - `--add-root` *path*\
+  - [`--add-root`]{#opt-add-root} *path*\
     Causes the result of a realisation (`--realise` and
     `--force-realise`) to be registered as a root of the garbage
     collector. *path* will be created as a symlink to the resulting
diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md
index d26a33b7f..3391ec0d8 100644
--- a/doc/manual/src/expressions/derivations.md
+++ b/doc/manual/src/expressions/derivations.md
@@ -4,7 +4,7 @@ The most important built-in function is `derivation`, which is used to
 describe a single derivation (a build action). It takes as input a set,
 the attributes of which specify the inputs of the build.
 
-  - There must be an attribute named `system` whose value must be a
+  - There must be an attribute named [`system`]{#attr-system} whose value must be a
     string specifying a Nix system type, such as `"i686-linux"` or
     `"x86_64-darwin"`. (To figure out your system type, run `nix -vv
     --version`.) The build can only be performed on a machine and
diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index e5fb50088..9fb9c80c3 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -186,7 +186,8 @@ and `/etc/zshrc` which you may remove.
 > read-only root will prevent you from manually deleting the empty `/nix`
 > mountpoint.
 
-# macOS Installation <a name="sect-macos-installation-change-store-prefix"></a><a name="sect-macos-installation-encrypted-volume"></a><a name="sect-macos-installation-symlink"></a><a name="sect-macos-installation-recommended-notes"></a>
+# macOS Installation
+[]{#sect-macos-installation-change-store-prefix}[]{#sect-macos-installation-encrypted-volume}[]{#sect-macos-installation-symlink}[]{#sect-macos-installation-recommended-notes}
 <!-- Note: anchors above to catch permalinks to old explanations -->
 
 We believe we have ironed out how to cleanly support the read-only root
-- 
cgit v1.2.3


From 8e8e9d8705a68e1be63d6d8059c6c07127826525 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 30 May 2022 11:32:37 +0200
Subject: Respect the outputSpecified attribute

E.g. 'nix build nixpkgs#libxml2.dev' will build the 'dev' output.
---
 doc/manual/src/release-notes/rl-next.md | 3 ---
 1 file changed, 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 878916dc9..7151751dd 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -22,9 +22,6 @@
   `meta.outputsToInstall` attribute if it exists, or all outputs
   otherwise.
 
-  Selecting derivation outputs using the attribute selection syntax
-  (e.g. `nixpkgs#glibc.dev`) no longer works.
-
 * Running nix with the new `--debugger` flag will cause it to start a repl session if
   there is an exception thrown during eval, or if `builtins.break` is called.  From
   there one can inspect symbol values and evaluate nix expressions.  In debug mode
-- 
cgit v1.2.3


From de13b445730e94a24690fed6480f86a5f9c102c8 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 30 May 2022 20:39:38 +0200
Subject: Branch 2.9 release notes

---
 doc/manual/src/SUMMARY.md.in            |  1 +
 doc/manual/src/release-notes/rl-2.9.md  | 47 +++++++++++++++++++++++++++++++++
 doc/manual/src/release-notes/rl-next.md | 38 --------------------------
 3 files changed, 48 insertions(+), 38 deletions(-)
 create mode 100644 doc/manual/src/release-notes/rl-2.9.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 860222337..825a8b4c0 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -72,6 +72,7 @@
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.9 (2022-05-30)](release-notes/rl-2.9.md)
   - [Release 2.8 (2022-04-19)](release-notes/rl-2.8.md)
   - [Release 2.7 (2022-03-07)](release-notes/rl-2.7.md)
   - [Release 2.6 (2022-01-24)](release-notes/rl-2.6.md)
diff --git a/doc/manual/src/release-notes/rl-2.9.md b/doc/manual/src/release-notes/rl-2.9.md
new file mode 100644
index 000000000..ab4b9e42f
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.9.md
@@ -0,0 +1,47 @@
+# Release 2.9 (2022-05-30)
+
+* Running Nix with the new `--debugger` flag will cause it to start a
+  repl session if if an exception is thrown during evaluation, or if
+  `builtins.break` is called.  From there you can inspect the values
+  of variables and evaluate Nix expressions.  In debug mode, the
+  following new repl commands are available:
+
+  ```
+  :env          Show env stack
+  :bt           Show trace stack
+  :st           Show current trace
+  :st <idx>     Change to another trace in the stack
+  :c            Go until end of program, exception, or builtins.break().
+  :s            Go one step
+  ```
+
+  Read more about the debugger
+  [here](https://www.zknotes.com/note/5970).
+
+* Nix now provides better integration with zsh's `run-help`
+  feature. It is now included in the Nix installation in the form of
+  an autoloadable shell function, `run-help-nix`. It picks up Nix
+  subcommands from the currently typed in command and directs the user
+  to the associated man pages.
+
+* `nix repl` has a new build-and-link (`:bl`) command that builds a
+  derivation while creating GC root symlinks.
+
+* The path produced by `builtins.toFile` is now allowed to be imported
+  or read even with restricted evaluation. Note that this will not
+  work with a read-only store.
+
+* `nix build` has a new `--print-out-paths` flag to print the
+  resulting output paths.  This matches the default behaviour of
+  `nix-build`.
+
+* You can now specify which outputs of a derivation `nix` should
+  operate on using the syntax `installable^outputs`,
+  e.g. `nixpkgs#glibc^dev,static` or `nixpkgs#glibc^*`. By default,
+  `nix` will use the outputs specified by the derivation's
+  `meta.outputsToInstall` attribute if it exists, or all outputs
+  otherwise.
+
+* `builtins.fetchTree` (and flake inputs) can now be used to fetch
+  plain files over the `http(s)` and `file` protocols in addition to
+  directory tarballs.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7151751dd..c869b5e2f 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,39 +1 @@
 # Release X.Y (202?-??-??)
-
-* Nix now provides better integration with zsh's run-help feature. It is now
-  included in the Nix installation in the form of an autoloadable shell
-  function, run-help-nix. It picks up Nix subcommands from the currently typed
-  in command and directs the user to the associated man pages.
-
-* `nix repl` has a new build-'n-link (`:bl`) command that builds a derivation
-  while creating GC root symlinks.
-
-* The path produced by `builtins.toFile` is now allowed to be imported or read
-  even with restricted evaluation. Note that this will not work with a
-  read-only store.
-
-* `nix build` has a new `--print-out-paths` flag to print the resulting output paths.
-  This matches the default behaviour of `nix-build`.
-
-* You can now specify which outputs of a derivation `nix` should
-  operate on using the syntax `installable^outputs`,
-  e.g. `nixpkgs#glibc^dev,static` or `nixpkgs#glibc^*`. By default,
-  `nix` will use the outputs specified by the derivation's
-  `meta.outputsToInstall` attribute if it exists, or all outputs
-  otherwise.
-
-* Running nix with the new `--debugger` flag will cause it to start a repl session if
-  there is an exception thrown during eval, or if `builtins.break` is called.  From
-  there one can inspect symbol values and evaluate nix expressions.  In debug mode
-  the following new repl commands are available:
-  ```
-  :env          Show env stack
-  :bt           Show trace stack
-  :st           Show current trace
-  :st <idx>     Change to another trace in the stack
-  :c            Go until end of program, exception, or builtins.break().
-  :s            Go one step
-  ```
-
-* `builtins.fetchTree` (and flake inputs) can now be used to fetch plain files
-  over the `http(s)` and `file` protocols in addition to directory tarballs.
-- 
cgit v1.2.3


From 04a699b8a9cebd83ece0011ec3a99e38a2adc3a8 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Tue, 31 May 2022 10:37:51 +0200
Subject: Typo

---
 doc/manual/src/release-notes/rl-2.9.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-2.9.md b/doc/manual/src/release-notes/rl-2.9.md
index ab4b9e42f..98cc4235d 100644
--- a/doc/manual/src/release-notes/rl-2.9.md
+++ b/doc/manual/src/release-notes/rl-2.9.md
@@ -1,7 +1,7 @@
 # Release 2.9 (2022-05-30)
 
 * Running Nix with the new `--debugger` flag will cause it to start a
-  repl session if if an exception is thrown during evaluation, or if
+  repl session if an exception is thrown during evaluation, or if
   `builtins.break` is called.  From there you can inspect the values
   of variables and evaluate Nix expressions.  In debug mode, the
   following new repl commands are available:
-- 
cgit v1.2.3


From 34d90fbe224e7b626366f98ea1bc9e370d9cb534 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?=
 <theophane.hufschmitt@tweag.io>
Date: Wed, 8 Jun 2022 15:25:52 +0200
Subject: Mention the parallel copy in the release notes

---
 doc/manual/src/release-notes/rl-next.md | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 52e3b6240..6c2c4689c 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -2,3 +2,7 @@
 
 * Nix can now be built with LTO by passing `--enable-lto` to `configure`.
   LTO is currently only supported when building with GCC.
+
+* `nix copy` now copies the store paths in parallel as much as possible (again).
+  This doesn't apply for the `daemon` and `ssh-ng` stores which copy everything
+  in one batch to avoid latencies issues.
-- 
cgit v1.2.3


From edfcc8256ee232736e335d6cc315f98f6f40d1f3 Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Sat, 11 Jun 2022 13:30:51 -0500
Subject: doc: add install test info to hacking.md

---
 doc/manual/src/contributing/hacking.md | 64 +++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 59ce5cac7..9a371afa7 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -83,7 +83,7 @@ by:
 $ nix develop
 ```
 
-## Testing
+## Testing Nix
 
 Nix comes with three different flavors of tests: unit, functional and integration.
 
@@ -108,3 +108,65 @@ These tests include everything that needs to interact with external services or
 Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on <https://hydra.nixos.org/jobset/nix/master>).
 
 You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}`
+
+## Testing the install scripts
+
+Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports).
+
+If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped "installer" and "installer_test" jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs.
+- The `installer` job will generate installers for these platforms: x86_64-linux, armv6l-linux, armv7l-linux, x86_64-darwin. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
+- the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`.
+
+### One-time setup
+1. Have a GitHub account with a fork of the Nix repo.
+2. At cachix.org:
+    - Create or log in to an account.
+    - Create a Cachix cache using the format `<github-username>-nix-install-tests`.
+    - Navigate to the new cache > Settings > Auth Tokens.
+    - Generate a new cachix auth token and copy the generated value.
+4. At github.com:
+    - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret.
+    - Name the secret `CACHIX_AUTH_TOKEN`
+    - Paste the copied value of the Cachix cache auth token.
+
+### Using the CI-generated installer for manual testing
+
+After the CI run completes, you can check the output to extract the installer url:
+1. Click into the detailed view of the CI run.
+2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them).
+3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`)
+4. Copy the install_url
+5. To generate an install command, plug this install_url and your github username into this template:
+
+    ```console
+    sh <(curl -L <install_url>) --tarball-url-prefix https://<github-username>-nix-install-tests.cachix.org/serve
+    ```
+
+<!-- ### Manually generating test installers
+
+There's obviously a manual way to do this, and it's still the only way for
+platforms that lack GA runners.
+
+I did do this back in Fall 2020 (before the GA approach encouraged here). I'll
+sketch what I recall in case it encourages someone to fill in detail, but: I
+didn't know what I was doing at the time and had to fumble/ask around a lot--
+so I don't want to uphold any of it as "right". It may have been dumb or
+the _hard_ way from the getgo. Fundamentals may have changed since.
+
+Here's the build command I used to do this on and for x86_64-darwin:
+nix build --out-link /tmp/foo ".#checks.x86_64-darwin.binaryTarball"
+
+I used the stable out-link to make it easier to script the next steps:
+link=$(readlink /tmp/foo)
+cp $link/*-darwin.tar.xz ~/somewheres
+
+I've lost the last steps and am just going from memory:
+
+From here, I think I had to extract and modify the `install` script to point
+it at this tarball (which I scped to my own site, but it might make more sense
+to just share them locally). I extracted this script once and then just
+search/replaced in it for each new build.
+
+The installer now supports a `--tarball-url-prefix` flag which _may_ have
+solved this need?
+-->
-- 
cgit v1.2.3


From fd7f795750ad97466c0fb9733ac3cc2a0909b84d Mon Sep 17 00:00:00 2001
From: Hugo Osvaldo Barrera <hugo@barrera.io>
Date: Fri, 3 Jun 2022 23:19:12 +0200
Subject: Add disambiguation to man page

This should help future lost newcomers like myself understand where to
find the docs for both of these commands and how they differ.
---
 doc/manual/src/command-ref/nix-build.md | 6 ++++++
 doc/manual/src/command-ref/nix-shell.md | 6 ++++++
 2 files changed, 12 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index aacb32a25..49c6f3f55 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -12,6 +12,12 @@
   [`--dry-run`]
   [{`--out-link` | `-o`} *outlink*]
 
+# Disambiguation
+
+This man page describes the command `nix-build`, which is distinct from `nix
+build`. For documentation on the latter, run `nix build --help` or see `man
+nix3-build`.
+
 # Description
 
 The `nix-build` command builds the derivations described by the Nix
diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index a2b6d8a8e..840bccd25 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -15,6 +15,12 @@
   [`--keep` *name*]
   {{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]}
 
+# Disambiguation
+
+This man page describes the command `nix-shell`, which is distinct from `nix
+shell`. For documentation on the latter, run `nix shell --help` or see `man
+nix3-shell`.
+
 # Description
 
 The command `nix-shell` will build the dependencies of the specified
-- 
cgit v1.2.3


From dae4a8a6c8d8dfde3292d3e9e05977bc13648bda Mon Sep 17 00:00:00 2001
From: tomberek <tomberek@users.noreply.github.com>
Date: Wed, 15 Jun 2022 09:02:36 -0400
Subject: Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
---
 doc/manual/src/release-notes/rl-next.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 5749f3924..9684a70d4 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -7,3 +7,5 @@
   with other commands that use `--file` and `--expr`. Primary breaking change
   is for the common usage of `nix repl '<nixpkgs>'` which can be recovered with
   `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`
+  
+  This is currently guarded by the 'repl-flake' experimental feature
-- 
cgit v1.2.3


From fe76b9f4b461c6a25f49a80a2476b7d60537c455 Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Thu, 16 Jun 2022 09:37:52 -0500
Subject: doc: fix some darwin uninstall gaps

---
 doc/manual/src/installation/installing-binary.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 9fb9c80c3..762402948 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -148,7 +148,8 @@ and `/etc/zshrc` which you may remove.
    This will remove all the build users that no longer serve a purpose.
 
 4. Edit fstab using `sudo vifs` to remove the line mounting the Nix Store
-   volume on `/nix`, which looks like this,
+   volume on `/nix`, which looks like
+   `UUID=<unique uuid> /nix apfs rw,noauto,nobrowse,suid,owners` or
    `LABEL=Nix\040Store /nix apfs rw,nobrowse`. This will prevent automatic
    mounting of the Nix Store volume.
 
@@ -175,6 +176,16 @@ and `/etc/zshrc` which you may remove.
    This will remove the Nix Store volume and everything that was added to the
    store.
 
+   If this command indicates that it couldn't remove the volume, your Nix Store
+   volume may not be mounted. Run the following to double-check:
+
+   ```console
+   diskutil list
+   ```
+
+   If you see a Nix Store volume, re-run the diskutil deleteVolume command, but
+   replace `/nix` with the volume's `diskXsY` identifier.
+
 > **Note**
 > 
 > After you complete the steps here, you will still have an empty `/nix`
-- 
cgit v1.2.3


From 649c9d9b4c0b2327b11c44cda7b5738efa245c08 Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Thu, 16 Jun 2022 09:47:15 -0500
Subject: doc: acknowledge post-rsync reality

Before #5150 the copy-to-store phase of the install was idempotent,
but the recursive cp isn't. This is probably baiting a few people
into trying corrective installs that will fail.
---
 doc/manual/src/installation/installing-binary.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 762402948..a2f284d5a 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -176,15 +176,17 @@ and `/etc/zshrc` which you may remove.
    This will remove the Nix Store volume and everything that was added to the
    store.
 
-   If this command indicates that it couldn't remove the volume, your Nix Store
-   volume may not be mounted. Run the following to double-check:
+   If this command indicates that it couldn't remove the volume, you should
+   make sure you don't have an _unmounted_ Nix Store volume. Look for a
+   "Nix Store" volume in the output of the following command:
 
    ```console
    diskutil list
    ```
 
-   If you see a Nix Store volume, re-run the diskutil deleteVolume command, but
-   replace `/nix` with the volume's `diskXsY` identifier.
+   If you _do_ see a "Nix Store" volume, delete it by re-running the diskutil
+   deleteVolume command, but replace `/nix` with the store volume's `diskXsY`
+   identifier.
 
 > **Note**
 > 
@@ -202,8 +204,7 @@ and `/etc/zshrc` which you may remove.
 <!-- Note: anchors above to catch permalinks to old explanations -->
 
 We believe we have ironed out how to cleanly support the read-only root
-on modern macOS. New installs will do this automatically, and you can
-also re-run a new installer to convert your existing setup.
+on modern macOS. New installs will do this automatically.
 
 This section previously detailed the situation, options, and trade-offs,
 but it now only outlines what the installer does. You don't need to know
-- 
cgit v1.2.3


From 6fa95c35c7f9d88ad7685614d275d06373394c87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?=
 <7226587+thufschmitt@users.noreply.github.com>
Date: Wed, 6 Jul 2022 06:46:54 +0200
Subject: Add a release notes entry for #4914

cc @gytis-ivaskevicius
---
 doc/manual/src/release-notes/rl-next.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 9684a70d4..f6a45184f 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -9,3 +9,6 @@
   `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`
   
   This is currently guarded by the 'repl-flake' experimental feature
+
+* A new primop `builtins.traceVerbose` is available. It is similar to `builtins.trace`
+  if the `trace-verbose` setting is set to true, and it is a no-op otherwise.
-- 
cgit v1.2.3


From eac211a171fa6253b5ae6fdcf56fc5d0aced0201 Mon Sep 17 00:00:00 2001
From: laalsaas <laalsaas@systemli.org>
Date: Sun, 10 Jul 2022 12:09:44 +0200
Subject: Fix logical and typographical errors in nix-env man page

---
 doc/manual/src/command-ref/nix-env.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index 8d6abaf52..a372c5eae 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -31,7 +31,7 @@ subcommand to be performed. These are documented below.
 Several commands, such as `nix-env -q` and `nix-env -i`, take a list of
 arguments that specify the packages on which to operate. These are
 extended regular expressions that must match the entire name of the
-package. (For details on regular expressions, see regex7.) The match is
+package. (For details on regular expressions, see **regex**(7).) The match is
 case-sensitive. The regular expression can optionally be followed by a
 dash and a version number; if omitted, any version of the package will
 match. Here are some examples:
@@ -412,7 +412,7 @@ The upgrade operation determines whether a derivation `y` is an upgrade
 of a derivation `x` by looking at their respective `name` attributes.
 The names (e.g., `gcc-3.3.1` are split into two parts: the package name
 (`gcc`), and the version (`3.3.1`). The version part starts after the
-first dash not followed by a letter. `x` is considered an upgrade of `y`
+first dash not followed by a letter. `y` is considered an upgrade of `x`
 if their package names match, and the version of `y` is higher than that
 of `x`.
 
-- 
cgit v1.2.3


From 517ce38dadc2c8d6282b6865ec0c620b7e26df3a Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 11 Jul 2022 11:17:19 +0200
Subject: Update release notes

---
 doc/manual/src/release-notes/rl-next.md | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index f6a45184f..bbaa68d4f 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,14 +1,31 @@
 # Release X.Y (202?-??-??)
 
-* Nix can now be built with LTO by passing `--enable-lto` to `configure`.
-  LTO is currently only supported when building with GCC.
-
 * `nix repl` now takes installables on the command line, unifying the usage
   with other commands that use `--file` and `--expr`. Primary breaking change
   is for the common usage of `nix repl '<nixpkgs>'` which can be recovered with
-  `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`
-  
-  This is currently guarded by the 'repl-flake' experimental feature
+  `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`.
+
+  This is currently guarded by the `repl-flake` experimental feature.
+
+* A new function `builtins.traceVerbose` is available. It is similar
+  to `builtins.trace` if the `trace-verbose` setting is set to true,
+  and it is a no-op otherwise.
+
+* `nix search` has a new flag `--exclude` to filter out packages.
 
-* A new primop `builtins.traceVerbose` is available. It is similar to `builtins.trace`
-  if the `trace-verbose` setting is set to true, and it is a no-op otherwise.
+* On Linux, if `/nix` doesn't exist and cannot be created and you're
+  not running as root, Nix will automatically use
+  `~/.local/share/nix/root` as a chroot store. This enables non-root
+  users to download the statically linked Nix binary and have it work
+  out of the box, e.g.
+
+  ```
+  # ~/nix run nixpkgs#hello
+  warning: '/nix' does not exists, so Nix will use '/home/ubuntu/.local/share/nix/root' as a chroot store
+  Hello, world!
+  ```
+
+* `flake-registry.json` is now fetched from `channels.nixos.org`.
+
+* Nix can now be built with LTO by passing `--enable-lto` to `configure`.
+  LTO is currently only supported when building with GCC.
-- 
cgit v1.2.3


From 28e913c605d36711546706b7ddbdb8ad711a2486 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 11 Jul 2022 21:10:23 +0200
Subject: Branch 2.10 release notes

---
 doc/manual/src/SUMMARY.md.in            |  1 +
 doc/manual/src/release-notes/rl-2.10.md | 31 +++++++++++++++++++++++++++++++
 doc/manual/src/release-notes/rl-next.md | 29 -----------------------------
 3 files changed, 32 insertions(+), 29 deletions(-)
 create mode 100644 doc/manual/src/release-notes/rl-2.10.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 825a8b4c0..9728728aa 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -72,6 +72,7 @@
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.10 (2022-07-11)](release-notes/rl-2.10.md)
   - [Release 2.9 (2022-05-30)](release-notes/rl-2.9.md)
   - [Release 2.8 (2022-04-19)](release-notes/rl-2.8.md)
   - [Release 2.7 (2022-03-07)](release-notes/rl-2.7.md)
diff --git a/doc/manual/src/release-notes/rl-2.10.md b/doc/manual/src/release-notes/rl-2.10.md
new file mode 100644
index 000000000..b99dbeef0
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.10.md
@@ -0,0 +1,31 @@
+# Release 2.10 (2022-07-11)
+
+* `nix repl` now takes installables on the command line, unifying the usage
+  with other commands that use `--file` and `--expr`. Primary breaking change
+  is for the common usage of `nix repl '<nixpkgs>'` which can be recovered with
+  `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`.
+
+  This is currently guarded by the `repl-flake` experimental feature.
+
+* A new function `builtins.traceVerbose` is available. It is similar
+  to `builtins.trace` if the `trace-verbose` setting is set to true,
+  and it is a no-op otherwise.
+
+* `nix search` has a new flag `--exclude` to filter out packages.
+
+* On Linux, if `/nix` doesn't exist and cannot be created and you're
+  not running as root, Nix will automatically use
+  `~/.local/share/nix/root` as a chroot store. This enables non-root
+  users to download the statically linked Nix binary and have it work
+  out of the box, e.g.
+
+  ```
+  # ~/nix run nixpkgs#hello
+  warning: '/nix' does not exists, so Nix will use '/home/ubuntu/.local/share/nix/root' as a chroot store
+  Hello, world!
+  ```
+
+* `flake-registry.json` is now fetched from `channels.nixos.org`.
+
+* Nix can now be built with LTO by passing `--enable-lto` to `configure`.
+  LTO is currently only supported when building with GCC.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index bbaa68d4f..78ae99f4b 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,31 +1,2 @@
 # Release X.Y (202?-??-??)
 
-* `nix repl` now takes installables on the command line, unifying the usage
-  with other commands that use `--file` and `--expr`. Primary breaking change
-  is for the common usage of `nix repl '<nixpkgs>'` which can be recovered with
-  `nix repl --file '<nixpkgs>'` or `nix repl --expr 'import <nixpkgs>{}'`.
-
-  This is currently guarded by the `repl-flake` experimental feature.
-
-* A new function `builtins.traceVerbose` is available. It is similar
-  to `builtins.trace` if the `trace-verbose` setting is set to true,
-  and it is a no-op otherwise.
-
-* `nix search` has a new flag `--exclude` to filter out packages.
-
-* On Linux, if `/nix` doesn't exist and cannot be created and you're
-  not running as root, Nix will automatically use
-  `~/.local/share/nix/root` as a chroot store. This enables non-root
-  users to download the statically linked Nix binary and have it work
-  out of the box, e.g.
-
-  ```
-  # ~/nix run nixpkgs#hello
-  warning: '/nix' does not exists, so Nix will use '/home/ubuntu/.local/share/nix/root' as a chroot store
-  Hello, world!
-  ```
-
-* `flake-registry.json` is now fetched from `channels.nixos.org`.
-
-* Nix can now be built with LTO by passing `--enable-lto` to `configure`.
-  LTO is currently only supported when building with GCC.
-- 
cgit v1.2.3


From 279ecf7cdee94b3b5e37e4ade3af3a6d20ca9cde Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Fri, 15 Jul 2022 13:29:15 +0000
Subject: Remove `computed-derivations` experimental feature

We don't need it yet.
---
 doc/manual/src/release-notes/rl-next.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 3bb12c013..7047e2421 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,4 +1,3 @@
 # Release X.Y (202?-??-??)
 
-* Add experimental *indexed store derivations* installable syntax, part of the
-  the `computed-derivations` experimental feature.
+* Add *indexed store derivations* installable syntax.
-- 
cgit v1.2.3


From 12461e246b02371c6b6981b4e65985e9397474e1 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Fri, 15 Jul 2022 13:59:32 +0000
Subject: Leverage existing docs for new store-path^outputs syntax

---
 doc/manual/src/release-notes/rl-next.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7047e2421..36b759a10 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,3 +1,3 @@
 # Release X.Y (202?-??-??)
 
-* Add *indexed store derivations* installable syntax.
+* Allow explicitly selecting outputs with *store derivations* installable syntax too.
-- 
cgit v1.2.3


From be4654c344f0745d4c2eefb33a878bd1f23f6b40 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 15:55:41 +0200
Subject: manual: fix section title in table of contents

---
 doc/manual/src/SUMMARY.md.in | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 9728728aa..5df4e2d75 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -33,7 +33,7 @@
     - [Arguments and Variables](expressions/arguments-variables.md)
     - [Building and Testing](expressions/simple-building-testing.md)
     - [Generic Builder Syntax](expressions/generic-builder.md)
-  - [Writing Nix Expressions](expressions/expression-language.md)
+  - [Nix Expression Language](expressions/expression-language.md)
     - [Values](expressions/language-values.md)
     - [Language Constructs](expressions/language-constructs.md)
     - [Operators](expressions/language-operators.md)
-- 
cgit v1.2.3


From 85cdaebcd69c4f6abd15b77888f0093be9c5ada4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 16:10:22 +0200
Subject: manual: set -> attribute set

reword description to have shorter sentences.
---
 doc/manual/src/expressions/language-values.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index 75ae9f2eb..abbe1fd35 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -172,25 +172,27 @@ function and the fifth being a set.
 
 Note that lists are only lazy in values, and they are strict in length.
 
-## Sets
+## Attribute Sets
 
-Sets are really the core of the language, since ultimately the Nix
-language is all about creating derivations, which are really just sets
-of attributes to be passed to build scripts.
+Attribute sets are collections of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
 
-Sets are just a list of name/value pairs (called *attributes*) enclosed
-in curly brackets, where each value is an arbitrary expression
-terminated by a semicolon. For example:
+Names and values are separated by an equal sign (`=`).
+Each value is an arbitrary expression terminated by a semicolon (`;`).
+
+Attributes can appear in any order.
+An attribute name may only occur once.
+
+Example:
 
 ```nix
-{ x = 123;
+{
+  x = 123;
   text = "Hello";
   y = f { bla = 456; };
 }
 ```
 
-This defines a set with attributes named `x`, `text`, `y`. The order of
-the attributes is irrelevant. An attribute name may only occur once.
+This defines a set with attributes named `x`, `text`, `y`.
 
 Attributes can be selected from a set using the `.` operator. For
 instance,
-- 
cgit v1.2.3


From 3063e5b94c1cc1f64cea6af792513c1a04e12155 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 17:09:53 +0200
Subject: manual: use subheadings for primitive types

this gives us HTML anchors for each of them
---
 doc/manual/src/expressions/language-values.md | 298 +++++++++++++-------------
 1 file changed, 154 insertions(+), 144 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index abbe1fd35..fa5743222 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -4,151 +4,161 @@
 
 Nix has the following basic data types:
 
-  - *Strings* can be written in three ways.
-    
-    The most common way is to enclose the string between double quotes,
-    e.g., `"foo bar"`. Strings can span multiple lines. The special
-    characters `"` and `\` and the character sequence `${` must be
-    escaped by prefixing them with a backslash (`\`). Newlines, carriage
-    returns and tabs can be written as `\n`, `\r` and `\t`,
-    respectively.
-    
-    You can include the result of an expression into a string by
-    enclosing it in `${...}`, a feature known as *antiquotation*. The
-    enclosed expression must evaluate to something that can be coerced
-    into a string (meaning that it must be a string, a path, or a
-    derivation). For instance, rather than writing
-    
-    ```nix
-    "--with-freetype2-library=" + freetype + "/lib"
-    ```
-    
-    (where `freetype` is a derivation), you can instead write the more
-    natural
-    
-    ```nix
-    "--with-freetype2-library=${freetype}/lib"
-    ```
-    
-    The latter is automatically translated to the former. A more
-    complicated example (from the Nix expression for
-    [Qt](http://www.trolltech.com/products/qt)):
-    
-    ```nix
-    configureFlags = "
-      -system-zlib -system-libpng -system-libjpeg
-      ${if openglSupport then "-dlopen-opengl
-        -L${mesa}/lib -I${mesa}/include
-        -L${libXmu}/lib -I${libXmu}/include" else ""}
-      ${if threadSupport then "-thread" else "-no-thread"}
-    ";
-    ```
-    
-    Note that Nix expressions and strings can be arbitrarily nested; in
-    this case the outer string contains various antiquotations that
-    themselves contain strings (e.g., `"-thread"`), some of which in
-    turn contain expressions (e.g., `${mesa}`).
-    
-    The second way to write string literals is as an *indented string*,
-    which is enclosed between pairs of *double single-quotes*, like so:
-    
-    ```nix
-    ''
-      This is the first line.
-      This is the second line.
-        This is the third line.
+### Strings
+
+*Strings* can be written in three ways.
+
+The most common way is to enclose the string between double quotes,
+e.g., `"foo bar"`. Strings can span multiple lines. The special
+characters `"` and `\` and the character sequence `${` must be
+escaped by prefixing them with a backslash (`\`). Newlines, carriage
+returns and tabs can be written as `\n`, `\r` and `\t`,
+respectively.
+
+You can include the result of an expression into a string by
+enclosing it in `${...}`, a feature known as *antiquotation*. The
+enclosed expression must evaluate to something that can be coerced
+into a string (meaning that it must be a string, a path, or a
+derivation). For instance, rather than writing
+
+```nix
+"--with-freetype2-library=" + freetype + "/lib"
+```
+
+(where `freetype` is a derivation), you can instead write the more
+natural
+
+```nix
+"--with-freetype2-library=${freetype}/lib"
+```
+
+The latter is automatically translated to the former. A more
+complicated example (from the Nix expression for
+[Qt](http://www.trolltech.com/products/qt)):
+
+```nix
+configureFlags = "
+  -system-zlib -system-libpng -system-libjpeg
+  ${if openglSupport then "-dlopen-opengl
+    -L${mesa}/lib -I${mesa}/include
+    -L${libXmu}/lib -I${libXmu}/include" else ""}
+  ${if threadSupport then "-thread" else "-no-thread"}
+";
+```
+
+Note that Nix expressions and strings can be arbitrarily nested; in
+this case the outer string contains various antiquotations that
+themselves contain strings (e.g., `"-thread"`), some of which in
+turn contain expressions (e.g., `${mesa}`).
+
+The second way to write string literals is as an *indented string*,
+which is enclosed between pairs of *double single-quotes*, like so:
+
+```nix
+''
+  This is the first line.
+  This is the second line.
+    This is the third line.
+''
+```
+
+This kind of string literal intelligently strips indentation from
+the start of each line. To be precise, it strips from each line a
+number of spaces equal to the minimal indentation of the string as a
+whole (disregarding the indentation of empty lines). For instance,
+the first and second line are indented two spaces, while the third
+line is indented four spaces. Thus, two spaces are stripped from
+each line, so the resulting string is
+
+```nix
+"This is the first line.\nThis is the second line.\n  This is the third line.\n"
+```
+
+Note that the whitespace and newline following the opening `''` is
+ignored if there is no non-whitespace text on the initial line.
+
+Antiquotation (`${expr}`) is supported in indented strings.
+
+Since `${` and `''` have special meaning in indented strings, you
+need a way to quote them. `$` can be escaped by prefixing it with
+`''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
+by prefixing it with `'`, i.e., `'''`. `$` removes any special
+meaning from the following `$`. Linefeed, carriage-return and tab
+characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
+escapes any other character.
+
+Indented strings are primarily useful in that they allow multi-line
+string literals to follow the indentation of the enclosing Nix
+expression, and that less escaping is typically necessary for
+strings representing languages such as shell scripts and
+configuration files because `''` is much less common than `"`.
+Example:
+
+```nix
+stdenv.mkDerivation {
+  ...
+  postInstall =
     ''
-    ```
-    
-    This kind of string literal intelligently strips indentation from
-    the start of each line. To be precise, it strips from each line a
-    number of spaces equal to the minimal indentation of the string as a
-    whole (disregarding the indentation of empty lines). For instance,
-    the first and second line are indented two spaces, while the third
-    line is indented four spaces. Thus, two spaces are stripped from
-    each line, so the resulting string is
-    
-    ```nix
-    "This is the first line.\nThis is the second line.\n  This is the third line.\n"
-    ```
-    
-    Note that the whitespace and newline following the opening `''` is
-    ignored if there is no non-whitespace text on the initial line.
-    
-    Antiquotation (`${expr}`) is supported in indented strings.
-    
-    Since `${` and `''` have special meaning in indented strings, you
-    need a way to quote them. `$` can be escaped by prefixing it with
-    `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
-    by prefixing it with `'`, i.e., `'''`. `$` removes any special
-    meaning from the following `$`. Linefeed, carriage-return and tab
-    characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
-    escapes any other character.
-    
-    Indented strings are primarily useful in that they allow multi-line
-    string literals to follow the indentation of the enclosing Nix
-    expression, and that less escaping is typically necessary for
-    strings representing languages such as shell scripts and
-    configuration files because `''` is much less common than `"`.
-    Example:
-    
-    ```nix
-    stdenv.mkDerivation {
-      ...
-      postInstall =
-        ''
-          mkdir $out/bin $out/etc
-          cp foo $out/bin
-          echo "Hello World" > $out/etc/foo.conf
-          ${if enableBar then "cp bar $out/bin" else ""}
-        '';
-      ...
-    }
-    ```
-    
-    Finally, as a convenience, *URIs* as defined in appendix B of
-    [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
-    is*, without quotes. For instance, the string
-    `"http://example.org/foo.tar.bz2"` can also be written as
-    `http://example.org/foo.tar.bz2`.
-
-  - Numbers, which can be *integers* (like `123`) or *floating point*
-    (like `123.43` or `.27e13`).
-    
-    Numbers are type-compatible: pure integer operations will always
-    return integers, whereas any operation involving at least one
-    floating point number will have a floating point number as a result.
-
-  - *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
-    least one slash to be recognised as such. For instance, `builder.sh`
-    is not a path: it's parsed as an expression that selects the
-    attribute `sh` from the variable `builder`. If the file name is
-    relative, i.e., if it does not begin with a slash, it is made
-    absolute at parse time relative to the directory of the Nix
-    expression that contained it. For instance, if a Nix expression in
-    `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
-    is `/foo/xyzzy/fnord.nix`.
-    
-    If the first component of a path is a `~`, it is interpreted as if
-    the rest of the path were relative to the user's home directory.
-    e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
-    whose home directory is `/home/edolstra`.
-    
-    Paths can also be specified between angle brackets, e.g.
-    `<nixpkgs>`. This means that the directories listed in the
-    environment variable `NIX_PATH` will be searched for the given file
-    or directory name.
-
-    Antiquotation is supported in any paths except those in angle brackets.
-    `./${foo}-${bar}.nix` is a more convenient way of writing 
-    `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
-    least one slash must appear *before* any antiquotations for this to be
-    recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
-    operation. `./a.${foo}/b.${bar}` is a path.
-
-  - *Booleans* with values `true` and `false`.
-
-  - The null value, denoted as `null`.
+      mkdir $out/bin $out/etc
+      cp foo $out/bin
+      echo "Hello World" > $out/etc/foo.conf
+      ${if enableBar then "cp bar $out/bin" else ""}
+    '';
+  ...
+}
+```
+
+Finally, as a convenience, *URIs* as defined in appendix B of
+[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
+is*, without quotes. For instance, the string
+`"http://example.org/foo.tar.bz2"` can also be written as
+`http://example.org/foo.tar.bz2`.
+
+### Numbers
+
+Numbers, which can be *integers* (like `123`) or *floating point*
+(like `123.43` or `.27e13`).
+
+Numbers are type-compatible: pure integer operations will always
+return integers, whereas any operation involving at least one
+floating point number will have a floating point number as a result.
+
+### Paths
+
+*Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
+least one slash to be recognised as such. For instance, `builder.sh`
+is not a path: it's parsed as an expression that selects the
+attribute `sh` from the variable `builder`. If the file name is
+relative, i.e., if it does not begin with a slash, it is made
+absolute at parse time relative to the directory of the Nix
+expression that contained it. For instance, if a Nix expression in
+`/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
+is `/foo/xyzzy/fnord.nix`.
+
+If the first component of a path is a `~`, it is interpreted as if
+the rest of the path were relative to the user's home directory.
+e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
+whose home directory is `/home/edolstra`.
+
+Paths can also be specified between angle brackets, e.g.
+`<nixpkgs>`. This means that the directories listed in the
+environment variable `NIX_PATH` will be searched for the given file
+or directory name.
+
+Antiquotation is supported in any paths except those in angle brackets.
+`./${foo}-${bar}.nix` is a more convenient way of writing
+`./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
+least one slash must appear *before* any antiquotations for this to be
+recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
+operation. `./a.${foo}/b.${bar}` is a path.
+
+### Booleans
+
+*Booleans* with values `true` and `false`.
+
+### Null
+
+The null value, denoted as `null`.
 
 ## Lists
 
-- 
cgit v1.2.3


From 4ff48854b85f5af6b7448957beae448939c56884 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 17:11:23 +0200
Subject: manual: simple values -> primitives

"simple" is a loaded term
---
 doc/manual/src/expressions/language-values.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index fa5743222..19d2f7c0d 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -1,8 +1,6 @@
 # Values
 
-## Simple Values
-
-Nix has the following basic data types:
+## Primitives
 
 ### Strings
 
-- 
cgit v1.2.3


From 8f4fab8fab9c321aea62b2953cbe16083781f099 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 17:25:18 +0200
Subject: manual: use singular for headings

---
 doc/manual/src/expressions/language-values.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index 19d2f7c0d..6b1047c71 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -2,7 +2,7 @@
 
 ## Primitives
 
-### Strings
+### String
 
 *Strings* can be written in three ways.
 
@@ -112,7 +112,7 @@ is*, without quotes. For instance, the string
 `"http://example.org/foo.tar.bz2"` can also be written as
 `http://example.org/foo.tar.bz2`.
 
-### Numbers
+### Number
 
 Numbers, which can be *integers* (like `123`) or *floating point*
 (like `123.43` or `.27e13`).
@@ -121,7 +121,7 @@ Numbers are type-compatible: pure integer operations will always
 return integers, whereas any operation involving at least one
 floating point number will have a floating point number as a result.
 
-### Paths
+### Path
 
 *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
 least one slash to be recognised as such. For instance, `builder.sh`
@@ -150,7 +150,7 @@ least one slash must appear *before* any antiquotations for this to be
 recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
 operation. `./a.${foo}/b.${bar}` is a path.
 
-### Booleans
+### Boolean
 
 *Booleans* with values `true` and `false`.
 
@@ -158,7 +158,7 @@ operation. `./a.${foo}/b.${bar}` is a path.
 
 The null value, denoted as `null`.
 
-## Lists
+## List
 
 Lists are formed by enclosing a whitespace-separated list of values
 between square brackets. For example,
@@ -180,7 +180,7 @@ function and the fifth being a set.
 
 Note that lists are only lazy in values, and they are strict in length.
 
-## Attribute Sets
+## Attribute Set
 
 Attribute sets are collections of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
 
-- 
cgit v1.2.3


From 41a3b315fd24b83d7e570e1dae8d384317fb89e6 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 17:25:25 +0200
Subject: manual: values -> data types

---
 doc/manual/src/SUMMARY.md.in                  | 2 +-
 doc/manual/src/expressions/language-values.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 5df4e2d75..c8cb72fc0 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -34,7 +34,7 @@
     - [Building and Testing](expressions/simple-building-testing.md)
     - [Generic Builder Syntax](expressions/generic-builder.md)
   - [Nix Expression Language](expressions/expression-language.md)
-    - [Values](expressions/language-values.md)
+    - [Data Types](expressions/language-values.md)
     - [Language Constructs](expressions/language-constructs.md)
     - [Operators](expressions/language-operators.md)
     - [Derivations](expressions/derivations.md)
diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index 6b1047c71..e4e3bf181 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -1,4 +1,4 @@
-# Values
+# Data Types
 
 ## Primitives
 
-- 
cgit v1.2.3


From 27138f1ec69c7a6f09ab467de317909780e4ae7a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Jul 2022 23:30:07 +0200
Subject: manual: use singular in body, too

Co-authored-by: Cole Helbling <cole.e.helbling@outlook.com>
---
 doc/manual/src/expressions/language-values.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index e4e3bf181..4aa354ba6 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -182,7 +182,7 @@ Note that lists are only lazy in values, and they are strict in length.
 
 ## Attribute Set
 
-Attribute sets are collections of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
+An attribute set is a collection of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
 
 Names and values are separated by an equal sign (`=`).
 Each value is an arbitrary expression terminated by a semicolon (`;`).
-- 
cgit v1.2.3


From f675ba53310f1bfbe6e9867184b3a5177532b370 Mon Sep 17 00:00:00 2001
From: K900 <me@0upti.me>
Date: Mon, 1 Aug 2022 13:50:35 +0300
Subject: doc/distributed-builds: don't use deprecated alias

`nix ping-store` -> `nix store ping`.
---
 doc/manual/src/advanced-topics/distributed-builds.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md
index b0d7fbf1a..fefd10100 100644
--- a/doc/manual/src/advanced-topics/distributed-builds.md
+++ b/doc/manual/src/advanced-topics/distributed-builds.md
@@ -12,14 +12,14 @@ machine is accessible via SSH and that it has Nix installed. You can
 test whether connecting to the remote Nix instance works, e.g.
 
 ```console
-$ nix ping-store --store ssh://mac
+$ nix store ping --store ssh://mac
 ```
 
 will try to connect to the machine named `mac`. It is possible to
 specify an SSH identity file as part of the remote store URI, e.g.
 
 ```console
-$ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key
+$ nix store ping --store ssh://mac?ssh-key=/home/alice/my-key
 ```
 
 Since builds should be non-interactive, the key should not have a
-- 
cgit v1.2.3


From ceed4d41426f6e2dc74473d5c137a8f061c49061 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 3 Aug 2022 11:23:40 +0200
Subject: encode primitive as list with anchors

to make it consistent with builtins and configuration options
---
 doc/manual/src/expressions/language-values.md | 310 +++++++++++++-------------
 1 file changed, 155 insertions(+), 155 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index 4aa354ba6..a53b2cb22 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -2,161 +2,161 @@
 
 ## Primitives
 
-### String
-
-*Strings* can be written in three ways.
-
-The most common way is to enclose the string between double quotes,
-e.g., `"foo bar"`. Strings can span multiple lines. The special
-characters `"` and `\` and the character sequence `${` must be
-escaped by prefixing them with a backslash (`\`). Newlines, carriage
-returns and tabs can be written as `\n`, `\r` and `\t`,
-respectively.
-
-You can include the result of an expression into a string by
-enclosing it in `${...}`, a feature known as *antiquotation*. The
-enclosed expression must evaluate to something that can be coerced
-into a string (meaning that it must be a string, a path, or a
-derivation). For instance, rather than writing
-
-```nix
-"--with-freetype2-library=" + freetype + "/lib"
-```
-
-(where `freetype` is a derivation), you can instead write the more
-natural
-
-```nix
-"--with-freetype2-library=${freetype}/lib"
-```
-
-The latter is automatically translated to the former. A more
-complicated example (from the Nix expression for
-[Qt](http://www.trolltech.com/products/qt)):
-
-```nix
-configureFlags = "
-  -system-zlib -system-libpng -system-libjpeg
-  ${if openglSupport then "-dlopen-opengl
-    -L${mesa}/lib -I${mesa}/include
-    -L${libXmu}/lib -I${libXmu}/include" else ""}
-  ${if threadSupport then "-thread" else "-no-thread"}
-";
-```
-
-Note that Nix expressions and strings can be arbitrarily nested; in
-this case the outer string contains various antiquotations that
-themselves contain strings (e.g., `"-thread"`), some of which in
-turn contain expressions (e.g., `${mesa}`).
-
-The second way to write string literals is as an *indented string*,
-which is enclosed between pairs of *double single-quotes*, like so:
-
-```nix
-''
-  This is the first line.
-  This is the second line.
-    This is the third line.
-''
-```
-
-This kind of string literal intelligently strips indentation from
-the start of each line. To be precise, it strips from each line a
-number of spaces equal to the minimal indentation of the string as a
-whole (disregarding the indentation of empty lines). For instance,
-the first and second line are indented two spaces, while the third
-line is indented four spaces. Thus, two spaces are stripped from
-each line, so the resulting string is
-
-```nix
-"This is the first line.\nThis is the second line.\n  This is the third line.\n"
-```
-
-Note that the whitespace and newline following the opening `''` is
-ignored if there is no non-whitespace text on the initial line.
-
-Antiquotation (`${expr}`) is supported in indented strings.
-
-Since `${` and `''` have special meaning in indented strings, you
-need a way to quote them. `$` can be escaped by prefixing it with
-`''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
-by prefixing it with `'`, i.e., `'''`. `$` removes any special
-meaning from the following `$`. Linefeed, carriage-return and tab
-characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
-escapes any other character.
-
-Indented strings are primarily useful in that they allow multi-line
-string literals to follow the indentation of the enclosing Nix
-expression, and that less escaping is typically necessary for
-strings representing languages such as shell scripts and
-configuration files because `''` is much less common than `"`.
-Example:
-
-```nix
-stdenv.mkDerivation {
-  ...
-  postInstall =
-    ''
-      mkdir $out/bin $out/etc
-      cp foo $out/bin
-      echo "Hello World" > $out/etc/foo.conf
-      ${if enableBar then "cp bar $out/bin" else ""}
-    '';
-  ...
-}
-```
-
-Finally, as a convenience, *URIs* as defined in appendix B of
-[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
-is*, without quotes. For instance, the string
-`"http://example.org/foo.tar.bz2"` can also be written as
-`http://example.org/foo.tar.bz2`.
-
-### Number
-
-Numbers, which can be *integers* (like `123`) or *floating point*
-(like `123.43` or `.27e13`).
-
-Numbers are type-compatible: pure integer operations will always
-return integers, whereas any operation involving at least one
-floating point number will have a floating point number as a result.
-
-### Path
-
-*Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
-least one slash to be recognised as such. For instance, `builder.sh`
-is not a path: it's parsed as an expression that selects the
-attribute `sh` from the variable `builder`. If the file name is
-relative, i.e., if it does not begin with a slash, it is made
-absolute at parse time relative to the directory of the Nix
-expression that contained it. For instance, if a Nix expression in
-`/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
-is `/foo/xyzzy/fnord.nix`.
-
-If the first component of a path is a `~`, it is interpreted as if
-the rest of the path were relative to the user's home directory.
-e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
-whose home directory is `/home/edolstra`.
-
-Paths can also be specified between angle brackets, e.g.
-`<nixpkgs>`. This means that the directories listed in the
-environment variable `NIX_PATH` will be searched for the given file
-or directory name.
-
-Antiquotation is supported in any paths except those in angle brackets.
-`./${foo}-${bar}.nix` is a more convenient way of writing
-`./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
-least one slash must appear *before* any antiquotations for this to be
-recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
-operation. `./a.${foo}/b.${bar}` is a path.
-
-### Boolean
-
-*Booleans* with values `true` and `false`.
-
-### Null
-
-The null value, denoted as `null`.
+- <a id="#type-string" href="#type-string">String</a>
+
+  *Strings* can be written in three ways.
+
+  The most common way is to enclose the string between double quotes,
+  e.g., `"foo bar"`. Strings can span multiple lines. The special
+  characters `"` and `\` and the character sequence `${` must be
+  escaped by prefixing them with a backslash (`\`). Newlines, carriage
+  returns and tabs can be written as `\n`, `\r` and `\t`,
+  respectively.
+
+  You can include the result of an expression into a string by
+  enclosing it in `${...}`, a feature known as *antiquotation*. The
+  enclosed expression must evaluate to something that can be coerced
+  into a string (meaning that it must be a string, a path, or a
+  derivation). For instance, rather than writing
+
+  ```nix
+  "--with-freetype2-library=" + freetype + "/lib"
+  ```
+
+  (where `freetype` is a derivation), you can instead write the more
+  natural
+
+  ```nix
+  "--with-freetype2-library=${freetype}/lib"
+  ```
+
+  The latter is automatically translated to the former. A more
+  complicated example (from the Nix expression for
+  [Qt](http://www.trolltech.com/products/qt)):
+
+  ```nix
+  configureFlags = "
+    -system-zlib -system-libpng -system-libjpeg
+    ${if openglSupport then "-dlopen-opengl
+      -L${mesa}/lib -I${mesa}/include
+      -L${libXmu}/lib -I${libXmu}/include" else ""}
+    ${if threadSupport then "-thread" else "-no-thread"}
+  ";
+  ```
+
+  Note that Nix expressions and strings can be arbitrarily nested; in
+  this case the outer string contains various antiquotations that
+  themselves contain strings (e.g., `"-thread"`), some of which in
+  turn contain expressions (e.g., `${mesa}`).
+
+  The second way to write string literals is as an *indented string*,
+  which is enclosed between pairs of *double single-quotes*, like so:
+
+  ```nix
+  ''
+    This is the first line.
+    This is the second line.
+      This is the third line.
+  ''
+  ```
+
+  This kind of string literal intelligently strips indentation from
+  the start of each line. To be precise, it strips from each line a
+  number of spaces equal to the minimal indentation of the string as a
+  whole (disregarding the indentation of empty lines). For instance,
+  the first and second line are indented two spaces, while the third
+  line is indented four spaces. Thus, two spaces are stripped from
+  each line, so the resulting string is
+
+  ```nix
+  "This is the first line.\nThis is the second line.\n  This is the third line.\n"
+  ```
+
+  Note that the whitespace and newline following the opening `''` is
+  ignored if there is no non-whitespace text on the initial line.
+
+  Antiquotation (`${expr}`) is supported in indented strings.
+
+  Since `${` and `''` have special meaning in indented strings, you
+  need a way to quote them. `$` can be escaped by prefixing it with
+  `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
+  by prefixing it with `'`, i.e., `'''`. `$` removes any special
+  meaning from the following `$`. Linefeed, carriage-return and tab
+  characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
+  escapes any other character.
+
+  Indented strings are primarily useful in that they allow multi-line
+  string literals to follow the indentation of the enclosing Nix
+  expression, and that less escaping is typically necessary for
+  strings representing languages such as shell scripts and
+  configuration files because `''` is much less common than `"`.
+  Example:
+
+  ```nix
+  stdenv.mkDerivation {
+    ...
+    postInstall =
+      ''
+        mkdir $out/bin $out/etc
+        cp foo $out/bin
+        echo "Hello World" > $out/etc/foo.conf
+        ${if enableBar then "cp bar $out/bin" else ""}
+      '';
+    ...
+  }
+  ```
+
+  Finally, as a convenience, *URIs* as defined in appendix B of
+  [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
+  is*, without quotes. For instance, the string
+  `"http://example.org/foo.tar.bz2"` can also be written as
+  `http://example.org/foo.tar.bz2`.
+
+- <a id="#type-number" href="#type-number">Number</a>
+
+  Numbers, which can be *integers* (like `123`) or *floating point*
+  (like `123.43` or `.27e13`).
+
+  Numbers are type-compatible: pure integer operations will always
+  return integers, whereas any operation involving at least one
+  floating point number will have a floating point number as a result.
+
+- <a id="#type-path" href="#type-path">Path</a>
+
+  *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
+  least one slash to be recognised as such. For instance, `builder.sh`
+  is not a path: it's parsed as an expression that selects the
+  attribute `sh` from the variable `builder`. If the file name is
+  relative, i.e., if it does not begin with a slash, it is made
+  absolute at parse time relative to the directory of the Nix
+  expression that contained it. For instance, if a Nix expression in
+  `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
+  is `/foo/xyzzy/fnord.nix`.
+
+  If the first component of a path is a `~`, it is interpreted as if
+  the rest of the path were relative to the user's home directory.
+  e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
+  whose home directory is `/home/edolstra`.
+
+  Paths can also be specified between angle brackets, e.g.
+  `<nixpkgs>`. This means that the directories listed in the
+  environment variable `NIX_PATH` will be searched for the given file
+  or directory name.
+
+  Antiquotation is supported in any paths except those in angle brackets.
+  `./${foo}-${bar}.nix` is a more convenient way of writing
+  `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
+  least one slash must appear *before* any antiquotations for this to be
+  recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
+  operation. `./a.${foo}/b.${bar}` is a path.
+
+- <a id="#type-boolean" href="#type-boolean">Boolean</a>
+
+  *Booleans* with values `true` and `false`.
+
+- <a id="#type-null" href="#type-null">Null</a>
+
+  The null value, denoted as `null`.
 
 ## List
 
-- 
cgit v1.2.3


From c55bea420402fcf995688ef6a12cfa413bc5e35f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?=
 <theophane.hufschmitt@tweag.io>
Date: Wed, 3 Aug 2022 14:16:00 +0200
Subject: Fix the html id of the list headers

---
 doc/manual/src/expressions/language-values.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
index a53b2cb22..f09400d02 100644
--- a/doc/manual/src/expressions/language-values.md
+++ b/doc/manual/src/expressions/language-values.md
@@ -2,7 +2,7 @@
 
 ## Primitives
 
-- <a id="#type-string" href="#type-string">String</a>
+- <a id="type-string" href="#type-string">String</a>
 
   *Strings* can be written in three ways.
 
@@ -112,7 +112,7 @@
   `"http://example.org/foo.tar.bz2"` can also be written as
   `http://example.org/foo.tar.bz2`.
 
-- <a id="#type-number" href="#type-number">Number</a>
+- <a id="type-number" href="#type-number">Number</a>
 
   Numbers, which can be *integers* (like `123`) or *floating point*
   (like `123.43` or `.27e13`).
@@ -121,7 +121,7 @@
   return integers, whereas any operation involving at least one
   floating point number will have a floating point number as a result.
 
-- <a id="#type-path" href="#type-path">Path</a>
+- <a id="type-path" href="#type-path">Path</a>
 
   *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
   least one slash to be recognised as such. For instance, `builder.sh`
@@ -150,11 +150,11 @@
   recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
   operation. `./a.${foo}/b.${bar}` is a path.
 
-- <a id="#type-boolean" href="#type-boolean">Boolean</a>
+- <a id="type-boolean" href="#type-boolean">Boolean</a>
 
   *Booleans* with values `true` and `false`.
 
-- <a id="#type-null" href="#type-null">Null</a>
+- <a id="type-null" href="#type-null">Null</a>
 
   The null value, denoted as `null`.
 
-- 
cgit v1.2.3


From 499ed265088948e823c83cc95d1097a6362d205b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 4 Aug 2022 11:36:32 +0200
Subject: manual: remove "Writing Nix Expressions" chapter

it is out of date, all over the place in level of detail, is really
about `nixpkgs`, and in general instructions should not be part of
a reference manual.

also:
- update redirects and internal links
- use "Nix language" consistently
---
 doc/manual/src/SUMMARY.md.in                       |  23 +-
 doc/manual/src/command-ref/nix-env.md              |   2 +-
 doc/manual/src/command-ref/nix-instantiate.md      |   4 +-
 doc/manual/src/command-ref/nix-store.md            |   2 +-
 doc/manual/src/command-ref/opt-common.md           |   4 +-
 doc/manual/src/expressions/advanced-attributes.md  | 257 ---------------
 doc/manual/src/expressions/arguments-variables.md  |  80 -----
 doc/manual/src/expressions/build-script.md         |  70 ----
 doc/manual/src/expressions/builtin-constants.md    |  20 --
 doc/manual/src/expressions/builtins-prefix.md      |  16 -
 doc/manual/src/expressions/builtins-suffix.md      |   1 -
 doc/manual/src/expressions/derivations.md          | 161 ----------
 doc/manual/src/expressions/expression-language.md  |  12 -
 doc/manual/src/expressions/expression-syntax.md    |  93 ------
 doc/manual/src/expressions/generic-builder.md      |  66 ----
 doc/manual/src/expressions/language-constructs.md  | 354 ---------------------
 doc/manual/src/expressions/language-operators.md   |  28 --
 doc/manual/src/expressions/language-values.md      | 261 ---------------
 .../src/expressions/simple-building-testing.md     |  61 ----
 doc/manual/src/expressions/simple-expression.md    |  23 --
 .../src/expressions/writing-nix-expressions.md     |  12 -
 doc/manual/src/glossary.md                         |   2 +-
 doc/manual/src/language/advanced-attributes.md     | 257 +++++++++++++++
 doc/manual/src/language/builtin-constants.md       |  20 ++
 doc/manual/src/language/builtins-prefix.md         |  16 +
 doc/manual/src/language/builtins-suffix.md         |   1 +
 doc/manual/src/language/constructs.md              | 354 +++++++++++++++++++++
 doc/manual/src/language/derivations.md             | 161 ++++++++++
 doc/manual/src/language/index.md                   |  13 +
 doc/manual/src/language/operators.md               |  28 ++
 doc/manual/src/language/values.md                  | 261 +++++++++++++++
 .../src/package-management/package-management.md   |   3 +-
 32 files changed, 1127 insertions(+), 1539 deletions(-)
 delete mode 100644 doc/manual/src/expressions/advanced-attributes.md
 delete mode 100644 doc/manual/src/expressions/arguments-variables.md
 delete mode 100644 doc/manual/src/expressions/build-script.md
 delete mode 100644 doc/manual/src/expressions/builtin-constants.md
 delete mode 100644 doc/manual/src/expressions/builtins-prefix.md
 delete mode 100644 doc/manual/src/expressions/builtins-suffix.md
 delete mode 100644 doc/manual/src/expressions/derivations.md
 delete mode 100644 doc/manual/src/expressions/expression-language.md
 delete mode 100644 doc/manual/src/expressions/expression-syntax.md
 delete mode 100644 doc/manual/src/expressions/generic-builder.md
 delete mode 100644 doc/manual/src/expressions/language-constructs.md
 delete mode 100644 doc/manual/src/expressions/language-operators.md
 delete mode 100644 doc/manual/src/expressions/language-values.md
 delete mode 100644 doc/manual/src/expressions/simple-building-testing.md
 delete mode 100644 doc/manual/src/expressions/simple-expression.md
 delete mode 100644 doc/manual/src/expressions/writing-nix-expressions.md
 create mode 100644 doc/manual/src/language/advanced-attributes.md
 create mode 100644 doc/manual/src/language/builtin-constants.md
 create mode 100644 doc/manual/src/language/builtins-prefix.md
 create mode 100644 doc/manual/src/language/builtins-suffix.md
 create mode 100644 doc/manual/src/language/constructs.md
 create mode 100644 doc/manual/src/language/derivations.md
 create mode 100644 doc/manual/src/language/index.md
 create mode 100644 doc/manual/src/language/operators.md
 create mode 100644 doc/manual/src/language/values.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index c8cb72fc0..084c8f442 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -26,21 +26,14 @@
     - [Copying Closures via SSH](package-management/copy-closure.md)
     - [Serving a Nix store via SSH](package-management/ssh-substituter.md)
     - [Serving a Nix store via S3](package-management/s3-substituter.md)
-- [Writing Nix Expressions](expressions/writing-nix-expressions.md)
-  - [A Simple Nix Expression](expressions/simple-expression.md)
-    - [Expression Syntax](expressions/expression-syntax.md)
-    - [Build Script](expressions/build-script.md)
-    - [Arguments and Variables](expressions/arguments-variables.md)
-    - [Building and Testing](expressions/simple-building-testing.md)
-    - [Generic Builder Syntax](expressions/generic-builder.md)
-  - [Nix Expression Language](expressions/expression-language.md)
-    - [Data Types](expressions/language-values.md)
-    - [Language Constructs](expressions/language-constructs.md)
-    - [Operators](expressions/language-operators.md)
-    - [Derivations](expressions/derivations.md)
-      - [Advanced Attributes](expressions/advanced-attributes.md)
-    - [Built-in Constants](expressions/builtin-constants.md)
-    - [Built-in Functions](expressions/builtins.md)
+- [Nix Language](language/index.md)
+  - [Data Types](language/values.md)
+  - [Language Constructs](language/constructs.md)
+  - [Operators](language/operators.md)
+  - [Derivations](language/derivations.md)
+    - [Advanced Attributes](language/advanced-attributes.md)
+  - [Built-in Constants](language/builtin-constants.md)
+  - [Built-in Functions](language/builtins.md)
 - [Advanced Topics](advanced-topics/advanced-topics.md)
   - [Remote Builds](advanced-topics/distributed-builds.md)
   - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index a372c5eae..a5df35d77 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -198,7 +198,7 @@ a number of possible ways:
     another.
 
   - If `--from-expression` is given, *args* are Nix
-    [functions](../expressions/language-constructs.md#functions)
+    [functions](../language/constructs.md#functions)
     that are called with the active Nix expression as their single
     argument. The derivations returned by those function calls are
     installed. This allows derivations to be specified in an
diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md
index 2e198daed..8f143729e 100644
--- a/doc/manual/src/command-ref/nix-instantiate.md
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -51,7 +51,7 @@ standard input.
   - `--strict`\
     When used with `--eval`, recursively evaluate list elements and
     attributes. Normally, such sub-expressions are left unevaluated
-    (since the Nix expression language is lazy).
+    (since the Nix language is lazy).
 
     > **Warning**
     >
@@ -66,7 +66,7 @@ standard input.
     When used with `--eval`, print the resulting value as an XML
     representation of the abstract syntax tree rather than as an ATerm.
     The schema is the same as that used by the [`toXML`
-    built-in](../expressions/builtins.md).
+    built-in](../language/builtins.md).
 
   - `--read-write-mode`\
     When used with `--eval`, perform evaluation in read/write mode so
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index dc8faba68..ecd838e8d 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -121,7 +121,7 @@ Special exit codes:
   - `102`\
     Hash mismatch, the build output was rejected because it does not
     match the [`outputHash` attribute of the
-    derivation](../expressions/advanced-attributes.md).
+    derivation](../language/advanced-attributes.md).
 
   - `104`\
     Not deterministic, the build succeeded in check mode but the
diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md
index 51d7de18a..e612c416f 100644
--- a/doc/manual/src/command-ref/opt-common.md
+++ b/doc/manual/src/command-ref/opt-common.md
@@ -145,7 +145,7 @@ Most Nix commands accept the following command-line options:
     expression evaluator will automatically try to call functions that
     it encounters. It can automatically call functions for which every
     argument has a [default
-    value](../expressions/language-constructs.md#functions) (e.g.,
+    value](../language/constructs.md#functions) (e.g.,
     `{ argName ?  defaultValue }: ...`). With `--arg`, you can also
     call functions that have arguments without a default value (or
     override a default value). That is, if the evaluator encounters a
@@ -164,7 +164,7 @@ Most Nix commands accept the following command-line options:
 
     So if you call this Nix expression (e.g., when you do `nix-env -iA
     pkgname`), the function will be called automatically using the
-    value [`builtins.currentSystem`](../expressions/builtins.md) for
+    value [`builtins.currentSystem`](../language/builtins.md) for
     the `system` argument. You can override this using `--arg`, e.g.,
     `nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that
     since the argument is a Nix string literal, you have to escape the
diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md
deleted file mode 100644
index 2e7e80ed0..000000000
--- a/doc/manual/src/expressions/advanced-attributes.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# Advanced Attributes
-
-Derivations can declare some infrequently used optional attributes.
-
-  - [`allowedReferences`]{#adv-attr-allowedReferences}\
-    The optional attribute `allowedReferences` specifies a list of legal
-    references (dependencies) of the output of the builder. For example,
-
-    ```nix
-    allowedReferences = [];
-    ```
-
-    enforces that the output of a derivation cannot have any runtime
-    dependencies on its inputs. To allow an output to have a runtime
-    dependency on itself, use `"out"` as a list item. This is used in
-    NixOS to check that generated files such as initial ramdisks for
-    booting Linux don’t have accidental dependencies on other paths in
-    the Nix store.
-
-  - [`allowedRequisites`]{#adv-attr-allowedRequisites}\
-    This attribute is similar to `allowedReferences`, but it specifies
-    the legal requisites of the whole closure, so all the dependencies
-    recursively. For example,
-
-    ```nix
-    allowedRequisites = [ foobar ];
-    ```
-
-    enforces that the output of a derivation cannot have any other
-    runtime dependency than `foobar`, and in addition it enforces that
-    `foobar` itself doesn't introduce any other dependency itself.
-
-  - [`disallowedReferences`]{#adv-attr-disallowedReferences}\
-    The optional attribute `disallowedReferences` specifies a list of
-    illegal references (dependencies) of the output of the builder. For
-    example,
-
-    ```nix
-    disallowedReferences = [ foo ];
-    ```
-
-    enforces that the output of a derivation cannot have a direct
-    runtime dependencies on the derivation `foo`.
-
-  - [`disallowedRequisites`]{#adv-attr-disallowedRequisites}\
-    This attribute is similar to `disallowedReferences`, but it
-    specifies illegal requisites for the whole closure, so all the
-    dependencies recursively. For example,
-
-    ```nix
-    disallowedRequisites = [ foobar ];
-    ```
-
-    enforces that the output of a derivation cannot have any runtime
-    dependency on `foobar` or any other derivation depending recursively
-    on `foobar`.
-
-  - [`exportReferencesGraph`]{#adv-attr-exportReferencesGraph}\
-    This attribute allows builders access to the references graph of
-    their inputs. The attribute is a list of inputs in the Nix store
-    whose references graph the builder needs to know. The value of
-    this attribute should be a list of pairs `[ name1 path1 name2
-    path2 ...  ]`. The references graph of each *pathN* will be stored
-    in a text file *nameN* in the temporary build directory. The text
-    files have the format used by `nix-store --register-validity`
-    (with the deriver fields left empty). For example, when the
-    following derivation is built:
-
-    ```nix
-    derivation {
-      ...
-      exportReferencesGraph = [ "libfoo-graph" libfoo ];
-    };
-    ```
-
-    the references graph of `libfoo` is placed in the file
-    `libfoo-graph` in the temporary build directory.
-
-    `exportReferencesGraph` is useful for builders that want to do
-    something with the closure of a store path. Examples include the
-    builders in NixOS that generate the initial ramdisk for booting
-    Linux (a `cpio` archive containing the closure of the boot script)
-    and the ISO-9660 image for the installation CD (which is populated
-    with a Nix store containing the closure of a bootable NixOS
-    configuration).
-
-  - [`impureEnvVars`]{#adv-attr-impureEnvVars}\
-    This attribute allows you to specify a list of environment variables
-    that should be passed from the environment of the calling user to
-    the builder. Usually, the environment is cleared completely when the
-    builder is executed, but with this attribute you can allow specific
-    environment variables to be passed unmodified. For example,
-    `fetchurl` in Nixpkgs has the line
-
-    ```nix
-    impureEnvVars = [ "http_proxy" "https_proxy" ... ];
-    ```
-
-    to make it use the proxy server configuration specified by the user
-    in the environment variables `http_proxy` and friends.
-
-    This attribute is only allowed in *fixed-output derivations* (see
-    below), where impurities such as these are okay since (the hash
-    of) the output is known in advance. It is ignored for all other
-    derivations.
-
-    > **Warning**
-    >
-    > `impureEnvVars` implementation takes environment variables from
-    > the current builder process. When a daemon is building its
-    > environmental variables are used. Without the daemon, the
-    > environmental variables come from the environment of the
-    > `nix-build`.
-
-  - [`outputHash`]{#adv-attr-outputHash}; [`outputHashAlgo`]{#adv-attr-outputHashAlgo}; [`outputHashMode`]{#adv-attr-outputHashMode}\
-    These attributes declare that the derivation is a so-called
-    *fixed-output derivation*, which means that a cryptographic hash of
-    the output is already known in advance. When the build of a
-    fixed-output derivation finishes, Nix computes the cryptographic
-    hash of the output and compares it to the hash declared with these
-    attributes. If there is a mismatch, the build fails.
-
-    The rationale for fixed-output derivations is derivations such as
-    those produced by the `fetchurl` function. This function downloads a
-    file from a given URL. To ensure that the downloaded file has not
-    been modified, the caller must also specify a cryptographic hash of
-    the file. For example,
-
-    ```nix
-    fetchurl {
-      url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
-      sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
-    }
-    ```
-
-    It sometimes happens that the URL of the file changes, e.g., because
-    servers are reorganised or no longer available. We then must update
-    the call to `fetchurl`, e.g.,
-
-    ```nix
-    fetchurl {
-      url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
-      sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
-    }
-    ```
-
-    If a `fetchurl` derivation was treated like a normal derivation, the
-    output paths of the derivation and *all derivations depending on it*
-    would change. For instance, if we were to change the URL of the
-    Glibc source distribution in Nixpkgs (a package on which almost all
-    other packages depend) massive rebuilds would be needed. This is
-    unfortunate for a change which we know cannot have a real effect as
-    it propagates upwards through the dependency graph.
-
-    For fixed-output derivations, on the other hand, the name of the
-    output path only depends on the `outputHash*` and `name` attributes,
-    while all other attributes are ignored for the purpose of computing
-    the output path. (The `name` attribute is included because it is
-    part of the path.)
-
-    As an example, here is the (simplified) Nix expression for
-    `fetchurl`:
-
-    ```nix
-    { stdenv, curl }: # The curl program is used for downloading.
-
-    { url, sha256 }:
-
-    stdenv.mkDerivation {
-      name = baseNameOf (toString url);
-      builder = ./builder.sh;
-      buildInputs = [ curl ];
-
-      # This is a fixed-output derivation; the output must be a regular
-      # file with SHA256 hash sha256.
-      outputHashMode = "flat";
-      outputHashAlgo = "sha256";
-      outputHash = sha256;
-
-      inherit url;
-    }
-    ```
-
-    The `outputHashAlgo` attribute specifies the hash algorithm used to
-    compute the hash. It can currently be `"sha1"`, `"sha256"` or
-    `"sha512"`.
-
-    The `outputHashMode` attribute determines how the hash is computed.
-    It must be one of the following two values:
-
-      - `"flat"`\
-        The output must be a non-executable regular file. If it isn’t,
-        the build fails. The hash is simply computed over the contents
-        of that file (so it’s equal to what Unix commands like
-        `sha256sum` or `sha1sum` produce).
-
-        This is the default.
-
-      - `"recursive"`\
-        The hash is computed over the NAR archive dump of the output
-        (i.e., the result of [`nix-store
-        --dump`](../command-ref/nix-store.md#operation---dump)). In
-        this case, the output can be anything, including a directory
-        tree.
-
-    The `outputHash` attribute, finally, must be a string containing
-    the hash in either hexadecimal or base-32 notation. (See the
-    [`nix-hash` command](../command-ref/nix-hash.md) for information
-    about converting to and from base-32 notation.)
-    
-  - [`__contentAddressed`]{#adv-attr-__contentAddressed}
-    If this **experimental** attribute is set to true, then the derivation
-    outputs will be stored in a content-addressed location rather than the
-    traditional input-addressed one.
-    This only has an effect if the `ca-derivation` experimental feature is enabled.
-    
-    Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above).
-
-  - [`passAsFile`]{#adv-attr-passAsFile}\
-    A list of names of attributes that should be passed via files rather
-    than environment variables. For example, if you have
-
-    ```nix
-    passAsFile = ["big"];
-    big = "a very long string";
-    ```
-
-    then when the builder runs, the environment variable `bigPath`
-    will contain the absolute path to a temporary file containing `a
-    very long string`. That is, for any attribute *x* listed in
-    `passAsFile`, Nix will pass an environment variable `xPath`
-    holding the path of the file containing the value of attribute
-    *x*. This is useful when you need to pass large strings to a
-    builder, since most operating systems impose a limit on the size
-    of the environment (typically, a few hundred kilobyte).
-
-  - [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
-    If this attribute is set to `true` and [distributed building is
-    enabled](../advanced-topics/distributed-builds.md), then, if
-    possible, the derivation will be built locally instead of forwarded
-    to a remote machine. This is appropriate for trivial builders
-    where the cost of doing a download or remote build would exceed
-    the cost of building locally.
-
-  - [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
-    If this attribute is set to `false`, then Nix will always build this
-    derivation; it will not try to substitute its outputs. This is
-    useful for very trivial derivations (such as `writeText` in Nixpkgs)
-    that are cheaper to build than to substitute from a binary cache.
-
-    > **Note**
-    >
-    > You need to have a builder configured which satisfies the
-    > derivation’s `system` attribute, since the derivation cannot be
-    > substituted. Thus it is usually a good idea to align `system` with
-    > `builtins.currentSystem` when setting `allowSubstitutes` to
-    > `false`. For most trivial derivations this should be the case.
diff --git a/doc/manual/src/expressions/arguments-variables.md b/doc/manual/src/expressions/arguments-variables.md
deleted file mode 100644
index 12198c879..000000000
--- a/doc/manual/src/expressions/arguments-variables.md
+++ /dev/null
@@ -1,80 +0,0 @@
-# Arguments and Variables
-
-The [Nix expression for GNU Hello](expression-syntax.md) is a
-function; it is missing some arguments that have to be filled in
-somewhere. In the Nix Packages collection this is done in the file
-`pkgs/top-level/all-packages.nix`, where all Nix expressions for
-packages are imported and called with the appropriate arguments. Here
-are some fragments of `all-packages.nix`, with annotations of what
-they mean:
-
-```nix
-...
-
-rec { ①
-
-  hello = import ../applications/misc/hello/ex-1 ② { ③
-    inherit fetchurl stdenv perl;
-  };
-
-  perl = import ../development/interpreters/perl { ④
-    inherit fetchurl stdenv;
-  };
-
-  fetchurl = import ../build-support/fetchurl {
-    inherit stdenv; ...
-  };
-
-  stdenv = ...;
-
-}
-```
-
-1.  This file defines a set of attributes, all of which are concrete
-    derivations (i.e., not functions). In fact, we define a *mutually
-    recursive* set of attributes. That is, the attributes can refer to
-    each other. This is precisely what we want since we want to “plug”
-    the various packages into each other.
-
-2.  Here we *import* the Nix expression for GNU Hello. The import
-    operation just loads and returns the specified Nix expression. In
-    fact, we could just have put the contents of the Nix expression
-    for GNU Hello in `all-packages.nix` at this point. That would be
-    completely equivalent, but it would make `all-packages.nix` rather
-    bulky.
-    
-    Note that we refer to `../applications/misc/hello/ex-1`, not
-    `../applications/misc/hello/ex-1/default.nix`. When you try to
-    import a directory, Nix automatically appends `/default.nix` to the
-    file name.
-
-3.  This is where the actual composition takes place. Here we *call* the
-    function imported from `../applications/misc/hello/ex-1` with a set
-    containing the things that the function expects, namely `fetchurl`,
-    `stdenv`, and `perl`. We use inherit again to use the attributes
-    defined in the surrounding scope (we could also have written
-    `fetchurl = fetchurl;`, etc.).
-    
-    The result of this function call is an actual derivation that can be
-    built by Nix (since when we fill in the arguments of the function,
-    what we get is its body, which is the call to `stdenv.mkDerivation`
-    in the [Nix expression for GNU Hello](expression-syntax.md)).
-    
-    > **Note**
-    > 
-    > Nixpkgs has a convenience function `callPackage` that imports and
-    > calls a function, filling in any missing arguments by passing the
-    > corresponding attribute from the Nixpkgs set, like this:
-    > 
-    > ```nix
-    > hello = callPackage ../applications/misc/hello/ex-1 { };
-    > ```
-    > 
-    > If necessary, you can set or override arguments:
-    > 
-    > ```nix
-    > hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
-    > ```
-
-4.  Likewise, we have to instantiate Perl, `fetchurl`, and the standard
-    environment.
diff --git a/doc/manual/src/expressions/build-script.md b/doc/manual/src/expressions/build-script.md
deleted file mode 100644
index b1eacae88..000000000
--- a/doc/manual/src/expressions/build-script.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Build Script
-
-Here is the builder referenced from Hello's Nix expression (stored in
-`pkgs/applications/misc/hello/ex-1/builder.sh`):
-
-```bash
-source $stdenv/setup ①
-
-PATH=$perl/bin:$PATH ②
-
-tar xvfz $src ③
-cd hello-*
-./configure --prefix=$out ④
-make ⑤
-make install
-```
-
-The builder can actually be made a lot shorter by using the *generic
-builder* functions provided by `stdenv`, but here we write out the build
-steps to elucidate what a builder does. It performs the following steps:
-
-1.  When Nix runs a builder, it initially completely clears the
-    environment (except for the attributes declared in the derivation).
-    This is done to prevent undeclared inputs from being used in the
-    build process. If for example the `PATH` contained `/usr/bin`, then
-    you might accidentally use `/usr/bin/gcc`.
-    
-    So the first step is to set up the environment. This is done by
-    calling the `setup` script of the standard environment. The
-    environment variable `stdenv` points to the location of the
-    standard environment being used. (It wasn't specified explicitly
-    as an attribute in Hello's Nix expression, but `mkDerivation` adds
-    it automatically.)
-
-2.  Since Hello needs Perl, we have to make sure that Perl is in the
-    `PATH`. The `perl` environment variable points to the location of
-    the Perl package (since it was passed in as an attribute to the
-    derivation), so `$perl/bin` is the directory containing the Perl
-    interpreter.
-
-3.  Now we have to unpack the sources. The `src` attribute was bound to
-    the result of fetching the Hello source tarball from the network, so
-    the `src` environment variable points to the location in the Nix
-    store to which the tarball was downloaded. After unpacking, we `cd`
-    to the resulting source directory.
-    
-    The whole build is performed in a temporary directory created in
-    `/tmp`, by the way. This directory is removed after the builder
-    finishes, so there is no need to clean up the sources afterwards.
-    Also, the temporary directory is always newly created, so you don't
-    have to worry about files from previous builds interfering with the
-    current build.
-
-4.  GNU Hello is a typical Autoconf-based package, so we first have to
-    run its `configure` script. In Nix every package is stored in a
-    separate location in the Nix store, for instance
-    `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
-    computes this path by cryptographically hashing all attributes of
-    the derivation. The path is passed to the builder through the `out`
-    environment variable. So here we give `configure` the parameter
-    `--prefix=$out` to cause Hello to be installed in the expected
-    location.
-
-5.  Finally we build Hello (`make`) and install it into the location
-    specified by `out` (`make install`).
-
-If you are wondering about the absence of error checking on the result
-of various commands called in the builder: this is because the shell
-script is evaluated with Bash's `-e` option, which causes the script to
-be aborted if any command fails without an error check.
diff --git a/doc/manual/src/expressions/builtin-constants.md b/doc/manual/src/expressions/builtin-constants.md
deleted file mode 100644
index 78d066a82..000000000
--- a/doc/manual/src/expressions/builtin-constants.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Built-in Constants
-
-Here are the constants built into the Nix expression evaluator:
-
-  - `builtins`\
-    The set `builtins` contains all the built-in functions and values.
-    You can use `builtins` to test for the availability of features in
-    the Nix installation, e.g.,
-    
-    ```nix
-    if builtins ? getEnv then builtins.getEnv "PATH" else ""
-    ```
-    
-    This allows a Nix expression to fall back gracefully on older Nix
-    installations that don’t have the desired built-in function.
-
-  - [`builtins.currentSystem`]{#builtins-currentSystem}\
-    The built-in value `currentSystem` evaluates to the Nix platform
-    identifier for the Nix installation on which the expression is being
-    evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
diff --git a/doc/manual/src/expressions/builtins-prefix.md b/doc/manual/src/expressions/builtins-prefix.md
deleted file mode 100644
index c631a8453..000000000
--- a/doc/manual/src/expressions/builtins-prefix.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Built-in Functions
-
-This section lists the functions built into the Nix expression
-evaluator. (The built-in function `derivation` is discussed above.)
-Some built-ins, such as `derivation`, are always in scope of every Nix
-expression; you can just access them right away. But to prevent
-polluting the namespace too much, most built-ins are not in
-scope. Instead, you can access them through the `builtins` built-in
-value, which is a set that contains all built-in functions and values.
-For instance, `derivation` is also available as `builtins.derivation`.
-
-<dl>
-  <dt><code>derivation <var>attrs</var></code>;
-      <code>builtins.derivation <var>attrs</var></code></dt>
-  <dd><p><var>derivation</var> is described in
-         <a href="derivations.md">its own section</a>.</p></dd>
diff --git a/doc/manual/src/expressions/builtins-suffix.md b/doc/manual/src/expressions/builtins-suffix.md
deleted file mode 100644
index a74db2857..000000000
--- a/doc/manual/src/expressions/builtins-suffix.md
+++ /dev/null
@@ -1 +0,0 @@
-</dl>
diff --git a/doc/manual/src/expressions/derivations.md b/doc/manual/src/expressions/derivations.md
deleted file mode 100644
index 3391ec0d8..000000000
--- a/doc/manual/src/expressions/derivations.md
+++ /dev/null
@@ -1,161 +0,0 @@
-# Derivations
-
-The most important built-in function is `derivation`, which is used to
-describe a single derivation (a build action). It takes as input a set,
-the attributes of which specify the inputs of the build.
-
-  - There must be an attribute named [`system`]{#attr-system} whose value must be a
-    string specifying a Nix system type, such as `"i686-linux"` or
-    `"x86_64-darwin"`. (To figure out your system type, run `nix -vv
-    --version`.) The build can only be performed on a machine and
-    operating system matching the system type. (Nix can automatically
-    [forward builds for other
-    platforms](../advanced-topics/distributed-builds.md) by forwarding
-    them to other machines.)
-
-  - There must be an attribute named `name` whose value must be a
-    string. This is used as a symbolic name for the package by
-    `nix-env`, and it is appended to the output paths of the derivation.
-
-  - There must be an attribute named `builder` that identifies the
-    program that is executed to perform the build. It can be either a
-    derivation or a source (a local file reference, e.g.,
-    `./builder.sh`).
-
-  - Every attribute is passed as an environment variable to the builder.
-    Attribute values are translated to environment variables as follows:
-    
-      - Strings and numbers are just passed verbatim.
-    
-      - A *path* (e.g., `../foo/sources.tar`) causes the referenced file
-        to be copied to the store; its location in the store is put in
-        the environment variable. The idea is that all sources should
-        reside in the Nix store, since all inputs to a derivation should
-        reside in the Nix store.
-    
-      - A *derivation* causes that derivation to be built prior to the
-        present derivation; its default output path is put in the
-        environment variable.
-    
-      - Lists of the previous types are also allowed. They are simply
-        concatenated, separated by spaces.
-    
-      - `true` is passed as the string `1`, `false` and `null` are
-        passed as an empty string.
-
-  - The optional attribute `args` specifies command-line arguments to be
-    passed to the builder. It should be a list.
-
-  - The optional attribute `outputs` specifies a list of symbolic
-    outputs of the derivation. By default, a derivation produces a
-    single output path, denoted as `out`. However, derivations can
-    produce multiple output paths. This is useful because it allows
-    outputs to be downloaded or garbage-collected separately. For
-    instance, imagine a library package that provides a dynamic library,
-    header files, and documentation. A program that links against the
-    library doesn’t need the header files and documentation at runtime,
-    and it doesn’t need the documentation at build time. Thus, the
-    library package could specify:
-    
-    ```nix
-    outputs = [ "lib" "headers" "doc" ];
-    ```
-    
-    This will cause Nix to pass environment variables `lib`, `headers`
-    and `doc` to the builder containing the intended store paths of each
-    output. The builder would typically do something like
-    
-    ```bash
-    ./configure \
-      --libdir=$lib/lib \
-      --includedir=$headers/include \
-      --docdir=$doc/share/doc
-    ```
-    
-    for an Autoconf-style package. You can refer to each output of a
-    derivation by selecting it as an attribute, e.g.
-    
-    ```nix
-    buildInputs = [ pkg.lib pkg.headers ];
-    ```
-    
-    The first element of `outputs` determines the *default output*.
-    Thus, you could also write
-    
-    ```nix
-    buildInputs = [ pkg pkg.headers ];
-    ```
-    
-    since `pkg` is equivalent to `pkg.lib`.
-
-The function `mkDerivation` in the Nixpkgs standard environment is a
-wrapper around `derivation` that adds a default value for `system` and
-always uses Bash as the builder, to which the supplied builder is passed
-as a command-line argument. See the Nixpkgs manual for details.
-
-The builder is executed as follows:
-
-  - A temporary directory is created under the directory specified by
-    `TMPDIR` (default `/tmp`) where the build will take place. The
-    current directory is changed to this directory.
-
-  - The environment is cleared and set to the derivation attributes, as
-    specified above.
-
-  - In addition, the following variables are set:
-    
-      - `NIX_BUILD_TOP` contains the path of the temporary directory for
-        this build.
-    
-      - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
-        temporary directory. This is to prevent the builder from
-        accidentally writing temporary files anywhere else. Doing so
-        might cause interference by other processes.
-    
-      - `PATH` is set to `/path-not-set` to prevent shells from
-        initialising it to their built-in default value.
-    
-      - `HOME` is set to `/homeless-shelter` to prevent programs from
-        using `/etc/passwd` or the like to find the user's home
-        directory, which could cause impurity. Usually, when `HOME` is
-        set, it is used as the location of the home directory, even if
-        it points to a non-existent path.
-    
-      - `NIX_STORE` is set to the path of the top-level Nix store
-        directory (typically, `/nix/store`).
-    
-      - For each output declared in `outputs`, the corresponding
-        environment variable is set to point to the intended path in the
-        Nix store for that output. Each output path is a concatenation
-        of the cryptographic hash of all build inputs, the `name`
-        attribute and the output name. (The output name is omitted if
-        it’s `out`.)
-
-  - If an output path already exists, it is removed. Also, locks are
-    acquired to prevent multiple Nix instances from performing the same
-    build at the same time.
-
-  - A log of the combined standard output and error is written to
-    `/nix/var/log/nix`.
-
-  - The builder is executed with the arguments specified by the
-    attribute `args`. If it exits with exit code 0, it is considered to
-    have succeeded.
-
-  - The temporary directory is removed (unless the `-K` option was
-    specified).
-
-  - If the build was successful, Nix scans each output path for
-    references to input paths by looking for the hash parts of the input
-    paths. Since these are potential runtime dependencies, Nix registers
-    them as dependencies of the output paths.
-
-  - After the build, Nix sets the last-modified timestamp on all files
-    in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
-    the default group, and sets the mode of the file to 0444 or 0555
-    (i.e., read-only, with execute permission enabled if the file was
-    originally executable). Note that possible `setuid` and `setgid`
-    bits are cleared. Setuid and setgid programs are not currently
-    supported by Nix. This is because the Nix archives used in
-    deployment have no concept of ownership information, and because it
-    makes the build result dependent on the user performing the build.
diff --git a/doc/manual/src/expressions/expression-language.md b/doc/manual/src/expressions/expression-language.md
deleted file mode 100644
index 267fcb983..000000000
--- a/doc/manual/src/expressions/expression-language.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Nix Expression Language
-
-The Nix expression language is a pure, lazy, functional language. Purity
-means that operations in the language don't have side-effects (for
-instance, there is no variable assignment). Laziness means that
-arguments to functions are evaluated only when they are needed.
-Functional means that functions are “normal” values that can be passed
-around and manipulated in interesting ways. The language is not a
-full-featured, general purpose language. Its main job is to describe
-packages, compositions of packages, and the variability within packages.
-
-This section presents the various features of the language.
diff --git a/doc/manual/src/expressions/expression-syntax.md b/doc/manual/src/expressions/expression-syntax.md
deleted file mode 100644
index 6b93e692c..000000000
--- a/doc/manual/src/expressions/expression-syntax.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Expression Syntax
-
-Here is a Nix expression for GNU Hello:
-
-```nix
-{ stdenv, fetchurl, perl }: ①
-
-stdenv.mkDerivation { ②
-  name = "hello-2.1.1"; ③
-  builder = ./builder.sh; ④
-  src = fetchurl { ⑤
-    url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
-    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
-  };
-  inherit perl; ⑥
-}
-```
-
-This file is actually already in the Nix Packages collection in
-`pkgs/applications/misc/hello/ex-1/default.nix`. It is customary to
-place each package in a separate directory and call the single Nix
-expression in that directory `default.nix`. The file has the following
-elements (referenced from the figure by number):
-
-1.  This states that the expression is a *function* that expects to be
-    called with three arguments: `stdenv`, `fetchurl`, and `perl`. They
-    are needed to build Hello, but we don't know how to build them here;
-    that's why they are function arguments. `stdenv` is a package that
-    is used by almost all Nix Packages; it provides a
-    “standard” environment consisting of the things you would expect
-    in a basic Unix environment: a C/C++ compiler (GCC, to be precise),
-    the Bash shell, fundamental Unix tools such as `cp`, `grep`, `tar`,
-    etc. `fetchurl` is a function that downloads files. `perl` is the
-    Perl interpreter.
-    
-    Nix functions generally have the form `{ x, y, ..., z }: e` where
-    `x`, `y`, etc. are the names of the expected arguments, and where
-    *e* is the body of the function. So here, the entire remainder of
-    the file is the body of the function; when given the required
-    arguments, the body should describe how to build an instance of
-    the Hello package.
-
-2.  So we have to build a package. Building something from other stuff
-    is called a *derivation* in Nix (as opposed to sources, which are
-    built by humans instead of computers). We perform a derivation by
-    calling `stdenv.mkDerivation`. `mkDerivation` is a function
-    provided by `stdenv` that builds a package from a set of
-    *attributes*. A set is just a list of key/value pairs where each
-    key is a string and each value is an arbitrary Nix
-    expression. They take the general form `{ name1 = expr1; ...
-    nameN = exprN; }`.
-
-3.  The attribute `name` specifies the symbolic name and version of
-    the package. Nix doesn't really care about these things, but they
-    are used by for instance `nix-env -q` to show a “human-readable”
-    name for packages. This attribute is required by `mkDerivation`.
-
-4.  The attribute `builder` specifies the builder. This attribute can
-    sometimes be omitted, in which case `mkDerivation` will fill in a
-    default builder (which does a `configure; make; make install`, in
-    essence). Hello is sufficiently simple that the default builder
-    would suffice, but in this case, we will show an actual builder
-    for educational purposes. The value `./builder.sh` refers to the
-    shell script shown in the [next section](build-script.md),
-    discussed below.
-
-5.  The builder has to know what the sources of the package are. Here,
-    the attribute `src` is bound to the result of a call to the
-    `fetchurl` function. Given a URL and a SHA-256 hash of the expected
-    contents of the file at that URL, this function builds a derivation
-    that downloads the file and checks its hash. So the sources are a
-    dependency that like all other dependencies is built before Hello
-    itself is built.
-    
-    Instead of `src` any other name could have been used, and in fact
-    there can be any number of sources (bound to different attributes).
-    However, `src` is customary, and it's also expected by the default
-    builder (which we don't use in this example).
-
-6.  Since the derivation requires Perl, we have to pass the value of the
-    `perl` function argument to the builder. All attributes in the set
-    are actually passed as environment variables to the builder, so
-    declaring an attribute
-
-    ```nix
-    perl = perl;
-    ```
-    
-    will do the trick: it binds an attribute `perl` to the function
-    argument which also happens to be called `perl`. However, it looks a
-    bit silly, so there is a shorter syntax. The `inherit` keyword
-    causes the specified attributes to be bound to whatever variables
-    with the same name happen to be in scope.
diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md
deleted file mode 100644
index cf26b5f82..000000000
--- a/doc/manual/src/expressions/generic-builder.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# Generic Builder Syntax
-
-Recall that the [build script for GNU Hello](build-script.md) looked
-something like this:
-
-```bash
-PATH=$perl/bin:$PATH
-tar xvfz $src
-cd hello-*
-./configure --prefix=$out
-make
-make install
-```
-
-The builders for almost all Unix packages look like this — set up some
-environment variables, unpack the sources, configure, build, and
-install. For this reason the standard environment provides some Bash
-functions that automate the build process. Here is what a builder using
-the generic build facilities looks like:
-
-```bash
-buildInputs="$perl" ①
-
-source $stdenv/setup ②
-
-genericBuild ③
-```
-
-Here is what each line means:
-
-1.  The `buildInputs` variable tells `setup` to use the indicated
-    packages as “inputs”. This means that if a package provides a `bin`
-    subdirectory, it's added to `PATH`; if it has a `include`
-    subdirectory, it's added to GCC's header search path; and so on.
-    (This is implemented in a modular way: `setup` tries to source the
-    file `pkg/nix-support/setup-hook` of all dependencies. These “setup
-    hooks” can then set up whatever environment variables they want; for
-    instance, the setup hook for Perl sets the `PERL5LIB` environment
-    variable to contain the `lib/site_perl` directories of all inputs.)
-
-2.  The function `genericBuild` is defined in the file `$stdenv/setup`.
-
-3.  The final step calls the shell function `genericBuild`, which
-    performs the steps that were done explicitly in the previous build
-    script. The generic builder is smart enough to figure out whether
-    to unpack the sources using `gzip`, `bzip2`, etc.  It can be
-    customised in many ways; see the Nixpkgs manual for details.
-
-Discerning readers will note that the `buildInputs` could just as well
-have been set in the Nix expression, like this:
-
-```nix
-  buildInputs = [ perl ];
-```
-
-The `perl` attribute can then be removed, and the builder becomes even
-shorter:
-
-```bash
-source $stdenv/setup
-genericBuild
-```
-
-In fact, `mkDerivation` provides a default builder that looks exactly
-like that, so it is actually possible to omit the builder for Hello
-entirely.
diff --git a/doc/manual/src/expressions/language-constructs.md b/doc/manual/src/expressions/language-constructs.md
deleted file mode 100644
index 1c01f2cc7..000000000
--- a/doc/manual/src/expressions/language-constructs.md
+++ /dev/null
@@ -1,354 +0,0 @@
-# Language Constructs
-
-## Recursive sets
-
-Recursive sets are just normal sets, but the attributes can refer to
-each other. For example,
-
-```nix
-rec {
-  x = y;
-  y = 123;
-}.x
-```
-
-evaluates to `123`. Note that without `rec` the binding `x = y;` would
-refer to the variable `y` in the surrounding scope, if one exists, and
-would be invalid if no such variable exists. That is, in a normal
-(non-recursive) set, attributes are not added to the lexical scope; in a
-recursive set, they are.
-
-Recursive sets of course introduce the danger of infinite recursion. For
-example, the expression
-
-```nix
-rec {
-  x = y;
-  y = x;
-}.x
-```
-
-will crash with an `infinite recursion encountered` error message.
-
-## Let-expressions
-
-A let-expression allows you to define local variables for an expression.
-For instance,
-
-```nix
-let
-  x = "foo";
-  y = "bar";
-in x + y
-```
-
-evaluates to `"foobar"`.
-
-## Inheriting attributes
-
-When defining a set or in a let-expression it is often convenient to
-copy variables from the surrounding lexical scope (e.g., when you want
-to propagate attributes). This can be shortened using the `inherit`
-keyword. For instance,
-
-```nix
-let x = 123; in
-{ inherit x;
-  y = 456;
-}
-```
-
-is equivalent to
-
-```nix
-let x = 123; in
-{ x = x;
-  y = 456;
-}
-```
-
-and both evaluate to `{ x = 123; y = 456; }`. (Note that this works
-because `x` is added to the lexical scope by the `let` construct.) It is
-also possible to inherit attributes from another set. For instance, in
-this fragment from `all-packages.nix`,
-
-```nix
-graphviz = (import ../tools/graphics/graphviz) {
-  inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
-  inherit (xlibs) libXaw;
-};
-
-xlibs = {
-  libX11 = ...;
-  libXaw = ...;
-  ...
-}
-
-libpng = ...;
-libjpg = ...;
-...
-```
-
-the set used in the function call to the function defined in
-`../tools/graphics/graphviz` inherits a number of variables from the
-surrounding scope (`fetchurl` ... `yacc`), but also inherits `libXaw`
-(the X Athena Widgets) from the `xlibs` (X11 client-side libraries) set.
-
-Summarizing the fragment
-
-```nix
-...
-inherit x y z;
-inherit (src-set) a b c;
-...
-```
-
-is equivalent to
-
-```nix
-...
-x = x; y = y; z = z;
-a = src-set.a; b = src-set.b; c = src-set.c;
-...
-```
-
-when used while defining local variables in a let-expression or while
-defining a set.
-
-## Functions
-
-Functions have the following form:
-
-```nix
-pattern: body
-```
-
-The pattern specifies what the argument of the function must look like,
-and binds variables in the body to (parts of) the argument. There are
-three kinds of patterns:
-
-  - If a pattern is a single identifier, then the function matches any
-    argument. Example:
-    
-    ```nix
-    let negate = x: !x;
-        concat = x: y: x + y;
-    in if negate true then concat "foo" "bar" else ""
-    ```
-    
-    Note that `concat` is a function that takes one argument and returns
-    a function that takes another argument. This allows partial
-    parameterisation (i.e., only filling some of the arguments of a
-    function); e.g.,
-    
-    ```nix
-    map (concat "foo") [ "bar" "bla" "abc" ]
-    ```
-    
-    evaluates to `[ "foobar" "foobla" "fooabc" ]`.
-
-  - A *set pattern* of the form `{ name1, name2, …, nameN }` matches a
-    set containing the listed attributes, and binds the values of those
-    attributes to variables in the function body. For example, the
-    function
-    
-    ```nix
-    { x, y, z }: z + y + x
-    ```
-    
-    can only be called with a set containing exactly the attributes `x`,
-    `y` and `z`. No other attributes are allowed. If you want to allow
-    additional arguments, you can use an ellipsis (`...`):
-    
-    ```nix
-    { x, y, z, ... }: z + y + x
-    ```
-    
-    This works on any set that contains at least the three named
-    attributes.
-    
-    It is possible to provide *default values* for attributes, in
-    which case they are allowed to be missing. A default value is
-    specified by writing `name ?  e`, where *e* is an arbitrary
-    expression. For example,
-    
-    ```nix
-    { x, y ? "foo", z ? "bar" }: z + y + x
-    ```
-    
-    specifies a function that only requires an attribute named `x`, but
-    optionally accepts `y` and `z`.
-
-  - An `@`-pattern provides a means of referring to the whole value
-    being matched:
-    
-    ```nix
-    args@{ x, y, z, ... }: z + y + x + args.a
-    ```
-    
-    but can also be written as:
-    
-    ```nix
-    { x, y, z, ... } @ args: z + y + x + args.a
-    ```
-    
-    Here `args` is bound to the entire argument, which is further
-    matched against the pattern `{ x, y, z,
-            ... }`. `@`-pattern makes mainly sense with an ellipsis(`...`) as
-    you can access attribute names as `a`, using `args.a`, which was
-    given as an additional attribute to the function.
-    
-    > **Warning**
-    > 
-    > The `args@` expression is bound to the argument passed to the
-    > function which means that attributes with defaults that aren't
-    > explicitly specified in the function call won't cause an
-    > evaluation error, but won't exist in `args`.
-    > 
-    > For instance
-    > 
-    > ```nix
-    > let
-    >   function = args@{ a ? 23, ... }: args;
-    > in
-    >   function {}
-    > ````
-    > 
-    > will evaluate to an empty attribute set.
-
-Note that functions do not have names. If you want to give them a name,
-you can bind them to an attribute, e.g.,
-
-```nix
-let concat = { x, y }: x + y;
-in concat { x = "foo"; y = "bar"; }
-```
-
-## Conditionals
-
-Conditionals look like this:
-
-```nix
-if e1 then e2 else e3
-```
-
-where *e1* is an expression that should evaluate to a Boolean value
-(`true` or `false`).
-
-## Assertions
-
-Assertions are generally used to check that certain requirements on or
-between features and dependencies hold. They look like this:
-
-```nix
-assert e1; e2
-```
-
-where *e1* is an expression that should evaluate to a Boolean value. If
-it evaluates to `true`, *e2* is returned; otherwise expression
-evaluation is aborted and a backtrace is printed.
-
-Here is a Nix expression for the Subversion package that shows how
-assertions can be used:.
-
-```nix
-{ localServer ? false
-, httpServer ? false
-, sslSupport ? false
-, pythonBindings ? false
-, javaSwigBindings ? false
-, javahlBindings ? false
-, stdenv, fetchurl
-, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null
-}:
-
-assert localServer -> db4 != null; ①
-assert httpServer -> httpd != null && httpd.expat == expat; ②
-assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); ③
-assert pythonBindings -> swig != null && swig.pythonSupport;
-assert javaSwigBindings -> swig != null && swig.javaSupport;
-assert javahlBindings -> j2sdk != null;
-
-stdenv.mkDerivation {
-  name = "subversion-1.1.1";
-  ...
-  openssl = if sslSupport then openssl else null; ④
-  ...
-}
-```
-
-The points of interest are:
-
-1.  This assertion states that if Subversion is to have support for
-    local repositories, then Berkeley DB is needed. So if the Subversion
-    function is called with the `localServer` argument set to `true` but
-    the `db4` argument set to `null`, then the evaluation fails.
-
-    Note that `->` is the [logical
-    implication](https://en.wikipedia.org/wiki/Truth_table#Logical_implication)
-    Boolean operation.
-
-2.  This is a more subtle condition: if Subversion is built with Apache
-    (`httpServer`) support, then the Expat library (an XML library) used
-    by Subversion should be same as the one used by Apache. This is
-    because in this configuration Subversion code ends up being linked
-    with Apache code, and if the Expat libraries do not match, a build-
-    or runtime link error or incompatibility might occur.
-
-3.  This assertion says that in order for Subversion to have SSL support
-    (so that it can access `https` URLs), an OpenSSL library must be
-    passed. Additionally, it says that *if* Apache support is enabled,
-    then Apache's OpenSSL should match Subversion's. (Note that if
-    Apache support is not enabled, we don't care about Apache's
-    OpenSSL.)
-
-4.  The conditional here is not really related to assertions, but is
-    worth pointing out: it ensures that if SSL support is disabled, then
-    the Subversion derivation is not dependent on OpenSSL, even if a
-    non-`null` value was passed. This prevents an unnecessary rebuild of
-    Subversion if OpenSSL changes.
-
-## With-expressions
-
-A *with-expression*,
-
-```nix
-with e1; e2
-```
-
-introduces the set *e1* into the lexical scope of the expression *e2*.
-For instance,
-
-```nix
-let as = { x = "foo"; y = "bar"; };
-in with as; x + y
-```
-
-evaluates to `"foobar"` since the `with` adds the `x` and `y` attributes
-of `as` to the lexical scope in the expression `x + y`. The most common
-use of `with` is in conjunction with the `import` function. E.g.,
-
-```nix
-with (import ./definitions.nix); ...
-```
-
-makes all attributes defined in the file `definitions.nix` available as
-if they were defined locally in a `let`-expression.
-
-The bindings introduced by `with` do not shadow bindings introduced by
-other means, e.g.
-
-```nix
-let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...
-```
-
-establishes the same scope as
-
-```nix
-let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
-```
-
-## Comments
-
-Comments can be single-line, started with a `#` character, or
-inline/multi-line, enclosed within `/* ... */`.
diff --git a/doc/manual/src/expressions/language-operators.md b/doc/manual/src/expressions/language-operators.md
deleted file mode 100644
index 268b44f4c..000000000
--- a/doc/manual/src/expressions/language-operators.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Operators
-
-The table below lists the operators in the Nix expression language, in
-order of precedence (from strongest to weakest binding).
-
-| Name                     | Syntax                              | Associativity | Description                                                                                                                                                                                                                   | Precedence |
-| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Select                   | *e* `.` *attrpath* \[ `or` *def* \] | none          | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | 1          |
-| Application              | *e1* *e2*                           | left          | Call function *e1* with argument *e2*.                                                                                                                                                                                        | 2          |
-| Arithmetic Negation      | `-` *e*                             | none          | Arithmetic negation.                                                                                                                                                                                                          | 3          |
-| Has Attribute            | *e* `?` *attrpath*                  | none          | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.                                                                                                                                  | 4          |
-| List Concatenation       | *e1* `++` *e2*                      | right         | List concatenation.                                                                                                                                                                                                           | 5          |
-| Multiplication           | *e1* `*` *e2*,                      | left          | Arithmetic multiplication.                                                                                                                                                                                                    | 6          |
-| Division                 | *e1* `/` *e2*                       | left          | Arithmetic division.                                                                                                                                                                                                          | 6          |
-| Addition                 | *e1* `+` *e2*                       | left          | Arithmetic addition.                                                                                                                                                                                                          | 7          |
-| Subtraction              | *e1* `-` *e2*                       | left          | Arithmetic subtraction.                                                                                                                                                                                                       | 7          |
-| String Concatenation     | *string1* `+` *string2*             | left          | String concatenation.                                                                                                                                                                                                         | 7          |
-| Not                      | `!` *e*                             | none          | Boolean negation.                                                                                                                                                                                                             | 8          |
-| Update                   | *e1* `//` *e2*                      | right         | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).                                                                           | 9          |
-| Less Than                | *e1* `<` *e2*,                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Less Than or Equal To    | *e1* `<=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Greater Than             | *e1* `>` *e2*                       | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Greater Than or Equal To | *e1* `>=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Equality                 | *e1* `==` *e2*                      | none          | Equality.                                                                                                                                                                                                                     | 11         |
-| Inequality               | *e1* `!=` *e2*                      | none          | Inequality.                                                                                                                                                                                                                   | 11         |
-| Logical AND              | *e1* `&&` *e2*                      | left          | Logical AND.                                                                                                                                                                                                                  | 12         |
-| Logical OR               | *e1* <code>&#124;&#124;</code> *e2* | left          | Logical OR.                                                                                                                                                                                                                   | 13         |
-| Logical Implication      | *e1* `->` *e2*                      | none          | Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).                                                                                                                                                                            | 14         |
diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md
deleted file mode 100644
index f09400d02..000000000
--- a/doc/manual/src/expressions/language-values.md
+++ /dev/null
@@ -1,261 +0,0 @@
-# Data Types
-
-## Primitives
-
-- <a id="type-string" href="#type-string">String</a>
-
-  *Strings* can be written in three ways.
-
-  The most common way is to enclose the string between double quotes,
-  e.g., `"foo bar"`. Strings can span multiple lines. The special
-  characters `"` and `\` and the character sequence `${` must be
-  escaped by prefixing them with a backslash (`\`). Newlines, carriage
-  returns and tabs can be written as `\n`, `\r` and `\t`,
-  respectively.
-
-  You can include the result of an expression into a string by
-  enclosing it in `${...}`, a feature known as *antiquotation*. The
-  enclosed expression must evaluate to something that can be coerced
-  into a string (meaning that it must be a string, a path, or a
-  derivation). For instance, rather than writing
-
-  ```nix
-  "--with-freetype2-library=" + freetype + "/lib"
-  ```
-
-  (where `freetype` is a derivation), you can instead write the more
-  natural
-
-  ```nix
-  "--with-freetype2-library=${freetype}/lib"
-  ```
-
-  The latter is automatically translated to the former. A more
-  complicated example (from the Nix expression for
-  [Qt](http://www.trolltech.com/products/qt)):
-
-  ```nix
-  configureFlags = "
-    -system-zlib -system-libpng -system-libjpeg
-    ${if openglSupport then "-dlopen-opengl
-      -L${mesa}/lib -I${mesa}/include
-      -L${libXmu}/lib -I${libXmu}/include" else ""}
-    ${if threadSupport then "-thread" else "-no-thread"}
-  ";
-  ```
-
-  Note that Nix expressions and strings can be arbitrarily nested; in
-  this case the outer string contains various antiquotations that
-  themselves contain strings (e.g., `"-thread"`), some of which in
-  turn contain expressions (e.g., `${mesa}`).
-
-  The second way to write string literals is as an *indented string*,
-  which is enclosed between pairs of *double single-quotes*, like so:
-
-  ```nix
-  ''
-    This is the first line.
-    This is the second line.
-      This is the third line.
-  ''
-  ```
-
-  This kind of string literal intelligently strips indentation from
-  the start of each line. To be precise, it strips from each line a
-  number of spaces equal to the minimal indentation of the string as a
-  whole (disregarding the indentation of empty lines). For instance,
-  the first and second line are indented two spaces, while the third
-  line is indented four spaces. Thus, two spaces are stripped from
-  each line, so the resulting string is
-
-  ```nix
-  "This is the first line.\nThis is the second line.\n  This is the third line.\n"
-  ```
-
-  Note that the whitespace and newline following the opening `''` is
-  ignored if there is no non-whitespace text on the initial line.
-
-  Antiquotation (`${expr}`) is supported in indented strings.
-
-  Since `${` and `''` have special meaning in indented strings, you
-  need a way to quote them. `$` can be escaped by prefixing it with
-  `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
-  by prefixing it with `'`, i.e., `'''`. `$` removes any special
-  meaning from the following `$`. Linefeed, carriage-return and tab
-  characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
-  escapes any other character.
-
-  Indented strings are primarily useful in that they allow multi-line
-  string literals to follow the indentation of the enclosing Nix
-  expression, and that less escaping is typically necessary for
-  strings representing languages such as shell scripts and
-  configuration files because `''` is much less common than `"`.
-  Example:
-
-  ```nix
-  stdenv.mkDerivation {
-    ...
-    postInstall =
-      ''
-        mkdir $out/bin $out/etc
-        cp foo $out/bin
-        echo "Hello World" > $out/etc/foo.conf
-        ${if enableBar then "cp bar $out/bin" else ""}
-      '';
-    ...
-  }
-  ```
-
-  Finally, as a convenience, *URIs* as defined in appendix B of
-  [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
-  is*, without quotes. For instance, the string
-  `"http://example.org/foo.tar.bz2"` can also be written as
-  `http://example.org/foo.tar.bz2`.
-
-- <a id="type-number" href="#type-number">Number</a>
-
-  Numbers, which can be *integers* (like `123`) or *floating point*
-  (like `123.43` or `.27e13`).
-
-  Numbers are type-compatible: pure integer operations will always
-  return integers, whereas any operation involving at least one
-  floating point number will have a floating point number as a result.
-
-- <a id="type-path" href="#type-path">Path</a>
-
-  *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
-  least one slash to be recognised as such. For instance, `builder.sh`
-  is not a path: it's parsed as an expression that selects the
-  attribute `sh` from the variable `builder`. If the file name is
-  relative, i.e., if it does not begin with a slash, it is made
-  absolute at parse time relative to the directory of the Nix
-  expression that contained it. For instance, if a Nix expression in
-  `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
-  is `/foo/xyzzy/fnord.nix`.
-
-  If the first component of a path is a `~`, it is interpreted as if
-  the rest of the path were relative to the user's home directory.
-  e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
-  whose home directory is `/home/edolstra`.
-
-  Paths can also be specified between angle brackets, e.g.
-  `<nixpkgs>`. This means that the directories listed in the
-  environment variable `NIX_PATH` will be searched for the given file
-  or directory name.
-
-  Antiquotation is supported in any paths except those in angle brackets.
-  `./${foo}-${bar}.nix` is a more convenient way of writing
-  `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
-  least one slash must appear *before* any antiquotations for this to be
-  recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
-  operation. `./a.${foo}/b.${bar}` is a path.
-
-- <a id="type-boolean" href="#type-boolean">Boolean</a>
-
-  *Booleans* with values `true` and `false`.
-
-- <a id="type-null" href="#type-null">Null</a>
-
-  The null value, denoted as `null`.
-
-## List
-
-Lists are formed by enclosing a whitespace-separated list of values
-between square brackets. For example,
-
-```nix
-[ 123 ./foo.nix "abc" (f { x = y; }) ]
-```
-
-defines a list of four elements, the last being the result of a call to
-the function `f`. Note that function calls have to be enclosed in
-parentheses. If they had been omitted, e.g.,
-
-```nix
-[ 123 ./foo.nix "abc" f { x = y; } ]
-```
-
-the result would be a list of five elements, the fourth one being a
-function and the fifth being a set.
-
-Note that lists are only lazy in values, and they are strict in length.
-
-## Attribute Set
-
-An attribute set is a collection of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
-
-Names and values are separated by an equal sign (`=`).
-Each value is an arbitrary expression terminated by a semicolon (`;`).
-
-Attributes can appear in any order.
-An attribute name may only occur once.
-
-Example:
-
-```nix
-{
-  x = 123;
-  text = "Hello";
-  y = f { bla = 456; };
-}
-```
-
-This defines a set with attributes named `x`, `text`, `y`.
-
-Attributes can be selected from a set using the `.` operator. For
-instance,
-
-```nix
-{ a = "Foo"; b = "Bar"; }.a
-```
-
-evaluates to `"Foo"`. It is possible to provide a default value in an
-attribute selection using the `or` keyword. For example,
-
-```nix
-{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"
-```
-
-will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
-
-You can use arbitrary double-quoted strings as attribute names:
-
-```nix
-{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
-```
-
-This will evaluate to `123` (Assuming `bar` is antiquotable). In the
-case where an attribute name is just a single antiquotation, the quotes
-can be dropped:
-
-```nix
-{ foo = 123; }.${bar} or 456
-```
-
-This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced
-to a string and `456` otherwise (again assuming `bar` is antiquotable).
-
-In the special case where an attribute name inside of a set declaration
-evaluates to `null` (which is normally an error, as `null` is not
-antiquotable), that attribute is simply not added to the set:
-
-```nix
-{ ${if foo then "bar" else null} = true; }
-```
-
-This will evaluate to `{}` if `foo` evaluates to `false`.
-
-A set that has a `__functor` attribute whose value is callable (i.e. is
-itself a function or a set with a `__functor` attribute whose value is
-callable) can be applied as if it were a function, with the set itself
-passed in first , e.g.,
-
-```nix
-let add = { __functor = self: x: x + self.x; };
-    inc = add // { x = 1; };
-in inc 1
-```
-
-evaluates to `2`. This can be used to attach metadata to a function
-without the caller needing to treat it specially, or to implement a form
-of object-oriented programming, for example.
diff --git a/doc/manual/src/expressions/simple-building-testing.md b/doc/manual/src/expressions/simple-building-testing.md
deleted file mode 100644
index 7f0d8f841..000000000
--- a/doc/manual/src/expressions/simple-building-testing.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Building and Testing
-
-You can now try to build Hello. Of course, you could do `nix-env -f . -iA
-hello`, but you may not want to install a possibly broken package just
-yet. The best way to test the package is by using the command
-`nix-build`, which builds a Nix expression and creates a symlink named
-`result` in the current directory:
-
-```console
-$ nix-build -A hello
-building path `/nix/store/632d2b22514d...-hello-2.1.1'
-hello-2.1.1/
-hello-2.1.1/intl/
-hello-2.1.1/intl/ChangeLog
-...
-
-$ ls -l result
-lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1
-
-$ ./result/bin/hello
-Hello, world!
-```
-
-The `-A` option selects the `hello` attribute. This is faster than
-using the symbolic package name specified by the `name` attribute
-(which also happens to be `hello`) and is unambiguous (there can be
-multiple packages with the symbolic name `hello`, but there can be
-only one attribute in a set named `hello`).
-
-`nix-build` registers the `./result` symlink as a garbage collection
-root, so unless and until you delete the `./result` symlink, the output
-of the build will be safely kept on your system. You can use
-`nix-build`’s `-o` switch to give the symlink another name.
-
-Nix has transactional semantics. Once a build finishes successfully, Nix
-makes a note of this in its database: it registers that the path denoted
-by `out` is now “valid”. If you try to build the derivation again, Nix
-will see that the path is already valid and finish immediately. If a
-build fails, either because it returns a non-zero exit code, because Nix
-or the builder are killed, or because the machine crashes, then the
-output paths will not be registered as valid. If you try to build the
-derivation again, Nix will remove the output paths if they exist (e.g.,
-because the builder died half-way through `make
-install`) and try again. Note that there is no “negative caching”: Nix
-doesn't remember that a build failed, and so a failed build can always
-be repeated. This is because Nix cannot distinguish between permanent
-failures (e.g., a compiler error due to a syntax error in the source)
-and transient failures (e.g., a disk full condition).
-
-Nix also performs locking. If you run multiple Nix builds
-simultaneously, and they try to build the same derivation, the first Nix
-instance that gets there will perform the build, while the others block
-(or perform other derivations if available) until the build finishes:
-
-```console
-$ nix-build -A hello
-waiting for lock on `/nix/store/0h5b7hp8d4hqfrw8igvx97x1xawrjnac-hello-2.1.1x'
-```
-
-So it is always safe to run multiple instances of Nix in parallel (which
-isn’t the case with, say, `make`).
diff --git a/doc/manual/src/expressions/simple-expression.md b/doc/manual/src/expressions/simple-expression.md
deleted file mode 100644
index 857f71b9b..000000000
--- a/doc/manual/src/expressions/simple-expression.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# A Simple Nix Expression
-
-This section shows how to add and test the [GNU Hello
-package](http://www.gnu.org/software/hello/hello.html) to the Nix
-Packages collection. Hello is a program that prints out the text “Hello,
-world\!”.
-
-To add a package to the Nix Packages collection, you generally need to
-do three things:
-
-1.  Write a Nix expression for the package. This is a file that
-    describes all the inputs involved in building the package, such as
-    dependencies, sources, and so on.
-
-2.  Write a *builder*. This is a shell script that builds the package
-    from the inputs. (In fact, it can be written in any language, but
-    typically it's a `bash` shell script.)
-
-3.  Add the package to the file `pkgs/top-level/all-packages.nix`. The
-    Nix expression written in the first step is a *function*; it
-    requires other packages in order to build it. In this step you put
-    it all together, i.e., you call the function with the right
-    arguments to build the actual package.
diff --git a/doc/manual/src/expressions/writing-nix-expressions.md b/doc/manual/src/expressions/writing-nix-expressions.md
deleted file mode 100644
index 5664108e7..000000000
--- a/doc/manual/src/expressions/writing-nix-expressions.md
+++ /dev/null
@@ -1,12 +0,0 @@
-This chapter shows you how to write Nix expressions, which instruct Nix
-how to build packages. It starts with a simple example (a Nix expression
-for GNU Hello), and then moves on to a more in-depth look at the Nix
-expression language.
-
-> **Note**
-> 
-> This chapter is mostly about the Nix expression language. For more
-> extensive information on adding packages to the Nix Packages
-> collection (such as functions in the standard environment and coding
-> conventions), please consult [its
-> manual](http://nixos.org/nixpkgs/manual/).
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 3448b971b..aa0ac78cb 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -3,7 +3,7 @@
   - [derivation]{#gloss-derivation}\
     A description of a build action. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
-    using the [`derivation` primitive](expressions/derivations.md). These are
+    using the [`derivation` primitive](language/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
diff --git a/doc/manual/src/language/advanced-attributes.md b/doc/manual/src/language/advanced-attributes.md
new file mode 100644
index 000000000..2e7e80ed0
--- /dev/null
+++ b/doc/manual/src/language/advanced-attributes.md
@@ -0,0 +1,257 @@
+# Advanced Attributes
+
+Derivations can declare some infrequently used optional attributes.
+
+  - [`allowedReferences`]{#adv-attr-allowedReferences}\
+    The optional attribute `allowedReferences` specifies a list of legal
+    references (dependencies) of the output of the builder. For example,
+
+    ```nix
+    allowedReferences = [];
+    ```
+
+    enforces that the output of a derivation cannot have any runtime
+    dependencies on its inputs. To allow an output to have a runtime
+    dependency on itself, use `"out"` as a list item. This is used in
+    NixOS to check that generated files such as initial ramdisks for
+    booting Linux don’t have accidental dependencies on other paths in
+    the Nix store.
+
+  - [`allowedRequisites`]{#adv-attr-allowedRequisites}\
+    This attribute is similar to `allowedReferences`, but it specifies
+    the legal requisites of the whole closure, so all the dependencies
+    recursively. For example,
+
+    ```nix
+    allowedRequisites = [ foobar ];
+    ```
+
+    enforces that the output of a derivation cannot have any other
+    runtime dependency than `foobar`, and in addition it enforces that
+    `foobar` itself doesn't introduce any other dependency itself.
+
+  - [`disallowedReferences`]{#adv-attr-disallowedReferences}\
+    The optional attribute `disallowedReferences` specifies a list of
+    illegal references (dependencies) of the output of the builder. For
+    example,
+
+    ```nix
+    disallowedReferences = [ foo ];
+    ```
+
+    enforces that the output of a derivation cannot have a direct
+    runtime dependencies on the derivation `foo`.
+
+  - [`disallowedRequisites`]{#adv-attr-disallowedRequisites}\
+    This attribute is similar to `disallowedReferences`, but it
+    specifies illegal requisites for the whole closure, so all the
+    dependencies recursively. For example,
+
+    ```nix
+    disallowedRequisites = [ foobar ];
+    ```
+
+    enforces that the output of a derivation cannot have any runtime
+    dependency on `foobar` or any other derivation depending recursively
+    on `foobar`.
+
+  - [`exportReferencesGraph`]{#adv-attr-exportReferencesGraph}\
+    This attribute allows builders access to the references graph of
+    their inputs. The attribute is a list of inputs in the Nix store
+    whose references graph the builder needs to know. The value of
+    this attribute should be a list of pairs `[ name1 path1 name2
+    path2 ...  ]`. The references graph of each *pathN* will be stored
+    in a text file *nameN* in the temporary build directory. The text
+    files have the format used by `nix-store --register-validity`
+    (with the deriver fields left empty). For example, when the
+    following derivation is built:
+
+    ```nix
+    derivation {
+      ...
+      exportReferencesGraph = [ "libfoo-graph" libfoo ];
+    };
+    ```
+
+    the references graph of `libfoo` is placed in the file
+    `libfoo-graph` in the temporary build directory.
+
+    `exportReferencesGraph` is useful for builders that want to do
+    something with the closure of a store path. Examples include the
+    builders in NixOS that generate the initial ramdisk for booting
+    Linux (a `cpio` archive containing the closure of the boot script)
+    and the ISO-9660 image for the installation CD (which is populated
+    with a Nix store containing the closure of a bootable NixOS
+    configuration).
+
+  - [`impureEnvVars`]{#adv-attr-impureEnvVars}\
+    This attribute allows you to specify a list of environment variables
+    that should be passed from the environment of the calling user to
+    the builder. Usually, the environment is cleared completely when the
+    builder is executed, but with this attribute you can allow specific
+    environment variables to be passed unmodified. For example,
+    `fetchurl` in Nixpkgs has the line
+
+    ```nix
+    impureEnvVars = [ "http_proxy" "https_proxy" ... ];
+    ```
+
+    to make it use the proxy server configuration specified by the user
+    in the environment variables `http_proxy` and friends.
+
+    This attribute is only allowed in *fixed-output derivations* (see
+    below), where impurities such as these are okay since (the hash
+    of) the output is known in advance. It is ignored for all other
+    derivations.
+
+    > **Warning**
+    >
+    > `impureEnvVars` implementation takes environment variables from
+    > the current builder process. When a daemon is building its
+    > environmental variables are used. Without the daemon, the
+    > environmental variables come from the environment of the
+    > `nix-build`.
+
+  - [`outputHash`]{#adv-attr-outputHash}; [`outputHashAlgo`]{#adv-attr-outputHashAlgo}; [`outputHashMode`]{#adv-attr-outputHashMode}\
+    These attributes declare that the derivation is a so-called
+    *fixed-output derivation*, which means that a cryptographic hash of
+    the output is already known in advance. When the build of a
+    fixed-output derivation finishes, Nix computes the cryptographic
+    hash of the output and compares it to the hash declared with these
+    attributes. If there is a mismatch, the build fails.
+
+    The rationale for fixed-output derivations is derivations such as
+    those produced by the `fetchurl` function. This function downloads a
+    file from a given URL. To ensure that the downloaded file has not
+    been modified, the caller must also specify a cryptographic hash of
+    the file. For example,
+
+    ```nix
+    fetchurl {
+      url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
+      sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+    }
+    ```
+
+    It sometimes happens that the URL of the file changes, e.g., because
+    servers are reorganised or no longer available. We then must update
+    the call to `fetchurl`, e.g.,
+
+    ```nix
+    fetchurl {
+      url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
+      sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
+    }
+    ```
+
+    If a `fetchurl` derivation was treated like a normal derivation, the
+    output paths of the derivation and *all derivations depending on it*
+    would change. For instance, if we were to change the URL of the
+    Glibc source distribution in Nixpkgs (a package on which almost all
+    other packages depend) massive rebuilds would be needed. This is
+    unfortunate for a change which we know cannot have a real effect as
+    it propagates upwards through the dependency graph.
+
+    For fixed-output derivations, on the other hand, the name of the
+    output path only depends on the `outputHash*` and `name` attributes,
+    while all other attributes are ignored for the purpose of computing
+    the output path. (The `name` attribute is included because it is
+    part of the path.)
+
+    As an example, here is the (simplified) Nix expression for
+    `fetchurl`:
+
+    ```nix
+    { stdenv, curl }: # The curl program is used for downloading.
+
+    { url, sha256 }:
+
+    stdenv.mkDerivation {
+      name = baseNameOf (toString url);
+      builder = ./builder.sh;
+      buildInputs = [ curl ];
+
+      # This is a fixed-output derivation; the output must be a regular
+      # file with SHA256 hash sha256.
+      outputHashMode = "flat";
+      outputHashAlgo = "sha256";
+      outputHash = sha256;
+
+      inherit url;
+    }
+    ```
+
+    The `outputHashAlgo` attribute specifies the hash algorithm used to
+    compute the hash. It can currently be `"sha1"`, `"sha256"` or
+    `"sha512"`.
+
+    The `outputHashMode` attribute determines how the hash is computed.
+    It must be one of the following two values:
+
+      - `"flat"`\
+        The output must be a non-executable regular file. If it isn’t,
+        the build fails. The hash is simply computed over the contents
+        of that file (so it’s equal to what Unix commands like
+        `sha256sum` or `sha1sum` produce).
+
+        This is the default.
+
+      - `"recursive"`\
+        The hash is computed over the NAR archive dump of the output
+        (i.e., the result of [`nix-store
+        --dump`](../command-ref/nix-store.md#operation---dump)). In
+        this case, the output can be anything, including a directory
+        tree.
+
+    The `outputHash` attribute, finally, must be a string containing
+    the hash in either hexadecimal or base-32 notation. (See the
+    [`nix-hash` command](../command-ref/nix-hash.md) for information
+    about converting to and from base-32 notation.)
+    
+  - [`__contentAddressed`]{#adv-attr-__contentAddressed}
+    If this **experimental** attribute is set to true, then the derivation
+    outputs will be stored in a content-addressed location rather than the
+    traditional input-addressed one.
+    This only has an effect if the `ca-derivation` experimental feature is enabled.
+    
+    Setting this attribute also requires setting `outputHashMode` and `outputHashAlgo` like for *fixed-output derivations* (see above).
+
+  - [`passAsFile`]{#adv-attr-passAsFile}\
+    A list of names of attributes that should be passed via files rather
+    than environment variables. For example, if you have
+
+    ```nix
+    passAsFile = ["big"];
+    big = "a very long string";
+    ```
+
+    then when the builder runs, the environment variable `bigPath`
+    will contain the absolute path to a temporary file containing `a
+    very long string`. That is, for any attribute *x* listed in
+    `passAsFile`, Nix will pass an environment variable `xPath`
+    holding the path of the file containing the value of attribute
+    *x*. This is useful when you need to pass large strings to a
+    builder, since most operating systems impose a limit on the size
+    of the environment (typically, a few hundred kilobyte).
+
+  - [`preferLocalBuild`]{#adv-attr-preferLocalBuild}\
+    If this attribute is set to `true` and [distributed building is
+    enabled](../advanced-topics/distributed-builds.md), then, if
+    possible, the derivation will be built locally instead of forwarded
+    to a remote machine. This is appropriate for trivial builders
+    where the cost of doing a download or remote build would exceed
+    the cost of building locally.
+
+  - [`allowSubstitutes`]{#adv-attr-allowSubstitutes}\
+    If this attribute is set to `false`, then Nix will always build this
+    derivation; it will not try to substitute its outputs. This is
+    useful for very trivial derivations (such as `writeText` in Nixpkgs)
+    that are cheaper to build than to substitute from a binary cache.
+
+    > **Note**
+    >
+    > You need to have a builder configured which satisfies the
+    > derivation’s `system` attribute, since the derivation cannot be
+    > substituted. Thus it is usually a good idea to align `system` with
+    > `builtins.currentSystem` when setting `allowSubstitutes` to
+    > `false`. For most trivial derivations this should be the case.
diff --git a/doc/manual/src/language/builtin-constants.md b/doc/manual/src/language/builtin-constants.md
new file mode 100644
index 000000000..78d066a82
--- /dev/null
+++ b/doc/manual/src/language/builtin-constants.md
@@ -0,0 +1,20 @@
+# Built-in Constants
+
+Here are the constants built into the Nix expression evaluator:
+
+  - `builtins`\
+    The set `builtins` contains all the built-in functions and values.
+    You can use `builtins` to test for the availability of features in
+    the Nix installation, e.g.,
+    
+    ```nix
+    if builtins ? getEnv then builtins.getEnv "PATH" else ""
+    ```
+    
+    This allows a Nix expression to fall back gracefully on older Nix
+    installations that don’t have the desired built-in function.
+
+  - [`builtins.currentSystem`]{#builtins-currentSystem}\
+    The built-in value `currentSystem` evaluates to the Nix platform
+    identifier for the Nix installation on which the expression is being
+    evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
diff --git a/doc/manual/src/language/builtins-prefix.md b/doc/manual/src/language/builtins-prefix.md
new file mode 100644
index 000000000..c631a8453
--- /dev/null
+++ b/doc/manual/src/language/builtins-prefix.md
@@ -0,0 +1,16 @@
+# Built-in Functions
+
+This section lists the functions built into the Nix expression
+evaluator. (The built-in function `derivation` is discussed above.)
+Some built-ins, such as `derivation`, are always in scope of every Nix
+expression; you can just access them right away. But to prevent
+polluting the namespace too much, most built-ins are not in
+scope. Instead, you can access them through the `builtins` built-in
+value, which is a set that contains all built-in functions and values.
+For instance, `derivation` is also available as `builtins.derivation`.
+
+<dl>
+  <dt><code>derivation <var>attrs</var></code>;
+      <code>builtins.derivation <var>attrs</var></code></dt>
+  <dd><p><var>derivation</var> is described in
+         <a href="derivations.md">its own section</a>.</p></dd>
diff --git a/doc/manual/src/language/builtins-suffix.md b/doc/manual/src/language/builtins-suffix.md
new file mode 100644
index 000000000..a74db2857
--- /dev/null
+++ b/doc/manual/src/language/builtins-suffix.md
@@ -0,0 +1 @@
+</dl>
diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md
new file mode 100644
index 000000000..1c01f2cc7
--- /dev/null
+++ b/doc/manual/src/language/constructs.md
@@ -0,0 +1,354 @@
+# Language Constructs
+
+## Recursive sets
+
+Recursive sets are just normal sets, but the attributes can refer to
+each other. For example,
+
+```nix
+rec {
+  x = y;
+  y = 123;
+}.x
+```
+
+evaluates to `123`. Note that without `rec` the binding `x = y;` would
+refer to the variable `y` in the surrounding scope, if one exists, and
+would be invalid if no such variable exists. That is, in a normal
+(non-recursive) set, attributes are not added to the lexical scope; in a
+recursive set, they are.
+
+Recursive sets of course introduce the danger of infinite recursion. For
+example, the expression
+
+```nix
+rec {
+  x = y;
+  y = x;
+}.x
+```
+
+will crash with an `infinite recursion encountered` error message.
+
+## Let-expressions
+
+A let-expression allows you to define local variables for an expression.
+For instance,
+
+```nix
+let
+  x = "foo";
+  y = "bar";
+in x + y
+```
+
+evaluates to `"foobar"`.
+
+## Inheriting attributes
+
+When defining a set or in a let-expression it is often convenient to
+copy variables from the surrounding lexical scope (e.g., when you want
+to propagate attributes). This can be shortened using the `inherit`
+keyword. For instance,
+
+```nix
+let x = 123; in
+{ inherit x;
+  y = 456;
+}
+```
+
+is equivalent to
+
+```nix
+let x = 123; in
+{ x = x;
+  y = 456;
+}
+```
+
+and both evaluate to `{ x = 123; y = 456; }`. (Note that this works
+because `x` is added to the lexical scope by the `let` construct.) It is
+also possible to inherit attributes from another set. For instance, in
+this fragment from `all-packages.nix`,
+
+```nix
+graphviz = (import ../tools/graphics/graphviz) {
+  inherit fetchurl stdenv libpng libjpeg expat x11 yacc;
+  inherit (xlibs) libXaw;
+};
+
+xlibs = {
+  libX11 = ...;
+  libXaw = ...;
+  ...
+}
+
+libpng = ...;
+libjpg = ...;
+...
+```
+
+the set used in the function call to the function defined in
+`../tools/graphics/graphviz` inherits a number of variables from the
+surrounding scope (`fetchurl` ... `yacc`), but also inherits `libXaw`
+(the X Athena Widgets) from the `xlibs` (X11 client-side libraries) set.
+
+Summarizing the fragment
+
+```nix
+...
+inherit x y z;
+inherit (src-set) a b c;
+...
+```
+
+is equivalent to
+
+```nix
+...
+x = x; y = y; z = z;
+a = src-set.a; b = src-set.b; c = src-set.c;
+...
+```
+
+when used while defining local variables in a let-expression or while
+defining a set.
+
+## Functions
+
+Functions have the following form:
+
+```nix
+pattern: body
+```
+
+The pattern specifies what the argument of the function must look like,
+and binds variables in the body to (parts of) the argument. There are
+three kinds of patterns:
+
+  - If a pattern is a single identifier, then the function matches any
+    argument. Example:
+    
+    ```nix
+    let negate = x: !x;
+        concat = x: y: x + y;
+    in if negate true then concat "foo" "bar" else ""
+    ```
+    
+    Note that `concat` is a function that takes one argument and returns
+    a function that takes another argument. This allows partial
+    parameterisation (i.e., only filling some of the arguments of a
+    function); e.g.,
+    
+    ```nix
+    map (concat "foo") [ "bar" "bla" "abc" ]
+    ```
+    
+    evaluates to `[ "foobar" "foobla" "fooabc" ]`.
+
+  - A *set pattern* of the form `{ name1, name2, …, nameN }` matches a
+    set containing the listed attributes, and binds the values of those
+    attributes to variables in the function body. For example, the
+    function
+    
+    ```nix
+    { x, y, z }: z + y + x
+    ```
+    
+    can only be called with a set containing exactly the attributes `x`,
+    `y` and `z`. No other attributes are allowed. If you want to allow
+    additional arguments, you can use an ellipsis (`...`):
+    
+    ```nix
+    { x, y, z, ... }: z + y + x
+    ```
+    
+    This works on any set that contains at least the three named
+    attributes.
+    
+    It is possible to provide *default values* for attributes, in
+    which case they are allowed to be missing. A default value is
+    specified by writing `name ?  e`, where *e* is an arbitrary
+    expression. For example,
+    
+    ```nix
+    { x, y ? "foo", z ? "bar" }: z + y + x
+    ```
+    
+    specifies a function that only requires an attribute named `x`, but
+    optionally accepts `y` and `z`.
+
+  - An `@`-pattern provides a means of referring to the whole value
+    being matched:
+    
+    ```nix
+    args@{ x, y, z, ... }: z + y + x + args.a
+    ```
+    
+    but can also be written as:
+    
+    ```nix
+    { x, y, z, ... } @ args: z + y + x + args.a
+    ```
+    
+    Here `args` is bound to the entire argument, which is further
+    matched against the pattern `{ x, y, z,
+            ... }`. `@`-pattern makes mainly sense with an ellipsis(`...`) as
+    you can access attribute names as `a`, using `args.a`, which was
+    given as an additional attribute to the function.
+    
+    > **Warning**
+    > 
+    > The `args@` expression is bound to the argument passed to the
+    > function which means that attributes with defaults that aren't
+    > explicitly specified in the function call won't cause an
+    > evaluation error, but won't exist in `args`.
+    > 
+    > For instance
+    > 
+    > ```nix
+    > let
+    >   function = args@{ a ? 23, ... }: args;
+    > in
+    >   function {}
+    > ````
+    > 
+    > will evaluate to an empty attribute set.
+
+Note that functions do not have names. If you want to give them a name,
+you can bind them to an attribute, e.g.,
+
+```nix
+let concat = { x, y }: x + y;
+in concat { x = "foo"; y = "bar"; }
+```
+
+## Conditionals
+
+Conditionals look like this:
+
+```nix
+if e1 then e2 else e3
+```
+
+where *e1* is an expression that should evaluate to a Boolean value
+(`true` or `false`).
+
+## Assertions
+
+Assertions are generally used to check that certain requirements on or
+between features and dependencies hold. They look like this:
+
+```nix
+assert e1; e2
+```
+
+where *e1* is an expression that should evaluate to a Boolean value. If
+it evaluates to `true`, *e2* is returned; otherwise expression
+evaluation is aborted and a backtrace is printed.
+
+Here is a Nix expression for the Subversion package that shows how
+assertions can be used:.
+
+```nix
+{ localServer ? false
+, httpServer ? false
+, sslSupport ? false
+, pythonBindings ? false
+, javaSwigBindings ? false
+, javahlBindings ? false
+, stdenv, fetchurl
+, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null
+}:
+
+assert localServer -> db4 != null; ①
+assert httpServer -> httpd != null && httpd.expat == expat; ②
+assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); ③
+assert pythonBindings -> swig != null && swig.pythonSupport;
+assert javaSwigBindings -> swig != null && swig.javaSupport;
+assert javahlBindings -> j2sdk != null;
+
+stdenv.mkDerivation {
+  name = "subversion-1.1.1";
+  ...
+  openssl = if sslSupport then openssl else null; ④
+  ...
+}
+```
+
+The points of interest are:
+
+1.  This assertion states that if Subversion is to have support for
+    local repositories, then Berkeley DB is needed. So if the Subversion
+    function is called with the `localServer` argument set to `true` but
+    the `db4` argument set to `null`, then the evaluation fails.
+
+    Note that `->` is the [logical
+    implication](https://en.wikipedia.org/wiki/Truth_table#Logical_implication)
+    Boolean operation.
+
+2.  This is a more subtle condition: if Subversion is built with Apache
+    (`httpServer`) support, then the Expat library (an XML library) used
+    by Subversion should be same as the one used by Apache. This is
+    because in this configuration Subversion code ends up being linked
+    with Apache code, and if the Expat libraries do not match, a build-
+    or runtime link error or incompatibility might occur.
+
+3.  This assertion says that in order for Subversion to have SSL support
+    (so that it can access `https` URLs), an OpenSSL library must be
+    passed. Additionally, it says that *if* Apache support is enabled,
+    then Apache's OpenSSL should match Subversion's. (Note that if
+    Apache support is not enabled, we don't care about Apache's
+    OpenSSL.)
+
+4.  The conditional here is not really related to assertions, but is
+    worth pointing out: it ensures that if SSL support is disabled, then
+    the Subversion derivation is not dependent on OpenSSL, even if a
+    non-`null` value was passed. This prevents an unnecessary rebuild of
+    Subversion if OpenSSL changes.
+
+## With-expressions
+
+A *with-expression*,
+
+```nix
+with e1; e2
+```
+
+introduces the set *e1* into the lexical scope of the expression *e2*.
+For instance,
+
+```nix
+let as = { x = "foo"; y = "bar"; };
+in with as; x + y
+```
+
+evaluates to `"foobar"` since the `with` adds the `x` and `y` attributes
+of `as` to the lexical scope in the expression `x + y`. The most common
+use of `with` is in conjunction with the `import` function. E.g.,
+
+```nix
+with (import ./definitions.nix); ...
+```
+
+makes all attributes defined in the file `definitions.nix` available as
+if they were defined locally in a `let`-expression.
+
+The bindings introduced by `with` do not shadow bindings introduced by
+other means, e.g.
+
+```nix
+let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...
+```
+
+establishes the same scope as
+
+```nix
+let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
+```
+
+## Comments
+
+Comments can be single-line, started with a `#` character, or
+inline/multi-line, enclosed within `/* ... */`.
diff --git a/doc/manual/src/language/derivations.md b/doc/manual/src/language/derivations.md
new file mode 100644
index 000000000..3391ec0d8
--- /dev/null
+++ b/doc/manual/src/language/derivations.md
@@ -0,0 +1,161 @@
+# Derivations
+
+The most important built-in function is `derivation`, which is used to
+describe a single derivation (a build action). It takes as input a set,
+the attributes of which specify the inputs of the build.
+
+  - There must be an attribute named [`system`]{#attr-system} whose value must be a
+    string specifying a Nix system type, such as `"i686-linux"` or
+    `"x86_64-darwin"`. (To figure out your system type, run `nix -vv
+    --version`.) The build can only be performed on a machine and
+    operating system matching the system type. (Nix can automatically
+    [forward builds for other
+    platforms](../advanced-topics/distributed-builds.md) by forwarding
+    them to other machines.)
+
+  - There must be an attribute named `name` whose value must be a
+    string. This is used as a symbolic name for the package by
+    `nix-env`, and it is appended to the output paths of the derivation.
+
+  - There must be an attribute named `builder` that identifies the
+    program that is executed to perform the build. It can be either a
+    derivation or a source (a local file reference, e.g.,
+    `./builder.sh`).
+
+  - Every attribute is passed as an environment variable to the builder.
+    Attribute values are translated to environment variables as follows:
+    
+      - Strings and numbers are just passed verbatim.
+    
+      - A *path* (e.g., `../foo/sources.tar`) causes the referenced file
+        to be copied to the store; its location in the store is put in
+        the environment variable. The idea is that all sources should
+        reside in the Nix store, since all inputs to a derivation should
+        reside in the Nix store.
+    
+      - A *derivation* causes that derivation to be built prior to the
+        present derivation; its default output path is put in the
+        environment variable.
+    
+      - Lists of the previous types are also allowed. They are simply
+        concatenated, separated by spaces.
+    
+      - `true` is passed as the string `1`, `false` and `null` are
+        passed as an empty string.
+
+  - The optional attribute `args` specifies command-line arguments to be
+    passed to the builder. It should be a list.
+
+  - The optional attribute `outputs` specifies a list of symbolic
+    outputs of the derivation. By default, a derivation produces a
+    single output path, denoted as `out`. However, derivations can
+    produce multiple output paths. This is useful because it allows
+    outputs to be downloaded or garbage-collected separately. For
+    instance, imagine a library package that provides a dynamic library,
+    header files, and documentation. A program that links against the
+    library doesn’t need the header files and documentation at runtime,
+    and it doesn’t need the documentation at build time. Thus, the
+    library package could specify:
+    
+    ```nix
+    outputs = [ "lib" "headers" "doc" ];
+    ```
+    
+    This will cause Nix to pass environment variables `lib`, `headers`
+    and `doc` to the builder containing the intended store paths of each
+    output. The builder would typically do something like
+    
+    ```bash
+    ./configure \
+      --libdir=$lib/lib \
+      --includedir=$headers/include \
+      --docdir=$doc/share/doc
+    ```
+    
+    for an Autoconf-style package. You can refer to each output of a
+    derivation by selecting it as an attribute, e.g.
+    
+    ```nix
+    buildInputs = [ pkg.lib pkg.headers ];
+    ```
+    
+    The first element of `outputs` determines the *default output*.
+    Thus, you could also write
+    
+    ```nix
+    buildInputs = [ pkg pkg.headers ];
+    ```
+    
+    since `pkg` is equivalent to `pkg.lib`.
+
+The function `mkDerivation` in the Nixpkgs standard environment is a
+wrapper around `derivation` that adds a default value for `system` and
+always uses Bash as the builder, to which the supplied builder is passed
+as a command-line argument. See the Nixpkgs manual for details.
+
+The builder is executed as follows:
+
+  - A temporary directory is created under the directory specified by
+    `TMPDIR` (default `/tmp`) where the build will take place. The
+    current directory is changed to this directory.
+
+  - The environment is cleared and set to the derivation attributes, as
+    specified above.
+
+  - In addition, the following variables are set:
+    
+      - `NIX_BUILD_TOP` contains the path of the temporary directory for
+        this build.
+    
+      - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
+        temporary directory. This is to prevent the builder from
+        accidentally writing temporary files anywhere else. Doing so
+        might cause interference by other processes.
+    
+      - `PATH` is set to `/path-not-set` to prevent shells from
+        initialising it to their built-in default value.
+    
+      - `HOME` is set to `/homeless-shelter` to prevent programs from
+        using `/etc/passwd` or the like to find the user's home
+        directory, which could cause impurity. Usually, when `HOME` is
+        set, it is used as the location of the home directory, even if
+        it points to a non-existent path.
+    
+      - `NIX_STORE` is set to the path of the top-level Nix store
+        directory (typically, `/nix/store`).
+    
+      - For each output declared in `outputs`, the corresponding
+        environment variable is set to point to the intended path in the
+        Nix store for that output. Each output path is a concatenation
+        of the cryptographic hash of all build inputs, the `name`
+        attribute and the output name. (The output name is omitted if
+        it’s `out`.)
+
+  - If an output path already exists, it is removed. Also, locks are
+    acquired to prevent multiple Nix instances from performing the same
+    build at the same time.
+
+  - A log of the combined standard output and error is written to
+    `/nix/var/log/nix`.
+
+  - The builder is executed with the arguments specified by the
+    attribute `args`. If it exits with exit code 0, it is considered to
+    have succeeded.
+
+  - The temporary directory is removed (unless the `-K` option was
+    specified).
+
+  - If the build was successful, Nix scans each output path for
+    references to input paths by looking for the hash parts of the input
+    paths. Since these are potential runtime dependencies, Nix registers
+    them as dependencies of the output paths.
+
+  - After the build, Nix sets the last-modified timestamp on all files
+    in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
+    the default group, and sets the mode of the file to 0444 or 0555
+    (i.e., read-only, with execute permission enabled if the file was
+    originally executable). Note that possible `setuid` and `setgid`
+    bits are cleared. Setuid and setgid programs are not currently
+    supported by Nix. This is because the Nix archives used in
+    deployment have no concept of ownership information, and because it
+    makes the build result dependent on the user performing the build.
diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
new file mode 100644
index 000000000..c4b3abf75
--- /dev/null
+++ b/doc/manual/src/language/index.md
@@ -0,0 +1,13 @@
+# Nix Language
+
+The Nix language is a pure, lazy, functional language. Purity
+means that operations in the language don't have side-effects (for
+instance, there is no variable assignment). Laziness means that
+arguments to functions are evaluated only when they are needed.
+Functional means that functions are “normal” values that can be passed
+around and manipulated in interesting ways. The language is not a
+full-featured, general purpose language. Its main job is to describe
+packages, compositions of packages, and the variability within packages.
+
+This section presents the various features of the language.
+
diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
new file mode 100644
index 000000000..32398189d
--- /dev/null
+++ b/doc/manual/src/language/operators.md
@@ -0,0 +1,28 @@
+# Operators
+
+The table below lists the operators in the Nix language, in
+order of precedence (from strongest to weakest binding).
+
+| Name                     | Syntax                              | Associativity | Description                                                                                                                                                                                                                   | Precedence |
+| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Select                   | *e* `.` *attrpath* \[ `or` *def* \] | none          | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | 1          |
+| Application              | *e1* *e2*                           | left          | Call function *e1* with argument *e2*.                                                                                                                                                                                        | 2          |
+| Arithmetic Negation      | `-` *e*                             | none          | Arithmetic negation.                                                                                                                                                                                                          | 3          |
+| Has Attribute            | *e* `?` *attrpath*                  | none          | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.                                                                                                                                  | 4          |
+| List Concatenation       | *e1* `++` *e2*                      | right         | List concatenation.                                                                                                                                                                                                           | 5          |
+| Multiplication           | *e1* `*` *e2*,                      | left          | Arithmetic multiplication.                                                                                                                                                                                                    | 6          |
+| Division                 | *e1* `/` *e2*                       | left          | Arithmetic division.                                                                                                                                                                                                          | 6          |
+| Addition                 | *e1* `+` *e2*                       | left          | Arithmetic addition.                                                                                                                                                                                                          | 7          |
+| Subtraction              | *e1* `-` *e2*                       | left          | Arithmetic subtraction.                                                                                                                                                                                                       | 7          |
+| String Concatenation     | *string1* `+` *string2*             | left          | String concatenation.                                                                                                                                                                                                         | 7          |
+| Not                      | `!` *e*                             | none          | Boolean negation.                                                                                                                                                                                                             | 8          |
+| Update                   | *e1* `//` *e2*                      | right         | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).                                                                           | 9          |
+| Less Than                | *e1* `<` *e2*,                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
+| Less Than or Equal To    | *e1* `<=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
+| Greater Than             | *e1* `>` *e2*                       | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
+| Greater Than or Equal To | *e1* `>=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
+| Equality                 | *e1* `==` *e2*                      | none          | Equality.                                                                                                                                                                                                                     | 11         |
+| Inequality               | *e1* `!=` *e2*                      | none          | Inequality.                                                                                                                                                                                                                   | 11         |
+| Logical AND              | *e1* `&&` *e2*                      | left          | Logical AND.                                                                                                                                                                                                                  | 12         |
+| Logical OR               | *e1* <code>&#124;&#124;</code> *e2* | left          | Logical OR.                                                                                                                                                                                                                   | 13         |
+| Logical Implication      | *e1* `->` *e2*                      | none          | Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).                                                                                                                                                                            | 14         |
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
new file mode 100644
index 000000000..f09400d02
--- /dev/null
+++ b/doc/manual/src/language/values.md
@@ -0,0 +1,261 @@
+# Data Types
+
+## Primitives
+
+- <a id="type-string" href="#type-string">String</a>
+
+  *Strings* can be written in three ways.
+
+  The most common way is to enclose the string between double quotes,
+  e.g., `"foo bar"`. Strings can span multiple lines. The special
+  characters `"` and `\` and the character sequence `${` must be
+  escaped by prefixing them with a backslash (`\`). Newlines, carriage
+  returns and tabs can be written as `\n`, `\r` and `\t`,
+  respectively.
+
+  You can include the result of an expression into a string by
+  enclosing it in `${...}`, a feature known as *antiquotation*. The
+  enclosed expression must evaluate to something that can be coerced
+  into a string (meaning that it must be a string, a path, or a
+  derivation). For instance, rather than writing
+
+  ```nix
+  "--with-freetype2-library=" + freetype + "/lib"
+  ```
+
+  (where `freetype` is a derivation), you can instead write the more
+  natural
+
+  ```nix
+  "--with-freetype2-library=${freetype}/lib"
+  ```
+
+  The latter is automatically translated to the former. A more
+  complicated example (from the Nix expression for
+  [Qt](http://www.trolltech.com/products/qt)):
+
+  ```nix
+  configureFlags = "
+    -system-zlib -system-libpng -system-libjpeg
+    ${if openglSupport then "-dlopen-opengl
+      -L${mesa}/lib -I${mesa}/include
+      -L${libXmu}/lib -I${libXmu}/include" else ""}
+    ${if threadSupport then "-thread" else "-no-thread"}
+  ";
+  ```
+
+  Note that Nix expressions and strings can be arbitrarily nested; in
+  this case the outer string contains various antiquotations that
+  themselves contain strings (e.g., `"-thread"`), some of which in
+  turn contain expressions (e.g., `${mesa}`).
+
+  The second way to write string literals is as an *indented string*,
+  which is enclosed between pairs of *double single-quotes*, like so:
+
+  ```nix
+  ''
+    This is the first line.
+    This is the second line.
+      This is the third line.
+  ''
+  ```
+
+  This kind of string literal intelligently strips indentation from
+  the start of each line. To be precise, it strips from each line a
+  number of spaces equal to the minimal indentation of the string as a
+  whole (disregarding the indentation of empty lines). For instance,
+  the first and second line are indented two spaces, while the third
+  line is indented four spaces. Thus, two spaces are stripped from
+  each line, so the resulting string is
+
+  ```nix
+  "This is the first line.\nThis is the second line.\n  This is the third line.\n"
+  ```
+
+  Note that the whitespace and newline following the opening `''` is
+  ignored if there is no non-whitespace text on the initial line.
+
+  Antiquotation (`${expr}`) is supported in indented strings.
+
+  Since `${` and `''` have special meaning in indented strings, you
+  need a way to quote them. `$` can be escaped by prefixing it with
+  `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
+  by prefixing it with `'`, i.e., `'''`. `$` removes any special
+  meaning from the following `$`. Linefeed, carriage-return and tab
+  characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
+  escapes any other character.
+
+  Indented strings are primarily useful in that they allow multi-line
+  string literals to follow the indentation of the enclosing Nix
+  expression, and that less escaping is typically necessary for
+  strings representing languages such as shell scripts and
+  configuration files because `''` is much less common than `"`.
+  Example:
+
+  ```nix
+  stdenv.mkDerivation {
+    ...
+    postInstall =
+      ''
+        mkdir $out/bin $out/etc
+        cp foo $out/bin
+        echo "Hello World" > $out/etc/foo.conf
+        ${if enableBar then "cp bar $out/bin" else ""}
+      '';
+    ...
+  }
+  ```
+
+  Finally, as a convenience, *URIs* as defined in appendix B of
+  [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
+  is*, without quotes. For instance, the string
+  `"http://example.org/foo.tar.bz2"` can also be written as
+  `http://example.org/foo.tar.bz2`.
+
+- <a id="type-number" href="#type-number">Number</a>
+
+  Numbers, which can be *integers* (like `123`) or *floating point*
+  (like `123.43` or `.27e13`).
+
+  Numbers are type-compatible: pure integer operations will always
+  return integers, whereas any operation involving at least one
+  floating point number will have a floating point number as a result.
+
+- <a id="type-path" href="#type-path">Path</a>
+
+  *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
+  least one slash to be recognised as such. For instance, `builder.sh`
+  is not a path: it's parsed as an expression that selects the
+  attribute `sh` from the variable `builder`. If the file name is
+  relative, i.e., if it does not begin with a slash, it is made
+  absolute at parse time relative to the directory of the Nix
+  expression that contained it. For instance, if a Nix expression in
+  `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
+  is `/foo/xyzzy/fnord.nix`.
+
+  If the first component of a path is a `~`, it is interpreted as if
+  the rest of the path were relative to the user's home directory.
+  e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
+  whose home directory is `/home/edolstra`.
+
+  Paths can also be specified between angle brackets, e.g.
+  `<nixpkgs>`. This means that the directories listed in the
+  environment variable `NIX_PATH` will be searched for the given file
+  or directory name.
+
+  Antiquotation is supported in any paths except those in angle brackets.
+  `./${foo}-${bar}.nix` is a more convenient way of writing
+  `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
+  least one slash must appear *before* any antiquotations for this to be
+  recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
+  operation. `./a.${foo}/b.${bar}` is a path.
+
+- <a id="type-boolean" href="#type-boolean">Boolean</a>
+
+  *Booleans* with values `true` and `false`.
+
+- <a id="type-null" href="#type-null">Null</a>
+
+  The null value, denoted as `null`.
+
+## List
+
+Lists are formed by enclosing a whitespace-separated list of values
+between square brackets. For example,
+
+```nix
+[ 123 ./foo.nix "abc" (f { x = y; }) ]
+```
+
+defines a list of four elements, the last being the result of a call to
+the function `f`. Note that function calls have to be enclosed in
+parentheses. If they had been omitted, e.g.,
+
+```nix
+[ 123 ./foo.nix "abc" f { x = y; } ]
+```
+
+the result would be a list of five elements, the fourth one being a
+function and the fifth being a set.
+
+Note that lists are only lazy in values, and they are strict in length.
+
+## Attribute Set
+
+An attribute set is a collection of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
+
+Names and values are separated by an equal sign (`=`).
+Each value is an arbitrary expression terminated by a semicolon (`;`).
+
+Attributes can appear in any order.
+An attribute name may only occur once.
+
+Example:
+
+```nix
+{
+  x = 123;
+  text = "Hello";
+  y = f { bla = 456; };
+}
+```
+
+This defines a set with attributes named `x`, `text`, `y`.
+
+Attributes can be selected from a set using the `.` operator. For
+instance,
+
+```nix
+{ a = "Foo"; b = "Bar"; }.a
+```
+
+evaluates to `"Foo"`. It is possible to provide a default value in an
+attribute selection using the `or` keyword. For example,
+
+```nix
+{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"
+```
+
+will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
+
+You can use arbitrary double-quoted strings as attribute names:
+
+```nix
+{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
+```
+
+This will evaluate to `123` (Assuming `bar` is antiquotable). In the
+case where an attribute name is just a single antiquotation, the quotes
+can be dropped:
+
+```nix
+{ foo = 123; }.${bar} or 456
+```
+
+This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced
+to a string and `456` otherwise (again assuming `bar` is antiquotable).
+
+In the special case where an attribute name inside of a set declaration
+evaluates to `null` (which is normally an error, as `null` is not
+antiquotable), that attribute is simply not added to the set:
+
+```nix
+{ ${if foo then "bar" else null} = true; }
+```
+
+This will evaluate to `{}` if `foo` evaluates to `false`.
+
+A set that has a `__functor` attribute whose value is callable (i.e. is
+itself a function or a set with a `__functor` attribute whose value is
+callable) can be applied as if it were a function, with the set itself
+passed in first , e.g.,
+
+```nix
+let add = { __functor = self: x: x + self.x; };
+    inc = add // { x = 1; };
+in inc 1
+```
+
+evaluates to `2`. This can be used to attach metadata to a function
+without the caller needing to treat it specially, or to implement a form
+of object-oriented programming, for example.
diff --git a/doc/manual/src/package-management/package-management.md b/doc/manual/src/package-management/package-management.md
index bd26a09ab..d528112e2 100644
--- a/doc/manual/src/package-management/package-management.md
+++ b/doc/manual/src/package-management/package-management.md
@@ -1,5 +1,4 @@
 This chapter discusses how to do package management with Nix, i.e.,
 how to obtain, install, upgrade, and erase packages. This is the
 “user’s” perspective of the Nix system — people who want to *create*
-packages should consult the [chapter on writing Nix
-expressions](../expressions/writing-nix-expressions.md).
+packages should consult the chapter on the [Nix language](../language/index.md).
-- 
cgit v1.2.3


From 523359d133ea8f048f69d8e8b3e5f1b674baf17a Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 24 Nov 2020 08:38:12 -0500
Subject: WIP: Document the design of Nix

The current docs are all "how to do things" and no "what is Nix" or "why
are things the way they are".

I see lots of misconception on the wider internet, and I also think we
would benefit from a "living document" to answer some questions people
currently turn to the thesis for.

I think a new section of the manual can address all these issues.
---
 doc/manual/src/SUMMARY.md.in           |  5 ++++
 doc/manual/src/design/design.md        |  5 ++++
 doc/manual/src/design/overview.md      | 13 ++++++++++
 doc/manual/src/design/store/entries.md | 46 ++++++++++++++++++++++++++++++++++
 doc/manual/src/design/store/paths.md   | 30 ++++++++++++++++++++++
 doc/manual/src/design/store/store.md   |  5 ++++
 6 files changed, 104 insertions(+)
 create mode 100644 doc/manual/src/design/design.md
 create mode 100644 doc/manual/src/design/overview.md
 create mode 100644 doc/manual/src/design/store/entries.md
 create mode 100644 doc/manual/src/design/store/paths.md
 create mode 100644 doc/manual/src/design/store/store.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index c8cb72fc0..c320bde3f 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -15,6 +15,11 @@
     - [Multi-User Mode](installation/multi-user.md)
   - [Environment Variables](installation/env-variables.md)
   - [Upgrading Nix](installation/upgrading.md)
+- [Design and Data Model](design/design.md)
+  - [Overview](design/overview.md)
+  - [The Store Layer](design/store/store.md)
+    - [Store Entries](design/store/entries.md)
+    - [Store Paths](design/store/paths.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/design/design.md b/doc/manual/src/design/design.md
new file mode 100644
index 000000000..7d4211764
--- /dev/null
+++ b/doc/manual/src/design/design.md
@@ -0,0 +1,5 @@
+# Design and Data Model
+
+Most of the manual is about how to use Nix.
+This chapter is about what Nix actually is.
+The hope is that it can serve as a reference for key concepts, and also shed light on why things are the way they are.
diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
new file mode 100644
index 000000000..05f4a70b2
--- /dev/null
+++ b/doc/manual/src/design/overview.md
@@ -0,0 +1,13 @@
+# Overview
+
+Nix is broken into layers that operate fairly independently.
+
+At the top is the *command line interface*, i.e. the argument parsing of the various Nix executables.
+
+Below that is the Nix *expression language*, in which packages and configurations are written.
+These are the layers which users interact with most.
+
+Below that is the *store layer*, Nix's machinery for presenting and files and fully elaborated build plans, and also executing those build plans.
+The store layer may not be as visible, but this is the heart of Nix.
+
+This chapter will start there and work up towards the more user-facing interfaces described in the rest of the manual.
diff --git a/doc/manual/src/design/store/entries.md b/doc/manual/src/design/store/entries.md
new file mode 100644
index 000000000..c16c98a36
--- /dev/null
+++ b/doc/manual/src/design/store/entries.md
@@ -0,0 +1,46 @@
+# Store Entries
+
+File system data in Nix is organized into *store entries*.
+A store entry is the combination of
+
+  - some file system data
+  - references to store entries
+
+## File system data
+
+Nix supports the a similar model of the file system as Git.
+Namely, every file system object falls into these three cases:
+
+ - File: arbitrary data
+
+ - Directory: mapping of names to child file system objects.
+   File children additionally have an executable flag.
+
+ - Symlink: may point anywhere.
+   In particular, Symlinks that do not point within the containing file system data or that of another store entry referenced by the containing store entry are allowed, but might not function as intended.
+
+A bare file as the "root" file system object is allowed.
+Note that there is no containing directory object to store its executable bit; it's deemed non-executable by default.
+
+## References
+
+Store entries can refer to both other store entries and themselves.
+
+Store references are normally calculated by scanning the file system data for store paths when a new store entry is created, but this isn't mandatory, as store entries are allowed to have references that don't correspond to contained store paths, and contained store paths that don't correspond to references.
+
+The references themselves need not be store paths per-se (this is an implementation detail of the store).
+But, like rendered store paths (see next section) in addition to identifying store entries they must also identify the store directory of the store(s) that contain those store entries.
+That said, all the references of the store entry must agree on a store dir.
+Also the store directory of the references must equal that of any store which contains the store entry doing the referencing.
+
+## Relocatability
+
+The two final restrictions of the previous section yield an alternative of view of the same information.
+Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least once reference.
+
+This corresponds to the observation that a store entry with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store entry without any references, i.e. thus without a store directory, can exist in any store.
+
+Lastly, this illustrates the purpose of tracking self references.
+Store entries without self-references or other references are relocatable, while store paths with self-references aren't.
+This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
+\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
new file mode 100644
index 000000000..1e4369625
--- /dev/null
+++ b/doc/manual/src/design/store/paths.md
@@ -0,0 +1,30 @@
+# Store Paths
+
+A store path is a pair of a 20-byte digest and a name.
+
+Historically it is the triple of those two and also the store directory, but the modern implementation's internal representation is just the pair.
+This change is because in the vast majority of cases, the store dir is fully determined by the context in which the store path occurs.
+
+## String representation
+
+A store path is rendered as the concatenation of
+
+  - the store directory
+
+  - a path-separator (`/`)
+
+  - the digest rendered as Base-32 (20 bytes becomes 32 bytes)
+
+  - a hyphen (`-`)
+
+  - the name
+
+Let's take the store path from the very beginning of this manual as an example:
+
+    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
+
+This parses like so:
+
+    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
+    ^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
+    store dir  digest                           name
diff --git a/doc/manual/src/design/store/store.md b/doc/manual/src/design/store/store.md
new file mode 100644
index 000000000..c2431f1c5
--- /dev/null
+++ b/doc/manual/src/design/store/store.md
@@ -0,0 +1,5 @@
+A Nix store is a collection of *store entries* referred to by *store paths*.
+Every store also has a "store directory path", which is a path prefix used for various purposes.
+
+There are many types of stores, but all of them at least respect this model.
+Some however offer additional functionality.
-- 
cgit v1.2.3


From a2b3160f2898c2009d458cc27d5e8ea925cf583b Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 24 Nov 2020 09:09:42 -0500
Subject: Briefly describe the digest of a store path

---
 doc/manual/src/design/store/paths.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
index 1e4369625..18ba27ecb 100644
--- a/doc/manual/src/design/store/paths.md
+++ b/doc/manual/src/design/store/paths.md
@@ -28,3 +28,24 @@ This parses like so:
     /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
     ^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
     store dir  digest                           name
+
+## The digest
+
+The calculation of the digest is quite complicated for historical reasons.
+Some of the details will be saved for later.
+
+> Historical note. The 20 byte restriction is because originally a digests were SHA-1 hashes.
+> This is no longer true, but longer hashes and other information is still boiled down to 20 bytes.
+
+Store paths are either content-addressed or "input-addressed".
+
+Content addressing means that the digest ultimately derives from referred store entry's file system data and references, and thus can be verified (if one knows how it was calculated).
+
+Input addressing means that the digest derives from how the store path was produced -- the "inputs" and plan that it was built from.
+Store paths of this sort can not be validated from the content of the store entry.
+Rather, the store entry might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
+The signature indicates that someone is vouching for the store entry really being the results of a plan with that digest.
+
+While metadata is included in the digest calculation explaining which method it was calculated by, this only serves to thwart pre-image attacks.
+That metadata is scrambled with everything else so that it is difficult to tell how a given store path was produced short of a brute-force search.
+In the parlance of referencing schemes, this means that store paths are not "self-describing".
-- 
cgit v1.2.3


From e64633f98f290cb571df72a667a0a267722fc397 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 24 Nov 2020 10:18:39 -0500
Subject: Flesh out TOC

---
 doc/manual/src/SUMMARY.md.in                    | 6 ++++++
 doc/manual/src/design/store/building.md         | 0
 doc/manual/src/design/store/drvs/ca.md          | 0
 doc/manual/src/design/store/drvs/drvs.md        | 0
 doc/manual/src/design/store/drvs/ia.md          | 0
 doc/manual/src/design/store/input-addressing.md | 1 +
 doc/manual/src/design/store/nar.md              | 1 +
 doc/manual/src/design/store/netry-ca.md         | 1 +
 8 files changed, 9 insertions(+)
 create mode 100644 doc/manual/src/design/store/building.md
 create mode 100644 doc/manual/src/design/store/drvs/ca.md
 create mode 100644 doc/manual/src/design/store/drvs/drvs.md
 create mode 100644 doc/manual/src/design/store/drvs/ia.md
 create mode 100644 doc/manual/src/design/store/input-addressing.md
 create mode 100644 doc/manual/src/design/store/nar.md
 create mode 100644 doc/manual/src/design/store/netry-ca.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index c320bde3f..8c4dbcb18 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -20,6 +20,12 @@
   - [The Store Layer](design/store/store.md)
     - [Store Entries](design/store/entries.md)
     - [Store Paths](design/store/paths.md)
+    - [Nix Archives](design/store/nar.md)
+    - [Content-Addressing Store Entries](design/store/entry-ca.md)
+    - [Derivations](design/store/drvs/drvs.md)
+      - [Input-Addressing](design/store/drvs/ia.md)
+      - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
+    - [Building](design/store/building.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/design/store/building.md b/doc/manual/src/design/store/building.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/manual/src/design/store/drvs/ca.md b/doc/manual/src/design/store/drvs/ca.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/manual/src/design/store/drvs/drvs.md b/doc/manual/src/design/store/drvs/drvs.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/manual/src/design/store/drvs/ia.md b/doc/manual/src/design/store/drvs/ia.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/manual/src/design/store/input-addressing.md b/doc/manual/src/design/store/input-addressing.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/design/store/input-addressing.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/design/store/nar.md b/doc/manual/src/design/store/nar.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/design/store/nar.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/design/store/netry-ca.md b/doc/manual/src/design/store/netry-ca.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/design/store/netry-ca.md
@@ -0,0 +1 @@
+TODO
-- 
cgit v1.2.3


From a210504bc7b67defe16fda97a6d2a844ecc9bd2b Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Mon, 21 Mar 2022 11:41:15 -0400
Subject: Apply suggestions from code review

---
 doc/manual/src/design/overview.md      |  2 +-
 doc/manual/src/design/store/entries.md | 24 ++++++++++++++++++------
 2 files changed, 19 insertions(+), 7 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 05f4a70b2..792cfefbf 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -10,4 +10,4 @@ These are the layers which users interact with most.
 Below that is the *store layer*, Nix's machinery for presenting and files and fully elaborated build plans, and also executing those build plans.
 The store layer may not be as visible, but this is the heart of Nix.
 
-This chapter will start there and work up towards the more user-facing interfaces described in the rest of the manual.
+This chapter describes Nix starting with that bottom store layer, then working its way up until it reaches the more user-facing interfaces described in the rest of the manual."
diff --git a/doc/manual/src/design/store/entries.md b/doc/manual/src/design/store/entries.md
index c16c98a36..2eb4bf90c 100644
--- a/doc/manual/src/design/store/entries.md
+++ b/doc/manual/src/design/store/entries.md
@@ -8,8 +8,8 @@ A store entry is the combination of
 
 ## File system data
 
-Nix supports the a similar model of the file system as Git.
-Namely, every file system object falls into these three cases:
+The nix store uses a simple filesystem model, similar to the one Git uses.
+In particular, every file system object falls into these three cases:
 
  - File: arbitrary data
 
@@ -20,13 +20,25 @@ Namely, every file system object falls into these three cases:
    In particular, Symlinks that do not point within the containing file system data or that of another store entry referenced by the containing store entry are allowed, but might not function as intended.
 
 A bare file as the "root" file system object is allowed.
-Note that there is no containing directory object to store its executable bit; it's deemed non-executable by default.
+Note that it cannot be executable, though.
+This is a consequence of the executable flags being part of the child entries of the directory, rather than the child files themselves.
+A root file has no parent directory; so there is no child entry about the root file, and therefore no executable flag for it.
+Without a flag saying which, whether root files are executable or non-executable by default must be decided by convention, and the choice of Nix (and git) is to make them non-executable.
 
 ## References
 
 Store entries can refer to both other store entries and themselves.
 
-Store references are normally calculated by scanning the file system data for store paths when a new store entry is created, but this isn't mandatory, as store entries are allowed to have references that don't correspond to contained store paths, and contained store paths that don't correspond to references.
+References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store entries.
+For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store entries by searching in all their files.   
+When we get to building in a future section, this process will be described in precise detail.
+
+However, scanning for references is not mandatory.
+Store entries are allowed to have official references that *don't* correspond to store paths contained in their contents,
+and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
+Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
+
+This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store entry, rather than try to recompute them on the fly by scanning their contents.
 
 The references themselves need not be store paths per-se (this is an implementation detail of the store).
 But, like rendered store paths (see next section) in addition to identifying store entries they must also identify the store directory of the store(s) that contain those store entries.
@@ -35,8 +47,8 @@ Also the store directory of the references must equal that of any store which co
 
 ## Relocatability
 
-The two final restrictions of the previous section yield an alternative of view of the same information.
-Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least once reference.
+The two final restrictions of the previous section yield an alternative view of the same information.
+Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least one reference.
 
 This corresponds to the observation that a store entry with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store entry without any references, i.e. thus without a store directory, can exist in any store.
 
-- 
cgit v1.2.3


From e3a0209a9e279a30ea9381743c77b2737e8ed95e Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 21 Mar 2022 12:35:01 -0400
Subject: Move the bits on relocating store entires to the end

They are too advanced for up front.
---
 doc/manual/src/SUMMARY.md.in                  |  1 +
 doc/manual/src/design/store/building.md       | 15 +++++++++++++++
 doc/manual/src/design/store/entries.md        | 17 -----------------
 doc/manual/src/design/store/relocatability.md | 15 +++++++++++++++
 4 files changed, 31 insertions(+), 17 deletions(-)
 create mode 100644 doc/manual/src/design/store/relocatability.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 8c4dbcb18..1e8b35483 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -26,6 +26,7 @@
       - [Input-Addressing](design/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
     - [Building](design/store/building.md)
+    - [Advanced Topic: store dir relocatability](design/store/relocatability.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/design/store/building.md b/doc/manual/src/design/store/building.md
index e69de29bb..5adccbc0b 100644
--- a/doc/manual/src/design/store/building.md
+++ b/doc/manual/src/design/store/building.md
@@ -0,0 +1,15 @@
+# Building
+
+## Scanning for references
+
+Before in the section on [store entries](../entries.md), we talked abstractly about scanning for references.
+Now we can make this concrete.
+
+After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store entries.
+There is a few steps of this, but let's start with the simple case of one input-addressed output first.
+
+\[Overview of things that need to happen.]
+
+For example, if Nix thinks `/nix/store/asdfasdfasdf-foo` and `/nix/store/qwerqwerqwer-bar` are paths the data might plausibly reference, Nix will scan all the contents of all files recursively for the "hash parts" `asdfasdfasdf`` and `qwerqwerqwer`.
+
+\[Explain why whitelist.]
diff --git a/doc/manual/src/design/store/entries.md b/doc/manual/src/design/store/entries.md
index 2eb4bf90c..74f429e78 100644
--- a/doc/manual/src/design/store/entries.md
+++ b/doc/manual/src/design/store/entries.md
@@ -39,20 +39,3 @@ and they are also allowed to *not* have references that *do* correspond to store
 Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
 
 This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store entry, rather than try to recompute them on the fly by scanning their contents.
-
-The references themselves need not be store paths per-se (this is an implementation detail of the store).
-But, like rendered store paths (see next section) in addition to identifying store entries they must also identify the store directory of the store(s) that contain those store entries.
-That said, all the references of the store entry must agree on a store dir.
-Also the store directory of the references must equal that of any store which contains the store entry doing the referencing.
-
-## Relocatability
-
-The two final restrictions of the previous section yield an alternative view of the same information.
-Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least one reference.
-
-This corresponds to the observation that a store entry with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store entry without any references, i.e. thus without a store directory, can exist in any store.
-
-Lastly, this illustrates the purpose of tracking self references.
-Store entries without self-references or other references are relocatable, while store paths with self-references aren't.
-This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
-\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
diff --git a/doc/manual/src/design/store/relocatability.md b/doc/manual/src/design/store/relocatability.md
new file mode 100644
index 000000000..04b581459
--- /dev/null
+++ b/doc/manual/src/design/store/relocatability.md
@@ -0,0 +1,15 @@
+## Advanced Topic: store entry relocatability
+
+Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissable to relocate a store entry to a store with a different mount point.
+
+Recall from the section on [store paths](./store-paths.md), concrete store paths look like `<store-dir>/<hash>-<name>`.
+
+~~The two final restrictions of the previous section yield an alternative view of the same information.~~
+Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least one reference.
+
+This corresponds to the observation that a store entry with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store entry without any references, i.e. thus without a store directory, can exist in any store.
+
+Lastly, this illustrates the purpose of tracking self references.
+Store entries without self-references or other references are relocatable, while store paths with self-references aren't.
+This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
+\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
-- 
cgit v1.2.3


From 678d75baeaca049042330e543f610d630e8c43b5 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 21 Mar 2022 13:13:55 -0400
Subject: Start on the derivations section

---
 doc/manual/src/SUMMARY.md.in             |  2 +-
 doc/manual/src/design/store/drvs/drvs.md | 59 ++++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 1e8b35483..a0efdb9cd 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -26,7 +26,7 @@
       - [Input-Addressing](design/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
     - [Building](design/store/building.md)
-    - [Advanced Topic: store dir relocatability](design/store/relocatability.md)
+    - [Advanced Topic: store entry relocatability](design/store/relocatability.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/design/store/drvs/drvs.md b/doc/manual/src/design/store/drvs/drvs.md
index e69de29bb..cedb05985 100644
--- a/doc/manual/src/design/store/drvs/drvs.md
+++ b/doc/manual/src/design/store/drvs/drvs.md
@@ -0,0 +1,59 @@
+# Derivations
+
+Derivations are recipes to create store entries.
+
+Derivations are the heart of Nix.
+Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
+This is where Nix comes in.
+
+Derivations produce data by running arbitrary commands, like Make or Ninja rules.
+Unlike those systems, derivations do not produce arbitrary files, but only specific store entries.
+They cannot modify the store in any way, other than creating those store entries.
+This rigid specification of what they do is what allows Nix's caching to be so simple and yet robust.
+
+Based on the above, we can conceptually break derivations down into 3 parts:
+
+1. What command will be run?
+
+2. What existing store entries are needed as inputs?
+
+3. What store entries will be produced as outputs?
+
+## What command will be run?
+
+The original core of Nix was very simple about this, in the mold of traditional Unix.
+Commands consist of 3 parts:
+
+1. Path to executable
+
+2. Arguments (Excecpt for `argv[0]`, which is taken from the path in the usual way)
+
+3. Environment variables.
+
+## What existing store entries are needed as inputs?
+
+The previous sub-section begs the question "how can we be sure the path to the executable points to what we think it does?"
+It's a good questions!
+
+## What store entries will be produced as outputs?
+
+## Extra extensions
+
+### `__structuredAttrs`
+
+Historically speaking, most users of Nix made GNU Bash with a script the command run, regardless of what they were doing.
+Bash variable are automatically created from env vars, but bash also supports array and string-keyed map variables in addition to string variables.
+People also usually create derivations using language which also support these richer data types.
+It was thus desired a way to get this data from the language "planning" the derivation to language to bash, the language evaluated at "run time".
+
+`__structuredAttrs` does this by smuggling inside the core derivation format a map of named richer data.
+At run time, this becomes two things:
+
+1. A JSON file containing that map.
+2. A bash script setting those variables.
+
+The bash command can be passed a script which will "source" that Nix-created bash script, setting those variables with the richer data.
+The outer script can then do whatever it likes with those richer variables as input.
+
+However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers.
+We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer.
-- 
cgit v1.2.3


From f5386d7059ad2c63b32356082d1f6ecacfc1e93b Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 21 Mar 2022 13:15:35 -0400
Subject: Fix stub file's name

---
 doc/manual/src/design/store/entry-ca.md | 1 +
 doc/manual/src/design/store/netry-ca.md | 1 -
 2 files changed, 1 insertion(+), 1 deletion(-)
 create mode 100644 doc/manual/src/design/store/entry-ca.md
 delete mode 100644 doc/manual/src/design/store/netry-ca.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/entry-ca.md b/doc/manual/src/design/store/entry-ca.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/design/store/entry-ca.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/design/store/netry-ca.md b/doc/manual/src/design/store/netry-ca.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/design/store/netry-ca.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
-- 
cgit v1.2.3


From a04340f9a1ce3c107b21a11395b4a2348fd19571 Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Tue, 22 Mar 2022 10:55:30 -0400
Subject: Update doc/manual/src/design/overview.md

Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
---
 doc/manual/src/design/overview.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 792cfefbf..7790e701e 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -7,7 +7,8 @@ At the top is the *command line interface*, i.e. the argument parsing of the var
 Below that is the Nix *expression language*, in which packages and configurations are written.
 These are the layers which users interact with most.
 
-Below that is the *store layer*, Nix's machinery for presenting and files and fully elaborated build plans, and also executing those build plans.
+Below that is the *store layer*, Nix' machinery to represent tracked files, dependencies, and fully elaborated build plans.
+It is also used for executing those build plans.
 The store layer may not be as visible, but this is the heart of Nix.
 
 This chapter describes Nix starting with that bottom store layer, then working its way up until it reaches the more user-facing interfaces described in the rest of the manual."
-- 
cgit v1.2.3


From 75c5191a1f8cf70a11098e89ed33edc203f52dab Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Tue, 22 Mar 2022 11:04:55 -0400
Subject: Update doc/manual/src/design/overview.md

Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
---
 doc/manual/src/design/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 7790e701e..bd3d935e6 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -1,6 +1,6 @@
 # Overview
 
-Nix is broken into layers that operate fairly independently.
+Nix consists of layers that operate fairly independently.
 
 At the top is the *command line interface*, i.e. the argument parsing of the various Nix executables.
 
-- 
cgit v1.2.3


From cdb0bf3b65172fd0e366d44f17392b4261c3d925 Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Tue, 22 Mar 2022 11:15:56 -0400
Subject: Update doc/manual/src/design/overview.md

Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
---
 doc/manual/src/design/overview.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index bd3d935e6..2d3e9226b 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -5,7 +5,8 @@ Nix consists of layers that operate fairly independently.
 At the top is the *command line interface*, i.e. the argument parsing of the various Nix executables.
 
 Below that is the Nix *expression language*, in which packages and configurations are written.
-These are the layers which users interact with most.
+
+The command line and expression language are what users interact with most.
 
 Below that is the *store layer*, Nix' machinery to represent tracked files, dependencies, and fully elaborated build plans.
 It is also used for executing those build plans.
-- 
cgit v1.2.3


From e308602fdfabf0ff1f0cd95baf1d90ba54a02281 Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Fri, 1 Apr 2022 20:48:03 -0400
Subject: Update doc/manual/src/design/store/drvs/drvs.md

Co-authored-by: Matthieu Coudron <teto@users.noreply.github.com>
---
 doc/manual/src/design/store/drvs/drvs.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/drvs/drvs.md b/doc/manual/src/design/store/drvs/drvs.md
index cedb05985..98e95809b 100644
--- a/doc/manual/src/design/store/drvs/drvs.md
+++ b/doc/manual/src/design/store/drvs/drvs.md
@@ -26,7 +26,7 @@ Commands consist of 3 parts:
 
 1. Path to executable
 
-2. Arguments (Excecpt for `argv[0]`, which is taken from the path in the usual way)
+2. Arguments (Except for `argv[0]`, which is taken from the path in the usual way)
 
 3. Environment variables.
 
-- 
cgit v1.2.3


From 4e2d5ae2027a19ab12d6d024cdf5125c3200a7a1 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 21:53:39 -0400
Subject: doc: Store entry -> store object

This matches the terminology in Eelco's thesis.
---
 doc/manual/src/SUMMARY.md.in                  |  6 +++---
 doc/manual/src/design/overview.md             |  2 +-
 doc/manual/src/design/store/building.md       |  4 ++--
 doc/manual/src/design/store/drvs/drvs.md      | 14 +++++++-------
 doc/manual/src/design/store/entries.md        | 20 ++++++++++----------
 doc/manual/src/design/store/paths.md          |  8 ++++----
 doc/manual/src/design/store/relocatability.md | 10 +++++-----
 doc/manual/src/design/store/store.md          |  2 +-
 8 files changed, 33 insertions(+), 33 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index a0efdb9cd..5c4cfc920 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -18,15 +18,15 @@
 - [Design and Data Model](design/design.md)
   - [Overview](design/overview.md)
   - [The Store Layer](design/store/store.md)
-    - [Store Entries](design/store/entries.md)
+    - [Store Objects](design/store/entries.md)
     - [Store Paths](design/store/paths.md)
     - [Nix Archives](design/store/nar.md)
-    - [Content-Addressing Store Entries](design/store/entry-ca.md)
+    - [Content-Addressing Store Objects](design/store/entry-ca.md)
     - [Derivations](design/store/drvs/drvs.md)
       - [Input-Addressing](design/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
     - [Building](design/store/building.md)
-    - [Advanced Topic: store entry relocatability](design/store/relocatability.md)
+    - [Advanced Topic: store object relocatability](design/store/relocatability.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 2d3e9226b..9329f2ad7 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -2,7 +2,7 @@
 
 Nix consists of layers that operate fairly independently.
 
-At the top is the *command line interface*, i.e. the argument parsing of the various Nix executables.
+At the top is the *command line interface*.
 
 Below that is the Nix *expression language*, in which packages and configurations are written.
 
diff --git a/doc/manual/src/design/store/building.md b/doc/manual/src/design/store/building.md
index 5adccbc0b..f97b74952 100644
--- a/doc/manual/src/design/store/building.md
+++ b/doc/manual/src/design/store/building.md
@@ -2,10 +2,10 @@
 
 ## Scanning for references
 
-Before in the section on [store entries](../entries.md), we talked abstractly about scanning for references.
+Before in the section on [store objects](../entries.md), we talked abstractly about scanning for references.
 Now we can make this concrete.
 
-After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store entries.
+After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
 There is a few steps of this, but let's start with the simple case of one input-addressed output first.
 
 \[Overview of things that need to happen.]
diff --git a/doc/manual/src/design/store/drvs/drvs.md b/doc/manual/src/design/store/drvs/drvs.md
index 98e95809b..766a7b47f 100644
--- a/doc/manual/src/design/store/drvs/drvs.md
+++ b/doc/manual/src/design/store/drvs/drvs.md
@@ -1,23 +1,23 @@
 # Derivations
 
-Derivations are recipes to create store entries.
+Derivations are recipes to create store objects.
 
 Derivations are the heart of Nix.
 Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
 This is where Nix comes in.
 
 Derivations produce data by running arbitrary commands, like Make or Ninja rules.
-Unlike those systems, derivations do not produce arbitrary files, but only specific store entries.
-They cannot modify the store in any way, other than creating those store entries.
+Unlike those systems, derivations do not produce arbitrary files, but only specific store objects.
+They cannot modify the store in any way, other than creating those store objects.
 This rigid specification of what they do is what allows Nix's caching to be so simple and yet robust.
 
 Based on the above, we can conceptually break derivations down into 3 parts:
 
 1. What command will be run?
 
-2. What existing store entries are needed as inputs?
+2. What existing store objects are needed as inputs?
 
-3. What store entries will be produced as outputs?
+3. What store objects will be produced as outputs?
 
 ## What command will be run?
 
@@ -30,12 +30,12 @@ Commands consist of 3 parts:
 
 3. Environment variables.
 
-## What existing store entries are needed as inputs?
+## What existing store objects are needed as inputs?
 
 The previous sub-section begs the question "how can we be sure the path to the executable points to what we think it does?"
 It's a good questions!
 
-## What store entries will be produced as outputs?
+## What store objects will be produced as outputs?
 
 ## Extra extensions
 
diff --git a/doc/manual/src/design/store/entries.md b/doc/manual/src/design/store/entries.md
index 74f429e78..ddfefa166 100644
--- a/doc/manual/src/design/store/entries.md
+++ b/doc/manual/src/design/store/entries.md
@@ -1,10 +1,10 @@
-# Store Entries
+# Store Objects
 
-File system data in Nix is organized into *store entries*.
-A store entry is the combination of
+File system data in Nix is organized into *store objects*.
+A store object is the combination of
 
   - some file system data
-  - references to store entries
+  - references to store objects
 
 ## File system data
 
@@ -17,7 +17,7 @@ In particular, every file system object falls into these three cases:
    File children additionally have an executable flag.
 
  - Symlink: may point anywhere.
-   In particular, Symlinks that do not point within the containing file system data or that of another store entry referenced by the containing store entry are allowed, but might not function as intended.
+   In particular, Symlinks that do not point within the containing file system data or that of another store object referenced by the containing store object are allowed, but might not function as intended.
 
 A bare file as the "root" file system object is allowed.
 Note that it cannot be executable, though.
@@ -27,15 +27,15 @@ Without a flag saying which, whether root files are executable or non-executable
 
 ## References
 
-Store entries can refer to both other store entries and themselves.
+Store objects can refer to both other store objects and themselves.
 
-References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store entries.
-For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store entries by searching in all their files.   
+References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store objects.
+For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.   
 When we get to building in a future section, this process will be described in precise detail.
 
 However, scanning for references is not mandatory.
-Store entries are allowed to have official references that *don't* correspond to store paths contained in their contents,
+Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
 and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
 Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
 
-This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store entry, rather than try to recompute them on the fly by scanning their contents.
+This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
index 18ba27ecb..d7d2ef960 100644
--- a/doc/manual/src/design/store/paths.md
+++ b/doc/manual/src/design/store/paths.md
@@ -39,12 +39,12 @@ Some of the details will be saved for later.
 
 Store paths are either content-addressed or "input-addressed".
 
-Content addressing means that the digest ultimately derives from referred store entry's file system data and references, and thus can be verified (if one knows how it was calculated).
+Content addressing means that the digest ultimately derives from referred store object's file system data and references, and thus can be verified (if one knows how it was calculated).
 
 Input addressing means that the digest derives from how the store path was produced -- the "inputs" and plan that it was built from.
-Store paths of this sort can not be validated from the content of the store entry.
-Rather, the store entry might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
-The signature indicates that someone is vouching for the store entry really being the results of a plan with that digest.
+Store paths of this sort can not be validated from the content of the store object.
+Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
+The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
 
 While metadata is included in the digest calculation explaining which method it was calculated by, this only serves to thwart pre-image attacks.
 That metadata is scrambled with everything else so that it is difficult to tell how a given store path was produced short of a brute-force search.
diff --git a/doc/manual/src/design/store/relocatability.md b/doc/manual/src/design/store/relocatability.md
index 04b581459..5cdbe9486 100644
--- a/doc/manual/src/design/store/relocatability.md
+++ b/doc/manual/src/design/store/relocatability.md
@@ -1,15 +1,15 @@
-## Advanced Topic: store entry relocatability
+## Advanced Topic: store object relocatability
 
-Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissable to relocate a store entry to a store with a different mount point.
+Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissable to relocate a store object to a store with a different mount point.
 
 Recall from the section on [store paths](./store-paths.md), concrete store paths look like `<store-dir>/<hash>-<name>`.
 
 ~~The two final restrictions of the previous section yield an alternative view of the same information.~~
-Rather than associating store dirs with the references, we can say a store entry itself has a store dir if and only if it has at least one reference.
+Rather than associating store dirs with the references, we can say a store object itself has a store dir if and only if it has at least one reference.
 
-This corresponds to the observation that a store entry with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store entry without any references, i.e. thus without a store directory, can exist in any store.
+This corresponds to the observation that a store object with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store object without any references, i.e. thus without a store directory, can exist in any store.
 
 Lastly, this illustrates the purpose of tracking self references.
-Store entries without self-references or other references are relocatable, while store paths with self-references aren't.
+Store objects without self-references or other references are relocatable, while store paths with self-references aren't.
 This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
 \[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
diff --git a/doc/manual/src/design/store/store.md b/doc/manual/src/design/store/store.md
index c2431f1c5..e91f0f6e4 100644
--- a/doc/manual/src/design/store/store.md
+++ b/doc/manual/src/design/store/store.md
@@ -1,4 +1,4 @@
-A Nix store is a collection of *store entries* referred to by *store paths*.
+A Nix store is a collection of *store objects* referred to by *store paths*.
 Every store also has a "store directory path", which is a path prefix used for various purposes.
 
 There are many types of stores, but all of them at least respect this model.
-- 
cgit v1.2.3


From 838ba26fda23649545cc61a274e20076a2e27892 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 21:57:10 -0400
Subject: Rename files after store entry -> store object rename

---
 doc/manual/src/SUMMARY.md.in             |  4 ++--
 doc/manual/src/design/store/building.md  |  2 +-
 doc/manual/src/design/store/entries.md   | 41 --------------------------------
 doc/manual/src/design/store/entry-ca.md  |  1 -
 doc/manual/src/design/store/object-ca.md |  1 +
 doc/manual/src/design/store/objects.md   | 41 ++++++++++++++++++++++++++++++++
 6 files changed, 45 insertions(+), 45 deletions(-)
 delete mode 100644 doc/manual/src/design/store/entries.md
 delete mode 100644 doc/manual/src/design/store/entry-ca.md
 create mode 100644 doc/manual/src/design/store/object-ca.md
 create mode 100644 doc/manual/src/design/store/objects.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 5c4cfc920..323a569d1 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -18,10 +18,10 @@
 - [Design and Data Model](design/design.md)
   - [Overview](design/overview.md)
   - [The Store Layer](design/store/store.md)
-    - [Store Objects](design/store/entries.md)
+    - [Store Objects](design/store/objects.md)
     - [Store Paths](design/store/paths.md)
     - [Nix Archives](design/store/nar.md)
-    - [Content-Addressing Store Objects](design/store/entry-ca.md)
+    - [Content-Addressing Store Objects](design/store/object-ca.md)
     - [Derivations](design/store/drvs/drvs.md)
       - [Input-Addressing](design/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
diff --git a/doc/manual/src/design/store/building.md b/doc/manual/src/design/store/building.md
index f97b74952..f4f2649a3 100644
--- a/doc/manual/src/design/store/building.md
+++ b/doc/manual/src/design/store/building.md
@@ -2,7 +2,7 @@
 
 ## Scanning for references
 
-Before in the section on [store objects](../entries.md), we talked abstractly about scanning for references.
+Before in the section on [store objects](../objects.md), we talked abstractly about scanning for references.
 Now we can make this concrete.
 
 After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
diff --git a/doc/manual/src/design/store/entries.md b/doc/manual/src/design/store/entries.md
deleted file mode 100644
index ddfefa166..000000000
--- a/doc/manual/src/design/store/entries.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Store Objects
-
-File system data in Nix is organized into *store objects*.
-A store object is the combination of
-
-  - some file system data
-  - references to store objects
-
-## File system data
-
-The nix store uses a simple filesystem model, similar to the one Git uses.
-In particular, every file system object falls into these three cases:
-
- - File: arbitrary data
-
- - Directory: mapping of names to child file system objects.
-   File children additionally have an executable flag.
-
- - Symlink: may point anywhere.
-   In particular, Symlinks that do not point within the containing file system data or that of another store object referenced by the containing store object are allowed, but might not function as intended.
-
-A bare file as the "root" file system object is allowed.
-Note that it cannot be executable, though.
-This is a consequence of the executable flags being part of the child entries of the directory, rather than the child files themselves.
-A root file has no parent directory; so there is no child entry about the root file, and therefore no executable flag for it.
-Without a flag saying which, whether root files are executable or non-executable by default must be decided by convention, and the choice of Nix (and git) is to make them non-executable.
-
-## References
-
-Store objects can refer to both other store objects and themselves.
-
-References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store objects.
-For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.   
-When we get to building in a future section, this process will be described in precise detail.
-
-However, scanning for references is not mandatory.
-Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
-and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
-Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
-
-This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
diff --git a/doc/manual/src/design/store/entry-ca.md b/doc/manual/src/design/store/entry-ca.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/design/store/entry-ca.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
diff --git a/doc/manual/src/design/store/object-ca.md b/doc/manual/src/design/store/object-ca.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/design/store/object-ca.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
new file mode 100644
index 000000000..ddfefa166
--- /dev/null
+++ b/doc/manual/src/design/store/objects.md
@@ -0,0 +1,41 @@
+# Store Objects
+
+File system data in Nix is organized into *store objects*.
+A store object is the combination of
+
+  - some file system data
+  - references to store objects
+
+## File system data
+
+The nix store uses a simple filesystem model, similar to the one Git uses.
+In particular, every file system object falls into these three cases:
+
+ - File: arbitrary data
+
+ - Directory: mapping of names to child file system objects.
+   File children additionally have an executable flag.
+
+ - Symlink: may point anywhere.
+   In particular, Symlinks that do not point within the containing file system data or that of another store object referenced by the containing store object are allowed, but might not function as intended.
+
+A bare file as the "root" file system object is allowed.
+Note that it cannot be executable, though.
+This is a consequence of the executable flags being part of the child entries of the directory, rather than the child files themselves.
+A root file has no parent directory; so there is no child entry about the root file, and therefore no executable flag for it.
+Without a flag saying which, whether root files are executable or non-executable by default must be decided by convention, and the choice of Nix (and git) is to make them non-executable.
+
+## References
+
+Store objects can refer to both other store objects and themselves.
+
+References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store objects.
+For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.   
+When we get to building in a future section, this process will be described in precise detail.
+
+However, scanning for references is not mandatory.
+Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
+and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
+Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
+
+This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
-- 
cgit v1.2.3


From 1bbad62c7d5f3b0d18c3fdb5a8e947ae5232139f Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 22:02:21 -0400
Subject: doc: File system data -> file system object, to match Nix

---
 doc/manual/src/design/store/objects.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
index ddfefa166..8783a1648 100644
--- a/doc/manual/src/design/store/objects.md
+++ b/doc/manual/src/design/store/objects.md
@@ -3,10 +3,10 @@
 File system data in Nix is organized into *store objects*.
 A store object is the combination of
 
-  - some file system data
+  - A (root) file system object
   - references to store objects
 
-## File system data
+## File system objects
 
 The nix store uses a simple filesystem model, similar to the one Git uses.
 In particular, every file system object falls into these three cases:
@@ -17,7 +17,7 @@ In particular, every file system object falls into these three cases:
    File children additionally have an executable flag.
 
  - Symlink: may point anywhere.
-   In particular, Symlinks that do not point within the containing file system data or that of another store object referenced by the containing store object are allowed, but might not function as intended.
+   In particular, Symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
 
 A bare file as the "root" file system object is allowed.
 Note that it cannot be executable, though.
@@ -29,7 +29,7 @@ Without a flag saying which, whether root files are executable or non-executable
 
 Store objects can refer to both other store objects and themselves.
 
-References are normally calculated by scanning the file system data for store paths (which we describe in the next section) referring to store objects.
+References are normally calculated by scanning the rooted file system objects for store paths (which we describe in the next section) referring to store objects.
 For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.   
 When we get to building in a future section, this process will be described in precise detail.
 
-- 
cgit v1.2.3


From 5f4d2ac091342c26d1a3f447961932139ed568b5 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 22:21:29 -0400
Subject: Improve store object section

In particular, Nix is *not* like Git, so that needs to be fixed.
---
 doc/manual/src/design/store/objects.md | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
index 8783a1648..2c2ed2bdb 100644
--- a/doc/manual/src/design/store/objects.md
+++ b/doc/manual/src/design/store/objects.md
@@ -1,34 +1,46 @@
 # Store Objects
 
 File system data in Nix is organized into *store objects*.
-A store object is the combination of
+A store object is the pair of
 
   - A (root) file system object
-  - references to store objects
+  - A set of references to store objects
 
 ## File system objects
 
-The nix store uses a simple filesystem model, similar to the one Git uses.
+The nix store uses a simple filesystem model.
 In particular, every file system object falls into these three cases:
 
- - File: arbitrary data
+ - File: an executable flag, and arbitrary data
 
  - Directory: mapping of names to child file system objects.
-   File children additionally have an executable flag.
 
  - Symlink: may point anywhere.
+
    In particular, Symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
 
-A bare file as the "root" file system object is allowed.
-Note that it cannot be executable, though.
-This is a consequence of the executable flags being part of the child entries of the directory, rather than the child files themselves.
-A root file has no parent directory; so there is no child entry about the root file, and therefore no executable flag for it.
-Without a flag saying which, whether root files are executable or non-executable by default must be decided by convention, and the choice of Nix (and git) is to make them non-executable.
+A bare file or symlink as the "root" file system object is allowed.
+
+### Comparison with Git
+
+This is close to Git's model, but with one crucial difference:
+Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
+
+So long as the root object is a directory, the representations are isomorphic.
+There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
+
+However, if the root object is a file, there is loss of fidelity.
+Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
+
+Git's model matches Unix tradition, but Nix's model is more natural.
 
 ## References
 
 Store objects can refer to both other store objects and themselves.
 
+Self-reference may seem pointless, but tracking them is in fact useful.
+We can best explain why later after more concepts have been established.
+
 References are normally calculated by scanning the rooted file system objects for store paths (which we describe in the next section) referring to store objects.
 For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.   
 When we get to building in a future section, this process will be described in precise detail.
-- 
cgit v1.2.3


From b4df351880bb019f6b3176f739059440f128dc43 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 22:28:26 -0400
Subject: Relocability -> relocation in store object title

---
 doc/manual/src/design/store/relocatability.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/relocatability.md b/doc/manual/src/design/store/relocatability.md
index 5cdbe9486..c7f869135 100644
--- a/doc/manual/src/design/store/relocatability.md
+++ b/doc/manual/src/design/store/relocatability.md
@@ -1,8 +1,8 @@
-## Advanced Topic: store object relocatability
+## Advanced Topic: Store object relocation
 
-Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissable to relocate a store object to a store with a different mount point.
+Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissible to relocate a store object to a store with a different mount point.
 
-Recall from the section on [store paths](./store-paths.md), concrete store paths look like `<store-dir>/<hash>-<name>`.
+Recall from the section on [store paths](./store-paths.md) that concrete store paths look like `<store-dir>/<hash>-<name>`.
 
 ~~The two final restrictions of the previous section yield an alternative view of the same information.~~
 Rather than associating store dirs with the references, we can say a store object itself has a store dir if and only if it has at least one reference.
-- 
cgit v1.2.3


From 55b437b5516dfdcd4358de48e7496b08d7be39c6 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 22:56:21 -0400
Subject: Improve store path section

---
 doc/manual/src/design/store/objects.md |  2 +-
 doc/manual/src/design/store/paths.md   | 37 +++++++++++++++++++++++++---------
 2 files changed, 29 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
index 2c2ed2bdb..8431958a5 100644
--- a/doc/manual/src/design/store/objects.md
+++ b/doc/manual/src/design/store/objects.md
@@ -17,7 +17,7 @@ In particular, every file system object falls into these three cases:
 
  - Symlink: may point anywhere.
 
-   In particular, Symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
+   In particular, symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
 
 A bare file or symlink as the "root" file system object is allowed.
 
diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
index d7d2ef960..1a00de5cb 100644
--- a/doc/manual/src/design/store/paths.md
+++ b/doc/manual/src/design/store/paths.md
@@ -2,18 +2,15 @@
 
 A store path is a pair of a 20-byte digest and a name.
 
-Historically it is the triple of those two and also the store directory, but the modern implementation's internal representation is just the pair.
-This change is because in the vast majority of cases, the store dir is fully determined by the context in which the store path occurs.
-
 ## String representation
 
 A store path is rendered as the concatenation of
 
-  - the store directory
+  - a store directory
 
   - a path-separator (`/`)
 
-  - the digest rendered as Base-32 (20 bytes becomes 32 bytes)
+  - the digest rendered as Base-32 (20 arbitrary bytes becomes 32 ASCII chars)
 
   - a hyphen (`-`)
 
@@ -21,14 +18,32 @@ A store path is rendered as the concatenation of
 
 Let's take the store path from the very beginning of this manual as an example:
 
-    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
+    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
 
 This parses like so:
 
-    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1/
+    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
     ^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
     store dir  digest                           name
 
+We then can discard the store dir to recover the conceptual pair that is a store path:
+
+    {
+      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
+      name:   "firefox-33.1",
+    }
+
+### Where did the "store directory" come from?
+
+If you notice, the above references a "store directory", but that is *not* part of the definition of a store path.
+We can discard it when parsing, but what about when printing?
+We need to get a store directory from *somewhere*.
+
+The answer is, the store directory is a property of the store that contains the store path.
+The explanation for this is simple enough: a store is notionally mounted as a directory at some location, and the store object's root file system likewise mounted at this path within that directory.
+
+This does, however, mean the string representation of a store path is not derived just from the store path itself, but is in fact "context dependent".
+
 ## The digest
 
 The calculation of the digest is quite complicated for historical reasons.
@@ -39,10 +54,14 @@ Some of the details will be saved for later.
 
 Store paths are either content-addressed or "input-addressed".
 
-Content addressing means that the digest ultimately derives from referred store object's file system data and references, and thus can be verified (if one knows how it was calculated).
+Content addressing means that the digest ultimately derives from referred store object's file system objects and references, and thus can be verified.
+There is more than one *method* of content-addressing, however.
+Still, if one does know the the content addressing schema that was used,
+(or guesses, there isn't that many yet!)
+one can recalcuate the store path and thus verify the store object.
 
 Input addressing means that the digest derives from how the store path was produced -- the "inputs" and plan that it was built from.
-Store paths of this sort can not be validated from the content of the store object.
+Store paths of this sort can *not* be validated from the content of the store object.
 Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
 The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
 
-- 
cgit v1.2.3


From b98dc3b19c62abb3b8edc778cee0ac8234c5577d Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 18 Apr 2022 23:03:38 -0400
Subject: store objects, better opining sentances

---
 doc/manual/src/design/store/objects.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
index 8431958a5..38c73bc7a 100644
--- a/doc/manual/src/design/store/objects.md
+++ b/doc/manual/src/design/store/objects.md
@@ -1,6 +1,6 @@
 # Store Objects
 
-File system data in Nix is organized into *store objects*.
+Data in Nix is chiefly organized into *store objects*.
 A store object is the pair of
 
   - A (root) file system object
@@ -8,7 +8,7 @@ A store object is the pair of
 
 ## File system objects
 
-The nix store uses a simple filesystem model.
+The Nix store uses a simple filesystem model.
 In particular, every file system object falls into these three cases:
 
  - File: an executable flag, and arbitrary data
-- 
cgit v1.2.3


From e4eea5e84e78cc57859cca9295da450258e8f55b Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 19 Apr 2022 01:44:02 -0400
Subject: Include abstract syntax based on the thesis for FSOs

See https://edolstra.github.io/pubs/phd-thesis.pdf, page 91.
---
 doc/manual/src/design/store/objects.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
index 38c73bc7a..0f3d2a499 100644
--- a/doc/manual/src/design/store/objects.md
+++ b/doc/manual/src/design/store/objects.md
@@ -9,6 +9,16 @@ A store object is the pair of
 ## File system objects
 
 The Nix store uses a simple filesystem model.
+
+    data FileSystemObject
+      = Regular Executable ByteString
+      | Directory (Map FileName FSO)
+      | SymLink ByteString
+
+    data Executable
+      = Executable
+      | NonExecutable
+
 In particular, every file system object falls into these three cases:
 
  - File: an executable flag, and arbitrary data
@@ -26,10 +36,21 @@ A bare file or symlink as the "root" file system object is allowed.
 This is close to Git's model, but with one crucial difference:
 Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
 
+    data GitObject
+      = Blob ByteString
+      | Tree (Map FileName (Persission, FSO))
+
+    data Persission
+      = Directory -- IFF paired with tree
+      -- Iff paired with blob, one of:
+      | RegFile
+      | ExecutableFile
+      | Symlink
+
 So long as the root object is a directory, the representations are isomorphic.
 There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
 
-However, if the root object is a file, there is loss of fidelity.
+However, if the root object is a blob, there is loss of fidelity.
 Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
 
 Git's model matches Unix tradition, but Nix's model is more natural.
-- 
cgit v1.2.3


From 4e4bbd9e832e810b4e4cf33aced0ec0322cf55b6 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 19 Apr 2022 02:02:11 -0400
Subject: Improve store objects session more

---
 doc/manual/src/design/store/paths.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
index 1a00de5cb..cf51eb866 100644
--- a/doc/manual/src/design/store/paths.md
+++ b/doc/manual/src/design/store/paths.md
@@ -47,20 +47,28 @@ This does, however, mean the string representation of a store path is not derive
 ## The digest
 
 The calculation of the digest is quite complicated for historical reasons.
-Some of the details will be saved for later.
+The details of the algorithms will be discussed later once more concepts have been introduced.
+For now, we just concern ourselves with the *key properties* of those algorithms.
 
-> Historical note. The 20 byte restriction is because originally a digests were SHA-1 hashes.
-> This is no longer true, but longer hashes and other information is still boiled down to 20 bytes.
+::: {.note}
+**Historical note** The 20 byte restriction is because originally a digests were SHA-1 hashes.
+This is no longer true, but longer hashes and other information are still boiled down to 20 bytes.
+:::
 
-Store paths are either content-addressed or "input-addressed".
+Store paths are either *content-addressed* or *input-addressed*.
 
-Content addressing means that the digest ultimately derives from referred store object's file system objects and references, and thus can be verified.
+::: {.note}
+The former is a standard term used elsewhere.
+The later is our own creation to evoke a contrast with content addressing.
+:::
+
+Content addressing means that the store path digest ultimately derives from referred store object's contents, namely its file system objects and references.
 There is more than one *method* of content-addressing, however.
-Still, if one does know the the content addressing schema that was used,
+Still, if one does know the content addressing schema that was used,
 (or guesses, there isn't that many yet!)
-one can recalcuate the store path and thus verify the store object.
+one can recalculate the store path and thus verify the store object.
 
-Input addressing means that the digest derives from how the store path was produced -- the "inputs" and plan that it was built from.
+Input addressing means that the store path digest derives from how the store path was produced, namely the "inputs" and plan that it was built from.
 Store paths of this sort can *not* be validated from the content of the store object.
 Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
 The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
-- 
cgit v1.2.3


From c86c1ec7e31c2725be20e4087845e96878134846 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Tue, 19 Apr 2022 02:20:15 -0400
Subject: Make refernces sneak preview more concise

---
 doc/manual/src/design/store/objects.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
index 0f3d2a499..e4f49a170 100644
--- a/doc/manual/src/design/store/objects.md
+++ b/doc/manual/src/design/store/objects.md
@@ -62,9 +62,8 @@ Store objects can refer to both other store objects and themselves.
 Self-reference may seem pointless, but tracking them is in fact useful.
 We can best explain why later after more concepts have been established.
 
-References are normally calculated by scanning the rooted file system objects for store paths (which we describe in the next section) referring to store objects.
-For now, it suffices to say that a store path is a string encoding of a reference to a store paths, and therefore it is something that we can search for in the contents of files, and thus in store objects by searching in all their files.   
-When we get to building in a future section, this process will be described in precise detail.
+References are normally calculated so as to to record the presence of textual references in store object's file systems obejcts.
+This process will be described precisely in the section on [building](./building.md), once more concepts are explained, as building is the primary path new store objects with non-trivial references are created.
 
 However, scanning for references is not mandatory.
 Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
-- 
cgit v1.2.3


From 0737094161cc2b13a6ec06a58a78200cb2116b88 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Fri, 22 Apr 2022 01:39:30 -0400
Subject: Add draft "Rosetta stone" by @fricklerhandwerk and stub commentary

The idea and most of the execution are @fricklerhandwerk's. I changed a
few things best I could based on @edolstra's corrections, and a Bazel
glossary.

Valentin Gagarin <valentin@fricklerhandwerk.de>
---
 doc/manual/src/SUMMARY.md.in                |  3 ++-
 doc/manual/src/design/store/related-work.md | 37 +++++++++++++++++++++++++++++
 doc/manual/src/design/store/store.md        | 22 +++++++++++++++++
 3 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 doc/manual/src/design/store/related-work.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 323a569d1..9cde44a0d 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -26,7 +26,8 @@
       - [Input-Addressing](design/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
     - [Building](design/store/building.md)
-    - [Advanced Topic: store object relocatability](design/store/relocatability.md)
+    - [Advanced Topic: Store object relocatability](design/store/relocatability.md)
+    - [Advanced Topic: Related work](design/store/related-work.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/design/store/related-work.md b/doc/manual/src/design/store/related-work.md
new file mode 100644
index 000000000..b64b41988
--- /dev/null
+++ b/doc/manual/src/design/store/related-work.md
@@ -0,0 +1,37 @@
+# Advanced Topic: Related Work
+
+## Bazel
+
+TODO skylark and layering.
+
+TODO being monadic, if RFC 92.
+
+## Build Systems à la Carte
+
+TODO user-choosen keys vs keys chosen automatically?
+Purity in face of dynamic tasks (no conflicts, guaranteed).
+
+TODO Does Nix constitute a different way to be be monadic?
+Purity of keys, as mentioned.
+Dynamic tasks/keys vs dynamic dependencies.
+(Not sure yet.)
+
+## Lazy evaluation
+
+We clearly have thunks that produce thunks, but less clearly functions that produce functions.
+
+Do we have open terms?
+
+Do we hve thunks vs expressions distinction?
+c.f. John Shutt's modern fexprs, when the syntax can "leak".
+
+## Machine models
+
+TODO
+Derivations as store objects via drv files makes Nix a "Von Neumann" archicture.
+Can also imagine a "Harvard" archicture where derivations are stored separately?
+Can we in general imagine N heaps for N different sorts of objects?
+
+TODO
+Also, leaning on the notion of "builtin builders" more, having multiple different sorts of user-defined builders too.
+The builder is a black box as far as the Nix model is concerned.
diff --git a/doc/manual/src/design/store/store.md b/doc/manual/src/design/store/store.md
index e91f0f6e4..458c1e2b8 100644
--- a/doc/manual/src/design/store/store.md
+++ b/doc/manual/src/design/store/store.md
@@ -1,5 +1,27 @@
+# Nix Store
+
 A Nix store is a collection of *store objects* referred to by *store paths*.
 Every store also has a "store directory path", which is a path prefix used for various purposes.
 
 There are many types of stores, but all of them at least respect this model.
 Some however offer additional functionality.
+
+## A Rosetta stone for the Nix store.
+
+The design of Nix is comparable to other build systems, even programming languages in general.
+Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
+If you are familiar with one of these columns, this might help the following sections make more sense.
+
+generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
+-- | -- | -- | -- | --
+data (build input, build result) | component | file (source, target) | value | value
+build plan | derivation graph | action graph | `Tasks` | thunk
+build step | derivation | rule | `Task` | thunk
+build instructions | builder | (depends on action type) | `Task` | function
+build | build | build | `Build` applied to arguments | evaluation
+persistence layer | store | file system | `Store` | heap
+
+(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)
+
+Plenty more could be said elaborating these comparisons.
+We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.
-- 
cgit v1.2.3


From 0eae4bfad1bfa94347252b51dec8c87fa73644fb Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 21 Apr 2022 14:39:35 +0200
Subject: reword overview with clear terminology

trying to capture alternative terms in one go here, mirroring everyday
use:

derivation - build plan
realise - execute build

there will be more of that sort.
---
 doc/manual/src/design/overview.md | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 9329f2ad7..6a5555dff 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -2,14 +2,22 @@
 
 Nix consists of layers that operate fairly independently.
 
-At the top is the *command line interface*.
+At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
-Below that is the Nix *expression language*, in which packages and configurations are written.
+Below that is the *Nix language*, a [purely functional programming](https://en.m.wikipedia.org/wiki/Purely_functional_programming) language.
+It is used to compose  expressions which ultimately evaluate to *derivations* — self-contained *build plans* to derive new data from referenced input data.
 
-The command line and expression language are what users interact with most.
+::: {.note}
+The Nix language itself does not have a notion of *packages* or *configurations*.
+As far as we are concerned here, the result of a derivation is just data.
+In practice this amounts to a set of files in a file system.
+:::
 
-Below that is the *store layer*, Nix' machinery to represent tracked files, dependencies, and fully elaborated build plans.
-It is also used for executing those build plans.
-The store layer may not be as visible, but this is the heart of Nix.
+The command line and Nix language are what users interact with most.
+
+Underlying everything is the *Nix store*, a mechanism to keep track of derivations, data, and references between them.
+It can also *realise derivations*, that is, *execute build instructions* to produce new data.
+It uses the file system as a persistence layer, and a database to keep track of references.
+
+This chapter describes Nix starting at the bottom with the store layer, working its way up to the user-facing components described in the rest of the manual.
 
-This chapter describes Nix starting with that bottom store layer, then working its way up until it reaches the more user-facing interfaces described in the rest of the manual."
-- 
cgit v1.2.3


From 327ccd3b0787f7803a51aa5124cf0cbab694523c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 21 Apr 2022 15:06:05 +0200
Subject: only use generic build system terminology

we will use a translation table to introduce nix-specific terms
---
 doc/manual/src/design/overview.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 6a5555dff..c60121a01 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -5,18 +5,18 @@ Nix consists of layers that operate fairly independently.
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the *Nix language*, a [purely functional programming](https://en.m.wikipedia.org/wiki/Purely_functional_programming) language.
-It is used to compose  expressions which ultimately evaluate to *derivations* — self-contained *build plans* to derive new data from referenced input data.
+It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
-As far as we are concerned here, the result of a derivation is just data.
+As far as we are concerned here, the inputs and results of a derivation are just data.
 In practice this amounts to a set of files in a file system.
 :::
 
 The command line and Nix language are what users interact with most.
 
-Underlying everything is the *Nix store*, a mechanism to keep track of derivations, data, and references between them.
-It can also *realise derivations*, that is, *execute build instructions* to produce new data.
+Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
+It can also execute *build instructions* captured in the build plans, to produce new data.
 It uses the file system as a persistence layer, and a database to keep track of references.
 
 This chapter describes Nix starting at the bottom with the store layer, working its way up to the user-facing components described in the rest of the manual.
-- 
cgit v1.2.3


From 804e8bd7473516b087f39161bd34730e26480517 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Fri, 22 Apr 2022 10:43:19 +0200
Subject: indicate sequence with "then"

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/design/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index c60121a01..20a3fe653 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -19,5 +19,5 @@ Underlying everything is the *Nix store*, a mechanism to keep track of build pla
 It can also execute *build instructions* captured in the build plans, to produce new data.
 It uses the file system as a persistence layer, and a database to keep track of references.
 
-This chapter describes Nix starting at the bottom with the store layer, working its way up to the user-facing components described in the rest of the manual.
+This chapter describes Nix starting at the bottom with the store layer, then working its way up to the user-facing components described in the rest of the manual.
 
-- 
cgit v1.2.3


From 23ee0b24f7c0fd43ccf6f99b87941df4cb071689 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Fri, 22 Apr 2022 10:44:00 +0200
Subject: correctly use comma for nesting

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/design/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 20a3fe653..b1adb143b 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -16,7 +16,7 @@ In practice this amounts to a set of files in a file system.
 The command line and Nix language are what users interact with most.
 
 Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
-It can also execute *build instructions* captured in the build plans, to produce new data.
+It can also execute *build instructions*, captured in the build plans, to produce new data.
 It uses the file system as a persistence layer, and a database to keep track of references.
 
 This chapter describes Nix starting at the bottom with the store layer, then working its way up to the user-facing components described in the rest of the manual.
-- 
cgit v1.2.3


From 51e6bed25e073afac5a7b5e11033769a615d0473 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Fri, 22 Apr 2022 10:54:43 +0200
Subject: do not mention implementation details

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/design/overview.md | 1 -
 1 file changed, 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index b1adb143b..0cead62ab 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -17,7 +17,6 @@ The command line and Nix language are what users interact with most.
 
 Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
 It can also execute *build instructions*, captured in the build plans, to produce new data.
-It uses the file system as a persistence layer, and a database to keep track of references.
 
 This chapter describes Nix starting at the bottom with the store layer, then working its way up to the user-facing components described in the rest of the manual.
 
-- 
cgit v1.2.3


From 89a7c956ffadbc9c17849051f3c91a1225dcfce2 Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Fri, 22 Apr 2022 14:05:50 -0400
Subject: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin@fricklerhandwerk.de>
---
 doc/manual/src/design/overview.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 0cead62ab..15ddb562d 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -5,7 +5,7 @@ Nix consists of layers that operate fairly independently.
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the *Nix language*, a [purely functional programming](https://en.m.wikipedia.org/wiki/Purely_functional_programming) language.
-It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
-- 
cgit v1.2.3


From b387d809437b0c787691b814bf65e1647fd18009 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Sun, 24 Apr 2022 21:13:45 +0200
Subject: remove sentence for chapter transition

idea: sections could be read in different orders by linking them in
different ways (e.g. depth-first or breadth-first). adding hard-coded
transitions makes that confusing.
---
 doc/manual/src/design/overview.md | 2 --
 1 file changed, 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
index 15ddb562d..b5f8b6aad 100644
--- a/doc/manual/src/design/overview.md
+++ b/doc/manual/src/design/overview.md
@@ -18,5 +18,3 @@ The command line and Nix language are what users interact with most.
 Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
 It can also execute *build instructions*, captured in the build plans, to produce new data.
 
-This chapter describes Nix starting at the bottom with the store layer, then working its way up to the user-facing components described in the rest of the manual.
-
-- 
cgit v1.2.3


From 34ea74c9ec21641399a96386094b021d7a2b30f4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 26 Apr 2022 11:46:15 +0200
Subject: reword introductory section

there should be a meta section for each chapter to give motivation of
the presented structure. the structure itself is visible from the table
of contents.
---
 doc/manual/src/design/design.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/design.md b/doc/manual/src/design/design.md
index 7d4211764..f5135bc9a 100644
--- a/doc/manual/src/design/design.md
+++ b/doc/manual/src/design/design.md
@@ -1,5 +1,6 @@
 # Design and Data Model
 
 Most of the manual is about how to use Nix.
-This chapter is about what Nix actually is.
-The hope is that it can serve as a reference for key concepts, and also shed light on why things are the way they are.
+This chapter is about the technical principles behind Nix.
+
+It describes each architectural layer and its components in its own section, starting at the bottom with the store layer, then working its way up to the user-facing components described in the rest of the manual.
-- 
cgit v1.2.3


From 75981263912805a77890bcdb63c4aa3bbb0d8e09 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 27 Apr 2022 21:17:44 +0200
Subject: remove separate meta-section, add architecture diagram

the diagram is a first approximation and only covers that same section.
of course there is much more going on, and other features should at some
point also be illustrated.

we also have to think about presentation format and technicalities
behind it. the manual has to render to `man`, but we may want something
more refined for web view.
---
 doc/manual/src/SUMMARY.md.in         |  3 +--
 doc/manual/src/design/design.md      | 39 ++++++++++++++++++++++++++++++++++--
 doc/manual/src/design/overview.md    | 20 ------------------
 doc/manual/src/design/store/store.md |  2 +-
 4 files changed, 39 insertions(+), 25 deletions(-)
 delete mode 100644 doc/manual/src/design/overview.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 9cde44a0d..ec457126a 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -16,8 +16,7 @@
   - [Environment Variables](installation/env-variables.md)
   - [Upgrading Nix](installation/upgrading.md)
 - [Design and Data Model](design/design.md)
-  - [Overview](design/overview.md)
-  - [The Store Layer](design/store/store.md)
+  - [Store](design/store/store.md)
     - [Store Objects](design/store/objects.md)
     - [Store Paths](design/store/paths.md)
     - [Nix Archives](design/store/nar.md)
diff --git a/doc/manual/src/design/design.md b/doc/manual/src/design/design.md
index f5135bc9a..960a68f41 100644
--- a/doc/manual/src/design/design.md
+++ b/doc/manual/src/design/design.md
@@ -1,6 +1,41 @@
 # Design and Data Model
 
-Most of the manual is about how to use Nix.
 This chapter is about the technical principles behind Nix.
 
-It describes each architectural layer and its components in its own section, starting at the bottom with the store layer, then working its way up to the user-facing components described in the rest of the manual.
+## Architecture
+
+Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers).
+
+```
+               [ commmand line interface ]
+                            |
+                            | evaluates
+                            V
+               [ configuration language  ]
+                            |
+                            | evaluates to
+                            |
+              reference     V       build
+[ build inputs ] --> [ build plans ] --> [ build results ]
+          \                 |                 /
+            \               | persisted to  /
+              \             V             /
+              [           store           ]
+```
+
+At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
+
+Below that is the *Nix language*, a [purely functional programming](https://en.m.wikipedia.org/wiki/Purely_functional_programming) language.
+It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
+
+::: {.note}
+The Nix language itself does not have a notion of *packages* or *configurations*.
+As far as we are concerned here, the inputs and results of a derivation are just data.
+In practice this amounts to a set of files in a file system.
+:::
+
+The command line and Nix language are what users interact with most.
+
+Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
+It can also execute *build instructions*, captured in the build plans, to produce new data.
+
diff --git a/doc/manual/src/design/overview.md b/doc/manual/src/design/overview.md
deleted file mode 100644
index b5f8b6aad..000000000
--- a/doc/manual/src/design/overview.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Overview
-
-Nix consists of layers that operate fairly independently.
-
-At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
-
-Below that is the *Nix language*, a [purely functional programming](https://en.m.wikipedia.org/wiki/Purely_functional_programming) language.
-It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
-
-::: {.note}
-The Nix language itself does not have a notion of *packages* or *configurations*.
-As far as we are concerned here, the inputs and results of a derivation are just data.
-In practice this amounts to a set of files in a file system.
-:::
-
-The command line and Nix language are what users interact with most.
-
-Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
-It can also execute *build instructions*, captured in the build plans, to produce new data.
-
diff --git a/doc/manual/src/design/store/store.md b/doc/manual/src/design/store/store.md
index 458c1e2b8..d4add52f5 100644
--- a/doc/manual/src/design/store/store.md
+++ b/doc/manual/src/design/store/store.md
@@ -1,4 +1,4 @@
-# Nix Store
+# Store
 
 A Nix store is a collection of *store objects* referred to by *store paths*.
 Every store also has a "store directory path", which is a path prefix used for various purposes.
-- 
cgit v1.2.3


From d30033759a07a0d5df7aac4c22bfa274b74baf0e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 27 Apr 2022 21:21:46 +0200
Subject: address Nix language consistently as configuration language

---
 doc/manual/src/design/design.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/design/design.md b/doc/manual/src/design/design.md
index 960a68f41..16c51533b 100644
--- a/doc/manual/src/design/design.md
+++ b/doc/manual/src/design/design.md
@@ -25,7 +25,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
-Below that is the *Nix language*, a [purely functional programming](https://en.m.wikipedia.org/wiki/Purely_functional_programming) language.
+Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
 It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
-- 
cgit v1.2.3


From 39f01176a713bad4e090e19c8a25c2447056640d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 27 Apr 2022 23:25:33 +0200
Subject: design -> architecture, add motivation

following ideas found in Architecture of Gazelle[1]

[1]: https://github.com/bazelbuild/bazel-gazelle/blob/56d35f8db086bb65ef876f96f7baa7b71516daf8/Design.rst
---
 doc/manual/src/SUMMARY.md.in                       |  2 +-
 doc/manual/src/architecture/architecture.md        | 42 ++++++++++++
 doc/manual/src/architecture/store/building.md      | 15 +++++
 doc/manual/src/architecture/store/drvs/ca.md       |  0
 doc/manual/src/architecture/store/drvs/drvs.md     | 59 ++++++++++++++++
 doc/manual/src/architecture/store/drvs/ia.md       |  0
 .../src/architecture/store/input-addressing.md     |  1 +
 doc/manual/src/architecture/store/nar.md           |  1 +
 doc/manual/src/architecture/store/object-ca.md     |  1 +
 doc/manual/src/architecture/store/objects.md       | 73 ++++++++++++++++++++
 doc/manual/src/architecture/store/paths.md         | 78 ++++++++++++++++++++++
 doc/manual/src/architecture/store/related-work.md  | 37 ++++++++++
 .../src/architecture/store/relocatability.md       | 15 +++++
 doc/manual/src/architecture/store/store.md         | 27 ++++++++
 doc/manual/src/design/design.md                    | 41 ------------
 doc/manual/src/design/store/building.md            | 15 -----
 doc/manual/src/design/store/drvs/ca.md             |  0
 doc/manual/src/design/store/drvs/drvs.md           | 59 ----------------
 doc/manual/src/design/store/drvs/ia.md             |  0
 doc/manual/src/design/store/input-addressing.md    |  1 -
 doc/manual/src/design/store/nar.md                 |  1 -
 doc/manual/src/design/store/object-ca.md           |  1 -
 doc/manual/src/design/store/objects.md             | 73 --------------------
 doc/manual/src/design/store/paths.md               | 78 ----------------------
 doc/manual/src/design/store/related-work.md        | 37 ----------
 doc/manual/src/design/store/relocatability.md      | 15 -----
 doc/manual/src/design/store/store.md               | 27 --------
 27 files changed, 350 insertions(+), 349 deletions(-)
 create mode 100644 doc/manual/src/architecture/architecture.md
 create mode 100644 doc/manual/src/architecture/store/building.md
 create mode 100644 doc/manual/src/architecture/store/drvs/ca.md
 create mode 100644 doc/manual/src/architecture/store/drvs/drvs.md
 create mode 100644 doc/manual/src/architecture/store/drvs/ia.md
 create mode 100644 doc/manual/src/architecture/store/input-addressing.md
 create mode 100644 doc/manual/src/architecture/store/nar.md
 create mode 100644 doc/manual/src/architecture/store/object-ca.md
 create mode 100644 doc/manual/src/architecture/store/objects.md
 create mode 100644 doc/manual/src/architecture/store/paths.md
 create mode 100644 doc/manual/src/architecture/store/related-work.md
 create mode 100644 doc/manual/src/architecture/store/relocatability.md
 create mode 100644 doc/manual/src/architecture/store/store.md
 delete mode 100644 doc/manual/src/design/design.md
 delete mode 100644 doc/manual/src/design/store/building.md
 delete mode 100644 doc/manual/src/design/store/drvs/ca.md
 delete mode 100644 doc/manual/src/design/store/drvs/drvs.md
 delete mode 100644 doc/manual/src/design/store/drvs/ia.md
 delete mode 100644 doc/manual/src/design/store/input-addressing.md
 delete mode 100644 doc/manual/src/design/store/nar.md
 delete mode 100644 doc/manual/src/design/store/object-ca.md
 delete mode 100644 doc/manual/src/design/store/objects.md
 delete mode 100644 doc/manual/src/design/store/paths.md
 delete mode 100644 doc/manual/src/design/store/related-work.md
 delete mode 100644 doc/manual/src/design/store/relocatability.md
 delete mode 100644 doc/manual/src/design/store/store.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index ec457126a..c029e30bf 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -15,7 +15,7 @@
     - [Multi-User Mode](installation/multi-user.md)
   - [Environment Variables](installation/env-variables.md)
   - [Upgrading Nix](installation/upgrading.md)
-- [Design and Data Model](design/design.md)
+- [Architecture](architecture/architecture.md)
   - [Store](design/store/store.md)
     - [Store Objects](design/store/objects.md)
     - [Store Paths](design/store/paths.md)
diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
new file mode 100644
index 000000000..b17eacd2e
--- /dev/null
+++ b/doc/manual/src/architecture/architecture.md
@@ -0,0 +1,42 @@
+# Architecture
+
+This chapter describes how Nix works.
+It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
+
+## Overview
+
+Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers).
+
+```
+               [ commmand line interface ]
+                            |
+                            | evaluates
+                            V
+               [ configuration language  ]
+                            |
+                            | evaluates to
+                            |
+              reference     V       build
+[ build inputs ] --> [ build plans ] --> [ build results ]
+          \                 |                 /
+            \               | persisted to  /
+              \             V             /
+              [           store           ]
+```
+
+At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
+
+Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
+It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
+
+::: {.note}
+The Nix language itself does not have a notion of *packages* or *configurations*.
+As far as we are concerned here, the inputs and results of a derivation are just data.
+In practice this amounts to a set of files in a file system.
+:::
+
+The command line and Nix language are what users interact with most.
+
+Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
+It can also execute *build instructions*, captured in the build plans, to produce new data.
+
diff --git a/doc/manual/src/architecture/store/building.md b/doc/manual/src/architecture/store/building.md
new file mode 100644
index 000000000..f4f2649a3
--- /dev/null
+++ b/doc/manual/src/architecture/store/building.md
@@ -0,0 +1,15 @@
+# Building
+
+## Scanning for references
+
+Before in the section on [store objects](../objects.md), we talked abstractly about scanning for references.
+Now we can make this concrete.
+
+After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
+There is a few steps of this, but let's start with the simple case of one input-addressed output first.
+
+\[Overview of things that need to happen.]
+
+For example, if Nix thinks `/nix/store/asdfasdfasdf-foo` and `/nix/store/qwerqwerqwer-bar` are paths the data might plausibly reference, Nix will scan all the contents of all files recursively for the "hash parts" `asdfasdfasdf`` and `qwerqwerqwer`.
+
+\[Explain why whitelist.]
diff --git a/doc/manual/src/architecture/store/drvs/ca.md b/doc/manual/src/architecture/store/drvs/ca.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/manual/src/architecture/store/drvs/drvs.md b/doc/manual/src/architecture/store/drvs/drvs.md
new file mode 100644
index 000000000..766a7b47f
--- /dev/null
+++ b/doc/manual/src/architecture/store/drvs/drvs.md
@@ -0,0 +1,59 @@
+# Derivations
+
+Derivations are recipes to create store objects.
+
+Derivations are the heart of Nix.
+Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
+This is where Nix comes in.
+
+Derivations produce data by running arbitrary commands, like Make or Ninja rules.
+Unlike those systems, derivations do not produce arbitrary files, but only specific store objects.
+They cannot modify the store in any way, other than creating those store objects.
+This rigid specification of what they do is what allows Nix's caching to be so simple and yet robust.
+
+Based on the above, we can conceptually break derivations down into 3 parts:
+
+1. What command will be run?
+
+2. What existing store objects are needed as inputs?
+
+3. What store objects will be produced as outputs?
+
+## What command will be run?
+
+The original core of Nix was very simple about this, in the mold of traditional Unix.
+Commands consist of 3 parts:
+
+1. Path to executable
+
+2. Arguments (Except for `argv[0]`, which is taken from the path in the usual way)
+
+3. Environment variables.
+
+## What existing store objects are needed as inputs?
+
+The previous sub-section begs the question "how can we be sure the path to the executable points to what we think it does?"
+It's a good questions!
+
+## What store objects will be produced as outputs?
+
+## Extra extensions
+
+### `__structuredAttrs`
+
+Historically speaking, most users of Nix made GNU Bash with a script the command run, regardless of what they were doing.
+Bash variable are automatically created from env vars, but bash also supports array and string-keyed map variables in addition to string variables.
+People also usually create derivations using language which also support these richer data types.
+It was thus desired a way to get this data from the language "planning" the derivation to language to bash, the language evaluated at "run time".
+
+`__structuredAttrs` does this by smuggling inside the core derivation format a map of named richer data.
+At run time, this becomes two things:
+
+1. A JSON file containing that map.
+2. A bash script setting those variables.
+
+The bash command can be passed a script which will "source" that Nix-created bash script, setting those variables with the richer data.
+The outer script can then do whatever it likes with those richer variables as input.
+
+However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers.
+We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer.
diff --git a/doc/manual/src/architecture/store/drvs/ia.md b/doc/manual/src/architecture/store/drvs/ia.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/doc/manual/src/architecture/store/input-addressing.md b/doc/manual/src/architecture/store/input-addressing.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/architecture/store/input-addressing.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/architecture/store/nar.md b/doc/manual/src/architecture/store/nar.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/architecture/store/nar.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/architecture/store/object-ca.md b/doc/manual/src/architecture/store/object-ca.md
new file mode 100644
index 000000000..1333ed77b
--- /dev/null
+++ b/doc/manual/src/architecture/store/object-ca.md
@@ -0,0 +1 @@
+TODO
diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
new file mode 100644
index 000000000..e4f49a170
--- /dev/null
+++ b/doc/manual/src/architecture/store/objects.md
@@ -0,0 +1,73 @@
+# Store Objects
+
+Data in Nix is chiefly organized into *store objects*.
+A store object is the pair of
+
+  - A (root) file system object
+  - A set of references to store objects
+
+## File system objects
+
+The Nix store uses a simple filesystem model.
+
+    data FileSystemObject
+      = Regular Executable ByteString
+      | Directory (Map FileName FSO)
+      | SymLink ByteString
+
+    data Executable
+      = Executable
+      | NonExecutable
+
+In particular, every file system object falls into these three cases:
+
+ - File: an executable flag, and arbitrary data
+
+ - Directory: mapping of names to child file system objects.
+
+ - Symlink: may point anywhere.
+
+   In particular, symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
+
+A bare file or symlink as the "root" file system object is allowed.
+
+### Comparison with Git
+
+This is close to Git's model, but with one crucial difference:
+Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
+
+    data GitObject
+      = Blob ByteString
+      | Tree (Map FileName (Persission, FSO))
+
+    data Persission
+      = Directory -- IFF paired with tree
+      -- Iff paired with blob, one of:
+      | RegFile
+      | ExecutableFile
+      | Symlink
+
+So long as the root object is a directory, the representations are isomorphic.
+There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
+
+However, if the root object is a blob, there is loss of fidelity.
+Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
+
+Git's model matches Unix tradition, but Nix's model is more natural.
+
+## References
+
+Store objects can refer to both other store objects and themselves.
+
+Self-reference may seem pointless, but tracking them is in fact useful.
+We can best explain why later after more concepts have been established.
+
+References are normally calculated so as to to record the presence of textual references in store object's file systems obejcts.
+This process will be described precisely in the section on [building](./building.md), once more concepts are explained, as building is the primary path new store objects with non-trivial references are created.
+
+However, scanning for references is not mandatory.
+Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
+and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
+Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
+
+This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
diff --git a/doc/manual/src/architecture/store/paths.md b/doc/manual/src/architecture/store/paths.md
new file mode 100644
index 000000000..cf51eb866
--- /dev/null
+++ b/doc/manual/src/architecture/store/paths.md
@@ -0,0 +1,78 @@
+# Store Paths
+
+A store path is a pair of a 20-byte digest and a name.
+
+## String representation
+
+A store path is rendered as the concatenation of
+
+  - a store directory
+
+  - a path-separator (`/`)
+
+  - the digest rendered as Base-32 (20 arbitrary bytes becomes 32 ASCII chars)
+
+  - a hyphen (`-`)
+
+  - the name
+
+Let's take the store path from the very beginning of this manual as an example:
+
+    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
+
+This parses like so:
+
+    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
+    ^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
+    store dir  digest                           name
+
+We then can discard the store dir to recover the conceptual pair that is a store path:
+
+    {
+      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
+      name:   "firefox-33.1",
+    }
+
+### Where did the "store directory" come from?
+
+If you notice, the above references a "store directory", but that is *not* part of the definition of a store path.
+We can discard it when parsing, but what about when printing?
+We need to get a store directory from *somewhere*.
+
+The answer is, the store directory is a property of the store that contains the store path.
+The explanation for this is simple enough: a store is notionally mounted as a directory at some location, and the store object's root file system likewise mounted at this path within that directory.
+
+This does, however, mean the string representation of a store path is not derived just from the store path itself, but is in fact "context dependent".
+
+## The digest
+
+The calculation of the digest is quite complicated for historical reasons.
+The details of the algorithms will be discussed later once more concepts have been introduced.
+For now, we just concern ourselves with the *key properties* of those algorithms.
+
+::: {.note}
+**Historical note** The 20 byte restriction is because originally a digests were SHA-1 hashes.
+This is no longer true, but longer hashes and other information are still boiled down to 20 bytes.
+:::
+
+Store paths are either *content-addressed* or *input-addressed*.
+
+::: {.note}
+The former is a standard term used elsewhere.
+The later is our own creation to evoke a contrast with content addressing.
+:::
+
+Content addressing means that the store path digest ultimately derives from referred store object's contents, namely its file system objects and references.
+There is more than one *method* of content-addressing, however.
+Still, if one does know the content addressing schema that was used,
+(or guesses, there isn't that many yet!)
+one can recalculate the store path and thus verify the store object.
+
+Input addressing means that the store path digest derives from how the store path was produced, namely the "inputs" and plan that it was built from.
+Store paths of this sort can *not* be validated from the content of the store object.
+Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
+The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
+
+While metadata is included in the digest calculation explaining which method it was calculated by, this only serves to thwart pre-image attacks.
+That metadata is scrambled with everything else so that it is difficult to tell how a given store path was produced short of a brute-force search.
+In the parlance of referencing schemes, this means that store paths are not "self-describing".
diff --git a/doc/manual/src/architecture/store/related-work.md b/doc/manual/src/architecture/store/related-work.md
new file mode 100644
index 000000000..b64b41988
--- /dev/null
+++ b/doc/manual/src/architecture/store/related-work.md
@@ -0,0 +1,37 @@
+# Advanced Topic: Related Work
+
+## Bazel
+
+TODO skylark and layering.
+
+TODO being monadic, if RFC 92.
+
+## Build Systems à la Carte
+
+TODO user-choosen keys vs keys chosen automatically?
+Purity in face of dynamic tasks (no conflicts, guaranteed).
+
+TODO Does Nix constitute a different way to be be monadic?
+Purity of keys, as mentioned.
+Dynamic tasks/keys vs dynamic dependencies.
+(Not sure yet.)
+
+## Lazy evaluation
+
+We clearly have thunks that produce thunks, but less clearly functions that produce functions.
+
+Do we have open terms?
+
+Do we hve thunks vs expressions distinction?
+c.f. John Shutt's modern fexprs, when the syntax can "leak".
+
+## Machine models
+
+TODO
+Derivations as store objects via drv files makes Nix a "Von Neumann" archicture.
+Can also imagine a "Harvard" archicture where derivations are stored separately?
+Can we in general imagine N heaps for N different sorts of objects?
+
+TODO
+Also, leaning on the notion of "builtin builders" more, having multiple different sorts of user-defined builders too.
+The builder is a black box as far as the Nix model is concerned.
diff --git a/doc/manual/src/architecture/store/relocatability.md b/doc/manual/src/architecture/store/relocatability.md
new file mode 100644
index 000000000..c7f869135
--- /dev/null
+++ b/doc/manual/src/architecture/store/relocatability.md
@@ -0,0 +1,15 @@
+## Advanced Topic: Store object relocation
+
+Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissible to relocate a store object to a store with a different mount point.
+
+Recall from the section on [store paths](./store-paths.md) that concrete store paths look like `<store-dir>/<hash>-<name>`.
+
+~~The two final restrictions of the previous section yield an alternative view of the same information.~~
+Rather than associating store dirs with the references, we can say a store object itself has a store dir if and only if it has at least one reference.
+
+This corresponds to the observation that a store object with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store object without any references, i.e. thus without a store directory, can exist in any store.
+
+Lastly, this illustrates the purpose of tracking self references.
+Store objects without self-references or other references are relocatable, while store paths with self-references aren't.
+This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
+\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
new file mode 100644
index 000000000..d4add52f5
--- /dev/null
+++ b/doc/manual/src/architecture/store/store.md
@@ -0,0 +1,27 @@
+# Store
+
+A Nix store is a collection of *store objects* referred to by *store paths*.
+Every store also has a "store directory path", which is a path prefix used for various purposes.
+
+There are many types of stores, but all of them at least respect this model.
+Some however offer additional functionality.
+
+## A Rosetta stone for the Nix store.
+
+The design of Nix is comparable to other build systems, even programming languages in general.
+Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
+If you are familiar with one of these columns, this might help the following sections make more sense.
+
+generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
+-- | -- | -- | -- | --
+data (build input, build result) | component | file (source, target) | value | value
+build plan | derivation graph | action graph | `Tasks` | thunk
+build step | derivation | rule | `Task` | thunk
+build instructions | builder | (depends on action type) | `Task` | function
+build | build | build | `Build` applied to arguments | evaluation
+persistence layer | store | file system | `Store` | heap
+
+(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)
+
+Plenty more could be said elaborating these comparisons.
+We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.
diff --git a/doc/manual/src/design/design.md b/doc/manual/src/design/design.md
deleted file mode 100644
index 16c51533b..000000000
--- a/doc/manual/src/design/design.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Design and Data Model
-
-This chapter is about the technical principles behind Nix.
-
-## Architecture
-
-Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers).
-
-```
-               [ commmand line interface ]
-                            |
-                            | evaluates
-                            V
-               [ configuration language  ]
-                            |
-                            | evaluates to
-                            |
-              reference     V       build
-[ build inputs ] --> [ build plans ] --> [ build results ]
-          \                 |                 /
-            \               | persisted to  /
-              \             V             /
-              [           store           ]
-```
-
-At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
-
-Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
-
-::: {.note}
-The Nix language itself does not have a notion of *packages* or *configurations*.
-As far as we are concerned here, the inputs and results of a derivation are just data.
-In practice this amounts to a set of files in a file system.
-:::
-
-The command line and Nix language are what users interact with most.
-
-Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
-It can also execute *build instructions*, captured in the build plans, to produce new data.
-
diff --git a/doc/manual/src/design/store/building.md b/doc/manual/src/design/store/building.md
deleted file mode 100644
index f4f2649a3..000000000
--- a/doc/manual/src/design/store/building.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# Building
-
-## Scanning for references
-
-Before in the section on [store objects](../objects.md), we talked abstractly about scanning for references.
-Now we can make this concrete.
-
-After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
-There is a few steps of this, but let's start with the simple case of one input-addressed output first.
-
-\[Overview of things that need to happen.]
-
-For example, if Nix thinks `/nix/store/asdfasdfasdf-foo` and `/nix/store/qwerqwerqwer-bar` are paths the data might plausibly reference, Nix will scan all the contents of all files recursively for the "hash parts" `asdfasdfasdf`` and `qwerqwerqwer`.
-
-\[Explain why whitelist.]
diff --git a/doc/manual/src/design/store/drvs/ca.md b/doc/manual/src/design/store/drvs/ca.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/doc/manual/src/design/store/drvs/drvs.md b/doc/manual/src/design/store/drvs/drvs.md
deleted file mode 100644
index 766a7b47f..000000000
--- a/doc/manual/src/design/store/drvs/drvs.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Derivations
-
-Derivations are recipes to create store objects.
-
-Derivations are the heart of Nix.
-Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
-This is where Nix comes in.
-
-Derivations produce data by running arbitrary commands, like Make or Ninja rules.
-Unlike those systems, derivations do not produce arbitrary files, but only specific store objects.
-They cannot modify the store in any way, other than creating those store objects.
-This rigid specification of what they do is what allows Nix's caching to be so simple and yet robust.
-
-Based on the above, we can conceptually break derivations down into 3 parts:
-
-1. What command will be run?
-
-2. What existing store objects are needed as inputs?
-
-3. What store objects will be produced as outputs?
-
-## What command will be run?
-
-The original core of Nix was very simple about this, in the mold of traditional Unix.
-Commands consist of 3 parts:
-
-1. Path to executable
-
-2. Arguments (Except for `argv[0]`, which is taken from the path in the usual way)
-
-3. Environment variables.
-
-## What existing store objects are needed as inputs?
-
-The previous sub-section begs the question "how can we be sure the path to the executable points to what we think it does?"
-It's a good questions!
-
-## What store objects will be produced as outputs?
-
-## Extra extensions
-
-### `__structuredAttrs`
-
-Historically speaking, most users of Nix made GNU Bash with a script the command run, regardless of what they were doing.
-Bash variable are automatically created from env vars, but bash also supports array and string-keyed map variables in addition to string variables.
-People also usually create derivations using language which also support these richer data types.
-It was thus desired a way to get this data from the language "planning" the derivation to language to bash, the language evaluated at "run time".
-
-`__structuredAttrs` does this by smuggling inside the core derivation format a map of named richer data.
-At run time, this becomes two things:
-
-1. A JSON file containing that map.
-2. A bash script setting those variables.
-
-The bash command can be passed a script which will "source" that Nix-created bash script, setting those variables with the richer data.
-The outer script can then do whatever it likes with those richer variables as input.
-
-However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers.
-We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer.
diff --git a/doc/manual/src/design/store/drvs/ia.md b/doc/manual/src/design/store/drvs/ia.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/doc/manual/src/design/store/input-addressing.md b/doc/manual/src/design/store/input-addressing.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/design/store/input-addressing.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
diff --git a/doc/manual/src/design/store/nar.md b/doc/manual/src/design/store/nar.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/design/store/nar.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
diff --git a/doc/manual/src/design/store/object-ca.md b/doc/manual/src/design/store/object-ca.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/design/store/object-ca.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
diff --git a/doc/manual/src/design/store/objects.md b/doc/manual/src/design/store/objects.md
deleted file mode 100644
index e4f49a170..000000000
--- a/doc/manual/src/design/store/objects.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Store Objects
-
-Data in Nix is chiefly organized into *store objects*.
-A store object is the pair of
-
-  - A (root) file system object
-  - A set of references to store objects
-
-## File system objects
-
-The Nix store uses a simple filesystem model.
-
-    data FileSystemObject
-      = Regular Executable ByteString
-      | Directory (Map FileName FSO)
-      | SymLink ByteString
-
-    data Executable
-      = Executable
-      | NonExecutable
-
-In particular, every file system object falls into these three cases:
-
- - File: an executable flag, and arbitrary data
-
- - Directory: mapping of names to child file system objects.
-
- - Symlink: may point anywhere.
-
-   In particular, symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
-
-A bare file or symlink as the "root" file system object is allowed.
-
-### Comparison with Git
-
-This is close to Git's model, but with one crucial difference:
-Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
-
-    data GitObject
-      = Blob ByteString
-      | Tree (Map FileName (Persission, FSO))
-
-    data Persission
-      = Directory -- IFF paired with tree
-      -- Iff paired with blob, one of:
-      | RegFile
-      | ExecutableFile
-      | Symlink
-
-So long as the root object is a directory, the representations are isomorphic.
-There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
-
-However, if the root object is a blob, there is loss of fidelity.
-Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
-
-Git's model matches Unix tradition, but Nix's model is more natural.
-
-## References
-
-Store objects can refer to both other store objects and themselves.
-
-Self-reference may seem pointless, but tracking them is in fact useful.
-We can best explain why later after more concepts have been established.
-
-References are normally calculated so as to to record the presence of textual references in store object's file systems obejcts.
-This process will be described precisely in the section on [building](./building.md), once more concepts are explained, as building is the primary path new store objects with non-trivial references are created.
-
-However, scanning for references is not mandatory.
-Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
-and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
-Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
-
-This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
diff --git a/doc/manual/src/design/store/paths.md b/doc/manual/src/design/store/paths.md
deleted file mode 100644
index cf51eb866..000000000
--- a/doc/manual/src/design/store/paths.md
+++ /dev/null
@@ -1,78 +0,0 @@
-# Store Paths
-
-A store path is a pair of a 20-byte digest and a name.
-
-## String representation
-
-A store path is rendered as the concatenation of
-
-  - a store directory
-
-  - a path-separator (`/`)
-
-  - the digest rendered as Base-32 (20 arbitrary bytes becomes 32 ASCII chars)
-
-  - a hyphen (`-`)
-
-  - the name
-
-Let's take the store path from the very beginning of this manual as an example:
-
-    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
-
-This parses like so:
-
-    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
-    ^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
-    store dir  digest                           name
-
-We then can discard the store dir to recover the conceptual pair that is a store path:
-
-    {
-      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
-      name:   "firefox-33.1",
-    }
-
-### Where did the "store directory" come from?
-
-If you notice, the above references a "store directory", but that is *not* part of the definition of a store path.
-We can discard it when parsing, but what about when printing?
-We need to get a store directory from *somewhere*.
-
-The answer is, the store directory is a property of the store that contains the store path.
-The explanation for this is simple enough: a store is notionally mounted as a directory at some location, and the store object's root file system likewise mounted at this path within that directory.
-
-This does, however, mean the string representation of a store path is not derived just from the store path itself, but is in fact "context dependent".
-
-## The digest
-
-The calculation of the digest is quite complicated for historical reasons.
-The details of the algorithms will be discussed later once more concepts have been introduced.
-For now, we just concern ourselves with the *key properties* of those algorithms.
-
-::: {.note}
-**Historical note** The 20 byte restriction is because originally a digests were SHA-1 hashes.
-This is no longer true, but longer hashes and other information are still boiled down to 20 bytes.
-:::
-
-Store paths are either *content-addressed* or *input-addressed*.
-
-::: {.note}
-The former is a standard term used elsewhere.
-The later is our own creation to evoke a contrast with content addressing.
-:::
-
-Content addressing means that the store path digest ultimately derives from referred store object's contents, namely its file system objects and references.
-There is more than one *method* of content-addressing, however.
-Still, if one does know the content addressing schema that was used,
-(or guesses, there isn't that many yet!)
-one can recalculate the store path and thus verify the store object.
-
-Input addressing means that the store path digest derives from how the store path was produced, namely the "inputs" and plan that it was built from.
-Store paths of this sort can *not* be validated from the content of the store object.
-Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
-The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
-
-While metadata is included in the digest calculation explaining which method it was calculated by, this only serves to thwart pre-image attacks.
-That metadata is scrambled with everything else so that it is difficult to tell how a given store path was produced short of a brute-force search.
-In the parlance of referencing schemes, this means that store paths are not "self-describing".
diff --git a/doc/manual/src/design/store/related-work.md b/doc/manual/src/design/store/related-work.md
deleted file mode 100644
index b64b41988..000000000
--- a/doc/manual/src/design/store/related-work.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Advanced Topic: Related Work
-
-## Bazel
-
-TODO skylark and layering.
-
-TODO being monadic, if RFC 92.
-
-## Build Systems à la Carte
-
-TODO user-choosen keys vs keys chosen automatically?
-Purity in face of dynamic tasks (no conflicts, guaranteed).
-
-TODO Does Nix constitute a different way to be be monadic?
-Purity of keys, as mentioned.
-Dynamic tasks/keys vs dynamic dependencies.
-(Not sure yet.)
-
-## Lazy evaluation
-
-We clearly have thunks that produce thunks, but less clearly functions that produce functions.
-
-Do we have open terms?
-
-Do we hve thunks vs expressions distinction?
-c.f. John Shutt's modern fexprs, when the syntax can "leak".
-
-## Machine models
-
-TODO
-Derivations as store objects via drv files makes Nix a "Von Neumann" archicture.
-Can also imagine a "Harvard" archicture where derivations are stored separately?
-Can we in general imagine N heaps for N different sorts of objects?
-
-TODO
-Also, leaning on the notion of "builtin builders" more, having multiple different sorts of user-defined builders too.
-The builder is a black box as far as the Nix model is concerned.
diff --git a/doc/manual/src/design/store/relocatability.md b/doc/manual/src/design/store/relocatability.md
deleted file mode 100644
index c7f869135..000000000
--- a/doc/manual/src/design/store/relocatability.md
+++ /dev/null
@@ -1,15 +0,0 @@
-## Advanced Topic: Store object relocation
-
-Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissible to relocate a store object to a store with a different mount point.
-
-Recall from the section on [store paths](./store-paths.md) that concrete store paths look like `<store-dir>/<hash>-<name>`.
-
-~~The two final restrictions of the previous section yield an alternative view of the same information.~~
-Rather than associating store dirs with the references, we can say a store object itself has a store dir if and only if it has at least one reference.
-
-This corresponds to the observation that a store object with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store object without any references, i.e. thus without a store directory, can exist in any store.
-
-Lastly, this illustrates the purpose of tracking self references.
-Store objects without self-references or other references are relocatable, while store paths with self-references aren't.
-This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
-\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
diff --git a/doc/manual/src/design/store/store.md b/doc/manual/src/design/store/store.md
deleted file mode 100644
index d4add52f5..000000000
--- a/doc/manual/src/design/store/store.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Store
-
-A Nix store is a collection of *store objects* referred to by *store paths*.
-Every store also has a "store directory path", which is a path prefix used for various purposes.
-
-There are many types of stores, but all of them at least respect this model.
-Some however offer additional functionality.
-
-## A Rosetta stone for the Nix store.
-
-The design of Nix is comparable to other build systems, even programming languages in general.
-Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
-If you are familiar with one of these columns, this might help the following sections make more sense.
-
-generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
--- | -- | -- | -- | --
-data (build input, build result) | component | file (source, target) | value | value
-build plan | derivation graph | action graph | `Tasks` | thunk
-build step | derivation | rule | `Task` | thunk
-build instructions | builder | (depends on action type) | `Task` | function
-build | build | build | `Build` applied to arguments | evaluation
-persistence layer | store | file system | `Store` | heap
-
-(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)
-
-Plenty more could be said elaborating these comparisons.
-We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.
-- 
cgit v1.2.3


From c8c1b705ad5cdf115997cef387d83c4b04fe0660 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Sun, 24 Apr 2022 21:34:33 +0200
Subject: reword section on Nix store

---
 doc/manual/src/architecture/store/store.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index d4add52f5..b52fe8255 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -1,10 +1,14 @@
 # Store
 
-A Nix store is a collection of *store objects* referred to by *store paths*.
-Every store also has a "store directory path", which is a path prefix used for various purposes.
+A Nix store is a collection of [store objects](objects.md) and associated operations.
 
-There are many types of stores, but all of them at least respect this model.
-Some however offer additional functionality.
+These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
+
+Store objects are accessible in a file system through [store paths](paths.md).
+Every store has a *store directory*, which contains that store’s objects and is a prefix of their store paths.
+It defaults to `/nix/store`, but is in principle arbitrary.
+
+A Nix store can perform builds, that is, transform build inputs using instructions from the build plans into build outputs. It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
 
 ## A Rosetta stone for the Nix store.
 
-- 
cgit v1.2.3


From 7b5c00f67f729bb3c0d026f3f4d14e727c4cf420 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 01:15:27 +0200
Subject: add concrete store examples, reword note on file system

---
 doc/manual/src/architecture/store/store.md | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index b52fe8255..688c7e1a2 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -4,11 +4,18 @@ A Nix store is a collection of [store objects](objects.md) and associated operat
 
 These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
 
-Store objects are accessible in a file system through [store paths](paths.md).
-Every store has a *store directory*, which contains that store’s objects and is a prefix of their store paths.
-It defaults to `/nix/store`, but is in principle arbitrary.
-
-A Nix store can perform builds, that is, transform build inputs using instructions from the build plans into build outputs. It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
+A Nix store allows to add and retrieve store objects.
+It can perform builds, that is, transform build inputs using instructions from the build plans into build outputs.
+It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
+
+There exist different types of stores, which all follow this model.
+Examples:
+- store on the local file system
+- remote store accessible via SSH
+- binary cache store accessible via HTTP
+
+Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
+The store directory defaults to `/nix/store`, but is in principle arbitrary.
 
 ## A Rosetta stone for the Nix store.
 
-- 
cgit v1.2.3


From 070c85499b370bf886db1a87c04ed9c319bb6323 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 28 Apr 2022 09:44:46 +0200
Subject: fix grammar

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 688c7e1a2..96796f26c 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -4,7 +4,7 @@ A Nix store is a collection of [store objects](objects.md) and associated operat
 
 These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
 
-A Nix store allows to add and retrieve store objects.
+A Nix store allows adding and retrieving store objects.
 It can perform builds, that is, transform build inputs using instructions from the build plans into build outputs.
 It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
 
-- 
cgit v1.2.3


From 5f96a0b4e830bef59b5986c916727d07b244c22c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 28 Apr 2022 23:18:03 +0200
Subject: associated operations are not collected

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 96796f26c..624439f73 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -1,6 +1,6 @@
 # Store
 
-A Nix store is a collection of [store objects](objects.md) and associated operations.
+A Nix store is a collection of [store objects](objects.md) with associated operations.
 
 These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
 
-- 
cgit v1.2.3


From 610ddf44aa86924834bf2ac3735c7cb75a6a1f1c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 25 Apr 2022 13:25:43 +0200
Subject: reword introduction to rosetta stone, add links

attempt to explain used and documented terminology, as well as how
the declarative programming paradigm relates to building software.

in the future one could highlight encouraged terms to shape future
material into higher consistency.
---
 doc/manual/src/architecture/architecture.md |  2 +-
 doc/manual/src/architecture/store/store.md  | 31 ++++++++++++++---------------
 2 files changed, 16 insertions(+), 17 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index b17eacd2e..836b40c91 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -27,7 +27,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build steps*, used to derive *build results* from referenced *build inputs*.
+It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 624439f73..af0609d4b 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -17,22 +17,21 @@ Examples:
 Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
 The store directory defaults to `/nix/store`, but is in principle arbitrary.
 
-## A Rosetta stone for the Nix store.
+## A [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology
 
-The design of Nix is comparable to other build systems, even programming languages in general.
-Here is a rough [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology.
-If you are familiar with one of these columns, this might help the following sections make more sense.
+The Nix store's design is comparable to other build systems.
+Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
 
-generic build system | Nix | Bazel | Build Systems à la Carte | lazy programming language
--- | -- | -- | -- | --
-data (build input, build result) | component | file (source, target) | value | value
-build plan | derivation graph | action graph | `Tasks` | thunk
-build step | derivation | rule | `Task` | thunk
-build instructions | builder | (depends on action type) | `Task` | function
-build | build | build | `Build` applied to arguments | evaluation
-persistence layer | store | file system | `Store` | heap
-
-(n.b. Bazel terms gotten from https://docs.bazel.build/versions/main/glossary.html.)
+The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
 
-Plenty more could be said elaborating these comparisons.
-We will save that for the end of this chapter, in the [Related Work](./related-work.md) section.
+generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) | programming language
+-- | -- | -- | -- | --
+data (build input, build result) | component | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
+build plan | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
+build graph | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
+build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | `Task` | function
+build | realisation | build | application of `Build` | evaluation
+persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
+
+All of these systems share features of [declarative programming](https://en.m.wikipedia.org/wiki/Declarative_programming) languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment](https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf) (2004), elaborated in his PhD thesis [The Purely Functional Software
+Deployment Model](https://edolstra.github.io/pubs/phd-thesis.pdf) (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) (2018).
-- 
cgit v1.2.3


From ca5ebf63827f82ae63796d775070b2f9cf828625 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 23:34:53 +0200
Subject: revert build plan/step distinction, reorder rows

---
 doc/manual/src/architecture/store/store.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index af0609d4b..f4f5a3e16 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -27,9 +27,9 @@ The following translation table points out similarities and equivalent terms, to
 generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) | programming language
 -- | -- | -- | -- | --
 data (build input, build result) | component | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
-build plan | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
-build graph | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
 build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | `Task` | function
+build step | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
+build plan | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
 build | realisation | build | application of `Build` | evaluation
 persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
 
-- 
cgit v1.2.3


From 40efe5b30b24e75b26017eb68c62acfc6b7ebf93 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 23:36:36 +0200
Subject: build instrcution: Task -> function

---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index f4f5a3e16..e851444c9 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -27,7 +27,7 @@ The following translation table points out similarities and equivalent terms, to
 generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) | programming language
 -- | -- | -- | -- | --
 data (build input, build result) | component | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
-build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | `Task` | function
+build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | function | function
 build step | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
 build plan | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
 build | realisation | build | application of `Build` | evaluation
-- 
cgit v1.2.3


From a145007a577fda8a8f3b65b66f4c359410b4af82 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 23:48:59 +0200
Subject: component -> store object, realisation -> build

---
 doc/manual/src/architecture/store/store.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index e851444c9..74d3d7f84 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -26,11 +26,11 @@ The following translation table points out similarities and equivalent terms, to
 
 generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) | programming language
 -- | -- | -- | -- | --
-data (build input, build result) | component | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
+data (build input, build result) | store object | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
 build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | function | function
 build step | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
 build plan | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
-build | realisation | build | application of `Build` | evaluation
+build | build | build | application of `Build` | evaluation
 persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
 
 All of these systems share features of [declarative programming](https://en.m.wikipedia.org/wiki/Declarative_programming) languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment](https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf) (2004), elaborated in his PhD thesis [The Purely Functional Software
-- 
cgit v1.2.3


From e5e48593c85d052585ff8a275c54823caf575a9d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 10:16:27 +0200
Subject: move git comparison to related work

it should be pulled out of the branch before we go for merging
---
 doc/manual/src/architecture/store/objects.md      | 23 ----------------------
 doc/manual/src/architecture/store/related-work.md | 24 +++++++++++++++++++++++
 2 files changed, 24 insertions(+), 23 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index e4f49a170..caa00d862 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -31,29 +31,6 @@ In particular, every file system object falls into these three cases:
 
 A bare file or symlink as the "root" file system object is allowed.
 
-### Comparison with Git
-
-This is close to Git's model, but with one crucial difference:
-Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
-
-    data GitObject
-      = Blob ByteString
-      | Tree (Map FileName (Persission, FSO))
-
-    data Persission
-      = Directory -- IFF paired with tree
-      -- Iff paired with blob, one of:
-      | RegFile
-      | ExecutableFile
-      | Symlink
-
-So long as the root object is a directory, the representations are isomorphic.
-There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
-
-However, if the root object is a blob, there is loss of fidelity.
-Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
-
-Git's model matches Unix tradition, but Nix's model is more natural.
 
 ## References
 
diff --git a/doc/manual/src/architecture/store/related-work.md b/doc/manual/src/architecture/store/related-work.md
index b64b41988..92b7d480e 100644
--- a/doc/manual/src/architecture/store/related-work.md
+++ b/doc/manual/src/architecture/store/related-work.md
@@ -25,6 +25,30 @@ Do we have open terms?
 Do we hve thunks vs expressions distinction?
 c.f. John Shutt's modern fexprs, when the syntax can "leak".
 
+## Comparison with Git file system model
+
+This is close to Git's model, but with one crucial difference:
+Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
+
+    data GitObject
+      = Blob ByteString
+      | Tree (Map FileName (Persission, FSO))
+
+    data Persission
+      = Directory -- IFF paired with tree
+      -- Iff paired with blob, one of:
+      | RegFile
+      | ExecutableFile
+      | Symlink
+
+So long as the root object is a directory, the representations are isomorphic.
+There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
+
+However, if the root object is a blob, there is loss of fidelity.
+Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
+
+Git's model matches Unix tradition, but Nix's model is more natural.
+
 ## Machine models
 
 TODO
-- 
cgit v1.2.3


From 90fc5b41a83575c0bd008868f989b6e1497ce3a5 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 10:18:23 +0200
Subject: reword file system objects

- use singular for the "class"
- more consistency in type definition
- minor fixes in wording
---
 doc/manual/src/architecture/store/objects.md | 40 +++++++++++-----------------
 1 file changed, 16 insertions(+), 24 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index caa00d862..872a209c3 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -1,40 +1,32 @@
-# Store Objects
+# Store Object
 
-Data in Nix is chiefly organized into *store objects*.
+Nix organizes the data it manages into *store objects*.
 A store object is the pair of
 
-  - A (root) file system object
-  - A set of references to store objects
+  - a [file system object](#file-system-object)
+  - a set of [references](#reference) to store objects.
 
-## File system objects
+## File system object {#file-system-object}
 
-The Nix store uses a simple filesystem model.
+The Nix store uses a simple file system model.
 
     data FileSystemObject
-      = Regular Executable ByteString
-      | Directory (Map FileName FSO)
-      | SymLink ByteString
-
-    data Executable
-      = Executable
-      | NonExecutable
-
-In particular, every file system object falls into these three cases:
+      = File Executable Data
+      | Directory (Map FileName FileSystemObject)
+      | SymLink Path
 
+Every file system object is one of the following:
  - File: an executable flag, and arbitrary data
+ - Directory: mapping of names to child file system objects
+ - [Symbolic link](https://en.m.wikipedia.org/wiki/Symbolic_link): may point anywhere.
 
- - Directory: mapping of names to child file system objects.
-
- - Symlink: may point anywhere.
-
-   In particular, symlinks that do not point within the containing root file system object or that of another store object referenced by the containing store object are allowed, but might not function as intended.
-
-A bare file or symlink as the "root" file system object is allowed.
+   In particular, symlinks pointing outside of their own root file system object, or to a store object without a matching reference, are allowed, but might not function as intended.
 
+A bare file or symlink can be a root file system object.
 
-## References
+## Reference {#reference}
 
-Store objects can refer to both other store objects and themselves.
+A store object can refer to both other store objects and itself.
 
 Self-reference may seem pointless, but tracking them is in fact useful.
 We can best explain why later after more concepts have been established.
-- 
cgit v1.2.3


From fb2ec7e4ec758e17f247218625d23ceba685e8a5 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 28 Apr 2022 10:54:51 +0200
Subject: reword section on references

use file Contents instead of Data, as that flows more naturally in the
prose.

simplify explanation of the idea behind scanning for store paths

remove references to unfinished sections.
---
 doc/manual/src/architecture/store/objects.md | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index 872a209c3..d7a27b528 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -11,12 +11,12 @@ A store object is the pair of
 The Nix store uses a simple file system model.
 
     data FileSystemObject
-      = File Executable Data
+      = File Executable Contents
       | Directory (Map FileName FileSystemObject)
       | SymLink Path
 
 Every file system object is one of the following:
- - File: an executable flag, and arbitrary data
+ - File: an executable flag, and arbitrary data for contents
  - Directory: mapping of names to child file system objects
  - [Symbolic link](https://en.m.wikipedia.org/wiki/Symbolic_link): may point anywhere.
 
@@ -26,17 +26,16 @@ A bare file or symlink can be a root file system object.
 
 ## Reference {#reference}
 
-A store object can refer to both other store objects and itself.
+A store object can refer to other store objects or itself.
 
-Self-reference may seem pointless, but tracking them is in fact useful.
-We can best explain why later after more concepts have been established.
+Nix collects these references by scanning file contents for [store paths](./paths.md) when a new store object is created.
 
-References are normally calculated so as to to record the presence of textual references in store object's file systems obejcts.
-This process will be described precisely in the section on [building](./building.md), once more concepts are explained, as building is the primary path new store objects with non-trivial references are created.
+While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness:
+Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
 
-However, scanning for references is not mandatory.
-Store objects are allowed to have official references that *don't* correspond to store paths contained in their contents,
-and they are also allowed to *not* have references that *do* correspond to store paths contained in their store.
-Taken together, this means there is no actual rule relating the store paths contained in the contents to the store paths deemed references.
+However, having references match store paths in files is not enforced by the data model:
+Store objects could have excess or incomplete references with respect to store paths found in their file contents.
+
+Scanning files therefore allows reliably capturing run time dependencies without declaring them explicitly.
+Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
 
-This is why it's its necessary for correctness, and not just performance, that Nix remember the references of each store object, rather than try to recompute them on the fly by scanning their contents.
-- 
cgit v1.2.3


From 5fda995491f1f6b32b46b45c2b47f3e329c997f6 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 29 Apr 2022 00:24:23 +0200
Subject: formalize file system objects

convention: describe every data type in prose, and illustrate with
a class diagram, and a textual representation of an abstract
data type.

right now we save ourselves the trouble of doing class diagrams, we can
add them later. but they are important.
---
 doc/manual/src/architecture/store/objects.md | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index d7a27b528..7f341c87c 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -6,31 +6,42 @@ A store object is the pair of
   - a [file system object](#file-system-object)
   - a set of [references](#reference) to store objects.
 
+We call a store object's outermost file system object the *root*.
+
+```haskell
+data StoreOject = StoreObject {
+  root       :: FileSystemObject
+, references :: Set StoreObject
+}
+```
+
 ## File system object {#file-system-object}
 
 The Nix store uses a simple file system model.
 
-    data FileSystemObject
-      = File Executable Contents
-      | Directory (Map FileName FileSystemObject)
-      | SymLink Path
-
 Every file system object is one of the following:
  - File: an executable flag, and arbitrary data for contents
  - Directory: mapping of names to child file system objects
  - [Symbolic link](https://en.m.wikipedia.org/wiki/Symbolic_link): may point anywhere.
 
-   In particular, symlinks pointing outside of their own root file system object, or to a store object without a matching reference, are allowed, but might not function as intended.
+```haskell
+data FileSystemObject
+  = File { isExecutable :: Bool, contents :: Bytes }
+  | Directory { entries ::  Map FileName FileSystemObject }
+  | SymLink { target :: Path }
+```
 
 A bare file or symlink can be a root file system object.
 
+Symlinks pointing outside of their own root, or to a store object without a matching reference, are allowed, but might not function as intended.
+
 ## Reference {#reference}
 
 A store object can refer to other store objects or itself.
 
 Nix collects these references by scanning file contents for [store paths](./paths.md) when a new store object is created.
 
-While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness:
+While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
 Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
 
 However, having references match store paths in files is not enforced by the data model:
-- 
cgit v1.2.3


From 07d490fd895b09144684dd8b389ef02f0f1256c4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 29 Apr 2022 00:58:40 +0200
Subject: stores can also delete objects

---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 74d3d7f84..cbb5a4169 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -4,7 +4,7 @@ A Nix store is a collection of [store objects](objects.md) with associated opera
 
 These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
 
-A Nix store allows adding and retrieving store objects.
+A Nix store allows adding, retrieving, and deleting store objects.
 It can perform builds, that is, transform build inputs using instructions from the build plans into build outputs.
 It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
 
-- 
cgit v1.2.3


From e90586c0a40cf59df9d39407dcc49d5944a8b853 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 29 Apr 2022 01:15:33 +0200
Subject: add motivation for references

---
 doc/manual/src/architecture/store/objects.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index 7f341c87c..30683d22d 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -37,9 +37,20 @@ Symlinks pointing outside of their own root, or to a store object without a matc
 
 ## Reference {#reference}
 
-A store object can refer to other store objects or itself.
+A store object can reference other store objects.
 
-Nix collects these references by scanning file contents for [store paths](./paths.md) when a new store object is created.
+Nix stores have the *closure property*: for each store object in the store, all the store objects it references must also be in the store.
+
+Building, copying and deleting store objects must be done in a way that obeys this property:
+
+- We can only safely delete unreferenced objects.
+
+- When copying, to maintain correctness, either the result must be "revealed" atomically to the destination store, or objects must be copied in reference-dependency order.
+
+- Newly built store objects must only refer to store objects in the closure of the build inputs.
+  This ensures the purity of the build.
+
+### Reference scanning
 
 While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
 Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
-- 
cgit v1.2.3


From b5ca3d12b6f3414302363c8ae362334c020448c7 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 29 Apr 2022 02:10:24 +0200
Subject: reword details on keeping closure property

---
 doc/manual/src/architecture/store/objects.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index 30683d22d..f7587e112 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -43,12 +43,12 @@ Nix stores have the *closure property*: for each store object in the store, all
 
 Building, copying and deleting store objects must be done in a way that obeys this property:
 
-- We can only safely delete unreferenced objects.
+- Build results must only refer to store objects in the closure of the build inputs.
 
-- When copying, to maintain correctness, either the result must be "revealed" atomically to the destination store, or objects must be copied in reference-dependency order.
+- Store objects being copied must refer to objects already in the destination store.
+  Recursive copying must either proceed in dependency order or be atomic.
 
-- Newly built store objects must only refer to store objects in the closure of the build inputs.
-  This ensures the purity of the build.
+- We can only safely delete unreferenced objects.
 
 ### Reference scanning
 
-- 
cgit v1.2.3


From b01bb65d3023281c601024578a9c19f32e7ad011 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 28 Apr 2022 21:41:04 -0400
Subject: Fix rel path in doc

---
 doc/manual/src/architecture/store/building.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/building.md b/doc/manual/src/architecture/store/building.md
index f4f2649a3..d43904126 100644
--- a/doc/manual/src/architecture/store/building.md
+++ b/doc/manual/src/architecture/store/building.md
@@ -2,7 +2,7 @@
 
 ## Scanning for references
 
-Before in the section on [store objects](../objects.md), we talked abstractly about scanning for references.
+Before in the section on [store objects](./objects.md), we talked abstractly about scanning for references.
 Now we can make this concrete.
 
 After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
-- 
cgit v1.2.3


From 3d8f2f5cc1faa4d42138267f21d2996da99c49a4 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 28 Apr 2022 17:53:10 -0400
Subject: Fix manual TOC links

---
 doc/manual/src/SUMMARY.md.in | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index c029e30bf..80a228741 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -16,17 +16,17 @@
   - [Environment Variables](installation/env-variables.md)
   - [Upgrading Nix](installation/upgrading.md)
 - [Architecture](architecture/architecture.md)
-  - [Store](design/store/store.md)
-    - [Store Objects](design/store/objects.md)
-    - [Store Paths](design/store/paths.md)
-    - [Nix Archives](design/store/nar.md)
-    - [Content-Addressing Store Objects](design/store/object-ca.md)
-    - [Derivations](design/store/drvs/drvs.md)
-      - [Input-Addressing](design/store/drvs/ia.md)
-      - [Content-Addressing (Experimental)](design/store/drvs/ca.md)
-    - [Building](design/store/building.md)
-    - [Advanced Topic: Store object relocatability](design/store/relocatability.md)
-    - [Advanced Topic: Related work](design/store/related-work.md)
+  - [Store](architecture/store/store.md)
+    - [Store Objects](architecture/store/objects.md)
+    - [Store Paths](architecture/store/paths.md)
+    - [Nix Archives](architecture/store/nar.md)
+    - [Content-Addressing Store Objects](architecture/store/object-ca.md)
+    - [Derivations](architecture/store/drvs/drvs.md)
+      - [Input-Addressing](architecture/store/drvs/ia.md)
+      - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
+    - [Building](architecture/store/building.md)
+    - [Advanced Topic: Store object relocatability](architecture/store/relocatability.md)
+    - [Advanced Topic: Related work](architecture/store/related-work.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
-- 
cgit v1.2.3


From 1ba6d8fb1d59f4d40825141f75098dfbfd3b0153 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 13:53:37 +0200
Subject: remove incomplete section: building

---
 doc/manual/src/SUMMARY.md.in                  |  1 -
 doc/manual/src/architecture/store/building.md | 15 ---------------
 2 files changed, 16 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/building.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 80a228741..596843057 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -24,7 +24,6 @@
     - [Derivations](architecture/store/drvs/drvs.md)
       - [Input-Addressing](architecture/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
-    - [Building](architecture/store/building.md)
     - [Advanced Topic: Store object relocatability](architecture/store/relocatability.md)
     - [Advanced Topic: Related work](architecture/store/related-work.md)
 - [Package Management](package-management/package-management.md)
diff --git a/doc/manual/src/architecture/store/building.md b/doc/manual/src/architecture/store/building.md
deleted file mode 100644
index d43904126..000000000
--- a/doc/manual/src/architecture/store/building.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# Building
-
-## Scanning for references
-
-Before in the section on [store objects](./objects.md), we talked abstractly about scanning for references.
-Now we can make this concrete.
-
-After the derivation's command is run, Nix needs to process the "raw" output directories to turn them into legit store objects.
-There is a few steps of this, but let's start with the simple case of one input-addressed output first.
-
-\[Overview of things that need to happen.]
-
-For example, if Nix thinks `/nix/store/asdfasdfasdf-foo` and `/nix/store/qwerqwerqwer-bar` are paths the data might plausibly reference, Nix will scan all the contents of all files recursively for the "hash parts" `asdfasdfasdf`` and `qwerqwerqwer`.
-
-\[Explain why whitelist.]
-- 
cgit v1.2.3


From 96876b1eaeae95e3f2f338c6b3495040fc843c57 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 13:54:06 +0200
Subject: remove incomplete section: related work

---
 doc/manual/src/SUMMARY.md.in                      |  1 -
 doc/manual/src/architecture/store/related-work.md | 61 -----------------------
 2 files changed, 62 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/related-work.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 596843057..ee7f5d7ac 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -25,7 +25,6 @@
       - [Input-Addressing](architecture/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
     - [Advanced Topic: Store object relocatability](architecture/store/relocatability.md)
-    - [Advanced Topic: Related work](architecture/store/related-work.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/architecture/store/related-work.md b/doc/manual/src/architecture/store/related-work.md
deleted file mode 100644
index 92b7d480e..000000000
--- a/doc/manual/src/architecture/store/related-work.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Advanced Topic: Related Work
-
-## Bazel
-
-TODO skylark and layering.
-
-TODO being monadic, if RFC 92.
-
-## Build Systems à la Carte
-
-TODO user-choosen keys vs keys chosen automatically?
-Purity in face of dynamic tasks (no conflicts, guaranteed).
-
-TODO Does Nix constitute a different way to be be monadic?
-Purity of keys, as mentioned.
-Dynamic tasks/keys vs dynamic dependencies.
-(Not sure yet.)
-
-## Lazy evaluation
-
-We clearly have thunks that produce thunks, but less clearly functions that produce functions.
-
-Do we have open terms?
-
-Do we hve thunks vs expressions distinction?
-c.f. John Shutt's modern fexprs, when the syntax can "leak".
-
-## Comparison with Git file system model
-
-This is close to Git's model, but with one crucial difference:
-Git puts the "permission" info within the directory map's values instead of making it part of the file (blob, in it's parlance) object.
-
-    data GitObject
-      = Blob ByteString
-      | Tree (Map FileName (Persission, FSO))
-
-    data Persission
-      = Directory -- IFF paired with tree
-      -- Iff paired with blob, one of:
-      | RegFile
-      | ExecutableFile
-      | Symlink
-
-So long as the root object is a directory, the representations are isomorphic.
-There is no "wiggle room" the git way since whenever the permission info wouldn't matter (e.g. the child object being mapped to is a directory), the permission info must be a sentinel value.
-
-However, if the root object is a blob, there is loss of fidelity.
-Since the permission info is used to distinguish executable files, non-executable files, and symlinks, but there isn't a "parent" directory of the root to contain that info, these 3 cases cannot be distinguished.
-
-Git's model matches Unix tradition, but Nix's model is more natural.
-
-## Machine models
-
-TODO
-Derivations as store objects via drv files makes Nix a "Von Neumann" archicture.
-Can also imagine a "Harvard" archicture where derivations are stored separately?
-Can we in general imagine N heaps for N different sorts of objects?
-
-TODO
-Also, leaning on the notion of "builtin builders" more, having multiple different sorts of user-defined builders too.
-The builder is a black box as far as the Nix model is concerned.
-- 
cgit v1.2.3


From 7cec9ee3612c7255e6dc4fb94fc238f3d81ced03 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 13:54:24 +0200
Subject: remove incomplete section: relocatability

---
 doc/manual/src/SUMMARY.md.in                        |  1 -
 doc/manual/src/architecture/store/relocatability.md | 15 ---------------
 2 files changed, 16 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/relocatability.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index ee7f5d7ac..c35505bbe 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -24,7 +24,6 @@
     - [Derivations](architecture/store/drvs/drvs.md)
       - [Input-Addressing](architecture/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
-    - [Advanced Topic: Store object relocatability](architecture/store/relocatability.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/architecture/store/relocatability.md b/doc/manual/src/architecture/store/relocatability.md
deleted file mode 100644
index c7f869135..000000000
--- a/doc/manual/src/architecture/store/relocatability.md
+++ /dev/null
@@ -1,15 +0,0 @@
-## Advanced Topic: Store object relocation
-
-Now that we know the fundamentals of the design of the Nix store, let's explore one consequence of that design: the question when it is permissible to relocate a store object to a store with a different mount point.
-
-Recall from the section on [store paths](./store-paths.md) that concrete store paths look like `<store-dir>/<hash>-<name>`.
-
-~~The two final restrictions of the previous section yield an alternative view of the same information.~~
-Rather than associating store dirs with the references, we can say a store object itself has a store dir if and only if it has at least one reference.
-
-This corresponds to the observation that a store object with references, i.e. with a store directory under this interpretation, is confined to stores sharing that same store directory, but a store object without any references, i.e. thus without a store directory, can exist in any store.
-
-Lastly, this illustrates the purpose of tracking self references.
-Store objects without self-references or other references are relocatable, while store paths with self-references aren't.
-This is used to tell apart e.g. source code which can be stored anywhere, and pesky non-reloctable executables which assume they are installed to a certain path.
-\[The default method of calculating references by scanning for store paths handles these two example cases surprisingly well.\]
-- 
cgit v1.2.3


From b18852eb3fc1d62ec307d3b2f102c6bd8574d069 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 13:55:11 +0200
Subject: remove incomplete section: content-addressed objects

---
 doc/manual/src/SUMMARY.md.in                   | 1 -
 doc/manual/src/architecture/store/object-ca.md | 1 -
 2 files changed, 2 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/object-ca.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index c35505bbe..11a974b47 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -20,7 +20,6 @@
     - [Store Objects](architecture/store/objects.md)
     - [Store Paths](architecture/store/paths.md)
     - [Nix Archives](architecture/store/nar.md)
-    - [Content-Addressing Store Objects](architecture/store/object-ca.md)
     - [Derivations](architecture/store/drvs/drvs.md)
       - [Input-Addressing](architecture/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
diff --git a/doc/manual/src/architecture/store/object-ca.md b/doc/manual/src/architecture/store/object-ca.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/architecture/store/object-ca.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
-- 
cgit v1.2.3


From 3bd125ebbeae38c9efb5790e13265b7534e66c45 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 13:55:52 +0200
Subject: remove incomplete section: nix archives

---
 doc/manual/src/SUMMARY.md.in             | 1 -
 doc/manual/src/architecture/store/nar.md | 1 -
 2 files changed, 2 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/nar.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 11a974b47..38277aaf2 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -19,7 +19,6 @@
   - [Store](architecture/store/store.md)
     - [Store Objects](architecture/store/objects.md)
     - [Store Paths](architecture/store/paths.md)
-    - [Nix Archives](architecture/store/nar.md)
     - [Derivations](architecture/store/drvs/drvs.md)
       - [Input-Addressing](architecture/store/drvs/ia.md)
       - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
diff --git a/doc/manual/src/architecture/store/nar.md b/doc/manual/src/architecture/store/nar.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/architecture/store/nar.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
-- 
cgit v1.2.3


From ad8c2ed7f0566a5fe1b4a3591240eb06804bd958 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 13:59:03 +0200
Subject: remove incomplete section: input/content-addressing

---
 doc/manual/src/SUMMARY.md.in                          | 2 --
 doc/manual/src/architecture/store/drvs/ca.md          | 0
 doc/manual/src/architecture/store/drvs/ia.md          | 0
 doc/manual/src/architecture/store/input-addressing.md | 1 -
 4 files changed, 3 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/drvs/ca.md
 delete mode 100644 doc/manual/src/architecture/store/drvs/ia.md
 delete mode 100644 doc/manual/src/architecture/store/input-addressing.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 38277aaf2..257880efe 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -20,8 +20,6 @@
     - [Store Objects](architecture/store/objects.md)
     - [Store Paths](architecture/store/paths.md)
     - [Derivations](architecture/store/drvs/drvs.md)
-      - [Input-Addressing](architecture/store/drvs/ia.md)
-      - [Content-Addressing (Experimental)](architecture/store/drvs/ca.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/architecture/store/drvs/ca.md b/doc/manual/src/architecture/store/drvs/ca.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/doc/manual/src/architecture/store/drvs/ia.md b/doc/manual/src/architecture/store/drvs/ia.md
deleted file mode 100644
index e69de29bb..000000000
diff --git a/doc/manual/src/architecture/store/input-addressing.md b/doc/manual/src/architecture/store/input-addressing.md
deleted file mode 100644
index 1333ed77b..000000000
--- a/doc/manual/src/architecture/store/input-addressing.md
+++ /dev/null
@@ -1 +0,0 @@
-TODO
-- 
cgit v1.2.3


From d3effd014b17bc957b9af8ed35b2f25a3b54e02c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 14:05:46 +0200
Subject: update architecture diagram

---
 doc/manual/src/architecture/architecture.md | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 836b40c91..25b6a9616 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -8,20 +8,20 @@ It should help users understand why Nix behaves as it does, and it should help d
 Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers).
 
 ```
-               [ commmand line interface ]
-                            |
-                            | evaluates
-                            V
-               [ configuration language  ]
-                            |
-                            | evaluates to
-                            |
-              reference     V       build
-[ build inputs ] --> [ build plans ] --> [ build results ]
-          \                 |                 /
-            \               | persisted to  /
-              \             V             /
-              [           store           ]
+                   [ commmand line interface ]--------+
+                                |                     |
+                                | evaluates           | manages
+                                V                     |
+                   [ configuration language  ]        |
+                                |                     V
++-------------------------------|---------------------------------+
+| store                         |                                 |
+|                               | evaluates to                    |
+|                               |                                 |
+|                  references   V       builds                    |
+|     [ build input ] --> [ build plan ] --> [ build result ]     |
+|                                                                 |
++-----------------------------------------------------------------+
 ```
 
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
-- 
cgit v1.2.3


From 87523f01e3dc27d4cf57354a67346f8473e93cc5 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 10 May 2022 12:27:44 +0200
Subject: match grammatical case to arrow direction

---
 doc/manual/src/architecture/architecture.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 25b6a9616..a0aa713f3 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -18,8 +18,8 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 | store                         |                                 |
 |                               | evaluates to                    |
 |                               |                                 |
-|                  references   V       builds                    |
-|     [ build input ] --> [ build plan ] --> [ build result ]     |
+|               referenced by   V       builds                    |
+|   [ build input ] ----> [ build plan ] ----> [ build result ]   |
 |                                                                 |
 +-----------------------------------------------------------------+
 ```
-- 
cgit v1.2.3


From 902638c519fb46b0f0a3f7092ccb7cd2a622b206 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 3 May 2022 14:06:51 +0200
Subject: build step -> build rule

"step" sounds atomic, while "rule" hints at internal structure, which in
our case consists of mapping inputs to outputs using build instructions.
---
 doc/manual/src/architecture/architecture.md | 7 ++++---
 doc/manual/src/architecture/store/store.md  | 6 +++---
 2 files changed, 7 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index a0aa713f3..81348c570 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -27,7 +27,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+It is used to compose expressions which ultimately evaluate to self-contained *build rules*, used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
@@ -37,6 +37,7 @@ In practice this amounts to a set of files in a file system.
 
 The command line and Nix language are what users interact with most.
 
-Underlying everything is the *Nix store*, a mechanism to keep track of build plans, data, and references between them.
-It can also execute *build instructions*, captured in the build plans, to produce new data.
+Underlying everything is the *Nix store*, a mechanism to keep track of build rules, data, and references between them.
+It can also execute *build instructions*, captured in the build rules, to produce new data.
 
+A series of build rules is a *build plan*.
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index cbb5a4169..b03aa690e 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -2,10 +2,10 @@
 
 A Nix store is a collection of [store objects](objects.md) with associated operations.
 
-These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build plans.
+These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build rules.
 
 A Nix store allows adding, retrieving, and deleting store objects.
-It can perform builds, that is, transform build inputs using instructions from the build plans into build outputs.
+It can perform builds, that is, transform build inputs using instructions from the build rules into build outputs.
 It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
 
 There exist different types of stores, which all follow this model.
@@ -28,7 +28,7 @@ generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [B
 -- | -- | -- | -- | --
 data (build input, build result) | store object | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
 build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | function | function
-build step | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
+build rule | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
 build plan | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
 build | build | build | application of `Build` | evaluation
 persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
-- 
cgit v1.2.3


From 2a8532fb61ba2b988448e93f5074590e40df7e04 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 9 May 2022 16:39:26 +0200
Subject: build rule -> build task

closer to "build systems a la carte", satisfies all other complaints
---
 doc/manual/src/architecture/architecture.md | 10 +++++-----
 doc/manual/src/architecture/store/store.md  |  6 +++---
 2 files changed, 8 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 81348c570..407e8d0f8 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -19,7 +19,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 |                               | evaluates to                    |
 |                               |                                 |
 |               referenced by   V       builds                    |
-|   [ build input ] ----> [ build plan ] ----> [ build result ]   |
+|     [ build input ] --> [ build task ] --> [ build result ]     |
 |                                                                 |
 +-----------------------------------------------------------------+
 ```
@@ -27,7 +27,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build rules*, used to derive *build results* from referenced *build inputs*.
+It is used to compose expressions which ultimately evaluate to self-contained *build tasks*, used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
@@ -37,7 +37,7 @@ In practice this amounts to a set of files in a file system.
 
 The command line and Nix language are what users interact with most.
 
-Underlying everything is the *Nix store*, a mechanism to keep track of build rules, data, and references between them.
-It can also execute *build instructions*, captured in the build rules, to produce new data.
+Underlying everything is the *Nix store*, a mechanism to keep track of build tasks, data, and references between them.
+It can also execute *build instructions*, captured in the build tasks, to produce new data.
 
-A series of build rules is a *build plan*.
+A series of build tasks is a *build plan*.
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index b03aa690e..cc6698a40 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -2,10 +2,10 @@
 
 A Nix store is a collection of [store objects](objects.md) with associated operations.
 
-These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build rules.
+These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build tasks.
 
 A Nix store allows adding, retrieving, and deleting store objects.
-It can perform builds, that is, transform build inputs using instructions from the build rules into build outputs.
+It can perform builds, that is, transform build inputs using instructions from the build tasks into build outputs.
 It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
 
 There exist different types of stores, which all follow this model.
@@ -28,7 +28,7 @@ generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [B
 -- | -- | -- | -- | --
 data (build input, build result) | store object | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
 build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | function | function
-build rule | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
+build task | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
 build plan | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
 build | build | build | application of `Build` | evaluation
 persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
-- 
cgit v1.2.3


From 689b32a543240db992c9e8240401f32bd39e6736 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 12 May 2022 12:30:28 +0200
Subject: clarify relation of tasks and plans

---
 doc/manual/src/architecture/architecture.md | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 407e8d0f8..e8d87f8ae 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -13,21 +13,21 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
                                 | evaluates           | manages
                                 V                     |
                    [ configuration language  ]        |
-                                |                     V
-+-------------------------------|---------------------------------+
-| store                         |                                 |
-|                               | evaluates to                    |
-|                               |                                 |
-|               referenced by   V       builds                    |
-|     [ build input ] --> [ build task ] --> [ build result ]     |
-|                                                                 |
+                                |                     |
++-------------------------------|---------------------V-----------+
+| store                         | evaluates to                    |
+|  .............................V...............................  |
+|  : build plan                                                :  |
+|  :            referenced by           builds                 :  |
+|  :  [ build input ] --> [ build task ] --> [ build result ]  :  |
+|  :...........................................................:  |
 +-----------------------------------------------------------------+
 ```
 
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build tasks*, used to derive *build results* from referenced *build inputs*.
+It is used to compose expressions which ultimately evaluate to self-contained *build plans*, made up *build tasks* used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
@@ -40,4 +40,3 @@ The command line and Nix language are what users interact with most.
 Underlying everything is the *Nix store*, a mechanism to keep track of build tasks, data, and references between them.
 It can also execute *build instructions*, captured in the build tasks, to produce new data.
 
-A series of build tasks is a *build plan*.
-- 
cgit v1.2.3


From 75ce32405235614235dbe343beb13bb0d17934eb Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 4 May 2022 09:55:24 +0200
Subject: use singular for class names consistently

---
 doc/manual/src/SUMMARY.md.in                   | 6 +++---
 doc/manual/src/architecture/store/drvs/drvs.md | 2 +-
 doc/manual/src/architecture/store/paths.md     | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 257880efe..f356bd07d 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -17,9 +17,9 @@
   - [Upgrading Nix](installation/upgrading.md)
 - [Architecture](architecture/architecture.md)
   - [Store](architecture/store/store.md)
-    - [Store Objects](architecture/store/objects.md)
-    - [Store Paths](architecture/store/paths.md)
-    - [Derivations](architecture/store/drvs/drvs.md)
+    - [Store Object](architecture/store/objects.md)
+    - [Store Path](architecture/store/paths.md)
+    - [Derivation](architecture/store/drvs/drvs.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/architecture/store/drvs/drvs.md b/doc/manual/src/architecture/store/drvs/drvs.md
index 766a7b47f..5f374357d 100644
--- a/doc/manual/src/architecture/store/drvs/drvs.md
+++ b/doc/manual/src/architecture/store/drvs/drvs.md
@@ -1,4 +1,4 @@
-# Derivations
+# Derivation
 
 Derivations are recipes to create store objects.
 
diff --git a/doc/manual/src/architecture/store/paths.md b/doc/manual/src/architecture/store/paths.md
index cf51eb866..402e55e69 100644
--- a/doc/manual/src/architecture/store/paths.md
+++ b/doc/manual/src/architecture/store/paths.md
@@ -1,4 +1,4 @@
-# Store Paths
+# Store Path
 
 A store path is a pair of a 20-byte digest and a name.
 
-- 
cgit v1.2.3


From 68d26010f6d7341b73675aa30b24b67dcd479a7b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 10 May 2022 12:40:00 +0200
Subject: architecture overview: add link to Nix expression language reference

update summary title to match file contents
---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index e8d87f8ae..b818b7aa1 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -26,7 +26,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 
 At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
 
-Below that is the *Nix language*, a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
+Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
 It is used to compose expressions which ultimately evaluate to self-contained *build plans*, made up *build tasks* used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
-- 
cgit v1.2.3


From ef81276cc161b0ce38cb2681867529c1cbdbd7cb Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 10 May 2022 12:40:28 +0200
Subject: architecture overview: add link to command line reference

---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index b818b7aa1..77d5ebc2c 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -24,7 +24,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 +-----------------------------------------------------------------+
 ```
 
-At the top is the *command line interface*, translating from invocations of Nix executables to interactions with the underlying layers.
+At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
 It is used to compose expressions which ultimately evaluate to self-contained *build plans*, made up *build tasks* used to derive *build results* from referenced *build inputs*.
-- 
cgit v1.2.3


From 0e63b9bf8872f3556ea8925cea0c639f329d7c6e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 4 May 2022 19:02:28 +0200
Subject: add link from overview to store section

the overview should only link to the three main concepts presented. the
store is now fairly fleshed out. others can follow later.
---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 77d5ebc2c..ae977a7e1 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -37,6 +37,6 @@ In practice this amounts to a set of files in a file system.
 
 The command line and Nix language are what users interact with most.
 
-Underlying everything is the *Nix store*, a mechanism to keep track of build tasks, data, and references between them.
+Underlying everything is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute *build instructions*, captured in the build tasks, to produce new data.
 
-- 
cgit v1.2.3


From 25926c5fc673264288b5d9f7f175178e5b1fdad4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Wed, 11 May 2022 09:37:28 +0200
Subject: Nix store does not underly literally everything

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index ae977a7e1..fa992e563 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -37,6 +37,6 @@ In practice this amounts to a set of files in a file system.
 
 The command line and Nix language are what users interact with most.
 
-Underlying everything is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
+Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute *build instructions*, captured in the build tasks, to produce new data.
 
-- 
cgit v1.2.3


From 2303f84a684e41139a549595edf5d57aada4c685 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 20 May 2022 23:46:34 +0200
Subject: revert to "build plan" in overview diagram

this displays correct composition again. build inputs and build results
are not part of build plans in terms of data objects.

also this is a much less complicated setup. this will be the first
impression of architecture, and we want to get it right.
---
 doc/manual/src/architecture/architecture.md | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index fa992e563..c0fd1b0b5 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -8,19 +8,22 @@ It should help users understand why Nix behaves as it does, and it should help d
 Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers).
 
 ```
-                   [ commmand line interface ]--------+
-                                |                     |
-                                | evaluates           | manages
-                                V                     |
-                   [ configuration language  ]        |
-                                |                     |
-+-------------------------------|---------------------V-----------+
-| store                         | evaluates to                    |
-|  .............................V...............................  |
-|  : build plan                                                :  |
-|  :            referenced by           builds                 :  |
-|  :  [ build input ] --> [ build task ] --> [ build result ]  :  |
-|  :...........................................................:  |
++-----------------------------------------------------------------+
+| Nix                                                             |
+|                  [ commmand line interface ]------,             |
+|                               |                   |             |
+|                           evaluates               |             |
+|                               |                manages          |
+|                               V                   |             |
+|                  [ configuration language  ]      |             |
+|                               |                   |             |
+| +-----------------------------|-------------------V-----------+ |
+| | store                  evaluates to                         | |
+| |                             |                               | |
+| |             referenced by   V       builds                  | |
+| |  [ build input ] ---> [ build plan ] ---> [ build result ]  | |
+| |                                                             | |
+| +-------------------------------------------------------------+ |
 +-----------------------------------------------------------------+
 ```
 
-- 
cgit v1.2.3


From 4639b36b53fd369024d90e95b0178e4fae0a4203 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 20 May 2022 23:56:47 +0200
Subject: use reference links for URLs

---
 doc/manual/src/architecture/architecture.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index c0fd1b0b5..4dfe34fd6 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -5,7 +5,7 @@ It should help users understand why Nix behaves as it does, and it should help d
 
 ## Overview
 
-Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers).
+Nix consists of [hierarchical layers][layer-architecture].
 
 ```
 +-----------------------------------------------------------------+
@@ -29,7 +29,7 @@ Nix consists of hierarchical [layers](https://en.m.wikipedia.org/wiki/Multitier_
 
 At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
 
-Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional](https://en.m.wikipedia.org/wiki/Purely_functional_programming) configuration language.
+Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional][purely-functional-programming] configuration language.
 It is used to compose expressions which ultimately evaluate to self-contained *build plans*, made up *build tasks* used to derive *build results* from referenced *build inputs*.
 
 ::: {.note}
@@ -43,3 +43,5 @@ The command line and Nix language are what users interact with most.
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute *build instructions*, captured in the build tasks, to produce new data.
 
+[layer-architecture]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
+[purely-functional-programming]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
-- 
cgit v1.2.3


From 7c3bca1372aeeb5074fa4038df2984b316e99bb8 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Sat, 21 May 2022 00:16:24 +0200
Subject: revert to build plans in top-level overview

do not introduce build tasks yet, that is the next level of detail.
---
 doc/manual/src/architecture/architecture.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 4dfe34fd6..6d4b86935 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -30,7 +30,9 @@ Nix consists of [hierarchical layers][layer-architecture].
 At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
 
 Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional][purely-functional-programming] configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build plans*, made up *build tasks* used to derive *build results* from referenced *build inputs*.
+It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+
+The command line and Nix language are what users interact with most.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
@@ -38,10 +40,8 @@ As far as we are concerned here, the inputs and results of a derivation are just
 In practice this amounts to a set of files in a file system.
 :::
 
-The command line and Nix language are what users interact with most.
-
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
-It can also execute *build instructions*, captured in the build tasks, to produce new data.
+It can also execute build plans to produce new data.
 
 [layer-architecture]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
 [purely-functional-programming]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
-- 
cgit v1.2.3


From d5eea66615266e7c341e8d4e982af12d6cb82887 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 02:52:10 +0200
Subject: introduce build tasks

while it appears a bit much for the overview, this way we set the stage
for going directly into data types when describing the store, instead of
first having to say what build tasks are and how they relate to build
plans.
---
 doc/manual/src/architecture/architecture.md | 32 +++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 6d4b86935..8000aecd1 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -43,5 +43,37 @@ In practice this amounts to a set of files in a file system.
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute build plans to produce new data.
 
+A build plan is a series of *build tasks*.
+Each build task has a special build input which is used as *build instructions*.
+The result of a build task can be input to another build task.
+
+```
++-----------------------------------------------------------------------------------------+
+| store                                                                                   |
+|                   .................................................                     |
+|                   :  build plan                                   :                     |
+|                   :                                               :                     |
+|  [ build input ]-----instructions-,                               :                     |
+|                   :               |                               :                     |
+|                   :               v                               :                     |
+|  [ build input ]----------->[ build task ]--instructions-,        :                     |
+|                   :                                      |        :                     |
+|                   :                                      |        :                     |
+|                   :                                      v        :                     |
+|                   :                               [ build task ]----->[ build result ]  |
+|  [ build input ]-----instructions-,                      ^        :                     |
+|                   :               |                      |        :                     |
+|                   :               v                      |        :                     |
+|  [ build input ]----------->[ build task ]---------------'        :                     |
+|                   :               ^                               :                     |
+|                   :               |                               :                     |
+|  [ build input ]------------------'                               :                     |
+|                   :                                               :                     |
+|                   :                                               :                     |
+|                   :...............................................:                     |
+|                                                                                         |
++-----------------------------------------------------------------------------------------+
+```
+
 [layer-architecture]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
 [purely-functional-programming]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
-- 
cgit v1.2.3


From b6b112b366bed363f94231410946ad82122b317c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 02:28:40 +0200
Subject: use reference links for URLs

---
 doc/manual/src/architecture/store/store.md | 34 +++++++++++++++++++++---------
 1 file changed, 24 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index cc6698a40..d710ca4c0 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -17,21 +17,35 @@ Examples:
 Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
 The store directory defaults to `/nix/store`, but is in principle arbitrary.
 
-## A [Rosetta stone](https://en.m.wikipedia.org/wiki/Rosetta_Stone) for build system terminology
+## A [Rosetta stone][rosetta-stone] for build system terminology
 
 The Nix store's design is comparable to other build systems.
 Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
 
 The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
 
-generic build system | Nix | [Bazel](https://bazel.build/start/bazel-intro) | [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) | programming language
+generic build system | Nix | [Bazel][bazel] | [Build Systems à la Carte][bsalc] | programming language
 -- | -- | -- | -- | --
-data (build input, build result) | store object | [artifact](https://bazel.build/reference/glossary#artifact) | value | value
-build instructions | builder | ([depends on action type](https://docs.bazel.build/versions/main/skylark/lib/actions.html)) | function | function
-build task | derivation | [action](https://bazel.build/reference/glossary#action) | `Task` | [thunk](https://en.m.wikipedia.org/wiki/Thunk)
-build plan | derivation graph | [action graph](https://bazel.build/reference/glossary#action-graph), [build graph](https://bazel.build/reference/glossary#build-graph) | `Tasks` | [call graph](https://en.m.wikipedia.org/wiki/Call_graph)
+data (build input, build result) | store object | [artifact][bazel-artifact] | value | value
+build instructions | builder | ([depends on action type][bazel-actions]) | function | function
+build task | derivation | [action][bazel-action] | `Task` | [thunk][thunk]
+build plan | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks` | [call graph][call-graph]
 build | build | build | application of `Build` | evaluation
-persistence layer | store | [action cache](https://bazel.build/reference/glossary#action-cache) | `Store` | heap
-
-All of these systems share features of [declarative programming](https://en.m.wikipedia.org/wiki/Declarative_programming) languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment](https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf) (2004), elaborated in his PhD thesis [The Purely Functional Software
-Deployment Model](https://edolstra.github.io/pubs/phd-thesis.pdf) (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte](https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf) (2018).
+persistence layer | store | [action cache][bazel-action-cache] | `Store` | heap
+
+All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
+
+[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
+[bazel]: https://bazel.build/start/bazel-intro
+[bazel-artifact]: https://bazel.build/reference/glossary#artifact
+[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
+[bazel-action]: https://bazel.build/reference/glossary#action
+[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
+[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
+[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
+[thunk]: https://en.m.wikipedia.org/wiki/Thunk
+[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
+[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
+[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
+[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
+[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
-- 
cgit v1.2.3


From e72a7874dc59e7dd9783fb2783cfaf88806bf085 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 02:29:59 +0200
Subject: beautify rosetta table

while this may eventually introduce ugly diffs, the table will now
render readably on the terminal (e.g. for `man nix` or `nix --help`)
without further intervention.
---
 doc/manual/src/architecture/store/store.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index d710ca4c0..808e87581 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -24,14 +24,14 @@ Usage of terms is, for historic reasons, not entirely consistent within the Nix
 
 The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
 
-generic build system | Nix | [Bazel][bazel] | [Build Systems à la Carte][bsalc] | programming language
--- | -- | -- | -- | --
-data (build input, build result) | store object | [artifact][bazel-artifact] | value | value
-build instructions | builder | ([depends on action type][bazel-actions]) | function | function
-build task | derivation | [action][bazel-action] | `Task` | [thunk][thunk]
-build plan | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks` | [call graph][call-graph]
-build | build | build | application of `Build` | evaluation
-persistence layer | store | [action cache][bazel-action-cache] | `Store` | heap
+| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
+| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
+| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
+| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
+| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
+| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
+| build                            | build            | build                                                                | application of `Build`            | evaluation               |
+| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
 
 All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
 
-- 
cgit v1.2.3


From 207992a71d5d9c9ee5d09c90f30a9dd35991691d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 11 May 2022 13:38:47 +0200
Subject: introduce store and store objects without file system details

this leaves open implementation details, especially about store paths
and file system objects, and allows explaining them together were it is
more appropriate. also leaves room to carefully introduce the key
insight behind Nix: applying results from programming language theory to
the operating system paradigm of files and processes.
---
 doc/manual/src/architecture/store/store.md | 57 +++++++++++++++++++++++++++---
 1 file changed, 52 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 808e87581..f421a9ec3 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -1,12 +1,59 @@
 # Store
 
-A Nix store is a collection of [store objects](objects.md) with associated operations.
+A Nix store is a collection of *store objects*.
 
-These store objects can hold arbitrary data, and Nix makes no distinction if they are used as build inputs, build results, or build tasks.
+Store objects can hold arbitrary *data* and *references* to one another.
+Nix makes no distinction if they are used as build inputs, build results, or build tasks.
 
-A Nix store allows adding, retrieving, and deleting store objects.
-It can perform builds, that is, transform build inputs using instructions from the build tasks into build outputs.
-It also keeps track of *references* between data and can therefore garbage-collect unused store objects.
+```haskell
+data Store = Set StoreObject
+
+data StoreObject = StoreObject {
+  data       :: Data
+, references :: Set Reference
+}
+```
+
+A Nix store can *add*, *retrieve*, and *delete* store objects.
+
+It can *perform builds*, that is, create new store objects by transforming build inputs, using instructions from the build tasks, into build outputs.
+
+As it keeps track of references, it can [garbage-collect](https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)) unused store objects.
+
+```haskell
+add    :: Store -> Data -> (Store, Reference)
+get    :: Store -> Reference -> StoreObject
+delete :: Store -> Reference -> Store
+
+build  :: Store -> Reference -> Maybe (Store, Reference)
+
+collectGarbage :: Store -> Store
+```
+
+Store objects are [immutable](https://en.m.wikipedia.org/wiki/Immutable_object): once created, they do not change until they are deleted.
+
+References are [opaque](https://en.m.wikipedia.org/wiki/Opaque_data_type), [unique identifiers](https://en.m.wikipedia.org/wiki/Unique_identifier):
+The only way to obtain references is by adding or building store objects.
+A reference will always point to exactly one store object.
+
+An added store object cannot have references, unless it is a build task.
+
+Building a store object will add appropriate references, according to provided build instructions.
+These references can only come from declared build inputs, and are not known by build instructions a priori.
+
+```haskell
+data Data = Data | Task BuildTask
+
+data BuildTask = BuildTask {
+  instructions ::  Reference
+, inputs       :: [Reference]
+}
+```
+
+A store object cannot be deleted as long as it is reachable from a reference still in use.
+Garbage collection will delete all store objects that cannot be reached from any reference in use.
+
+<!-- more details in section on garbage collection, link to it once it exists -->
 
 There exist different types of stores, which all follow this model.
 Examples:
-- 
cgit v1.2.3


From b84f2bdfdd21b9aa65cbfac7e0292971d52c40e4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 11 May 2022 14:20:56 +0200
Subject: introduce mapping to Unix files and processes

---
 doc/manual/src/architecture/architecture.md |  1 -
 doc/manual/src/architecture/store/store.md  | 51 +++++++++++++++++++++++++++--
 2 files changed, 48 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 8000aecd1..3d17074cc 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -37,7 +37,6 @@ The command line and Nix language are what users interact with most.
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
 As far as we are concerned here, the inputs and results of a derivation are just data.
-In practice this amounts to a set of files in a file system.
 :::
 
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index f421a9ec3..d2d64dd53 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -39,7 +39,7 @@ A reference will always point to exactly one store object.
 An added store object cannot have references, unless it is a build task.
 
 Building a store object will add appropriate references, according to provided build instructions.
-These references can only come from declared build inputs, and are not known by build instructions a priori.
+These references can only come from declared build inputs, and are not known to build instructions a priori.
 
 ```haskell
 data Data = Data | Task BuildTask
@@ -55,14 +55,59 @@ Garbage collection will delete all store objects that cannot be reached from any
 
 <!-- more details in section on garbage collection, link to it once it exists -->
 
+## Files and Processes
+
+Nix provides a mapping between its store model and the [Unix paradigm](https://en.m.wikipedia.org/wiki/Everything_is_a_file) on the interplay of [files and processes](https://en.m.wikipedia.org/wiki/File_descriptor).
+
+Nix encodes immutable store objects and opaque identifiers as file system primitives: files, directories, and paths.
+That allows processes to resolve references contained in files and thus access the contents of store objects.
+
+```
++-----------------------------------------------------------------+
+| Nix                                                             |
+|                  [ commmand line interface ]------,             |
+|                               |                   |             |
+|                           evaluates               |             |
+|                               |                manages          |
+|                               V                   |             |
+|                  [ configuration language  ]      |             |
+|                               |                   |             |
+| +-----------------------------|-------------------V-----------+ |
+| | store                  evaluates to                         | |
+| |                             |                               | |
+| |             referenced by   V       builds                  | |
+| |  [ build input ] ---> [ build plan ] ---> [ build result ]  | |
+| |         ^                                        |          | |
+| +---------|----------------------------------------|----------+ |
++-----------|----------------------------------------|------------+
+            |                                        |
+    file system object                          store path
+            |                                        |
++-----------|----------------------------------------|------------+
+| operating system        +------------+             |            |
+|           '------------ |            | <-----------'            |
+|                         |    file    |                          |
+|                     ,-- |            | <-,                      |
+|                     |   +------------+   |                      |
+|          execute as |                    | read, write, execute |
+|                     |   +------------+   |                      |
+|                     '-> |  process   | --'                      |
+|                         +------------+                          |
++-----------------------------------------------------------------+
+```
+
+Store objects are therefore implemented as the pair of
+
+  - a *file system object* for data
+  - a set of *store paths* for references.
+
 There exist different types of stores, which all follow this model.
 Examples:
 - store on the local file system
 - remote store accessible via SSH
 - binary cache store accessible via HTTP
 
-Every store with a file system representation has a *store directory*, which contains that store’s objects accessible through [store paths](paths.md).
-The store directory defaults to `/nix/store`, but is in principle arbitrary.
+Every store ultimately has to make store objects accessible to processes through the file system.
 
 ## A [Rosetta stone][rosetta-stone] for build system terminology
 
-- 
cgit v1.2.3


From 4eb11d45928a412643aaf2c2ed40aa7c35cd345c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 20 May 2022 00:30:08 +0200
Subject: fix grammar for clarity

---
 doc/manual/src/architecture/store/store.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index d2d64dd53..99a92bf8e 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -16,7 +16,7 @@ data StoreObject = StoreObject {
 
 A Nix store can *add*, *retrieve*, and *delete* store objects.
 
-It can *perform builds*, that is, create new store objects by transforming build inputs, using instructions from the build tasks, into build outputs.
+It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks.
 
 As it keeps track of references, it can [garbage-collect](https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)) unused store objects.
 
@@ -57,9 +57,9 @@ Garbage collection will delete all store objects that cannot be reached from any
 
 ## Files and Processes
 
-Nix provides a mapping between its store model and the [Unix paradigm](https://en.m.wikipedia.org/wiki/Everything_is_a_file) on the interplay of [files and processes](https://en.m.wikipedia.org/wiki/File_descriptor).
+Nix provides a mapping between its store model and the [Unix paradigm](https://en.m.wikipedia.org/wiki/Everything_is_a_file) that governs the interplay of [files and processes](https://en.m.wikipedia.org/wiki/File_descriptor).
 
-Nix encodes immutable store objects and opaque identifiers as file system primitives: files, directories, and paths.
+Nix encodes immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
 That allows processes to resolve references contained in files and thus access the contents of store objects.
 
 ```
-- 
cgit v1.2.3


From 4adb6602bdf274f1b0471d8a7ab53e80eaff4854 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 02:58:25 +0200
Subject: clarify first sentence on store objects

---
 doc/manual/src/architecture/store/store.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 99a92bf8e..18d25ca4d 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -2,8 +2,8 @@
 
 A Nix store is a collection of *store objects*.
 
-Store objects can hold arbitrary *data* and *references* to one another.
-Nix makes no distinction if they are used as build inputs, build results, or build tasks.
+A store object can hold arbitrary *data* and *references* to other store objects.
+Nix makes no distinction if store objects are used as build inputs, build results, or build tasks.
 
 ```haskell
 data Store = Set StoreObject
-- 
cgit v1.2.3


From db8703bcac78ed2d132e39fe9bc13a2cd0fe6efc Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 03:05:44 +0200
Subject: use reference links for URLs

---
 doc/manual/src/architecture/store/store.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 18d25ca4d..1640944ad 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -18,7 +18,7 @@ A Nix store can *add*, *retrieve*, and *delete* store objects.
 
 It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks.
 
-As it keeps track of references, it can [garbage-collect](https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)) unused store objects.
+As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
 
 ```haskell
 add    :: Store -> Data -> (Store, Reference)
@@ -30,9 +30,9 @@ build  :: Store -> Reference -> Maybe (Store, Reference)
 collectGarbage :: Store -> Store
 ```
 
-Store objects are [immutable](https://en.m.wikipedia.org/wiki/Immutable_object): once created, they do not change until they are deleted.
+Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
 
-References are [opaque](https://en.m.wikipedia.org/wiki/Opaque_data_type), [unique identifiers](https://en.m.wikipedia.org/wiki/Unique_identifier):
+References are [opaque][opaque-data-type], [unique identifiers][unique-identifier]:
 The only way to obtain references is by adding or building store objects.
 A reference will always point to exactly one store object.
 
@@ -55,6 +55,11 @@ Garbage collection will delete all store objects that cannot be reached from any
 
 <!-- more details in section on garbage collection, link to it once it exists -->
 
+[garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
+[immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
+[opaque-data-type]: https://en.m.wikipedia.org/wiki/Opaque_data_type
+[unique-identifier]: https://en.m.wikipedia.org/wiki/Unique_identifier
+
 ## Files and Processes
 
 Nix provides a mapping between its store model and the [Unix paradigm](https://en.m.wikipedia.org/wiki/Everything_is_a_file) that governs the interplay of [files and processes](https://en.m.wikipedia.org/wiki/File_descriptor).
-- 
cgit v1.2.3


From 445f753a820cb4b6076fec1d69d66c649618c4f0 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 03:40:17 +0200
Subject: replace pseudo code by diagrams

change prose description to visually resemble the data structure
---
 doc/manual/src/architecture/store/store.md | 57 +++++++++++++++++-------------
 1 file changed, 32 insertions(+), 25 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 1640944ad..5a0f4a2df 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -2,33 +2,49 @@
 
 A Nix store is a collection of *store objects*.
 
-A store object can hold arbitrary *data* and *references* to other store objects.
-Nix makes no distinction if store objects are used as build inputs, build results, or build tasks.
+A store object can hold
 
-```haskell
-data Store = Set StoreObject
+- arbitrary *data*
+- *references* to other store objects.
 
-data StoreObject = StoreObject {
-  data       :: Data
-, references :: Set Reference
-}
-```
+Nix makes no distinction if store objects are build inputs, build results, or build tasks.
 
 A Nix store can *add*, *retrieve*, and *delete* store objects.
 
+                [ data ]
+                    |
+                    V
+    [ store ] ---> add ----> [ store' ] [ reference ]
+
+<!-- -->
+
+              [ reference ]
+                    |
+                    V
+    [ store ] ---> get ----> [ store object ]
+
+<!-- -->
+
+              [ reference ]
+                    |
+                    V
+    [ store ] --> delete --> [ store' ]
+
+
 It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks.
 
+
+              [ reference ]
+                    |
+                    V
+    [ store ] --> build --(maybe)--> [ store' ] [ reference' ]
+
+
 As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
 
-```haskell
-add    :: Store -> Data -> (Store, Reference)
-get    :: Store -> Reference -> StoreObject
-delete :: Store -> Reference -> Store
 
-build  :: Store -> Reference -> Maybe (Store, Reference)
+    [ store ] --> collect garbage --> [ store' ]
 
-collectGarbage :: Store -> Store
-```
 
 Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
 
@@ -41,15 +57,6 @@ An added store object cannot have references, unless it is a build task.
 Building a store object will add appropriate references, according to provided build instructions.
 These references can only come from declared build inputs, and are not known to build instructions a priori.
 
-```haskell
-data Data = Data | Task BuildTask
-
-data BuildTask = BuildTask {
-  instructions ::  Reference
-, inputs       :: [Reference]
-}
-```
-
 A store object cannot be deleted as long as it is reachable from a reference still in use.
 Garbage collection will delete all store objects that cannot be reached from any reference in use.
 
-- 
cgit v1.2.3


From 4341849193cfd9b8e1e494292516a60734dfcc53 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 05:15:53 +0200
Subject: move closure property to discussion references

---
 doc/manual/src/architecture/store/objects.md | 15 ---------------
 doc/manual/src/architecture/store/store.md   | 23 +++++++++++++++++------
 2 files changed, 17 insertions(+), 21 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
index f7587e112..8ab0b9368 100644
--- a/doc/manual/src/architecture/store/objects.md
+++ b/doc/manual/src/architecture/store/objects.md
@@ -35,21 +35,6 @@ A bare file or symlink can be a root file system object.
 
 Symlinks pointing outside of their own root, or to a store object without a matching reference, are allowed, but might not function as intended.
 
-## Reference {#reference}
-
-A store object can reference other store objects.
-
-Nix stores have the *closure property*: for each store object in the store, all the store objects it references must also be in the store.
-
-Building, copying and deleting store objects must be done in a way that obeys this property:
-
-- Build results must only refer to store objects in the closure of the build inputs.
-
-- Store objects being copied must refer to objects already in the destination store.
-  Recursive copying must either proceed in dependency order or be atomic.
-
-- We can only safely delete unreferenced objects.
-
 ### Reference scanning
 
 While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 5a0f4a2df..a3d9e2eeb 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -52,15 +52,26 @@ References are [opaque][opaque-data-type], [unique identifiers][unique-identifie
 The only way to obtain references is by adding or building store objects.
 A reference will always point to exactly one store object.
 
-An added store object cannot have references, unless it is a build task.
+Nix stores have the *closure property*: for each store object in the store, all the store objects it references must also be in the store.
 
-Building a store object will add appropriate references, according to provided build instructions.
-These references can only come from declared build inputs, and are not known to build instructions a priori.
+Adding, building, copying and deleting store objects must be done in a way that obeys this property:
 
-A store object cannot be deleted as long as it is reachable from a reference still in use.
-Garbage collection will delete all store objects that cannot be reached from any reference in use.
+- A newly added store object cannot have references, unless it is a build task.
 
-<!-- more details in section on garbage collection, link to it once it exists -->
+- Build results must only refer to store objects in the closure of the build inputs.
+
+  Building a store object will add appropriate references, according to provided build instructions.
+  These references can only come from declared build inputs.
+
+- Store objects being copied must refer to objects already in the destination store.
+
+  Recursive copying must either proceed in dependency order or be atomic.
+
+- We can only safely delete store objects which are not reachable from any reference still in use.
+
+  Garbage collection will delete all store objects that cannot be reached from any reference in use.
+
+  <!-- more details in section on garbage collection, link to it once it exists -->
 
 [garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
 [immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
-- 
cgit v1.2.3


From 843288a451461610f67798af2598a2034668153a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 05:16:33 +0200
Subject: add subsections for objects and references

group description of data instead of spreading it across the section.

that should help direct skimming. as it turns out, people do not
actually read any of that.
---
 doc/manual/src/architecture/store/store.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index a3d9e2eeb..de12ac1dc 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -2,6 +2,8 @@
 
 A Nix store is a collection of *store objects*.
 
+## Store Object
+
 A store object can hold
 
 - arbitrary *data*
@@ -9,6 +11,16 @@ A store object can hold
 
 Nix makes no distinction if store objects are build inputs, build results, or build tasks.
 
+Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
+
+## Reference
+
+References to store objects are [opaque][opaque-data-type], [unique identifiers][unique-identifier]:
+The only way to obtain references is by adding or building store objects.
+A reference will always point to exactly one store object.
+
+## Operations
+
 A Nix store can *add*, *retrieve*, and *delete* store objects.
 
                 [ data ]
@@ -46,11 +58,7 @@ As it keeps track of references, it can [garbage-collect][garbage-collection] un
     [ store ] --> collect garbage --> [ store' ]
 
 
-Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
-
-References are [opaque][opaque-data-type], [unique identifiers][unique-identifier]:
-The only way to obtain references is by adding or building store objects.
-A reference will always point to exactly one store object.
+## Closure
 
 Nix stores have the *closure property*: for each store object in the store, all the store objects it references must also be in the store.
 
-- 
cgit v1.2.3


From e63a768e21d9bff605e51de54f9ec1a8f74650a8 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 05:18:07 +0200
Subject: use reference links for URLs

---
 doc/manual/src/architecture/store/store.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index de12ac1dc..710d3265d 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -88,11 +88,12 @@ Adding, building, copying and deleting store objects must be done in a way that
 
 ## Files and Processes
 
-Nix provides a mapping between its store model and the [Unix paradigm](https://en.m.wikipedia.org/wiki/Everything_is_a_file) that governs the interplay of [files and processes](https://en.m.wikipedia.org/wiki/File_descriptor).
-
-Nix encodes immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
+Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
 That allows processes to resolve references contained in files and thus access the contents of store objects.
 
+[unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
+[file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor
+
 ```
 +-----------------------------------------------------------------+
 | Nix                                                             |
-- 
cgit v1.2.3


From 7b7e4c6340513efb838aa576d95c5032a90dc50d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 05:20:21 +0200
Subject: use singular to match section heading

---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 710d3265d..7367b4626 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -15,7 +15,7 @@ Store objects are [immutable][immutable-object]: once created, they do not chang
 
 ## Reference
 
-References to store objects are [opaque][opaque-data-type], [unique identifiers][unique-identifier]:
+A store object reference is an [opaque][opaque-data-type], [unique identifier][unique-identifier]:
 The only way to obtain references is by adding or building store objects.
 A reference will always point to exactly one store object.
 
-- 
cgit v1.2.3


From 3794618ccecf56a468eb9befd351e3cd39595ab5 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 2 Jun 2022 23:11:58 +0200
Subject: add commas between output values

---
 doc/manual/src/architecture/store/store.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 7367b4626..6ac210856 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -26,7 +26,7 @@ A Nix store can *add*, *retrieve*, and *delete* store objects.
                 [ data ]
                     |
                     V
-    [ store ] ---> add ----> [ store' ] [ reference ]
+    [ store ] ---> add ----> [ store' ], [ reference ]
 
 <!-- -->
 
@@ -49,7 +49,7 @@ It can *perform builds*, that is, create new store objects by transforming build
               [ reference ]
                     |
                     V
-    [ store ] --> build --(maybe)--> [ store' ] [ reference' ]
+    [ store ] --> build --(maybe)--> [ store' ], [ reference' ]
 
 
 As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
-- 
cgit v1.2.3


From 80de4a4804bf16fe3266618cb79ad486dc6659ae Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 2 Jun 2022 23:20:11 +0200
Subject: operations diagram: store' to the right

this also looks more diverse, hopefully easier to distinguish

Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>
---
 doc/manual/src/architecture/store/store.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 6ac210856..33777dc0d 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -26,14 +26,20 @@ A Nix store can *add*, *retrieve*, and *delete* store objects.
                 [ data ]
                     |
                     V
-    [ store ] ---> add ----> [ store' ], [ reference ]
+    [ store ] ---> add ----> [ store' ]
+                    |
+                    V
+              [ reference ]
 
 <!-- -->
 
               [ reference ]
                     |
                     V
-    [ store ] ---> get ----> [ store object ]
+    [ store ] ---> get
+                    |
+                    V
+             [ store object ]
 
 <!-- -->
 
@@ -49,7 +55,12 @@ It can *perform builds*, that is, create new store objects by transforming build
               [ reference ]
                     |
                     V
-    [ store ] --> build --(maybe)--> [ store' ], [ reference' ]
+    [ store ] --> build
+                       \
+                      (maybe) --> [ store' ]
+                         |
+                         V
+                   [ reference ]
 
 
 As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
-- 
cgit v1.2.3


From 195aa28ff73ee21bfe2d398e570bf458f07f6757 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 2 Jun 2022 23:29:32 +0200
Subject: references are added according to build task

at this level of abstraction we do not really care about build instructions or what they are, and also build instructions including their arguments really amount to the build task.
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 33777dc0d..aff41d511 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -79,7 +79,7 @@ Adding, building, copying and deleting store objects must be done in a way that
 
 - Build results must only refer to store objects in the closure of the build inputs.
 
-  Building a store object will add appropriate references, according to provided build instructions.
+  Building a store object will add appropriate references, according to the build task.
   These references can only come from declared build inputs.
 
 - Store objects being copied must refer to objects already in the destination store.
-- 
cgit v1.2.3


From 7993ba1f388e509d7617808b4a947ed1bf1533a8 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 2 Jun 2022 23:34:24 +0200
Subject: constrain garbage collection scope

garbage collection is now incremental, and may (in theory) never delete all unreferenced objects if it is slow enough.
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index aff41d511..5b4c3072d 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -88,7 +88,7 @@ Adding, building, copying and deleting store objects must be done in a way that
 
 - We can only safely delete store objects which are not reachable from any reference still in use.
 
-  Garbage collection will delete all store objects that cannot be reached from any reference in use.
+  Garbage collection will delete those store objects that cannot be reached from any reference in use.
 
   <!-- more details in section on garbage collection, link to it once it exists -->
 
-- 
cgit v1.2.3


From a90fc62b618f571bc5e6512e66e9c8c9a8eb6e78 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 2 Jun 2022 23:50:51 +0200
Subject: make clear that file system is for processes

Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 5b4c3072d..3d1ad0bad 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -150,7 +150,7 @@ Examples:
 - remote store accessible via SSH
 - binary cache store accessible via HTTP
 
-Every store ultimately has to make store objects accessible to processes through the file system.
+To make store objects accessible to processes, stores ultimately have to expose store objects through the file system.
 
 ## A [Rosetta stone][rosetta-stone] for build system terminology
 
-- 
cgit v1.2.3


From 19d8a5d83942f13c3f532b4ac21cc91c7158c21a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 2 Jun 2022 23:45:04 +0200
Subject: move first mention of file system object before diagram

---
 doc/manual/src/architecture/store/store.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 3d1ad0bad..a22735e42 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -102,6 +102,11 @@ Adding, building, copying and deleting store objects must be done in a way that
 Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
 That allows processes to resolve references contained in files and thus access the contents of store objects.
 
+Store objects are therefore implemented as the pair of
+
+  - a *file system object* for data
+  - a set of *store paths* for references.
+
 [unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
 [file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor
 
@@ -139,11 +144,6 @@ That allows processes to resolve references contained in files and thus access t
 +-----------------------------------------------------------------+
 ```
 
-Store objects are therefore implemented as the pair of
-
-  - a *file system object* for data
-  - a set of *store paths* for references.
-
 There exist different types of stores, which all follow this model.
 Examples:
 - store on the local file system
-- 
cgit v1.2.3


From 93f721b0d26b6525d8eaa8a1606ebeb4b71a9b6a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 21 Jun 2022 14:36:29 +0200
Subject: remove draft on derivations

---
 doc/manual/src/SUMMARY.md.in                   |  1 -
 doc/manual/src/architecture/store/drvs/drvs.md | 59 --------------------------
 2 files changed, 60 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/drvs/drvs.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index f356bd07d..5e2d26bf7 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -19,7 +19,6 @@
   - [Store](architecture/store/store.md)
     - [Store Object](architecture/store/objects.md)
     - [Store Path](architecture/store/paths.md)
-    - [Derivation](architecture/store/drvs/drvs.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/architecture/store/drvs/drvs.md b/doc/manual/src/architecture/store/drvs/drvs.md
deleted file mode 100644
index 5f374357d..000000000
--- a/doc/manual/src/architecture/store/drvs/drvs.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Derivation
-
-Derivations are recipes to create store objects.
-
-Derivations are the heart of Nix.
-Other system (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
-This is where Nix comes in.
-
-Derivations produce data by running arbitrary commands, like Make or Ninja rules.
-Unlike those systems, derivations do not produce arbitrary files, but only specific store objects.
-They cannot modify the store in any way, other than creating those store objects.
-This rigid specification of what they do is what allows Nix's caching to be so simple and yet robust.
-
-Based on the above, we can conceptually break derivations down into 3 parts:
-
-1. What command will be run?
-
-2. What existing store objects are needed as inputs?
-
-3. What store objects will be produced as outputs?
-
-## What command will be run?
-
-The original core of Nix was very simple about this, in the mold of traditional Unix.
-Commands consist of 3 parts:
-
-1. Path to executable
-
-2. Arguments (Except for `argv[0]`, which is taken from the path in the usual way)
-
-3. Environment variables.
-
-## What existing store objects are needed as inputs?
-
-The previous sub-section begs the question "how can we be sure the path to the executable points to what we think it does?"
-It's a good questions!
-
-## What store objects will be produced as outputs?
-
-## Extra extensions
-
-### `__structuredAttrs`
-
-Historically speaking, most users of Nix made GNU Bash with a script the command run, regardless of what they were doing.
-Bash variable are automatically created from env vars, but bash also supports array and string-keyed map variables in addition to string variables.
-People also usually create derivations using language which also support these richer data types.
-It was thus desired a way to get this data from the language "planning" the derivation to language to bash, the language evaluated at "run time".
-
-`__structuredAttrs` does this by smuggling inside the core derivation format a map of named richer data.
-At run time, this becomes two things:
-
-1. A JSON file containing that map.
-2. A bash script setting those variables.
-
-The bash command can be passed a script which will "source" that Nix-created bash script, setting those variables with the richer data.
-The outer script can then do whatever it likes with those richer variables as input.
-
-However, since derivations can already contain arbitary input sources, the vast majority of `__structuredAttrs` can be handled by upper layers.
-We might consider implementing `__structuredAttrs` in higher layers in the future, and simplifying the store layer.
-- 
cgit v1.2.3


From 84ddfbf8fd9b1e77fefb3c2c11a9cedab2e530c2 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 8 Jun 2022 11:57:19 +0200
Subject: remove diagonal from operations diagram

---
 doc/manual/src/architecture/store/store.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index a22735e42..3b99982e4 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -55,12 +55,10 @@ It can *perform builds*, that is, create new store objects by transforming build
               [ reference ]
                     |
                     V
-    [ store ] --> build
-                       \
-                      (maybe) --> [ store' ]
-                         |
-                         V
-                   [ reference ]
+    [ store ] --> build --(maybe)--> [ store' ]
+                             |
+                             V
+                       [ reference ]
 
 
 As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
-- 
cgit v1.2.3


From f632816cbaefbba9cc27a8e0de6cffd39fa7a8dd Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 8 Jun 2022 11:09:27 +0200
Subject: add explanation and examples of file system objects

---
 doc/manual/src/architecture/store/fso.md   | 64 ++++++++++++++++++++++++++++++
 doc/manual/src/architecture/store/store.md |  4 +-
 2 files changed, 66 insertions(+), 2 deletions(-)
 create mode 100644 doc/manual/src/architecture/store/fso.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/fso.md b/doc/manual/src/architecture/store/fso.md
new file mode 100644
index 000000000..958b8f62a
--- /dev/null
+++ b/doc/manual/src/architecture/store/fso.md
@@ -0,0 +1,64 @@
+# File System Object
+
+The Nix store uses a simple file system model for the data it holds in [store objects](store.md#store-object).
+
+Every file system object is one of the following:
+
+ - File: an executable flag, and arbitrary data for contents
+ - Directory: mapping of names to child file system objects
+ - [Symbolic link][symlink]: may point anywhere.
+
+We call a store object's outermost file system object the *root*.
+
+    data FileSystemObject
+      = File      { isExecutable :: Bool, contents :: Bytes }
+      | Directory { entries :: Map FileName FileSystemObject }
+      | SymLink   { target :: Path }
+
+Examples:
+
+- a directory with contents
+
+    /nix/store/<hash>-hello-2.10
+    ├── bin
+    │   └── hello
+    └── share
+        ├── info
+        │   └── hello.info
+        └── man
+            └── man1
+                └── hello.1.gz
+
+- a directory with relative symlink and other contents
+
+    /nix/store/<hash>-go-1.16.9
+    ├── bin -> share/go/bin
+    ├── nix-support/
+    └── share/
+
+- a directory with absolute symlink
+
+    /nix/store/d3k...-nodejs
+    └── nix_node -> /nix/store/f20...-nodejs-10.24.
+
+A bare file or symlink can be a root file system object.
+Examles:
+
+    /nix/store/<hash>-hello-2.10.tar.gz
+
+    /nix/store/4j5...-pkg-config-wrapper-0.29.2-doc -> /nix/store/i99...-pkg-config-0.29.2-doc
+
+Symlinks pointing outside of their own root or to a store object without a matching reference are allowed, but might not function as intended.
+Examples:
+
+- an arbitrarily symlinked file may change or not exist at all
+
+    /nix/store/<hash>-foo
+    └── foo -> /home/foo
+
+- if a symlink to a store path was not automatically created by Nix, it may be invalid or get invalidated when the store object is deleted
+
+    /nix/store/<hash>-bar
+    └── bar -> /nix/store/abc...-foo
+
+[symlink]: https://en.m.wikipedia.org/wiki/Symbolic_link
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 3b99982e4..68bdadc4a 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -2,7 +2,7 @@
 
 A Nix store is a collection of *store objects*.
 
-## Store Object
+## Store Object {#store-object}
 
 A store object can hold
 
@@ -102,7 +102,7 @@ That allows processes to resolve references contained in files and thus access t
 
 Store objects are therefore implemented as the pair of
 
-  - a *file system object* for data
+  - a [file system object](fso.md) for data
   - a set of *store paths* for references.
 
 [unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
-- 
cgit v1.2.3


From fa7ad4593d09d04afe1d215d2da09be02c2e2836 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 11:07:50 +0200
Subject: explain store directory

---
 doc/manual/src/SUMMARY.md.in                 |   6 +-
 doc/manual/src/architecture/store/objects.md |  48 -----------
 doc/manual/src/architecture/store/paths.md   | 123 ++++++++++++++++-----------
 doc/manual/src/architecture/store/store.md   |  21 +++--
 4 files changed, 91 insertions(+), 107 deletions(-)
 delete mode 100644 doc/manual/src/architecture/store/objects.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 5e2d26bf7..997d75444 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -17,8 +17,10 @@
   - [Upgrading Nix](installation/upgrading.md)
 - [Architecture](architecture/architecture.md)
   - [Store](architecture/store/store.md)
-    - [Store Object](architecture/store/objects.md)
-    - [Store Path](architecture/store/paths.md)
+    - [Store Path](architecture/store/path.md)
+    - [Digest](architecture/store/path.md#digest)
+    - [Input Addressing](architecture/store/path.md#input-addressing)
+    - [Content Addressing](architecture/store/path.md#content-addressing)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
diff --git a/doc/manual/src/architecture/store/objects.md b/doc/manual/src/architecture/store/objects.md
deleted file mode 100644
index 8ab0b9368..000000000
--- a/doc/manual/src/architecture/store/objects.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Store Object
-
-Nix organizes the data it manages into *store objects*.
-A store object is the pair of
-
-  - a [file system object](#file-system-object)
-  - a set of [references](#reference) to store objects.
-
-We call a store object's outermost file system object the *root*.
-
-```haskell
-data StoreOject = StoreObject {
-  root       :: FileSystemObject
-, references :: Set StoreObject
-}
-```
-
-## File system object {#file-system-object}
-
-The Nix store uses a simple file system model.
-
-Every file system object is one of the following:
- - File: an executable flag, and arbitrary data for contents
- - Directory: mapping of names to child file system objects
- - [Symbolic link](https://en.m.wikipedia.org/wiki/Symbolic_link): may point anywhere.
-
-```haskell
-data FileSystemObject
-  = File { isExecutable :: Bool, contents :: Bytes }
-  | Directory { entries ::  Map FileName FileSystemObject }
-  | SymLink { target :: Path }
-```
-
-A bare file or symlink can be a root file system object.
-
-Symlinks pointing outside of their own root, or to a store object without a matching reference, are allowed, but might not function as intended.
-
-### Reference scanning
-
-While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
-Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
-
-However, having references match store paths in files is not enforced by the data model:
-Store objects could have excess or incomplete references with respect to store paths found in their file contents.
-
-Scanning files therefore allows reliably capturing run time dependencies without declaring them explicitly.
-Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
-
diff --git a/doc/manual/src/architecture/store/paths.md b/doc/manual/src/architecture/store/paths.md
index 402e55e69..4867e7fd3 100644
--- a/doc/manual/src/architecture/store/paths.md
+++ b/doc/manual/src/architecture/store/paths.md
@@ -1,78 +1,103 @@
 # Store Path
 
-A store path is a pair of a 20-byte digest and a name.
+Nix implements [references](store.md#reference) to [store objects](store.md#store-object) as *store paths*.
 
-## String representation
+Store paths are pairs of
 
-A store path is rendered as the concatenation of
+- a 20-byte [digest](#digest) for identification
+- a symbolic name for people to read.
 
-  - a store directory
+Example:
 
-  - a path-separator (`/`)
+    {
+      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
+      name:   "firefox-33.1",
+    }
 
-  - the digest rendered as Base-32 (20 arbitrary bytes becomes 32 ASCII chars)
+It is rendered to a file system path as the concatenation of
 
-  - a hyphen (`-`)
+  - [store directory](#store-directory)
+  - path-separator (`/`)
+  - [digest](#digest) rendered in [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
+  - hyphen (`-`)
+  - name
 
-  - the name
+Example:
 
-Let's take the store path from the very beginning of this manual as an example:
+      /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
+      |--------| |------------------------------| |----------|
+    store directory            digest                 name
 
-    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
+## Store Directory {#store-directory}
 
-This parses like so:
+Every [store](./store.md) has a store directory.
 
-    /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
-    ^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
-    store dir  digest                           name
+If the store has a [file system representation](./store.md#files-and-processes), this directory contains the store’s [file system objects](#file-system-object), which can be addressed by [store paths](#store-path).
 
-We then can discard the store dir to recover the conceptual pair that is a store path:
+This means a store path is not just derived from the referenced store object itself, but depends on the store the store object is in.
 
-    {
-      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
-      name:   "firefox-33.1",
-    }
+::: {.note}
+The store directory defaults to `/nix/store`, but is in principle arbitrary.
+:::
 
-### Where did the "store directory" come from?
+It is important which store a given store object belongs to:
+Files in the store object can contain store paths, and processes may read these paths.
+Nix can only guarantee [referential integrity](store.md#closure) if store paths do not cross store boundaries.
 
-If you notice, the above references a "store directory", but that is *not* part of the definition of a store path.
-We can discard it when parsing, but what about when printing?
-We need to get a store directory from *somewhere*.
+Therefore one can only copy store objects if
 
-The answer is, the store directory is a property of the store that contains the store path.
-The explanation for this is simple enough: a store is notionally mounted as a directory at some location, and the store object's root file system likewise mounted at this path within that directory.
+- the source and target stores' directories match
 
-This does, however, mean the string representation of a store path is not derived just from the store path itself, but is in fact "context dependent".
+  or
 
-## The digest
+- the store object in question has no references, that is, contains no store paths.
 
-The calculation of the digest is quite complicated for historical reasons.
-The details of the algorithms will be discussed later once more concepts have been introduced.
-For now, we just concern ourselves with the *key properties* of those algorithms.
+To move a store object to a store with a different store directory, it has to be rebuilt, together with all its dependencies.
+It is in general not enough to replace the store directory string in file contents, as this may break internal offsets or content hashes.
 
-::: {.note}
-**Historical note** The 20 byte restriction is because originally a digests were SHA-1 hashes.
-This is no longer true, but longer hashes and other information are still boiled down to 20 bytes.
-:::
+# Digest {#digest}
+
+In a [store path](#store-path), the [digest][digest] is the output of a [cryptographic hash function][hash] of either all *inputs* involved in building the referenced store object or its actual *contents*.
 
-Store paths are either *content-addressed* or *input-addressed*.
+Store objects are therefore said to be either [input-addressed](#input-addressing) or [content-addressed](#content-addressing).
 
 ::: {.note}
-The former is a standard term used elsewhere.
-The later is our own creation to evoke a contrast with content addressing.
+**Historical note**: The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
+This is no longer true, but longer hashes and other information are still truncated to 20 bytes for compatibility.
 :::
 
-Content addressing means that the store path digest ultimately derives from referred store object's contents, namely its file system objects and references.
-There is more than one *method* of content-addressing, however.
-Still, if one does know the content addressing schema that was used,
-(or guesses, there isn't that many yet!)
-one can recalculate the store path and thus verify the store object.
+[digest]: https://en.m.wiktionary.org/wiki/digest#Noun
+[hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
+[sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
+
+
+### Reference scanning
+
+While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
+Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
+
+However, having references match store paths in files is not enforced by the data model:
+Store objects could have excess or incomplete references with respect to store paths found in their file contents.
+
+Scanning files therefore allows reliably capturing run time dependencies without declaring them explicitly.
+Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
+
+## Input Addressing {#input-addressing}
+
+Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
+
+To compute the hash of a store object one needs a deterministic serialisation, i.e., a binary string representation which only changes if the store object changes.
+
+Nix has a custom serialisation format called Nix Archive (NAR)
+
+Store object references of this sort can *not* be validated from the content of the store object.
+Rather, a cryptographic signature has to be used to indicate that someone is vouching for the store object really being produced from a build plan with that digest.
+
+## Content Addressing {#content-addressing}
+
+Content addressing means that the digest derives from the store object's contents, namely its file system objects and references.
+If one knows content addressing was used, one can recalculate the reference and thus verify the store object.
 
-Input addressing means that the store path digest derives from how the store path was produced, namely the "inputs" and plan that it was built from.
-Store paths of this sort can *not* be validated from the content of the store object.
-Rather, the store object might come with the store path it expects to be referred to by, and a signature of that path, the contents of the store path, and other metadata.
-The signature indicates that someone is vouching for the store object really being the results of a plan with that digest.
+Content addressing is currently only used for the special cases of source files and "fixed-output derivations", where the contents of a store object are known in advance.
+Content addressing of build results is still an [experimental feature subject to some restrictions](https://github.com/tweag/rfcs/blob/cas-rfc/rfcs/0062-content-addressed-paths.md).
 
-While metadata is included in the digest calculation explaining which method it was calculated by, this only serves to thwart pre-image attacks.
-That metadata is scrambled with everything else so that it is difficult to tell how a given store path was produced short of a brute-force search.
-In the parlance of referencing schemes, this means that store paths are not "self-describing".
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 68bdadc4a..21a876f75 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -67,18 +67,19 @@ As it keeps track of references, it can [garbage-collect][garbage-collection] un
     [ store ] --> collect garbage --> [ store' ]
 
 
-## Closure
+## Closure {#closure}
 
-Nix stores have the *closure property*: for each store object in the store, all the store objects it references must also be in the store.
+Nix stores ensure [referential integrity][referential-integrity]: for each store object in the store, all the store objects it references must also be in the store.
 
-Adding, building, copying and deleting store objects must be done in a way that obeys this property:
+The set of all store objects reachable by following references from a given initial set of store objects is called a *closure*.
+
+Adding, building, copying and deleting store objects must be done in a way that preserves referential integrity:
 
 - A newly added store object cannot have references, unless it is a build task.
 
 - Build results must only refer to store objects in the closure of the build inputs.
 
   Building a store object will add appropriate references, according to the build task.
-  These references can only come from declared build inputs.
 
 - Store objects being copied must refer to objects already in the destination store.
 
@@ -86,16 +87,15 @@ Adding, building, copying and deleting store objects must be done in a way that
 
 - We can only safely delete store objects which are not reachable from any reference still in use.
 
-  Garbage collection will delete those store objects that cannot be reached from any reference in use.
-
   <!-- more details in section on garbage collection, link to it once it exists -->
 
+[referential-integrity]: https://en.m.wikipedia.org/wiki/Referential_integrity
 [garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
 [immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
 [opaque-data-type]: https://en.m.wikipedia.org/wiki/Opaque_data_type
 [unique-identifier]: https://en.m.wikipedia.org/wiki/Unique_identifier
 
-## Files and Processes
+## Files and Processes {#files-and-processes}
 
 Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
 That allows processes to resolve references contained in files and thus access the contents of store objects.
@@ -103,11 +103,16 @@ That allows processes to resolve references contained in files and thus access t
 Store objects are therefore implemented as the pair of
 
   - a [file system object](fso.md) for data
-  - a set of *store paths* for references.
+  - a set of [store paths](paths.md) for references.
 
 [unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
 [file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor
 
+The following diagram shows a radical simplification of how Nix interacts with the operating system:
+It uses files as build inputs, and build outputs are files again.
+On the operating system, files are either "dead" data, or "live" as processes, which in turn operate on files, or can bring them to life.
+A build function also amounts to an operating system process (not depicted).
+
 ```
 +-----------------------------------------------------------------+
 | Nix                                                             |
-- 
cgit v1.2.3


From 1681f4e9f3608973e3247e447fd9236eb32d66f3 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 13 Jun 2022 17:10:31 +0200
Subject: better explain reference scanning

---
 doc/manual/src/architecture/store/paths.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/paths.md b/doc/manual/src/architecture/store/paths.md
index 4867e7fd3..956049341 100644
--- a/doc/manual/src/architecture/store/paths.md
+++ b/doc/manual/src/architecture/store/paths.md
@@ -70,18 +70,21 @@ This is no longer true, but longer hashes and other information are still trunca
 [hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
 [sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
 
-
 ### Reference scanning
 
-While references could be arbitrary paths, Nix requires them to be store paths to ensure correctness.
-Anything outside a given store is not under control of Nix, and therefore cannot be guaranteed to be present when needed.
+When a new store object is built, Nix scans its file contents for store paths to construct its set of references.
 
-However, having references match store paths in files is not enforced by the data model:
-Store objects could have excess or incomplete references with respect to store paths found in their file contents.
+The special format of a store path's [digest](#digest) allows reliably detecting it among arbitrary data.
+Nix uses the [closure](store.md#closure) of build inputs to derive the list of allowed store paths, to avoid false positives.
 
-Scanning files therefore allows reliably capturing run time dependencies without declaring them explicitly.
+This way, scanning files captures run time dependencies without the user having to declare them explicitly.
 Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
 
+::: {.note}
+In practice, it is sometimes still necessary to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
+This depends on the specifics of the software to build and run.
+:::
+
 ## Input Addressing {#input-addressing}
 
 Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
-- 
cgit v1.2.3


From 9c544813d7883fa003d25f528f50c46faf06e1a2 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 21 Jun 2022 14:01:31 +0200
Subject: paths -> path

use singular for terminology uniformly
---
 doc/manual/src/architecture/store/path.md  | 106 +++++++++++++++++++++++++++++
 doc/manual/src/architecture/store/paths.md | 106 -----------------------------
 doc/manual/src/architecture/store/store.md |   2 +-
 3 files changed, 107 insertions(+), 107 deletions(-)
 create mode 100644 doc/manual/src/architecture/store/path.md
 delete mode 100644 doc/manual/src/architecture/store/paths.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
new file mode 100644
index 000000000..956049341
--- /dev/null
+++ b/doc/manual/src/architecture/store/path.md
@@ -0,0 +1,106 @@
+# Store Path
+
+Nix implements [references](store.md#reference) to [store objects](store.md#store-object) as *store paths*.
+
+Store paths are pairs of
+
+- a 20-byte [digest](#digest) for identification
+- a symbolic name for people to read.
+
+Example:
+
+    {
+      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
+      name:   "firefox-33.1",
+    }
+
+It is rendered to a file system path as the concatenation of
+
+  - [store directory](#store-directory)
+  - path-separator (`/`)
+  - [digest](#digest) rendered in [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
+  - hyphen (`-`)
+  - name
+
+Example:
+
+      /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
+      |--------| |------------------------------| |----------|
+    store directory            digest                 name
+
+## Store Directory {#store-directory}
+
+Every [store](./store.md) has a store directory.
+
+If the store has a [file system representation](./store.md#files-and-processes), this directory contains the store’s [file system objects](#file-system-object), which can be addressed by [store paths](#store-path).
+
+This means a store path is not just derived from the referenced store object itself, but depends on the store the store object is in.
+
+::: {.note}
+The store directory defaults to `/nix/store`, but is in principle arbitrary.
+:::
+
+It is important which store a given store object belongs to:
+Files in the store object can contain store paths, and processes may read these paths.
+Nix can only guarantee [referential integrity](store.md#closure) if store paths do not cross store boundaries.
+
+Therefore one can only copy store objects if
+
+- the source and target stores' directories match
+
+  or
+
+- the store object in question has no references, that is, contains no store paths.
+
+To move a store object to a store with a different store directory, it has to be rebuilt, together with all its dependencies.
+It is in general not enough to replace the store directory string in file contents, as this may break internal offsets or content hashes.
+
+# Digest {#digest}
+
+In a [store path](#store-path), the [digest][digest] is the output of a [cryptographic hash function][hash] of either all *inputs* involved in building the referenced store object or its actual *contents*.
+
+Store objects are therefore said to be either [input-addressed](#input-addressing) or [content-addressed](#content-addressing).
+
+::: {.note}
+**Historical note**: The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
+This is no longer true, but longer hashes and other information are still truncated to 20 bytes for compatibility.
+:::
+
+[digest]: https://en.m.wiktionary.org/wiki/digest#Noun
+[hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
+[sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
+
+### Reference scanning
+
+When a new store object is built, Nix scans its file contents for store paths to construct its set of references.
+
+The special format of a store path's [digest](#digest) allows reliably detecting it among arbitrary data.
+Nix uses the [closure](store.md#closure) of build inputs to derive the list of allowed store paths, to avoid false positives.
+
+This way, scanning files captures run time dependencies without the user having to declare them explicitly.
+Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
+
+::: {.note}
+In practice, it is sometimes still necessary to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
+This depends on the specifics of the software to build and run.
+:::
+
+## Input Addressing {#input-addressing}
+
+Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
+
+To compute the hash of a store object one needs a deterministic serialisation, i.e., a binary string representation which only changes if the store object changes.
+
+Nix has a custom serialisation format called Nix Archive (NAR)
+
+Store object references of this sort can *not* be validated from the content of the store object.
+Rather, a cryptographic signature has to be used to indicate that someone is vouching for the store object really being produced from a build plan with that digest.
+
+## Content Addressing {#content-addressing}
+
+Content addressing means that the digest derives from the store object's contents, namely its file system objects and references.
+If one knows content addressing was used, one can recalculate the reference and thus verify the store object.
+
+Content addressing is currently only used for the special cases of source files and "fixed-output derivations", where the contents of a store object are known in advance.
+Content addressing of build results is still an [experimental feature subject to some restrictions](https://github.com/tweag/rfcs/blob/cas-rfc/rfcs/0062-content-addressed-paths.md).
+
diff --git a/doc/manual/src/architecture/store/paths.md b/doc/manual/src/architecture/store/paths.md
deleted file mode 100644
index 956049341..000000000
--- a/doc/manual/src/architecture/store/paths.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Store Path
-
-Nix implements [references](store.md#reference) to [store objects](store.md#store-object) as *store paths*.
-
-Store paths are pairs of
-
-- a 20-byte [digest](#digest) for identification
-- a symbolic name for people to read.
-
-Example:
-
-    {
-      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
-      name:   "firefox-33.1",
-    }
-
-It is rendered to a file system path as the concatenation of
-
-  - [store directory](#store-directory)
-  - path-separator (`/`)
-  - [digest](#digest) rendered in [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
-  - hyphen (`-`)
-  - name
-
-Example:
-
-      /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
-      |--------| |------------------------------| |----------|
-    store directory            digest                 name
-
-## Store Directory {#store-directory}
-
-Every [store](./store.md) has a store directory.
-
-If the store has a [file system representation](./store.md#files-and-processes), this directory contains the store’s [file system objects](#file-system-object), which can be addressed by [store paths](#store-path).
-
-This means a store path is not just derived from the referenced store object itself, but depends on the store the store object is in.
-
-::: {.note}
-The store directory defaults to `/nix/store`, but is in principle arbitrary.
-:::
-
-It is important which store a given store object belongs to:
-Files in the store object can contain store paths, and processes may read these paths.
-Nix can only guarantee [referential integrity](store.md#closure) if store paths do not cross store boundaries.
-
-Therefore one can only copy store objects if
-
-- the source and target stores' directories match
-
-  or
-
-- the store object in question has no references, that is, contains no store paths.
-
-To move a store object to a store with a different store directory, it has to be rebuilt, together with all its dependencies.
-It is in general not enough to replace the store directory string in file contents, as this may break internal offsets or content hashes.
-
-# Digest {#digest}
-
-In a [store path](#store-path), the [digest][digest] is the output of a [cryptographic hash function][hash] of either all *inputs* involved in building the referenced store object or its actual *contents*.
-
-Store objects are therefore said to be either [input-addressed](#input-addressing) or [content-addressed](#content-addressing).
-
-::: {.note}
-**Historical note**: The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
-This is no longer true, but longer hashes and other information are still truncated to 20 bytes for compatibility.
-:::
-
-[digest]: https://en.m.wiktionary.org/wiki/digest#Noun
-[hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
-[sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
-
-### Reference scanning
-
-When a new store object is built, Nix scans its file contents for store paths to construct its set of references.
-
-The special format of a store path's [digest](#digest) allows reliably detecting it among arbitrary data.
-Nix uses the [closure](store.md#closure) of build inputs to derive the list of allowed store paths, to avoid false positives.
-
-This way, scanning files captures run time dependencies without the user having to declare them explicitly.
-Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
-
-::: {.note}
-In practice, it is sometimes still necessary to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
-This depends on the specifics of the software to build and run.
-:::
-
-## Input Addressing {#input-addressing}
-
-Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
-
-To compute the hash of a store object one needs a deterministic serialisation, i.e., a binary string representation which only changes if the store object changes.
-
-Nix has a custom serialisation format called Nix Archive (NAR)
-
-Store object references of this sort can *not* be validated from the content of the store object.
-Rather, a cryptographic signature has to be used to indicate that someone is vouching for the store object really being produced from a build plan with that digest.
-
-## Content Addressing {#content-addressing}
-
-Content addressing means that the digest derives from the store object's contents, namely its file system objects and references.
-If one knows content addressing was used, one can recalculate the reference and thus verify the store object.
-
-Content addressing is currently only used for the special cases of source files and "fixed-output derivations", where the contents of a store object are known in advance.
-Content addressing of build results is still an [experimental feature subject to some restrictions](https://github.com/tweag/rfcs/blob/cas-rfc/rfcs/0062-content-addressed-paths.md).
-
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 21a876f75..f662ed3e7 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -103,7 +103,7 @@ That allows processes to resolve references contained in files and thus access t
 Store objects are therefore implemented as the pair of
 
   - a [file system object](fso.md) for data
-  - a set of [store paths](paths.md) for references.
+  - a set of [store paths](path.md) for references.
 
 [unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
 [file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor
-- 
cgit v1.2.3


From c10dcccccda331499db75753ab6fed8938c31cca Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 21 Jun 2022 14:08:13 +0200
Subject: make example a simple list

using JSON notation is unwarranted and not explained.
---
 doc/manual/src/architecture/store/path.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 956049341..2cedc4234 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -9,10 +9,8 @@ Store paths are pairs of
 
 Example:
 
-    {
-      digest: "b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z",
-      name:   "firefox-33.1",
-    }
+- digest: `b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z`
+- name:   `firefox-33.1`
 
 It is rendered to a file system path as the concatenation of
 
-- 
cgit v1.2.3


From 631ca18ee62502dd2e51a8f3c9e2ab656b8382ec Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 21 Jun 2022 14:08:50 +0200
Subject: reword notes on copying

clarify that we are copying between different stores. we have not
introduced that notion or why it would be interesting, but for now it
should be fine to keep it in context of the store directory.

we could move that later to a more detailed explanation of different
store types.
---
 doc/manual/src/architecture/store/path.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 2cedc4234..3f2a4bbff 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -42,7 +42,7 @@ It is important which store a given store object belongs to:
 Files in the store object can contain store paths, and processes may read these paths.
 Nix can only guarantee [referential integrity](store.md#closure) if store paths do not cross store boundaries.
 
-Therefore one can only copy store objects if
+Therefore one can only copy store objects to a different store if
 
 - the source and target stores' directories match
 
@@ -50,8 +50,9 @@ Therefore one can only copy store objects if
 
 - the store object in question has no references, that is, contains no store paths.
 
-To move a store object to a store with a different store directory, it has to be rebuilt, together with all its dependencies.
-It is in general not enough to replace the store directory string in file contents, as this may break internal offsets or content hashes.
+One cannot copy a store object to a store with a different store directory.
+Instead, it has to be rebuilt, together with all its dependencies.
+It is in general not enough to replace the store directory string in file contents, as this may render executables unusable by invalidating their internal offsets or checksums.
 
 # Digest {#digest}
 
-- 
cgit v1.2.3


From 7c656d90ca2c3364fd72543c0aa27115d96ac463 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 21 Jun 2022 14:25:30 +0200
Subject: simplify description of diagram

try not to be too fancy, it's just for reading the diagram out loud.
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index f662ed3e7..b3517f9b6 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -110,7 +110,7 @@ Store objects are therefore implemented as the pair of
 
 The following diagram shows a radical simplification of how Nix interacts with the operating system:
 It uses files as build inputs, and build outputs are files again.
-On the operating system, files are either "dead" data, or "live" as processes, which in turn operate on files, or can bring them to life.
+On the operating system, files can be run as processes, which in turn operate on files.
 A build function also amounts to an operating system process (not depicted).
 
 ```
-- 
cgit v1.2.3


From ec43977553e605370d160ad0f852c15d0c754e74 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 14:10:44 +0200
Subject: store: match chapter introduction to outline

the various levels of detail should describe the same things.
---
 doc/manual/src/architecture/store/store.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index b3517f9b6..403a23bbd 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -1,6 +1,7 @@
 # Store
 
-A Nix store is a collection of *store objects*.
+A Nix store is a collection of *store objects* with references between them.
+It supports operations to manipulate that collection.
 
 ## Store Object {#store-object}
 
-- 
cgit v1.2.3


From 348432f48ffaf084c7ba1397fe63d805891bb68d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 14:17:28 +0200
Subject: store: add concept map

this should help nativate the chapter by indicating which terms should
be known to understand a given concept.
---
 doc/manual/src/architecture/store/store.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 403a23bbd..ed250ce0c 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -3,6 +3,28 @@
 A Nix store is a collection of *store objects* with references between them.
 It supports operations to manipulate that collection.
 
+The following concept map is a graphical outline of this chapter.
+Arrows indicate suggested reading order.
+
+```
+                                   ,----------------------[ store ]
+                                   |                          |
+                                   v                          v
+                            [ store object ]            [ operations ]----------------------,
+                                   |                          |                             |
+                                   v                          v                             |
+                        [ files and processes ]           [ build ]--------->[ derivation ] |
+                            |           |                     |                    |        |
+                            v           v                     v                    v        |
+           [ file system object ] [ store path ]--->[ reference scanning ]--->[ closure ]   |
+                     |                  ^                                          |        |
+                     v                  |                                          v        v
+                [ digest ]--------------'                                   [ garbage collection ]
+                   /   \
+                  v     v
+[ input addressing ]   [ content addressing ]
+```
+
 ## Store Object {#store-object}
 
 A store object can hold
-- 
cgit v1.2.3


From d8b2f9f772a7fb33db17f98605f221f5254c51b4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 14:21:12 +0200
Subject: make concept map more compact

invert arrows to/from derivation:
- we need closures to form derivations
- we need derivations to perform builds
---
 doc/manual/src/architecture/store/store.md | 35 ++++++++++++++++--------------
 1 file changed, 19 insertions(+), 16 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index ed250ce0c..fba2f90fd 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -7,22 +7,25 @@ The following concept map is a graphical outline of this chapter.
 Arrows indicate suggested reading order.
 
 ```
-                                   ,----------------------[ store ]
-                                   |                          |
-                                   v                          v
-                            [ store object ]            [ operations ]----------------------,
-                                   |                          |                             |
-                                   v                          v                             |
-                        [ files and processes ]           [ build ]--------->[ derivation ] |
-                            |           |                     |                    |        |
-                            v           v                     v                    v        |
-           [ file system object ] [ store path ]--->[ reference scanning ]--->[ closure ]   |
-                     |                  ^                                          |        |
-                     v                  |                                          v        v
-                [ digest ]--------------'                                   [ garbage collection ]
-                   /   \
-                  v     v
-[ input addressing ]   [ content addressing ]
+                      ,----------[ store ]---------,
+                      |                            |
+                      |                            v
+                      |                     [ operations ]
+                      |                      /          \
+                      v                     v            v
+               [ store object ] [ garbage collection ] [ build ]
+                      |                 ^                 ^ |
+                      v                 |                 | |
+           [ files and processes ]      | [ derivation ]--' |
+              /            \            |       ^           |
+             v              v           |       |           |
+[ file system object ]  [ store path ]  '--[ closure ]      |
+                  |         ^     \             |           |
+                  v         |      v            v           |
+             [ digest ]-----'  [ reference scanning ]<------'
+              /      \
+             v        v
+[ input addressing ] [ content addressing ]
 ```
 
 ## Store Object {#store-object}
-- 
cgit v1.2.3


From 475a332025fd9bc399206f79298d9897dde45380 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 14:25:19 +0200
Subject: make concept map even more compact

---
 doc/manual/src/architecture/store/store.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index fba2f90fd..c4eea33fa 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -11,18 +11,18 @@ Arrows indicate suggested reading order.
                       |                            |
                       |                            v
                       |                     [ operations ]
-                      |                      /          \
-                      v                     v            v
-               [ store object ] [ garbage collection ] [ build ]
-                      |                 ^                 ^ |
-                      v                 |                 | |
-           [ files and processes ]      | [ derivation ]--' |
-              /            \            |       ^           |
-             v              v           |       |           |
-[ file system object ]  [ store path ]  '--[ closure ]      |
-                  |         ^     \             |           |
-                  v         |      v            v           |
-             [ digest ]-----'  [ reference scanning ]<------'
+                      |                       |        |
+                      v                       v        |
+               [ store object ] [ garbage collection ] |
+                      |                  ^             |
+                      v                  |             v
+           [ files and processes ]  [ closure ]    [ build ]
+               /          \             |   |        ^    |
+              v            v            |   v        |    |
+[ file system object ] [ store path ]   |  [ derivation ] |
+                  |        ^      |     |                 |
+                  v        |      v     v                 |
+             [ digest ]----'  [ reference scanning ] <----'
               /      \
              v        v
 [ input addressing ] [ content addressing ]
-- 
cgit v1.2.3


From a28d6878b263270c7db271c414bef2c688bb872d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 14:27:08 +0200
Subject: concept map: put closure as it is in the chapter

this is not as compact any more, but it more closely resembles the
chapter structure, and clearly shows that the closure property is the
key idea on which most of Nix operates.
---
 doc/manual/src/architecture/store/store.md | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index c4eea33fa..0f43d5a62 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -7,22 +7,19 @@ The following concept map is a graphical outline of this chapter.
 Arrows indicate suggested reading order.
 
 ```
-                      ,----------[ store ]---------,
-                      |                            |
-                      |                            v
-                      |                     [ operations ]
-                      |                       |        |
-                      v                       v        |
-               [ store object ] [ garbage collection ] |
-                      |                  ^             |
-                      v                  |             v
-           [ files and processes ]  [ closure ]    [ build ]
-               /          \             |   |        ^    |
-              v            v            |   v        |    |
-[ file system object ] [ store path ]   |  [ derivation ] |
-                  |        ^      |     |                 |
-                  v        |      v     v                 |
-             [ digest ]----'  [ reference scanning ] <----'
+                      ,--------------[ store ]----------------,
+                      |                  |                    |
+                      v                  v                    v
+               [ store object ]     [ closure ]--,      [ operations ]
+                      |               |   |      |        |        |
+                      v               |   |      v        v        |
+           [ files and processes ]    |   | [ garbage collection ] |
+               /          \           |   V                        v
+              v            v          | [ derivation ]--->[ building ]
+[ file system object ] [ store path ] |                         |
+                  |        ^      |   |                         |
+                  v        |      v   v                         |
+             [ digest ]----' [ reference scanning ] <-----------'
               /      \
              v        v
 [ input addressing ] [ content addressing ]
-- 
cgit v1.2.3


From c345345deeb188830e62e9b2e957cf1d09d1c6b5 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 9 Jun 2022 14:33:31 +0200
Subject: concept map: align hights

this has the weird but nice emergent property that terms at the same
height are roughly at the same level of abstraction.
---
 doc/manual/src/architecture/store/store.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 0f43d5a62..cba875092 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -14,12 +14,12 @@ Arrows indicate suggested reading order.
                       |               |   |      |        |        |
                       v               |   |      v        v        |
            [ files and processes ]    |   | [ garbage collection ] |
-               /          \           |   V                        v
-              v            v          | [ derivation ]--->[ building ]
-[ file system object ] [ store path ] |                         |
+               /          \           |   |                        |
+              v            v          |   v                        v
+[ file system object ] [ store path ] | [ derivation ]--->[ building ]
                   |        ^      |   |                         |
                   v        |      v   v                         |
-             [ digest ]----' [ reference scanning ] <-----------'
+             [ digest ]----' [ reference scanning ]<------------'
               /      \
              v        v
 [ input addressing ] [ content addressing ]
-- 
cgit v1.2.3


From def80d5777dcd5d4b8a10e54be24d745b5d7562b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 8 Jun 2022 11:50:24 +0200
Subject: add subsections to table of contents

---
 doc/manual/src/SUMMARY.md.in               | 8 +++++++-
 doc/manual/src/architecture/store/store.md | 6 +++---
 2 files changed, 10 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 997d75444..5581bad3a 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -17,7 +17,13 @@
   - [Upgrading Nix](installation/upgrading.md)
 - [Architecture](architecture/architecture.md)
   - [Store](architecture/store/store.md)
-    - [Store Path](architecture/store/path.md)
+    - [Store Object](architecture/store/store.md#store-object)
+    - [Reference](architecture/store/store.md#reference)
+    - [Operations](architecture/store/store.md#operations)
+    - [Closure](architecture/store/store.md#closure)
+    - [Files and Processes](architecture/store/store.md#files-and-processes)
+    - [Build system terminology](architecture/store/store.md#build-system-terminology)
+  - [Store Path](architecture/store/path.md)
     - [Digest](architecture/store/path.md#digest)
     - [Input Addressing](architecture/store/path.md#input-addressing)
     - [Content Addressing](architecture/store/path.md#content-addressing)
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index cba875092..e1d983d99 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -36,13 +36,13 @@ Nix makes no distinction if store objects are build inputs, build results, or bu
 
 Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
 
-## Reference
+## Reference {#reference}
 
 A store object reference is an [opaque][opaque-data-type], [unique identifier][unique-identifier]:
 The only way to obtain references is by adding or building store objects.
 A reference will always point to exactly one store object.
 
-## Operations
+## Operations {#operations}
 
 A Nix store can *add*, *retrieve*, and *delete* store objects.
 
@@ -178,7 +178,7 @@ Examples:
 
 To make store objects accessible to processes, stores ultimately have to expose store objects through the file system.
 
-## A [Rosetta stone][rosetta-stone] for build system terminology
+## A [Rosetta stone][rosetta-stone] for build system terminology {#build-system-terminology}
 
 The Nix store's design is comparable to other build systems.
 Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
-- 
cgit v1.2.3


From fe4c0b8d75b9380ab64a752a7f1da680b1163731 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Tue, 12 Jul 2022 12:28:09 +0100
Subject: fix typo

Co-authored-by: Thomas <twatson52@mac.com>
---
 doc/manual/src/architecture/store/fso.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/fso.md b/doc/manual/src/architecture/store/fso.md
index 958b8f62a..c51996e41 100644
--- a/doc/manual/src/architecture/store/fso.md
+++ b/doc/manual/src/architecture/store/fso.md
@@ -42,7 +42,7 @@ Examples:
     └── nix_node -> /nix/store/f20...-nodejs-10.24.
 
 A bare file or symlink can be a root file system object.
-Examles:
+Examples:
 
     /nix/store/<hash>-hello-2.10.tar.gz
 
-- 
cgit v1.2.3


From de5dea45f7443dd14068e6289e8844816f445c35 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Wed, 13 Jul 2022 09:37:16 +0100
Subject: use correct Nix entity

Nix itself does care a lot about what type of store object you have.
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index e1d983d99..5ac512621 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -32,7 +32,7 @@ A store object can hold
 - arbitrary *data*
 - *references* to other store objects.
 
-Nix makes no distinction if store objects are build inputs, build results, or build tasks.
+A Nix store makes no distinction if store objects are build inputs, build results, or build tasks.
 
 Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
 
-- 
cgit v1.2.3


From 5a5a95696f4728010486ee01b375b861acc2fddd Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Wed, 13 Jul 2022 10:42:21 +0100
Subject: note customized base32

Nix omits E O U T characters for some reason.
---
 doc/manual/src/architecture/store/path.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 3f2a4bbff..9f47b877f 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -16,7 +16,7 @@ It is rendered to a file system path as the concatenation of
 
   - [store directory](#store-directory)
   - path-separator (`/`)
-  - [digest](#digest) rendered in [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
+  - [digest](#digest) rendered in a custom variant of [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
   - hyphen (`-`)
   - name
 
-- 
cgit v1.2.3


From bac86231add178e4def3e3fe0bc88ace83d86c21 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Wed, 13 Jul 2022 10:59:09 +0100
Subject: use "build plan" consistently

---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 3d17074cc..d9fb2e7e5 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -36,7 +36,7 @@ The command line and Nix language are what users interact with most.
 
 ::: {.note}
 The Nix language itself does not have a notion of *packages* or *configurations*.
-As far as we are concerned here, the inputs and results of a derivation are just data.
+As far as we are concerned here, the inputs and results of a build plan are just data.
 :::
 
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
-- 
cgit v1.2.3


From 9cabba1fc35c4989b0e280c12a845adf0e300dab Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 13 Jul 2022 11:17:46 +0100
Subject: mention hard links

Co-authored-by: Thomas <twatson52@mac.com>
---
 doc/manual/src/architecture/store/fso.md | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/fso.md b/doc/manual/src/architecture/store/fso.md
index c51996e41..2ec365eb6 100644
--- a/doc/manual/src/architecture/store/fso.md
+++ b/doc/manual/src/architecture/store/fso.md
@@ -61,4 +61,9 @@ Examples:
     /nix/store/<hash>-bar
     └── bar -> /nix/store/abc...-foo
 
+Nix file system objects do not support [hard links][hardlink]:
+each file system object which is not the root has exactly one parent and one name.
+However, as store objects are immutable, an underlying file system can use hard links for optimization.
+
 [symlink]: https://en.m.wikipedia.org/wiki/Symbolic_link
+[hardlink]: https://en.m.wikipedia.org/wiki/Hard_link
-- 
cgit v1.2.3


From 29c062537d37fc10997767edd3edb6af41f1fb00 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 13 Jul 2022 11:42:16 +0100
Subject: hashes: truncate -> reduce, mention SHA-256

the longer SHA-256 hashes are not truncated, but in fact processed.

Co-authored-by: Thomas <twatson52@mac.com>
---
 doc/manual/src/architecture/store/path.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 9f47b877f..64bc4a522 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -62,12 +62,13 @@ Store objects are therefore said to be either [input-addressed](#input-addressin
 
 ::: {.note}
 **Historical note**: The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
-This is no longer true, but longer hashes and other information are still truncated to 20 bytes for compatibility.
+Nix now uses [SHA-256][sha-256], and longer hashes are still reduced to 20 bytes for compatibility.
 :::
 
 [digest]: https://en.m.wiktionary.org/wiki/digest#Noun
 [hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
 [sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
+[sha-256]: https://en.m.wikipedia.org/wiki/SHA-256
 
 ### Reference scanning
 
-- 
cgit v1.2.3


From 0228eb8ae76d048b16caffff9628aec347ff1485 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Wed, 13 Jul 2022 11:53:59 +0100
Subject: add Java example on manual dependency declaration

---
 doc/manual/src/architecture/store/path.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 64bc4a522..7d793749b 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -83,6 +83,8 @@ Doing it at build time and persisting references in the store object avoids repe
 ::: {.note}
 In practice, it is sometimes still necessary to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
 This depends on the specifics of the software to build and run.
+
+For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
 :::
 
 ## Input Addressing {#input-addressing}
-- 
cgit v1.2.3


From db6faf44a9befeaabbbd1bb025b3f5a7d743dd16 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 28 Jul 2022 23:23:43 +0200
Subject: clarify what store objects can be

the store of course makes a distinction, but that is not relevant here
---
 doc/manual/src/architecture/store/store.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 5ac512621..920d483d5 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -32,7 +32,7 @@ A store object can hold
 - arbitrary *data*
 - *references* to other store objects.
 
-A Nix store makes no distinction if store objects are build inputs, build results, or build tasks.
+Store objects can be build inputs, build results, or build tasks.
 
 Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
 
-- 
cgit v1.2.3


From 00a7eaed6759c284444c161c69a3a585579a7d5f Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 4 Aug 2022 12:30:27 +0200
Subject: add file system object to table of contents

---
 doc/manual/src/SUMMARY.md.in | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 5581bad3a..d589156ec 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -27,6 +27,7 @@
     - [Digest](architecture/store/path.md#digest)
     - [Input Addressing](architecture/store/path.md#input-addressing)
     - [Content Addressing](architecture/store/path.md#content-addressing)
+  - [File System Object](architecture/store/fso.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
-- 
cgit v1.2.3


From b7309ce624d17a2dbe97f63700d59830c35b074a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 4 Aug 2022 12:31:24 +0200
Subject: move architecture to the end

---
 doc/manual/src/SUMMARY.md.in | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index d589156ec..9c2ae2ad3 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -15,19 +15,6 @@
     - [Multi-User Mode](installation/multi-user.md)
   - [Environment Variables](installation/env-variables.md)
   - [Upgrading Nix](installation/upgrading.md)
-- [Architecture](architecture/architecture.md)
-  - [Store](architecture/store/store.md)
-    - [Store Object](architecture/store/store.md#store-object)
-    - [Reference](architecture/store/store.md#reference)
-    - [Operations](architecture/store/store.md#operations)
-    - [Closure](architecture/store/store.md#closure)
-    - [Files and Processes](architecture/store/store.md#files-and-processes)
-    - [Build system terminology](architecture/store/store.md#build-system-terminology)
-  - [Store Path](architecture/store/path.md)
-    - [Digest](architecture/store/path.md#digest)
-    - [Input Addressing](architecture/store/path.md#input-addressing)
-    - [Content Addressing](architecture/store/path.md#content-addressing)
-  - [File System Object](architecture/store/fso.md)
 - [Package Management](package-management/package-management.md)
   - [Basic Package Management](package-management/basic-package-mgmt.md)
   - [Profiles](package-management/profiles.md)
@@ -79,6 +66,19 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
+- [Architecture](architecture/architecture.md)
+  - [Store](architecture/store/store.md)
+    - [Store Object](architecture/store/store.md#store-object)
+    - [Reference](architecture/store/store.md#reference)
+    - [Operations](architecture/store/store.md#operations)
+    - [Closure](architecture/store/store.md#closure)
+    - [Files and Processes](architecture/store/store.md#files-and-processes)
+    - [Build system terminology](architecture/store/store.md#build-system-terminology)
+  - [Store Path](architecture/store/path.md)
+    - [Digest](architecture/store/path.md#digest)
+    - [Input Addressing](architecture/store/path.md#input-addressing)
+    - [Content Addressing](architecture/store/path.md#content-addressing)
+  - [File System Object](architecture/store/fso.md)
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
-- 
cgit v1.2.3


From 3df1ee2ba573a999aebb87cc9c5cac21df158120 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin@fricklerhandwerk.de>
Date: Thu, 4 Aug 2022 12:32:35 +0200
Subject: clarify what explicitly declaring certain dependencies means

---
 doc/manual/src/architecture/store/path.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 7d793749b..3b14b2f3c 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -81,7 +81,7 @@ This way, scanning files captures run time dependencies without the user having
 Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
 
 ::: {.note}
-In practice, it is sometimes still necessary to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
+In practice, it is sometimes still necessary for users to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
 This depends on the specifics of the software to build and run.
 
 For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
-- 
cgit v1.2.3


From 3c2de2da01704ad2b43182b3b9080dc541e7efc7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Domen=20Ko=C5=BEar?= <domen@enlambda.com>
Date: Thu, 4 Aug 2022 06:23:36 -0500
Subject: Update doc/manual/src/installation/installing-binary.md

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/installation/installing-binary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index a2f284d5a..d94e78a91 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -149,7 +149,7 @@ and `/etc/zshrc` which you may remove.
 
 4. Edit fstab using `sudo vifs` to remove the line mounting the Nix Store
    volume on `/nix`, which looks like
-   `UUID=<unique uuid> /nix apfs rw,noauto,nobrowse,suid,owners` or
+   `UUID=<uuid> /nix apfs rw,noauto,nobrowse,suid,owners` or
    `LABEL=Nix\040Store /nix apfs rw,nobrowse`. This will prevent automatic
    mounting of the Nix Store volume.
 
-- 
cgit v1.2.3


From 84a26882f86e68df3f2d0f66ff627e0dbd6365f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Domen=20Ko=C5=BEar?= <domen@enlambda.com>
Date: Thu, 4 Aug 2022 06:23:45 -0500
Subject: Update doc/manual/src/installation/installing-binary.md

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/installation/installing-binary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index d94e78a91..ed0f65177 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -176,7 +176,7 @@ and `/etc/zshrc` which you may remove.
    This will remove the Nix Store volume and everything that was added to the
    store.
 
-   If this command indicates that it couldn't remove the volume, you should
+   If the output indicates that the command couldn't remove the volume, you should
    make sure you don't have an _unmounted_ Nix Store volume. Look for a
    "Nix Store" volume in the output of the following command:
 
-- 
cgit v1.2.3


From 8cec32e7f5e073946ef7bbf5ec1839e40b203bbc Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 4 Aug 2022 13:50:44 +0200
Subject: fix directory tree renderings

---
 doc/manual/src/architecture/store/fso.md | 38 ++++++++++++++++----------------
 1 file changed, 19 insertions(+), 19 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/fso.md b/doc/manual/src/architecture/store/fso.md
index 2ec365eb6..e0eb69f60 100644
--- a/doc/manual/src/architecture/store/fso.md
+++ b/doc/manual/src/architecture/store/fso.md
@@ -19,27 +19,27 @@ Examples:
 
 - a directory with contents
 
-    /nix/store/<hash>-hello-2.10
-    ├── bin
-    │   └── hello
-    └── share
-        ├── info
-        │   └── hello.info
-        └── man
-            └── man1
-                └── hello.1.gz
+      /nix/store/<hash>-hello-2.10
+      ├── bin
+      │   └── hello
+      └── share
+          ├── info
+          │   └── hello.info
+          └── man
+              └── man1
+                  └── hello.1.gz
 
 - a directory with relative symlink and other contents
 
-    /nix/store/<hash>-go-1.16.9
-    ├── bin -> share/go/bin
-    ├── nix-support/
-    └── share/
+      /nix/store/<hash>-go-1.16.9
+      ├── bin -> share/go/bin
+      ├── nix-support/
+      └── share/
 
 - a directory with absolute symlink
 
-    /nix/store/d3k...-nodejs
-    └── nix_node -> /nix/store/f20...-nodejs-10.24.
+      /nix/store/d3k...-nodejs
+      └── nix_node -> /nix/store/f20...-nodejs-10.24.
 
 A bare file or symlink can be a root file system object.
 Examples:
@@ -53,13 +53,13 @@ Examples:
 
 - an arbitrarily symlinked file may change or not exist at all
 
-    /nix/store/<hash>-foo
-    └── foo -> /home/foo
+      /nix/store/<hash>-foo
+      └── foo -> /home/foo
 
 - if a symlink to a store path was not automatically created by Nix, it may be invalid or get invalidated when the store object is deleted
 
-    /nix/store/<hash>-bar
-    └── bar -> /nix/store/abc...-foo
+      /nix/store/<hash>-bar
+      └── bar -> /nix/store/abc...-foo
 
 Nix file system objects do not support [hard links][hardlink]:
 each file system object which is not the root has exactly one parent and one name.
-- 
cgit v1.2.3


From cc3a5f4ba2cb6859e0f324a5e74a42668b96aff0 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 4 Aug 2022 14:04:02 +0200
Subject: use correct mdBook syntax for callouts

---
 doc/manual/src/architecture/architecture.md |  7 +++----
 doc/manual/src/architecture/store/path.md   | 21 +++++++++------------
 2 files changed, 12 insertions(+), 16 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index d9fb2e7e5..96371056b 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -34,10 +34,9 @@ It is used to compose expressions which ultimately evaluate to self-contained *b
 
 The command line and Nix language are what users interact with most.
 
-::: {.note}
-The Nix language itself does not have a notion of *packages* or *configurations*.
-As far as we are concerned here, the inputs and results of a build plan are just data.
-:::
+> **Note**
+> The Nix language itself does not have a notion of *packages* or *configurations*.
+> As far as we are concerned here, the inputs and results of a build plan are just data.
 
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute build plans to produce new data.
diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 3b14b2f3c..5a18df67a 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -34,9 +34,8 @@ If the store has a [file system representation](./store.md#files-and-processes),
 
 This means a store path is not just derived from the referenced store object itself, but depends on the store the store object is in.
 
-::: {.note}
-The store directory defaults to `/nix/store`, but is in principle arbitrary.
-:::
+> **Note**
+> The store directory defaults to `/nix/store`, but is in principle arbitrary.
 
 It is important which store a given store object belongs to:
 Files in the store object can contain store paths, and processes may read these paths.
@@ -60,10 +59,9 @@ In a [store path](#store-path), the [digest][digest] is the output of a [cryptog
 
 Store objects are therefore said to be either [input-addressed](#input-addressing) or [content-addressed](#content-addressing).
 
-::: {.note}
-**Historical note**: The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
-Nix now uses [SHA-256][sha-256], and longer hashes are still reduced to 20 bytes for compatibility.
-:::
+> **Historical Note**
+> The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
+> Nix now uses [SHA-256][sha-256], and longer hashes are still reduced to 20 bytes for compatibility.
 
 [digest]: https://en.m.wiktionary.org/wiki/digest#Noun
 [hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
@@ -80,12 +78,11 @@ Nix uses the [closure](store.md#closure) of build inputs to derive the list of a
 This way, scanning files captures run time dependencies without the user having to declare them explicitly.
 Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
 
-::: {.note}
-In practice, it is sometimes still necessary for users to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
+> **Note**
+> In practice, it is sometimes still necessary for users to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
 This depends on the specifics of the software to build and run.
-
-For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
-:::
+>
+> For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
 
 ## Input Addressing {#input-addressing}
 
-- 
cgit v1.2.3


From b63174227704c2a5fc11e815aaf3b4a6fd6f4576 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 4 Aug 2022 14:31:33 +0200
Subject: fix page rendering

apparently it is not possible to link to page anchors with `mdBook`[1]

[1]: https://github.com/rust-lang/mdBook/issues/167
---
 doc/manual/src/SUMMARY.md.in                       |  8 +--
 doc/manual/src/architecture/store/path.md          |  2 +-
 doc/manual/src/architecture/store/store.md         | 61 ----------------------
 doc/manual/src/architecture/store/store/closure.md | 29 ++++++++++
 .../src/architecture/store/store/terminology.md    | 32 ++++++++++++
 5 files changed, 64 insertions(+), 68 deletions(-)
 create mode 100644 doc/manual/src/architecture/store/store/closure.md
 create mode 100644 doc/manual/src/architecture/store/store/terminology.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 9c2ae2ad3..a95c385e4 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -68,12 +68,8 @@
     - [nix.conf](command-ref/conf-file.md)
 - [Architecture](architecture/architecture.md)
   - [Store](architecture/store/store.md)
-    - [Store Object](architecture/store/store.md#store-object)
-    - [Reference](architecture/store/store.md#reference)
-    - [Operations](architecture/store/store.md#operations)
-    - [Closure](architecture/store/store.md#closure)
-    - [Files and Processes](architecture/store/store.md#files-and-processes)
-    - [Build system terminology](architecture/store/store.md#build-system-terminology)
+    - [Closure](architecture/store/store/closure.md)
+    - [Build system terminology](architecture/store/build-system-terminology.md)
   - [Store Path](architecture/store/path.md)
     - [Digest](architecture/store/path.md#digest)
     - [Input Addressing](architecture/store/path.md#input-addressing)
diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 5a18df67a..039d8b1c6 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -39,7 +39,7 @@ This means a store path is not just derived from the referenced store object its
 
 It is important which store a given store object belongs to:
 Files in the store object can contain store paths, and processes may read these paths.
-Nix can only guarantee [referential integrity](store.md#closure) if store paths do not cross store boundaries.
+Nix can only guarantee [referential integrity](store/closure.md) if store paths do not cross store boundaries.
 
 Therefore one can only copy store objects to a different store if
 
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 920d483d5..9f580f9da 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -89,35 +89,6 @@ As it keeps track of references, it can [garbage-collect][garbage-collection] un
 
     [ store ] --> collect garbage --> [ store' ]
 
-
-## Closure {#closure}
-
-Nix stores ensure [referential integrity][referential-integrity]: for each store object in the store, all the store objects it references must also be in the store.
-
-The set of all store objects reachable by following references from a given initial set of store objects is called a *closure*.
-
-Adding, building, copying and deleting store objects must be done in a way that preserves referential integrity:
-
-- A newly added store object cannot have references, unless it is a build task.
-
-- Build results must only refer to store objects in the closure of the build inputs.
-
-  Building a store object will add appropriate references, according to the build task.
-
-- Store objects being copied must refer to objects already in the destination store.
-
-  Recursive copying must either proceed in dependency order or be atomic.
-
-- We can only safely delete store objects which are not reachable from any reference still in use.
-
-  <!-- more details in section on garbage collection, link to it once it exists -->
-
-[referential-integrity]: https://en.m.wikipedia.org/wiki/Referential_integrity
-[garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
-[immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
-[opaque-data-type]: https://en.m.wikipedia.org/wiki/Opaque_data_type
-[unique-identifier]: https://en.m.wikipedia.org/wiki/Unique_identifier
-
 ## Files and Processes {#files-and-processes}
 
 Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
@@ -178,35 +149,3 @@ Examples:
 
 To make store objects accessible to processes, stores ultimately have to expose store objects through the file system.
 
-## A [Rosetta stone][rosetta-stone] for build system terminology {#build-system-terminology}
-
-The Nix store's design is comparable to other build systems.
-Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
-
-The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
-
-| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
-| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
-| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
-| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
-| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
-| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
-| build                            | build            | build                                                                | application of `Build`            | evaluation               |
-| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
-
-All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
-
-[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
-[bazel]: https://bazel.build/start/bazel-intro
-[bazel-artifact]: https://bazel.build/reference/glossary#artifact
-[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
-[bazel-action]: https://bazel.build/reference/glossary#action
-[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
-[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
-[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
-[thunk]: https://en.m.wikipedia.org/wiki/Thunk
-[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
-[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
-[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
-[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
-[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
diff --git a/doc/manual/src/architecture/store/store/closure.md b/doc/manual/src/architecture/store/store/closure.md
new file mode 100644
index 000000000..065b95ffc
--- /dev/null
+++ b/doc/manual/src/architecture/store/store/closure.md
@@ -0,0 +1,29 @@
+# Closure
+
+Nix stores ensure [referential integrity][referential-integrity]: for each store object in the store, all the store objects it references must also be in the store.
+
+The set of all store objects reachable by following references from a given initial set of store objects is called a *closure*.
+
+Adding, building, copying and deleting store objects must be done in a way that preserves referential integrity:
+
+- A newly added store object cannot have references, unless it is a build task.
+
+- Build results must only refer to store objects in the closure of the build inputs.
+
+  Building a store object will add appropriate references, according to the build task.
+
+- Store objects being copied must refer to objects already in the destination store.
+
+  Recursive copying must either proceed in dependency order or be atomic.
+
+- We can only safely delete store objects which are not reachable from any reference still in use.
+
+  <!-- more details in section on garbage collection, link to it once it exists -->
+
+[referential-integrity]: https://en.m.wikipedia.org/wiki/Referential_integrity
+[garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
+[immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
+[opaque-data-type]: https://en.m.wikipedia.org/wiki/Opaque_data_type
+[unique-identifier]: https://en.m.wikipedia.org/wiki/Unique_identifier
+
+
diff --git a/doc/manual/src/architecture/store/store/terminology.md b/doc/manual/src/architecture/store/store/terminology.md
new file mode 100644
index 000000000..3dd7aa756
--- /dev/null
+++ b/doc/manual/src/architecture/store/store/terminology.md
@@ -0,0 +1,32 @@
+# A [Rosetta stone][rosetta-stone] for build system terminology {#build-system-terminology}
+
+The Nix store's design is comparable to other build systems.
+Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
+
+The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
+
+| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
+| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
+| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
+| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
+| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
+| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
+| build                            | build            | build                                                                | application of `Build`            | evaluation               |
+| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
+
+All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
+
+[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
+[bazel]: https://bazel.build/start/bazel-intro
+[bazel-artifact]: https://bazel.build/reference/glossary#artifact
+[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
+[bazel-action]: https://bazel.build/reference/glossary#action
+[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
+[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
+[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
+[thunk]: https://en.m.wikipedia.org/wiki/Thunk
+[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
+[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
+[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
+[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
+[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
-- 
cgit v1.2.3


From b430a6743c59aebc08968da3cf01e476edbc36c2 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 4 Aug 2022 14:01:55 -0400
Subject: Remove sections within from SUMMARY

---
 doc/manual/src/SUMMARY.md.in | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 812a3d732..a47d39f31 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -62,11 +62,8 @@
 - [Architecture](architecture/architecture.md)
   - [Store](architecture/store/store.md)
     - [Closure](architecture/store/store/closure.md)
-    - [Build system terminology](architecture/store/build-system-terminology.md)
+    - [Build system terminology](architecture/store/store/build-system-terminology.md)
   - [Store Path](architecture/store/path.md)
-    - [Digest](architecture/store/path.md#digest)
-    - [Input Addressing](architecture/store/path.md#input-addressing)
-    - [Content Addressing](architecture/store/path.md#content-addressing)
   - [File System Object](architecture/store/fso.md)
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
-- 
cgit v1.2.3


From 016d7a8f78bee2181d1d60bcf9a8a59a4f18e91f Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 4 Aug 2022 14:02:19 -0400
Subject: Fix rosetta stone file name

---
 .../store/store/build-system-terminology.md        | 32 ++++++++++++++++++++++
 .../src/architecture/store/store/terminology.md    | 32 ----------------------
 2 files changed, 32 insertions(+), 32 deletions(-)
 create mode 100644 doc/manual/src/architecture/store/store/build-system-terminology.md
 delete mode 100644 doc/manual/src/architecture/store/store/terminology.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/store/build-system-terminology.md b/doc/manual/src/architecture/store/store/build-system-terminology.md
new file mode 100644
index 000000000..eefbaa630
--- /dev/null
+++ b/doc/manual/src/architecture/store/store/build-system-terminology.md
@@ -0,0 +1,32 @@
+# A [Rosetta stone][rosetta-stone] for build system terminology
+
+The Nix store's design is comparable to other build systems.
+Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
+
+The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
+
+| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
+| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
+| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
+| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
+| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
+| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
+| build                            | build            | build                                                                | application of `Build`            | evaluation               |
+| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
+
+All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
+
+[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
+[bazel]: https://bazel.build/start/bazel-intro
+[bazel-artifact]: https://bazel.build/reference/glossary#artifact
+[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
+[bazel-action]: https://bazel.build/reference/glossary#action
+[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
+[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
+[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
+[thunk]: https://en.m.wikipedia.org/wiki/Thunk
+[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
+[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
+[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
+[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
+[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
diff --git a/doc/manual/src/architecture/store/store/terminology.md b/doc/manual/src/architecture/store/store/terminology.md
deleted file mode 100644
index 3dd7aa756..000000000
--- a/doc/manual/src/architecture/store/store/terminology.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# A [Rosetta stone][rosetta-stone] for build system terminology {#build-system-terminology}
-
-The Nix store's design is comparable to other build systems.
-Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
-
-The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
-
-| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
-| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
-| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
-| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
-| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
-| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
-| build                            | build            | build                                                                | application of `Build`            | evaluation               |
-| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
-
-All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
-
-[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
-[bazel]: https://bazel.build/start/bazel-intro
-[bazel-artifact]: https://bazel.build/reference/glossary#artifact
-[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
-[bazel-action]: https://bazel.build/reference/glossary#action
-[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
-[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
-[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
-[thunk]: https://en.m.wikipedia.org/wiki/Thunk
-[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
-[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
-[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
-[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
-[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
-- 
cgit v1.2.3


From 6f6498f59c9263d3d4bdc6d2c3776e6abad2e516 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 4 Aug 2022 14:02:38 -0400
Subject: Remove header fragments which is not needd

---
 doc/manual/src/architecture/store/path.md  | 8 ++++----
 doc/manual/src/architecture/store/store.md | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
index 039d8b1c6..663f04f46 100644
--- a/doc/manual/src/architecture/store/path.md
+++ b/doc/manual/src/architecture/store/path.md
@@ -26,7 +26,7 @@ Example:
       |--------| |------------------------------| |----------|
     store directory            digest                 name
 
-## Store Directory {#store-directory}
+## Store Directory
 
 Every [store](./store.md) has a store directory.
 
@@ -53,7 +53,7 @@ One cannot copy a store object to a store with a different store directory.
 Instead, it has to be rebuilt, together with all its dependencies.
 It is in general not enough to replace the store directory string in file contents, as this may render executables unusable by invalidating their internal offsets or checksums.
 
-# Digest {#digest}
+# Digest
 
 In a [store path](#store-path), the [digest][digest] is the output of a [cryptographic hash function][hash] of either all *inputs* involved in building the referenced store object or its actual *contents*.
 
@@ -84,7 +84,7 @@ This depends on the specifics of the software to build and run.
 >
 > For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
 
-## Input Addressing {#input-addressing}
+## Input Addressing
 
 Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
 
@@ -95,7 +95,7 @@ Nix has a custom serialisation format called Nix Archive (NAR)
 Store object references of this sort can *not* be validated from the content of the store object.
 Rather, a cryptographic signature has to be used to indicate that someone is vouching for the store object really being produced from a build plan with that digest.
 
-## Content Addressing {#content-addressing}
+## Content Addressing
 
 Content addressing means that the digest derives from the store object's contents, namely its file system objects and references.
 If one knows content addressing was used, one can recalculate the reference and thus verify the store object.
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
index 9f580f9da..08b6701d5 100644
--- a/doc/manual/src/architecture/store/store.md
+++ b/doc/manual/src/architecture/store/store.md
@@ -25,7 +25,7 @@ Arrows indicate suggested reading order.
 [ input addressing ] [ content addressing ]
 ```
 
-## Store Object {#store-object}
+## Store Object
 
 A store object can hold
 
@@ -36,13 +36,13 @@ Store objects can be build inputs, build results, or build tasks.
 
 Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
 
-## Reference {#reference}
+## Reference
 
 A store object reference is an [opaque][opaque-data-type], [unique identifier][unique-identifier]:
 The only way to obtain references is by adding or building store objects.
 A reference will always point to exactly one store object.
 
-## Operations {#operations}
+## Operations
 
 A Nix store can *add*, *retrieve*, and *delete* store objects.
 
@@ -89,7 +89,7 @@ As it keeps track of references, it can [garbage-collect][garbage-collection] un
 
     [ store ] --> collect garbage --> [ store' ]
 
-## Files and Processes {#files-and-processes}
+## Files and Processes
 
 Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
 That allows processes to resolve references contained in files and thus access the contents of store objects.
-- 
cgit v1.2.3


From 39d32ac4c63f4aa3784d114b19c0eca83e306ca9 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 4 Aug 2022 14:02:58 -0400
Subject: Add disclaimer that arch section is WIP and links may rot

So we can iterate without worrying so much.
---
 doc/manual/src/architecture/architecture.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 96371056b..41deb07af 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -1,5 +1,7 @@
 # Architecture
 
+*(This chapter is unstable and a work in progress. Incoming links may rot.)*
+
 This chapter describes how Nix works.
 It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
 
-- 
cgit v1.2.3


From a5be5e01200a12cc34d0e3a2e3f964d5c95208b9 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 4 Aug 2022 14:07:06 -0700
Subject: doc/manual: define {local,remote} store, binary cache, substituter

Nix veterans intuitively know what the following terms mean.  They are
used in several places in the nix documentation, but never defined:

- local store
- remote store
- binary cache
- substituter

In particular, I found the last two terms to be confusingly similar.
Let's give definitions for them.
---
 doc/manual/src/SUMMARY.md.in                     |  1 +
 doc/manual/src/package-management/terminology.md | 27 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 doc/manual/src/package-management/terminology.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index a47d39f31..f8da2247b 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -22,6 +22,7 @@
     - [Garbage Collector Roots](package-management/garbage-collector-roots.md)
   - [Channels](package-management/channels.md)
   - [Sharing Packages Between Machines](package-management/sharing-packages.md)
+    - [Terminology](package-management/terminology.md)
     - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md)
     - [Copying Closures via SSH](package-management/copy-closure.md)
     - [Serving a Nix store via SSH](package-management/ssh-substituter.md)
diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
new file mode 100644
index 000000000..28e2a1f0b
--- /dev/null
+++ b/doc/manual/src/package-management/terminology.md
@@ -0,0 +1,27 @@
+# Terminology
+
+A *local store* exists on the local filesystem of the machine where
+Nix is invoked.  The `/nix/store` directory is one example of a
+local store.  You can use other local stores by passing the
+`--store` flag to `nix`.
+
+A *remote store* is a store which exists anywhere other than the
+local filesystem.  One example is the `/nix/store` directory on
+another machine, accessed via `ssh` or served by the `nix-serve`
+Perl script.
+
+A *binary cache* is a remote store which is not the local store of
+any machine.  Examples of binary caches include S3 buckets and the
+[NixOS binary cache](https://cache.nixos.org).  Binary caches use a
+disk layout that is different from local stores; in particular, they
+keep metadata and signatures in `.narinfo` files rather than in
+`/nix/var/nix/db`.
+
+A *substituter* is a store other than `/nix/store` from which nix will
+copy the realisation of a derivation instead of building it.  Nix will
+not copy a realisation from a remote store unless one of the following
+is true:
+
+- the realisation is signed by one of the `trusted-public-key`s
+- the substituter is in the `trusted-substituters` list
+- the `no-require-sigs` option has been set to disable signature checking
-- 
cgit v1.2.3


From 56d4fc194ba90ee4e559a07a895f6bf4a61ef462 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 4 Aug 2022 14:14:24 -0700
Subject: fourth trust condition: FODs

---
 doc/manual/src/package-management/terminology.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 28e2a1f0b..1722a9fc8 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -25,3 +25,5 @@ is true:
 - the realisation is signed by one of the `trusted-public-key`s
 - the substituter is in the `trusted-substituters` list
 - the `no-require-sigs` option has been set to disable signature checking
+- the derivation is a fixed-output derivation
+
-- 
cgit v1.2.3


From 8f44d24c525160b2ddef5e18a4af4ce667e23e9f Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 4 Aug 2022 14:19:25 -0700
Subject: !fixup whitespace

---
 doc/manual/src/package-management/terminology.md | 1 -
 1 file changed, 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 1722a9fc8..d800bafc1 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -26,4 +26,3 @@ is true:
 - the substituter is in the `trusted-substituters` list
 - the `no-require-sigs` option has been set to disable signature checking
 - the derivation is a fixed-output derivation
-
-- 
cgit v1.2.3


From 62674659ed7b7fc6a2c884f52df2474e344400f8 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 4 Aug 2022 14:21:17 -0700
Subject: !fixup capitalize Nix

---
 doc/manual/src/package-management/terminology.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index d800bafc1..8dc2ede33 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -17,7 +17,7 @@ disk layout that is different from local stores; in particular, they
 keep metadata and signatures in `.narinfo` files rather than in
 `/nix/var/nix/db`.
 
-A *substituter* is a store other than `/nix/store` from which nix will
+A *substituter* is a store other than `/nix/store` from which Nix will
 copy the realisation of a derivation instead of building it.  Nix will
 not copy a realisation from a remote store unless one of the following
 is true:
-- 
cgit v1.2.3


From 1b97f3872ed70d9ad5d19d27dc56b42ba4d26382 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 4 Aug 2022 14:22:14 -0700
Subject: !fixup: transposed characters

---
 doc/manual/src/package-management/terminology.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 8dc2ede33..6ad0f6833 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -22,7 +22,7 @@ copy the realisation of a derivation instead of building it.  Nix will
 not copy a realisation from a remote store unless one of the following
 is true:
 
-- the realisation is signed by one of the `trusted-public-key`s
+- the realisation is signed by one of the `trusted-public-keys`
 - the substituter is in the `trusted-substituters` list
 - the `no-require-sigs` option has been set to disable signature checking
 - the derivation is a fixed-output derivation
-- 
cgit v1.2.3


From 4eb566603a1f6f08eae074d48e5c860e1d5d561b Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 5 Aug 2022 11:01:40 +0200
Subject: Comment out the architecture section

This needs more review and probably should be a separate book.
---
 doc/manual/src/SUMMARY.md.in | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index a47d39f31..8fbb59716 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -59,12 +59,14 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
+<!--
 - [Architecture](architecture/architecture.md)
   - [Store](architecture/store/store.md)
     - [Closure](architecture/store/store/closure.md)
     - [Build system terminology](architecture/store/store/build-system-terminology.md)
   - [Store Path](architecture/store/path.md)
   - [File System Object](architecture/store/fso.md)
+-->
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
-- 
cgit v1.2.3


From aae771cad26a3803ef0a0855c782823d22949cf3 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Fri, 5 Aug 2022 10:12:46 -0700
Subject: !implement
 https://github.com/NixOS/nix/pull/6870#discussion_r938912244

---
 doc/manual/src/package-management/terminology.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 6ad0f6833..241bb6c5a 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -18,11 +18,10 @@ keep metadata and signatures in `.narinfo` files rather than in
 `/nix/var/nix/db`.
 
 A *substituter* is a store other than `/nix/store` from which Nix will
-copy the realisation of a derivation instead of building it.  Nix will
-not copy a realisation from a remote store unless one of the following
-is true:
+copy a store path instead of building it.  Nix will not copy a store
+path from a remote store unless one of the following is true:
 
-- the realisation is signed by one of the `trusted-public-keys`
+- the store object is signed by one of the `trusted-public-keys`
 - the substituter is in the `trusted-substituters` list
 - the `no-require-sigs` option has been set to disable signature checking
-- the derivation is a fixed-output derivation
+- the store object is the realisation of a fixed-output derivation
-- 
cgit v1.2.3


From 2eb74c918dc7dc04ed36b3fdcd95406007d97690 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Fri, 5 Aug 2022 10:13:41 -0700
Subject: derivations do not need to be signed

---
 doc/manual/src/package-management/terminology.md | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 241bb6c5a..4b9e68de9 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -24,4 +24,5 @@ path from a remote store unless one of the following is true:
 - the store object is signed by one of the `trusted-public-keys`
 - the substituter is in the `trusted-substituters` list
 - the `no-require-sigs` option has been set to disable signature checking
+- the store object is a derivation
 - the store object is the realisation of a fixed-output derivation
-- 
cgit v1.2.3


From 66a93a76b9842ac18188b91f5a30c4ac4f2b6118 Mon Sep 17 00:00:00 2001
From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>
Date: Fri, 5 Aug 2022 17:15:37 +0000
Subject: Update doc/manual/src/package-management/terminology.md

Co-authored-by: Attila Gulyas <toraritte@gmail.com>
---
 doc/manual/src/package-management/terminology.md | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 4b9e68de9..564667f93 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -1,14 +1,22 @@
 # Terminology
 
-A *local store* exists on the local filesystem of the machine where
-Nix is invoked.  The `/nix/store` directory is one example of a
-local store.  You can use other local stores by passing the
-`--store` flag to `nix`.
+From   the  perspective   of   the  location   where  Nix   is
+invoked<sup><b>1</b></sup>, the  Nix store can be  referred to
+as a "_local_" or a "_remote_" one:
 
-A *remote store* is a store which exists anywhere other than the
-local filesystem.  One example is the `/nix/store` directory on
-another machine, accessed via `ssh` or served by the `nix-serve`
-Perl script.
+<sup>\[1]: Where "invoking Nix" means  an executing a Nix core
+action/operation on  a Nix store.  For example, using  any CLI
+commands from the `NixOS/nix` implementation.</sup>
+
++ A *local  store* exists  on the local  filesystem of
+  the machine where Nix is  invoked. You can use other
+  local stores  by passing  the `--store` flag  to the
+  `nix` command.
+
++ A  *remote store*  exists  anywhere  other than  the
+  local  filesystem. One  example is  the `/nix/store`
+  directory on another machine,  accessed via `ssh` or
+  served by the `nix-serve` Perl script.
 
 A *binary cache* is a remote store which is not the local store of
 any machine.  Examples of binary caches include S3 buckets and the
-- 
cgit v1.2.3


From d5506aa71200425b65cc1777077478f5ff8d2aff Mon Sep 17 00:00:00 2001
From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>
Date: Fri, 5 Aug 2022 17:19:52 +0000
Subject: Update doc/manual/src/package-management/terminology.md

Co-authored-by: Attila Gulyas <toraritte@gmail.com>
---
 doc/manual/src/package-management/terminology.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index 564667f93..b3e9ea040 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -18,12 +18,10 @@ commands from the `NixOS/nix` implementation.</sup>
   directory on another machine,  accessed via `ssh` or
   served by the `nix-serve` Perl script.
 
-A *binary cache* is a remote store which is not the local store of
-any machine.  Examples of binary caches include S3 buckets and the
-[NixOS binary cache](https://cache.nixos.org).  Binary caches use a
-disk layout that is different from local stores; in particular, they
-keep metadata and signatures in `.narinfo` files rather than in
-`/nix/var/nix/db`.
+A *binary cache* is a specialized Nix store whose metadata and
+signatures are kept in `.narinfo` files rather than in the Nix
+database. Examples of binary caches include S3 buckets and the
+[NixOS binary cache](https://cache.nixos.org).
 
 A *substituter* is a store other than `/nix/store` from which Nix will
 copy a store path instead of building it.  Nix will not copy a store
-- 
cgit v1.2.3


From 4de95f7f565df71d8ebddb7434e2b0feb49a833b Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Fri, 5 Aug 2022 10:33:48 -0700
Subject: gesture at explanation of why binary caches exist

---
 doc/manual/src/package-management/terminology.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
index b3e9ea040..493f5f03e 100644
--- a/doc/manual/src/package-management/terminology.md
+++ b/doc/manual/src/package-management/terminology.md
@@ -18,10 +18,12 @@ commands from the `NixOS/nix` implementation.</sup>
   directory on another machine,  accessed via `ssh` or
   served by the `nix-serve` Perl script.
 
-A *binary cache* is a specialized Nix store whose metadata and
-signatures are kept in `.narinfo` files rather than in the Nix
-database. Examples of binary caches include S3 buckets and the
-[NixOS binary cache](https://cache.nixos.org).
+A *binary cache* is a Nix store which uses a different format: its
+metadata and signatures are kept in `.narinfo` files rather than in a
+Nix database.  This different format simplifies serving store objects
+over the network, but cannot host builds.  Examples of binary caches
+include S3 buckets and the [NixOS binary
+cache](https://cache.nixos.org).
 
 A *substituter* is a store other than `/nix/store` from which Nix will
 copy a store path instead of building it.  Nix will not copy a store
-- 
cgit v1.2.3


From 1d3b92e80ca1564bf2c5ee207df707e215188633 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Fri, 5 Aug 2022 10:39:43 -0700
Subject: move package-management/terminology into glossary.md

---
 doc/manual/src/SUMMARY.md.in                     |  1 -
 doc/manual/src/glossary.md                       | 37 ++++++++++++++++++++++++
 doc/manual/src/package-management/terminology.md | 36 -----------------------
 3 files changed, 37 insertions(+), 37 deletions(-)
 delete mode 100644 doc/manual/src/package-management/terminology.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index f8da2247b..a47d39f31 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -22,7 +22,6 @@
     - [Garbage Collector Roots](package-management/garbage-collector-roots.md)
   - [Channels](package-management/channels.md)
   - [Sharing Packages Between Machines](package-management/sharing-packages.md)
-    - [Terminology](package-management/terminology.md)
     - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md)
     - [Copying Closures via SSH](package-management/copy-closure.md)
     - [Serving a Nix store via SSH](package-management/ssh-substituter.md)
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index aa0ac78cb..f4c51588d 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -11,6 +11,32 @@
     The location in the file system where store objects live. Typically
     `/nix/store`.
 
+    From   the  perspective   of   the  location   where  Nix   is
+    invoked<sup><b>1</b></sup>, the  Nix store can be  referred to
+    as a "_local_" or a "_remote_" one:
+
+    <sup>\[1]: Where "invoking Nix" means  an executing a Nix core
+    action/operation on  a Nix store.  For example, using  any CLI
+    commands from the `NixOS/nix` implementation.</sup>
+
+    + A *local  store* exists  on the local  filesystem of
+      the machine where Nix is  invoked. You can use other
+      local stores  by passing  the `--store` flag  to the
+      `nix` command.
+
+    + A  *remote store*  exists  anywhere  other than  the
+      local  filesystem. One  example is  the `/nix/store`
+      directory on another machine,  accessed via `ssh` or
+      served by the `nix-serve` Perl script.
+
+  - [binary cache]{#binary-cache}\
+    A *binary cache* is a Nix store which uses a different format: its
+    metadata and signatures are kept in `.narinfo` files rather than in a
+    Nix database.  This different format simplifies serving store objects
+    over the network, but cannot host builds.  Examples of binary caches
+    include S3 buckets and the [NixOS binary
+    cache](https://cache.nixos.org).
+
   - [store path]{#gloss-store-path}\
     The location in the file system of a store object, i.e., an
     immediate child of the Nix store directory.
@@ -29,6 +55,17 @@
     store object by downloading a pre-built version of the store object
     from some server.
 
+  - [substituter]{#gloss-substituter}\
+    A *substituter* is a store other than `/nix/store` from which Nix will
+    copy a store path instead of building it.  Nix will not copy a store
+    path from a remote store unless one of the following is true:
+
+    - the store object is signed by one of the `trusted-public-keys`
+    - the substituter is in the `trusted-substituters` list
+    - the `no-require-sigs` option has been set to disable signature checking
+    - the store object is a derivation
+    - the store object is the realisation of a fixed-output derivation
+
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
     the same output. This cannot be guaranteed in general (e.g., a
diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md
deleted file mode 100644
index 493f5f03e..000000000
--- a/doc/manual/src/package-management/terminology.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Terminology
-
-From   the  perspective   of   the  location   where  Nix   is
-invoked<sup><b>1</b></sup>, the  Nix store can be  referred to
-as a "_local_" or a "_remote_" one:
-
-<sup>\[1]: Where "invoking Nix" means  an executing a Nix core
-action/operation on  a Nix store.  For example, using  any CLI
-commands from the `NixOS/nix` implementation.</sup>
-
-+ A *local  store* exists  on the local  filesystem of
-  the machine where Nix is  invoked. You can use other
-  local stores  by passing  the `--store` flag  to the
-  `nix` command.
-
-+ A  *remote store*  exists  anywhere  other than  the
-  local  filesystem. One  example is  the `/nix/store`
-  directory on another machine,  accessed via `ssh` or
-  served by the `nix-serve` Perl script.
-
-A *binary cache* is a Nix store which uses a different format: its
-metadata and signatures are kept in `.narinfo` files rather than in a
-Nix database.  This different format simplifies serving store objects
-over the network, but cannot host builds.  Examples of binary caches
-include S3 buckets and the [NixOS binary
-cache](https://cache.nixos.org).
-
-A *substituter* is a store other than `/nix/store` from which Nix will
-copy a store path instead of building it.  Nix will not copy a store
-path from a remote store unless one of the following is true:
-
-- the store object is signed by one of the `trusted-public-keys`
-- the substituter is in the `trusted-substituters` list
-- the `no-require-sigs` option has been set to disable signature checking
-- the store object is a derivation
-- the store object is the realisation of a fixed-output derivation
-- 
cgit v1.2.3


From b5d85f0922e0f4a9585a281f6d938ec67cd07349 Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Fri, 5 Aug 2022 13:49:18 -0500
Subject: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/contributing/hacking.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 9a371afa7..86c6522f2 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -113,11 +113,12 @@ You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-
 
 Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports).
 
-If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped "installer" and "installer_test" jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs.
-- The `installer` job will generate installers for these platforms: x86_64-linux, armv6l-linux, armv7l-linux, x86_64-darwin. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
+If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped `installer` and `installer_test` jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs.
+- The `installer` job will generate installers for these platforms: `x86_64-linux`, `armv6l-linux`, `armv7l-linux`, `x86_64-darwin`. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
 - the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`.
 
 ### One-time setup
+
 1. Have a GitHub account with a fork of the Nix repo.
 2. At cachix.org:
     - Create or log in to an account.
-- 
cgit v1.2.3


From 9b7bd2dd1fc83f6df449fce3967a95cb098ca4b2 Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Mon, 8 Aug 2022 10:04:27 -0500
Subject: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/contributing/hacking.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 86c6522f2..d8a8c8591 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -114,7 +114,13 @@ You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-
 Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports).
 
 If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped `installer` and `installer_test` jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs.
-- The `installer` job will generate installers for these platforms: `x86_64-linux`, `armv6l-linux`, `armv7l-linux`, `x86_64-darwin`. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
+- The `installer` job will generate installers for these platforms:
+  - `x86_64-linux`
+  - `armv6l-linux`
+  - `armv7l-linux`
+  - `x86_64-darwin`.
+  
+  While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
 - the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`.
 
 ### One-time setup
-- 
cgit v1.2.3


From bac1e1bf8c359b5e6831c3974a05bdce867775a5 Mon Sep 17 00:00:00 2001
From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>
Date: Mon, 8 Aug 2022 17:52:31 +0000
Subject: Update doc/manual/src/glossary.md

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/glossary.md | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index f4c51588d..77de58965 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -12,13 +12,9 @@
     `/nix/store`.
 
     From   the  perspective   of   the  location   where  Nix   is
-    invoked<sup><b>1</b></sup>, the  Nix store can be  referred to
+    invoked, the  Nix store can be  referred to
     as a "_local_" or a "_remote_" one:
 
-    <sup>\[1]: Where "invoking Nix" means  an executing a Nix core
-    action/operation on  a Nix store.  For example, using  any CLI
-    commands from the `NixOS/nix` implementation.</sup>
-
     + A *local  store* exists  on the local  filesystem of
       the machine where Nix is  invoked. You can use other
       local stores  by passing  the `--store` flag  to the
-- 
cgit v1.2.3


From 88a0f3b6bace3a17b69dfb799494d78aae0dd71d Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Mon, 8 Aug 2022 16:01:59 -0400
Subject: Strip whitespace in installing-binary.md

---
 doc/manual/src/installation/installing-binary.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 9fb9c80c3..18fc8fff5 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -13,7 +13,7 @@ for your platform:
 - multi-user on macOS
 
   > **Notes on read-only filesystem root in macOS 10.15 Catalina +**
-  > 
+  >
   > - It took some time to support this cleanly. You may see posts,
   >   examples, and tutorials using obsolete workarounds.
   > - Supporting it cleanly made macOS installs too complex to qualify
@@ -75,7 +75,7 @@ should run this under your usual user account, *not* as root. The script
 will invoke `sudo` as needed.
 
 > **Note**
-> 
+>
 > If you need Nix to use a different group ID or user ID set, you will
 > have to download the tarball manually and [edit the install
 > script](#installing-from-a-binary-tarball).
@@ -167,7 +167,7 @@ and `/etc/zshrc` which you may remove.
    removed next.
 
 7. Remove the Nix Store volume:
-   
+
    ```console
    sudo diskutil apfs deleteVolume /nix
    ```
@@ -176,7 +176,7 @@ and `/etc/zshrc` which you may remove.
    store.
 
 > **Note**
-> 
+>
 > After you complete the steps here, you will still have an empty `/nix`
 > directory. This is an expected sign of a successful uninstall. The empty
 > `/nix` directory will disappear the next time you reboot.
-- 
cgit v1.2.3


From 7bb1e913b33499d3ce74929749977774bcc35aed Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Mon, 8 Aug 2022 15:46:17 -0400
Subject: Don't prompt about using sudo if we're already root

---
 doc/manual/src/installation/installing-binary.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 18fc8fff5..a46735196 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -31,8 +31,8 @@ $ sh <(curl -L https://nixos.org/nix/install) --no-daemon
 ```
 
 This will perform a single-user installation of Nix, meaning that `/nix`
-is owned by the invoking user. You should run this under your usual user
-account, *not* as root. The script will invoke `sudo` to create `/nix`
+is owned by the invoking user. You can run this under your usual user
+account or root. The script will invoke `sudo` to create `/nix`
 if it doesn’t already exist. If you don’t have `sudo`, you should
 manually create `/nix` first as root, e.g.:
 
@@ -71,7 +71,7 @@ $ sh <(curl -L https://nixos.org/nix/install) --daemon
 
 The multi-user installation of Nix will create build users between the
 user IDs 30001 and 30032, and a group with the group ID 30000. You
-should run this under your usual user account, *not* as root. The script
+can run this under your usual user account or root. The script
 will invoke `sudo` as needed.
 
 > **Note**
-- 
cgit v1.2.3


From 3378a3bce8a5dc1282d901f7f3ec152676198092 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:07:18 +0200
Subject: add syntax overview from NixOS manual

taken verbatim to keep track of required corrections.

made it an HTML table to more easily change structure and keep diffs
minimal.
---
 doc/manual/src/language/index.md | 306 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 306 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index c4b3abf75..6c355d923 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -11,3 +11,309 @@ packages, compositions of packages, and the variability within packages.
 
 This section presents the various features of the language.
 
+# Syntax Summary
+
+Below is a summary of the most important syntactic constructs in the Nix
+expression language. It's not complete. In particular, there are many
+other built-in functions. See the [Nix
+manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions) for
+the rest.
+
+<table>
+  <tr>
+    <th>
+       Example
+    </th>
+    <th>
+      Description
+    </th>
+  </tr>
+  <tr>
+    <td>
+       *Basic values*
+    </td>
+    <td>
+
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `"Hello world"`
+    </td>
+    <td>
+      A string
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `"${pkgs.bash}/bin/sh"`
+    </td>
+    <td>
+      A string containing an expression (expands to `"/nix/store/hash-bash-version/bin/sh"`)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `true`, `false`
+    </td>
+    <td>
+      Booleans
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `123`
+    </td>
+    <td>
+      An integer
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `./foo.png`
+    </td>
+    <td>
+      A path (relative to the containing Nix expression)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       *Compound values*
+    </td>
+    <td>
+
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x = 1; y = 2; }`
+    </td>
+    <td>
+      A set with attributes named `x` and `y`
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ foo.bar = 1; }`
+    </td>
+    <td>
+      A nested set, equivalent to `{ foo = { bar = 1; }; }`
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `rec { x = "foo"; y = x + "bar"; }`
+    </td>
+    <td>
+      A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `[ "foo" "bar" ]`
+    </td>
+    <td>
+      A list with two elements
+    </td>
+  </tr>
+  <tr>
+    <td>
+       *Operators*
+    </td>
+    <td>
+
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `"foo" + "bar"`
+    </td>
+    <td>
+      String concatenation
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `1 + 2`
+    </td>
+    <td>
+      Integer addition
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `"foo" == "f" + "oo"`
+    </td>
+    <td>
+      Equality test (evaluates to `true`)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `"foo" != "bar"`
+    </td>
+    <td>
+      Inequality test (evaluates to `true`)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `!true`
+    </td>
+    <td>
+      Boolean negation
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x = 1; y = 2; }.x`
+    </td>
+    <td>
+      Attribute selection (evaluates to `1`)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x = 1; y = 2; }.z or 3`
+    </td>
+    <td>
+      Attribute selection with default (evaluates to `3`)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x = 1; y = 2; } // { z = 3; }`
+    </td>
+    <td>
+      Merge two sets (attributes in the right-hand set taking precedence)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       *Control structures*
+    </td>
+    <td>
+
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `if 1 + 1 == 2 then "yes!" else "no!"`
+    </td>
+    <td>
+      Conditional expression
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `assert 1 + 1 == 2; "yes!"`
+    </td>
+    <td>
+      Assertion check (evaluates to `"yes!"`). See [](#sec-assertions) for using assertions in modules
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `let x = "foo"; y = "bar"; in x + y`
+    </td>
+    <td>
+      Variable definition
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `with pkgs.lib; head [ 1 2 3 ]`
+    </td>
+    <td>
+      Add all attributes from the given set to the scope (evaluates to `1`)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       *Functions (lambdas)*
+    </td>
+    <td>
+
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `x: x + 1`
+    </td>
+    <td>
+      A function that expects an integer and returns it increased by 1
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `(x: x + 1) 100`
+    </td>
+    <td>
+      A function call (evaluates to 101)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `let inc = x: x + 1; in inc (inc (inc 100))`
+    </td>
+    <td>
+      A function bound to a variable and subsequently called by name (evaluates to 103)
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x, y }: x + y`
+    </td>
+    <td>
+      A function that expects a set with required attributes `x` and `y` and concatenates them
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x, y ? "bar" }: x + y`
+    </td>
+    <td>
+      A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x, y, ... }: x + y`
+    </td>
+    <td>
+      A function that expects a set with required attributes `x` and `y` and ignores any other attributes
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `{ x, y } @ args: x + y`
+    </td>
+    <td>
+      A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+    </td>
+  </tr>
+  <tr>
+    <td>
+       *Built-in functions*
+    </td>
+    <td>
+
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `import ./foo.nix`
+    </td>
+    <td>
+      Load and return Nix expression in given file
+    </td>
+  </tr>
+  <tr>
+    <td>
+       `map (x: x + x) [ 1 2 3 ]`
+    </td>
+    <td>
+      Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
+    </td>
+  </tr>
+</table>
-- 
cgit v1.2.3


From 90836397d36080b097740fee587839e458763cf9 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:09:45 +0200
Subject: remove stale section link

---
 doc/manual/src/language/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 6c355d923..f22d66351 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -209,7 +209,7 @@ the rest.
        `assert 1 + 1 == 2; "yes!"`
     </td>
     <td>
-      Assertion check (evaluates to `"yes!"`). See [](#sec-assertions) for using assertions in modules
+      Assertion check (evaluates to `"yes!"`).
     </td>
   </tr>
   <tr>
-- 
cgit v1.2.3


From 43188d3d1818214fba6037af7ea3e87df5dfbdce Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:10:15 +0200
Subject: make hash and version distinguishable as placeholder

---
 doc/manual/src/language/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index f22d66351..41d20d835 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -49,7 +49,7 @@ the rest.
        `"${pkgs.bash}/bin/sh"`
     </td>
     <td>
-      A string containing an expression (expands to `"/nix/store/hash-bash-version/bin/sh"`)
+      A string containing an expression (expands to `"/nix/store/<hash>-bash-<version>/bin/sh"`)
     </td>
   </tr>
   <tr>
-- 
cgit v1.2.3


From f165a8ae0874529f979a2bf33283300bb1ccdef4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:10:48 +0200
Subject: flarify relative path semantics

---
 doc/manual/src/language/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 41d20d835..f601d1e16 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -73,7 +73,7 @@ the rest.
        `./foo.png`
     </td>
     <td>
-      A path (relative to the containing Nix expression)
+      A path relative to the file containing this Nix expression
     </td>
   </tr>
   <tr>
-- 
cgit v1.2.3


From 292cab039d7c2d1dc2e67f74a92dbf4953430935 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:16:13 +0200
Subject: add multi-line string

---
 doc/manual/src/language/index.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index f601d1e16..8241cd0cd 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -43,6 +43,18 @@ the rest.
     <td>
       A string
     </td>
+    <td>
+       ```
+        ''
+          multi
+           line
+            string
+        ''
+       ```
+    </td>
+    <td>
+      A multiline string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
+    </td>
   </tr>
   <tr>
     <td>
-- 
cgit v1.2.3


From e6f7c180de3553dbb4ebd3969f5da4423dafc4bd Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:18:59 +0200
Subject: add floating point number

---
 doc/manual/src/language/index.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 8241cd0cd..e623bc540 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -53,7 +53,7 @@ the rest.
        ```
     </td>
     <td>
-      A multiline string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
+      A multi-line string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
     </td>
   </tr>
   <tr>
@@ -80,6 +80,14 @@ the rest.
       An integer
     </td>
   </tr>
+  <tr>
+    <td>
+       `3.141`
+    </td>
+    <td>
+      A floating point number
+    </td>
+  </tr>
   <tr>
     <td>
        `./foo.png`
-- 
cgit v1.2.3


From 21438acc70575134e6d17e280f5172dc2bec971f Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:20:32 +0200
Subject: add absolute path

---
 doc/manual/src/language/index.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index e623bc540..b4ffe171b 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -88,6 +88,14 @@ the rest.
       A floating point number
     </td>
   </tr>
+  <tr>
+    <td>
+       `/etc`
+    </td>
+    <td>
+      An absolute path
+    </td>
+  </tr>
   <tr>
     <td>
        `./foo.png`
-- 
cgit v1.2.3


From 587ae9ada5e1a94184772542352df85549f0ce99 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:22:41 +0200
Subject: add search path

---
 doc/manual/src/language/index.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index b4ffe171b..3ed00d8e3 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -104,6 +104,14 @@ the rest.
       A path relative to the file containing this Nix expression
     </td>
   </tr>
+  <tr>
+    <td>
+       <nixpkgs>
+    </td>
+    <td>
+      Search path. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+    </td>
+  </tr>
   <tr>
     <td>
        *Compound values*
-- 
cgit v1.2.3


From 391fd10b12b00a3f61b178811fdecda7308e5193 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:25:40 +0200
Subject: add home path

---
 doc/manual/src/language/index.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 3ed00d8e3..5ad235819 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -104,6 +104,14 @@ the rest.
       A path relative to the file containing this Nix expression
     </td>
   </tr>
+  <tr>
+    <td>
+       `~/.config`
+    </td>
+    <td>
+      A home path. Evaluates to the `"<user's home directory>/.config"`.
+    </td>
+  </tr>
   <tr>
     <td>
        <nixpkgs>
-- 
cgit v1.2.3


From 5c25bdee509af297caddd7b6fdca275940282269 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 13:26:11 +0200
Subject: add null

---
 doc/manual/src/language/index.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 5ad235819..bc20f4316 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -72,6 +72,14 @@ the rest.
       Booleans
     </td>
   </tr>
+  <tr>
+    <td>
+       `null`
+    </td>
+    <td>
+      Null value
+    </td>
+  </tr>
   <tr>
     <td>
        `123`
-- 
cgit v1.2.3


From 2e4704ca9372c90826022d52360b6d57b564de5b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 14:13:03 +0200
Subject: add second @ pattern example

---
 doc/manual/src/language/index.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index bc20f4316..f201bbded 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -339,6 +339,8 @@ the rest.
   <tr>
     <td>
        `{ x, y } @ args: x + y`
+
+       `args @ { x, y }: x + y`
     </td>
     <td>
       A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
-- 
cgit v1.2.3


From 0378531bf2cdb19ab4601c6dbc04c3f2cd962caa Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 14:13:15 +0200
Subject: add curried function

---
 doc/manual/src/language/index.md | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index f201bbded..72e09b25d 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -296,6 +296,14 @@ the rest.
       A function that expects an integer and returns it increased by 1
     </td>
   </tr>
+  <tr>
+    <td>
+       `x: y: x + y`
+    </td>
+    <td>
+      Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+    </td>
+  </tr>
   <tr>
     <td>
        `(x: x + 1) 100`
-- 
cgit v1.2.3


From c209e6e108c95ba657992b208ce12af665eed9d4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 14:13:36 +0200
Subject: add more list examples

---
 doc/manual/src/language/index.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 72e09b25d..65463baa0 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -162,10 +162,14 @@ the rest.
   </tr>
   <tr>
     <td>
-       `[ "foo" "bar" ]`
+       `[ "foo" "bar" "baz" ]`
+
+       `[ 1 2 3 ]`
+
+       `[ (f 1) { a = 1; b = 2; } [ "c" ] ]`
     </td>
     <td>
-      A list with two elements
+      Lists with three elements.
     </td>
   </tr>
   <tr>
-- 
cgit v1.2.3


From 6ba8d6dc82f2b44734f5760225435642ae842725 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 12 Aug 2022 14:27:03 +0200
Subject: add more examples on string interpolation

---
 doc/manual/src/language/index.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 65463baa0..724484460 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -38,7 +38,7 @@ the rest.
   </tr>
   <tr>
     <td>
-       `"Hello world"`
+       `"hello world"`
     </td>
     <td>
       A string
@@ -58,10 +58,14 @@ the rest.
   </tr>
   <tr>
     <td>
+       `"hello ${ { a = "world" }.a }"`
+
+       `"1 2 ${3}"`
+
        `"${pkgs.bash}/bin/sh"`
     </td>
     <td>
-      A string containing an expression (expands to `"/nix/store/<hash>-bash-<version>/bin/sh"`)
+      String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
     </td>
   </tr>
   <tr>
-- 
cgit v1.2.3


From bc315326fa70876444cc7bc791a02e619f46304e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 15 Aug 2022 11:12:41 +0200
Subject: fix whitespace to please markdown

keep some indentation to ease source readability
---
 doc/manual/src/language/index.md | 908 +++++++++++++++++++++++----------------
 1 file changed, 542 insertions(+), 366 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index 724484460..cc71c3143 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -20,370 +20,546 @@ manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions) for
 the rest.
 
 <table>
-  <tr>
-    <th>
-       Example
-    </th>
-    <th>
-      Description
-    </th>
-  </tr>
-  <tr>
-    <td>
-       *Basic values*
-    </td>
-    <td>
-
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `"hello world"`
-    </td>
-    <td>
-      A string
-    </td>
-    <td>
-       ```
-        ''
-          multi
-           line
-            string
-        ''
-       ```
-    </td>
-    <td>
-      A multi-line string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `"hello ${ { a = "world" }.a }"`
-
-       `"1 2 ${3}"`
-
-       `"${pkgs.bash}/bin/sh"`
-    </td>
-    <td>
-      String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `true`, `false`
-    </td>
-    <td>
-      Booleans
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `null`
-    </td>
-    <td>
-      Null value
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `123`
-    </td>
-    <td>
-      An integer
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `3.141`
-    </td>
-    <td>
-      A floating point number
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `/etc`
-    </td>
-    <td>
-      An absolute path
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `./foo.png`
-    </td>
-    <td>
-      A path relative to the file containing this Nix expression
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `~/.config`
-    </td>
-    <td>
-      A home path. Evaluates to the `"<user's home directory>/.config"`.
-    </td>
-  </tr>
-  <tr>
-    <td>
-       <nixpkgs>
-    </td>
-    <td>
-      Search path. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
-    </td>
-  </tr>
-  <tr>
-    <td>
-       *Compound values*
-    </td>
-    <td>
-
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x = 1; y = 2; }`
-    </td>
-    <td>
-      A set with attributes named `x` and `y`
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ foo.bar = 1; }`
-    </td>
-    <td>
-      A nested set, equivalent to `{ foo = { bar = 1; }; }`
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `rec { x = "foo"; y = x + "bar"; }`
-    </td>
-    <td>
-      A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `[ "foo" "bar" "baz" ]`
-
-       `[ 1 2 3 ]`
-
-       `[ (f 1) { a = 1; b = 2; } [ "c" ] ]`
-    </td>
-    <td>
-      Lists with three elements.
-    </td>
-  </tr>
-  <tr>
-    <td>
-       *Operators*
-    </td>
-    <td>
-
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `"foo" + "bar"`
-    </td>
-    <td>
-      String concatenation
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `1 + 2`
-    </td>
-    <td>
-      Integer addition
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `"foo" == "f" + "oo"`
-    </td>
-    <td>
-      Equality test (evaluates to `true`)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `"foo" != "bar"`
-    </td>
-    <td>
-      Inequality test (evaluates to `true`)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `!true`
-    </td>
-    <td>
-      Boolean negation
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x = 1; y = 2; }.x`
-    </td>
-    <td>
-      Attribute selection (evaluates to `1`)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x = 1; y = 2; }.z or 3`
-    </td>
-    <td>
-      Attribute selection with default (evaluates to `3`)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x = 1; y = 2; } // { z = 3; }`
-    </td>
-    <td>
-      Merge two sets (attributes in the right-hand set taking precedence)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       *Control structures*
-    </td>
-    <td>
-
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `if 1 + 1 == 2 then "yes!" else "no!"`
-    </td>
-    <td>
-      Conditional expression
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `assert 1 + 1 == 2; "yes!"`
-    </td>
-    <td>
-      Assertion check (evaluates to `"yes!"`).
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `let x = "foo"; y = "bar"; in x + y`
-    </td>
-    <td>
-      Variable definition
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `with pkgs.lib; head [ 1 2 3 ]`
-    </td>
-    <td>
-      Add all attributes from the given set to the scope (evaluates to `1`)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       *Functions (lambdas)*
-    </td>
-    <td>
-
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `x: x + 1`
-    </td>
-    <td>
-      A function that expects an integer and returns it increased by 1
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `x: y: x + y`
-    </td>
-    <td>
-      Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `(x: x + 1) 100`
-    </td>
-    <td>
-      A function call (evaluates to 101)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `let inc = x: x + 1; in inc (inc (inc 100))`
-    </td>
-    <td>
-      A function bound to a variable and subsequently called by name (evaluates to 103)
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x, y }: x + y`
-    </td>
-    <td>
-      A function that expects a set with required attributes `x` and `y` and concatenates them
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x, y ? "bar" }: x + y`
-    </td>
-    <td>
-      A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x, y, ... }: x + y`
-    </td>
-    <td>
-      A function that expects a set with required attributes `x` and `y` and ignores any other attributes
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `{ x, y } @ args: x + y`
-
-       `args @ { x, y }: x + y`
-    </td>
-    <td>
-      A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
-    </td>
-  </tr>
-  <tr>
-    <td>
-       *Built-in functions*
-    </td>
-    <td>
-
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `import ./foo.nix`
-    </td>
-    <td>
-      Load and return Nix expression in given file
-    </td>
-  </tr>
-  <tr>
-    <td>
-       `map (x: x + x) [ 1 2 3 ]`
-    </td>
-    <td>
-      Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
-    </td>
-  </tr>
+ <tr>
+  <th>
+   Example
+  </th>
+  <th>
+   Description
+  </th>
+ </tr>
+ <tr>
+  <td>
+
+
+   *Basic values*
+
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"hello world"`
+
+  </td>
+  <td>
+
+   A string
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   ```
+   ''
+     multi
+      line
+       string
+   ''
+   ```
+
+  </td>
+  <td>
+
+   A multi-line string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n  string"`.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"hello ${ { a = "world" }.a }"`
+
+   `"1 2 ${3}"`
+
+   `"${pkgs.bash}/bin/sh"`
+
+  </td>
+  <td>
+
+   String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `true`, `false`
+
+  </td>
+  <td>
+
+   Booleans
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `null`
+
+  </td>
+  <td>
+
+   Null value
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `123`
+
+  </td>
+  <td>
+
+   An integer
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `3.141`
+
+  </td>
+  <td>
+
+   A floating point number
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `/etc`
+
+  </td>
+  <td>
+
+   An absolute path
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `./foo.png`
+
+  </td>
+  <td>
+
+   A path relative to the file containing this Nix expression
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `~/.config`
+
+  </td>
+  <td>
+
+   A home path. Evaluates to the `"<user's home directory>/.config"`.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   <nixpkgs>
+
+  </td>
+  <td>
+
+   Search path. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Compound values*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }`
+
+  </td>
+  <td>
+
+   A set with attributes named `x` and `y`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ foo.bar = 1; }`
+
+  </td>
+  <td>
+
+   A nested set, equivalent to `{ foo = { bar = 1; }; }`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `rec { x = "foo"; y = x + "bar"; }`
+
+  </td>
+  <td>
+
+   A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `[ "foo" "bar" "baz" ]`
+
+   `[ 1 2 3 ]`
+
+   `[ (f 1) { a = 1; b = 2; } [ "c" ] ]`
+
+  </td>
+  <td>
+
+   Lists with three elements.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Operators*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" + "bar"`
+
+  </td>
+  <td>
+
+   String concatenation
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `1 + 2`
+
+  </td>
+  <td>
+
+   Integer addition
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" == "f" + "oo"`
+
+  </td>
+  <td>
+
+   Equality test (evaluates to `true`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `"foo" != "bar"`
+
+  </td>
+  <td>
+
+   Inequality test (evaluates to `true`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `!true`
+
+  </td>
+  <td>
+
+   Boolean negation
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }.x`
+
+  </td>
+  <td>
+
+   Attribute selection (evaluates to `1`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; }.z or 3`
+
+  </td>
+  <td>
+
+   Attribute selection with default (evaluates to `3`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x = 1; y = 2; } // { z = 3; }`
+
+  </td>
+  <td>
+
+   Merge two sets (attributes in the right-hand set taking precedence)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Control structures*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `if 1 + 1 == 2 then "yes!" else "no!"`
+
+  </td>
+  <td>
+
+   Conditional expression
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `assert 1 + 1 == 2; "yes!"`
+
+  </td>
+  <td>
+
+   Assertion check (evaluates to `"yes!"`).
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `let x = "foo"; y = "bar"; in x + y`
+
+  </td>
+  <td>
+
+   Variable definition
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `with pkgs.lib; head [ 1 2 3 ]`
+
+  </td>
+  <td>
+
+   Add all attributes from the given set to the scope (evaluates to `1`)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Functions (lambdas)*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `x: x + 1`
+
+  </td>
+  <td>
+
+   A function that expects an integer and returns it increased by 1
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `x: y: x + y`
+
+  </td>
+  <td>
+
+   Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `(x: x + 1) 100`
+
+  </td>
+  <td>
+
+   A function call (evaluates to 101)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `let inc = x: x + 1; in inc (inc (inc 100))`
+
+  </td>
+  <td>
+
+   A function bound to a variable and subsequently called by name (evaluates to 103)
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y` and concatenates them
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y ? "bar" }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y, ... }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y` and ignores any other attributes
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `{ x, y } @ args: x + y`
+
+   `args @ { x, y }: x + y`
+
+  </td>
+  <td>
+
+   A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   *Built-in functions*
+
+  </td>
+  <td>
+
+
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `import ./foo.nix`
+
+  </td>
+  <td>
+
+   Load and return Nix expression in given file
+
+  </td>
+ </tr>
+ <tr>
+  <td>
+
+   `map (x: x + x) [ 1 2 3 ]`
+
+  </td>
+  <td>
+
+   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
+
+  </td>
+ </tr>
 </table>
-- 
cgit v1.2.3


From 71e9c2869429bb711bf728f4a7acd14f5c2e1eeb Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 15 Aug 2022 11:15:03 +0200
Subject: reword introduction to overview

---
 doc/manual/src/language/index.md | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index cc71c3143..cea17bedc 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -11,13 +11,9 @@ packages, compositions of packages, and the variability within packages.
 
 This section presents the various features of the language.
 
-# Syntax Summary
+# Overview
 
-Below is a summary of the most important syntactic constructs in the Nix
-expression language. It's not complete. In particular, there are many
-other built-in functions. See the [Nix
-manual](https://nixos.org/nix/manual/#chap-writing-nix-expressions) for
-the rest.
+This is an incomplete overview of language features, by example.
 
 <table>
  <tr>
-- 
cgit v1.2.3


From 703b335c1d187fb18ca5a5450b33e4e9a98abc7c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 15 Aug 2022 11:34:39 +0200
Subject: reword description of language properties

the list style is supposed to give more structure.
each property is explained as concisely as possible while trying not to
sound too fancy.
---
 doc/manual/src/language/index.md | 40 ++++++++++++++++++++++++++++++----------
 1 file changed, 30 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index c4b3abf75..a4b402f8b 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -1,13 +1,33 @@
 # Nix Language
 
-The Nix language is a pure, lazy, functional language. Purity
-means that operations in the language don't have side-effects (for
-instance, there is no variable assignment). Laziness means that
-arguments to functions are evaluated only when they are needed.
-Functional means that functions are “normal” values that can be passed
-around and manipulated in interesting ways. The language is not a
-full-featured, general purpose language. Its main job is to describe
-packages, compositions of packages, and the variability within packages.
-
-This section presents the various features of the language.
+The Nix language is
+
+- *domain-specific*
+
+  It only exists for the Nix package manager:
+  to describe packages and configurations as well as their variants and compositions.
+  It is not intended for general purpose use.
+
+- *declarative*
+
+  There is no notion of executing sequential steps.
+  Dependencies between operations are established only through data.
+
+- *pure*
+
+  Values cannot change during computation.
+  Functions always produce the same output if their input does not change.
+
+- *functional*
+
+  Functions are like any other value.
+  Functions can be assigned to names, taken as arguments, or returned by functions.
+
+- *lazy*
+
+  Expressions are only evaluated when their value is needed.
+
+- *dynamically typed*
+
+  Type errors are only detected when expressions are evaluated.
 
-- 
cgit v1.2.3


From d8e54d19f71f78540dd967b2e42be6a5d8a0b1bb Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 22 Aug 2022 12:50:48 +0200
Subject: Revert "Merge pull request #6420 from nix-community/doc-what-is-nix"

This reverts commit 81e101345fda2a8651c470f08b364a1ca6fa37cf, reversing
changes made to 7d1280bbaf7f4cd142c2259dec620c42bf6f96fd.
---
 doc/manual/src/SUMMARY.md.in                       |   8 --
 doc/manual/src/architecture/architecture.md        |  79 -----------
 doc/manual/src/architecture/store/fso.md           |  69 ----------
 doc/manual/src/architecture/store/path.md          | 105 --------------
 doc/manual/src/architecture/store/store.md         | 151 ---------------------
 .../store/store/build-system-terminology.md        |  32 -----
 doc/manual/src/architecture/store/store/closure.md |  29 ----
 7 files changed, 473 deletions(-)
 delete mode 100644 doc/manual/src/architecture/architecture.md
 delete mode 100644 doc/manual/src/architecture/store/fso.md
 delete mode 100644 doc/manual/src/architecture/store/path.md
 delete mode 100644 doc/manual/src/architecture/store/store.md
 delete mode 100644 doc/manual/src/architecture/store/store/build-system-terminology.md
 delete mode 100644 doc/manual/src/architecture/store/store/closure.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 8fbb59716..084c8f442 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -59,14 +59,6 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
-<!--
-- [Architecture](architecture/architecture.md)
-  - [Store](architecture/store/store.md)
-    - [Closure](architecture/store/store/closure.md)
-    - [Build system terminology](architecture/store/store/build-system-terminology.md)
-  - [Store Path](architecture/store/path.md)
-  - [File System Object](architecture/store/fso.md)
--->
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
deleted file mode 100644
index 41deb07af..000000000
--- a/doc/manual/src/architecture/architecture.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Architecture
-
-*(This chapter is unstable and a work in progress. Incoming links may rot.)*
-
-This chapter describes how Nix works.
-It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
-
-## Overview
-
-Nix consists of [hierarchical layers][layer-architecture].
-
-```
-+-----------------------------------------------------------------+
-| Nix                                                             |
-|                  [ commmand line interface ]------,             |
-|                               |                   |             |
-|                           evaluates               |             |
-|                               |                manages          |
-|                               V                   |             |
-|                  [ configuration language  ]      |             |
-|                               |                   |             |
-| +-----------------------------|-------------------V-----------+ |
-| | store                  evaluates to                         | |
-| |                             |                               | |
-| |             referenced by   V       builds                  | |
-| |  [ build input ] ---> [ build plan ] ---> [ build result ]  | |
-| |                                                             | |
-| +-------------------------------------------------------------+ |
-+-----------------------------------------------------------------+
-```
-
-At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
-
-Below that is the [Nix expression language](../expressions/expression-language.md), a [purely functional][purely-functional-programming] configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
-
-The command line and Nix language are what users interact with most.
-
-> **Note**
-> The Nix language itself does not have a notion of *packages* or *configurations*.
-> As far as we are concerned here, the inputs and results of a build plan are just data.
-
-Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
-It can also execute build plans to produce new data.
-
-A build plan is a series of *build tasks*.
-Each build task has a special build input which is used as *build instructions*.
-The result of a build task can be input to another build task.
-
-```
-+-----------------------------------------------------------------------------------------+
-| store                                                                                   |
-|                   .................................................                     |
-|                   :  build plan                                   :                     |
-|                   :                                               :                     |
-|  [ build input ]-----instructions-,                               :                     |
-|                   :               |                               :                     |
-|                   :               v                               :                     |
-|  [ build input ]----------->[ build task ]--instructions-,        :                     |
-|                   :                                      |        :                     |
-|                   :                                      |        :                     |
-|                   :                                      v        :                     |
-|                   :                               [ build task ]----->[ build result ]  |
-|  [ build input ]-----instructions-,                      ^        :                     |
-|                   :               |                      |        :                     |
-|                   :               v                      |        :                     |
-|  [ build input ]----------->[ build task ]---------------'        :                     |
-|                   :               ^                               :                     |
-|                   :               |                               :                     |
-|  [ build input ]------------------'                               :                     |
-|                   :                                               :                     |
-|                   :                                               :                     |
-|                   :...............................................:                     |
-|                                                                                         |
-+-----------------------------------------------------------------------------------------+
-```
-
-[layer-architecture]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
-[purely-functional-programming]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
diff --git a/doc/manual/src/architecture/store/fso.md b/doc/manual/src/architecture/store/fso.md
deleted file mode 100644
index e0eb69f60..000000000
--- a/doc/manual/src/architecture/store/fso.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# File System Object
-
-The Nix store uses a simple file system model for the data it holds in [store objects](store.md#store-object).
-
-Every file system object is one of the following:
-
- - File: an executable flag, and arbitrary data for contents
- - Directory: mapping of names to child file system objects
- - [Symbolic link][symlink]: may point anywhere.
-
-We call a store object's outermost file system object the *root*.
-
-    data FileSystemObject
-      = File      { isExecutable :: Bool, contents :: Bytes }
-      | Directory { entries :: Map FileName FileSystemObject }
-      | SymLink   { target :: Path }
-
-Examples:
-
-- a directory with contents
-
-      /nix/store/<hash>-hello-2.10
-      ├── bin
-      │   └── hello
-      └── share
-          ├── info
-          │   └── hello.info
-          └── man
-              └── man1
-                  └── hello.1.gz
-
-- a directory with relative symlink and other contents
-
-      /nix/store/<hash>-go-1.16.9
-      ├── bin -> share/go/bin
-      ├── nix-support/
-      └── share/
-
-- a directory with absolute symlink
-
-      /nix/store/d3k...-nodejs
-      └── nix_node -> /nix/store/f20...-nodejs-10.24.
-
-A bare file or symlink can be a root file system object.
-Examples:
-
-    /nix/store/<hash>-hello-2.10.tar.gz
-
-    /nix/store/4j5...-pkg-config-wrapper-0.29.2-doc -> /nix/store/i99...-pkg-config-0.29.2-doc
-
-Symlinks pointing outside of their own root or to a store object without a matching reference are allowed, but might not function as intended.
-Examples:
-
-- an arbitrarily symlinked file may change or not exist at all
-
-      /nix/store/<hash>-foo
-      └── foo -> /home/foo
-
-- if a symlink to a store path was not automatically created by Nix, it may be invalid or get invalidated when the store object is deleted
-
-      /nix/store/<hash>-bar
-      └── bar -> /nix/store/abc...-foo
-
-Nix file system objects do not support [hard links][hardlink]:
-each file system object which is not the root has exactly one parent and one name.
-However, as store objects are immutable, an underlying file system can use hard links for optimization.
-
-[symlink]: https://en.m.wikipedia.org/wiki/Symbolic_link
-[hardlink]: https://en.m.wikipedia.org/wiki/Hard_link
diff --git a/doc/manual/src/architecture/store/path.md b/doc/manual/src/architecture/store/path.md
deleted file mode 100644
index 663f04f46..000000000
--- a/doc/manual/src/architecture/store/path.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# Store Path
-
-Nix implements [references](store.md#reference) to [store objects](store.md#store-object) as *store paths*.
-
-Store paths are pairs of
-
-- a 20-byte [digest](#digest) for identification
-- a symbolic name for people to read.
-
-Example:
-
-- digest: `b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z`
-- name:   `firefox-33.1`
-
-It is rendered to a file system path as the concatenation of
-
-  - [store directory](#store-directory)
-  - path-separator (`/`)
-  - [digest](#digest) rendered in a custom variant of [base-32](https://en.m.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters)
-  - hyphen (`-`)
-  - name
-
-Example:
-
-      /nix/store/b6gvzjyb2pg0kjfwrjmg1vfhh54ad73z-firefox-33.1
-      |--------| |------------------------------| |----------|
-    store directory            digest                 name
-
-## Store Directory
-
-Every [store](./store.md) has a store directory.
-
-If the store has a [file system representation](./store.md#files-and-processes), this directory contains the store’s [file system objects](#file-system-object), which can be addressed by [store paths](#store-path).
-
-This means a store path is not just derived from the referenced store object itself, but depends on the store the store object is in.
-
-> **Note**
-> The store directory defaults to `/nix/store`, but is in principle arbitrary.
-
-It is important which store a given store object belongs to:
-Files in the store object can contain store paths, and processes may read these paths.
-Nix can only guarantee [referential integrity](store/closure.md) if store paths do not cross store boundaries.
-
-Therefore one can only copy store objects to a different store if
-
-- the source and target stores' directories match
-
-  or
-
-- the store object in question has no references, that is, contains no store paths.
-
-One cannot copy a store object to a store with a different store directory.
-Instead, it has to be rebuilt, together with all its dependencies.
-It is in general not enough to replace the store directory string in file contents, as this may render executables unusable by invalidating their internal offsets or checksums.
-
-# Digest
-
-In a [store path](#store-path), the [digest][digest] is the output of a [cryptographic hash function][hash] of either all *inputs* involved in building the referenced store object or its actual *contents*.
-
-Store objects are therefore said to be either [input-addressed](#input-addressing) or [content-addressed](#content-addressing).
-
-> **Historical Note**
-> The 20 byte restriction is because originally digests were [SHA-1][sha-1] hashes.
-> Nix now uses [SHA-256][sha-256], and longer hashes are still reduced to 20 bytes for compatibility.
-
-[digest]: https://en.m.wiktionary.org/wiki/digest#Noun
-[hash]: https://en.m.wikipedia.org/wiki/Cryptographic_hash_function
-[sha-1]: https://en.m.wikipedia.org/wiki/SHA-1
-[sha-256]: https://en.m.wikipedia.org/wiki/SHA-256
-
-### Reference scanning
-
-When a new store object is built, Nix scans its file contents for store paths to construct its set of references.
-
-The special format of a store path's [digest](#digest) allows reliably detecting it among arbitrary data.
-Nix uses the [closure](store.md#closure) of build inputs to derive the list of allowed store paths, to avoid false positives.
-
-This way, scanning files captures run time dependencies without the user having to declare them explicitly.
-Doing it at build time and persisting references in the store object avoids repeating this time-consuming operation.
-
-> **Note**
-> In practice, it is sometimes still necessary for users to declare certain dependencies explicitly, if they are to be preserved in the build result's closure.
-This depends on the specifics of the software to build and run.
->
-> For example, Java programs are compressed after compilation, which obfuscates any store paths they may refer to and prevents Nix from automatically detecting them.
-
-## Input Addressing
-
-Input addressing means that the digest derives from how the store object was produced, namely its build inputs and build plan.
-
-To compute the hash of a store object one needs a deterministic serialisation, i.e., a binary string representation which only changes if the store object changes.
-
-Nix has a custom serialisation format called Nix Archive (NAR)
-
-Store object references of this sort can *not* be validated from the content of the store object.
-Rather, a cryptographic signature has to be used to indicate that someone is vouching for the store object really being produced from a build plan with that digest.
-
-## Content Addressing
-
-Content addressing means that the digest derives from the store object's contents, namely its file system objects and references.
-If one knows content addressing was used, one can recalculate the reference and thus verify the store object.
-
-Content addressing is currently only used for the special cases of source files and "fixed-output derivations", where the contents of a store object are known in advance.
-Content addressing of build results is still an [experimental feature subject to some restrictions](https://github.com/tweag/rfcs/blob/cas-rfc/rfcs/0062-content-addressed-paths.md).
-
diff --git a/doc/manual/src/architecture/store/store.md b/doc/manual/src/architecture/store/store.md
deleted file mode 100644
index 08b6701d5..000000000
--- a/doc/manual/src/architecture/store/store.md
+++ /dev/null
@@ -1,151 +0,0 @@
-# Store
-
-A Nix store is a collection of *store objects* with references between them.
-It supports operations to manipulate that collection.
-
-The following concept map is a graphical outline of this chapter.
-Arrows indicate suggested reading order.
-
-```
-                      ,--------------[ store ]----------------,
-                      |                  |                    |
-                      v                  v                    v
-               [ store object ]     [ closure ]--,      [ operations ]
-                      |               |   |      |        |        |
-                      v               |   |      v        v        |
-           [ files and processes ]    |   | [ garbage collection ] |
-               /          \           |   |                        |
-              v            v          |   v                        v
-[ file system object ] [ store path ] | [ derivation ]--->[ building ]
-                  |        ^      |   |                         |
-                  v        |      v   v                         |
-             [ digest ]----' [ reference scanning ]<------------'
-              /      \
-             v        v
-[ input addressing ] [ content addressing ]
-```
-
-## Store Object
-
-A store object can hold
-
-- arbitrary *data*
-- *references* to other store objects.
-
-Store objects can be build inputs, build results, or build tasks.
-
-Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
-
-## Reference
-
-A store object reference is an [opaque][opaque-data-type], [unique identifier][unique-identifier]:
-The only way to obtain references is by adding or building store objects.
-A reference will always point to exactly one store object.
-
-## Operations
-
-A Nix store can *add*, *retrieve*, and *delete* store objects.
-
-                [ data ]
-                    |
-                    V
-    [ store ] ---> add ----> [ store' ]
-                    |
-                    V
-              [ reference ]
-
-<!-- -->
-
-              [ reference ]
-                    |
-                    V
-    [ store ] ---> get
-                    |
-                    V
-             [ store object ]
-
-<!-- -->
-
-              [ reference ]
-                    |
-                    V
-    [ store ] --> delete --> [ store' ]
-
-
-It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks.
-
-
-              [ reference ]
-                    |
-                    V
-    [ store ] --> build --(maybe)--> [ store' ]
-                             |
-                             V
-                       [ reference ]
-
-
-As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
-
-
-    [ store ] --> collect garbage --> [ store' ]
-
-## Files and Processes
-
-Nix maps between its store model and the [Unix paradigm][unix-paradigm] of [files and processes][file-descriptor], by encoding immutable store objects and opaque identifiers as file system primitives: files and directories, and paths.
-That allows processes to resolve references contained in files and thus access the contents of store objects.
-
-Store objects are therefore implemented as the pair of
-
-  - a [file system object](fso.md) for data
-  - a set of [store paths](path.md) for references.
-
-[unix-paradigm]: https://en.m.wikipedia.org/wiki/Everything_is_a_file
-[file-descriptor]: https://en.m.wikipedia.org/wiki/File_descriptor
-
-The following diagram shows a radical simplification of how Nix interacts with the operating system:
-It uses files as build inputs, and build outputs are files again.
-On the operating system, files can be run as processes, which in turn operate on files.
-A build function also amounts to an operating system process (not depicted).
-
-```
-+-----------------------------------------------------------------+
-| Nix                                                             |
-|                  [ commmand line interface ]------,             |
-|                               |                   |             |
-|                           evaluates               |             |
-|                               |                manages          |
-|                               V                   |             |
-|                  [ configuration language  ]      |             |
-|                               |                   |             |
-| +-----------------------------|-------------------V-----------+ |
-| | store                  evaluates to                         | |
-| |                             |                               | |
-| |             referenced by   V       builds                  | |
-| |  [ build input ] ---> [ build plan ] ---> [ build result ]  | |
-| |         ^                                        |          | |
-| +---------|----------------------------------------|----------+ |
-+-----------|----------------------------------------|------------+
-            |                                        |
-    file system object                          store path
-            |                                        |
-+-----------|----------------------------------------|------------+
-| operating system        +------------+             |            |
-|           '------------ |            | <-----------'            |
-|                         |    file    |                          |
-|                     ,-- |            | <-,                      |
-|                     |   +------------+   |                      |
-|          execute as |                    | read, write, execute |
-|                     |   +------------+   |                      |
-|                     '-> |  process   | --'                      |
-|                         +------------+                          |
-+-----------------------------------------------------------------+
-```
-
-There exist different types of stores, which all follow this model.
-Examples:
-- store on the local file system
-- remote store accessible via SSH
-- binary cache store accessible via HTTP
-
-To make store objects accessible to processes, stores ultimately have to expose store objects through the file system.
-
diff --git a/doc/manual/src/architecture/store/store/build-system-terminology.md b/doc/manual/src/architecture/store/store/build-system-terminology.md
deleted file mode 100644
index eefbaa630..000000000
--- a/doc/manual/src/architecture/store/store/build-system-terminology.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# A [Rosetta stone][rosetta-stone] for build system terminology
-
-The Nix store's design is comparable to other build systems.
-Usage of terms is, for historic reasons, not entirely consistent within the Nix ecosystem, and still subject to slow change.
-
-The following translation table points out similarities and equivalent terms, to help clarify their meaning and inform consistent use in the future.
-
-| generic build system             | Nix              | [Bazel][bazel]                                                       | [Build Systems à la Carte][bsalc] | programming language     |
-| -------------------------------- | ---------------- | -------------------------------------------------------------------- | --------------------------------- | ------------------------ |
-| data (build input, build result) | store object     | [artifact][bazel-artifact]                                           | value                             | value                    |
-| build instructions               | builder          | ([depends on action type][bazel-actions])                            | function                          | function                 |
-| build task                       | derivation       | [action][bazel-action]                                               | `Task`                            | [thunk][thunk]           |
-| build plan                       | derivation graph | [action graph][bazel-action-graph], [build graph][bazel-build-graph] | `Tasks`                           | [call graph][call-graph] |
-| build                            | build            | build                                                                | application of `Build`            | evaluation               |
-| persistence layer                | store            | [action cache][bazel-action-cache]                                   | `Store`                           | heap                     |
-
-All of these systems share features of [declarative programming][declarative-programming] languages, a key insight first put forward by Eelco Dolstra et al. in [Imposing a Memory Management Discipline on Software Deployment][immdsd] (2004), elaborated in his PhD thesis [The Purely Functional Software Deployment Model][phd-thesis] (2006), and further refined by Andrey Mokhov et al. in [Build Systems à la Carte][bsalc] (2018).
-
-[rosetta-stone]: https://en.m.wikipedia.org/wiki/Rosetta_Stone
-[bazel]: https://bazel.build/start/bazel-intro
-[bazel-artifact]: https://bazel.build/reference/glossary#artifact
-[bazel-actions]: https://docs.bazel.build/versions/main/skylark/lib/actions.html
-[bazel-action]: https://bazel.build/reference/glossary#action
-[bazel-action-graph]: https://bazel.build/reference/glossary#action-graph
-[bazel-build-graph]: https://bazel.build/reference/glossary#build-graph
-[bazel-action-cache]: https://bazel.build/reference/glossary#action-cache
-[thunk]: https://en.m.wikipedia.org/wiki/Thunk
-[call-graph]: https://en.m.wikipedia.org/wiki/Call_graph
-[declarative-programming]: https://en.m.wikipedia.org/wiki/Declarative_programming
-[immdsd]: https://edolstra.github.io/pubs/immdsd-icse2004-final.pdf
-[phd-thesis]: https://edolstra.github.io/pubs/phd-thesis.pdf
-[bsalc]: https://www.microsoft.com/en-us/research/uploads/prod/2018/03/build-systems.pdf
diff --git a/doc/manual/src/architecture/store/store/closure.md b/doc/manual/src/architecture/store/store/closure.md
deleted file mode 100644
index 065b95ffc..000000000
--- a/doc/manual/src/architecture/store/store/closure.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Closure
-
-Nix stores ensure [referential integrity][referential-integrity]: for each store object in the store, all the store objects it references must also be in the store.
-
-The set of all store objects reachable by following references from a given initial set of store objects is called a *closure*.
-
-Adding, building, copying and deleting store objects must be done in a way that preserves referential integrity:
-
-- A newly added store object cannot have references, unless it is a build task.
-
-- Build results must only refer to store objects in the closure of the build inputs.
-
-  Building a store object will add appropriate references, according to the build task.
-
-- Store objects being copied must refer to objects already in the destination store.
-
-  Recursive copying must either proceed in dependency order or be atomic.
-
-- We can only safely delete store objects which are not reachable from any reference still in use.
-
-  <!-- more details in section on garbage collection, link to it once it exists -->
-
-[referential-integrity]: https://en.m.wikipedia.org/wiki/Referential_integrity
-[garbage-collection]: https://en.m.wikipedia.org/wiki/Garbage_collection_(computer_science)
-[immutable-object]: https://en.m.wikipedia.org/wiki/Immutable_object
-[opaque-data-type]: https://en.m.wikipedia.org/wiki/Opaque_data_type
-[unique-identifier]: https://en.m.wikipedia.org/wiki/Unique_identifier
-
-
-- 
cgit v1.2.3


From b0488a29dc7401e5ecd9221215da5ea9879e56d6 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 24 Aug 2022 22:44:58 +0200
Subject: Branch 2.11 release notes

---
 doc/manual/src/SUMMARY.md.in            | 1 +
 doc/manual/src/release-notes/rl-2.11.md | 5 +++++
 doc/manual/src/release-notes/rl-next.md | 3 ---
 3 files changed, 6 insertions(+), 3 deletions(-)
 create mode 100644 doc/manual/src/release-notes/rl-2.11.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 8fbb59716..9b66ec3db 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -73,6 +73,7 @@
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.11 (2022-08-25)](release-notes/rl-2.11.md)
   - [Release 2.10 (2022-07-11)](release-notes/rl-2.10.md)
   - [Release 2.9 (2022-05-30)](release-notes/rl-2.9.md)
   - [Release 2.8 (2022-04-19)](release-notes/rl-2.8.md)
diff --git a/doc/manual/src/release-notes/rl-2.11.md b/doc/manual/src/release-notes/rl-2.11.md
new file mode 100644
index 000000000..b322a4e5e
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.11.md
@@ -0,0 +1,5 @@
+# Release 2.11 (2022-08-24)
+
+* `nix copy` now copies the store paths in parallel as much as possible (again).
+  This doesn't apply for the `daemon` and `ssh-ng` stores which copy everything
+  in one batch to avoid latencies issues.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 7d82c3dc4..78ae99f4b 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,5 +1,2 @@
 # Release X.Y (202?-??-??)
 
-* `nix copy` now copies the store paths in parallel as much as possible (again).
-  This doesn't apply for the `daemon` and `ssh-ng` stores which copy everything
-  in one batch to avoid latencies issues.
\ No newline at end of file
-- 
cgit v1.2.3


From f35b3aa47bc6edc2a929e1803c8429113c34012b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 24 Aug 2022 08:48:34 +0200
Subject: do not use unwarranted pkgs in example

---
 doc/manual/src/language/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index cea17bedc..83484dced 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -403,7 +403,7 @@ This is an incomplete overview of language features, by example.
  <tr>
   <td>
 
-   `with pkgs.lib; head [ 1 2 3 ]`
+   `with builtins; head [ 1 2 3 ]`
 
   </td>
   <td>
-- 
cgit v1.2.3


From 520587b9a0327194371146f4dd25c9227a2c79e2 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 13:38:07 -0700
Subject: glossary: local store: clarify

---
 doc/manual/src/glossary.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 77de58965..d653a2ae4 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -15,10 +15,10 @@
     invoked, the  Nix store can be  referred to
     as a "_local_" or a "_remote_" one:
 
-    + A *local  store* exists  on the local  filesystem of
+    + A *local  store* exists  on the filesystem of
       the machine where Nix is  invoked. You can use other
       local stores  by passing  the `--store` flag  to the
-      `nix` command.
+      `nix` command.  Local stores can be used for building derivations.
 
     + A  *remote store*  exists  anywhere  other than  the
       local  filesystem. One  example is  the `/nix/store`
-- 
cgit v1.2.3


From 2812682ebee9d4419ba89690177b31564ce5ba77 Mon Sep 17 00:00:00 2001
From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>
Date: Thu, 1 Sep 2022 20:40:39 +0000
Subject: Update doc/manual/src/glossary.md

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index d653a2ae4..f072f35e1 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -52,7 +52,7 @@
     from some server.
 
   - [substituter]{#gloss-substituter}\
-    A *substituter* is a store other than `/nix/store` from which Nix will
+    A *substituter* is an additional store from which Nix will
     copy a store path instead of building it.  Nix will not copy a store
     path from a remote store unless one of the following is true:
 
-- 
cgit v1.2.3


From 9cb84121435e8ca6a51950b9d96a3d3be47c809e Mon Sep 17 00:00:00 2001
From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com>
Date: Thu, 1 Sep 2022 20:41:04 +0000
Subject: Update doc/manual/src/glossary.md

Co-authored-by: John Ericson <git@JohnEricson.me>
---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index f072f35e1..91865c807 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -53,7 +53,7 @@
 
   - [substituter]{#gloss-substituter}\
     A *substituter* is an additional store from which Nix will
-    copy a store path instead of building it.  Nix will not copy a store
+    copy store objects it doesn't have. Nix will not copy a store
     path from a remote store unless one of the following is true:
 
     - the store object is signed by one of the `trusted-public-keys`
-- 
cgit v1.2.3


From 41153f30bd5ca1bd9fa10d18da7a6b5b78a94087 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 13:54:09 -0700
Subject: glossary: substituter: merge output-addressed cases

---
 doc/manual/src/glossary.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 91865c807..608beb8f8 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -59,8 +59,9 @@
     - the store object is signed by one of the `trusted-public-keys`
     - the substituter is in the `trusted-substituters` list
     - the `no-require-sigs` option has been set to disable signature checking
-    - the store object is a derivation
-    - the store object is the realisation of a fixed-output derivation
+    - the store object is *output-addressed*; this includes
+      derivations, the outputs of content-addressed derivations, and
+      the outputs of fixed-output derivations.
 
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
-- 
cgit v1.2.3


From 1f56b5d77247d89a15a2c16ba2f5d1d672c835e8 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 14:09:06 -0700
Subject: doc/manual: un-inline definitions from `substitute`

---
 doc/manual/src/glossary.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 608beb8f8..8dff4646c 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -7,6 +7,14 @@
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
+  - [content-addressed derivation]{#gloss-fixed-output-derivation}
+    FIXME
+
+  - [fixed-output derivation]{#gloss-fixed-output-derivation}
+    A derivation which includes the `__outHash` attribute; the output
+    of such derivations must exactly match the hash.  All fixed-output
+    derivations are [content-addressed derivations](#gloss-content-addressed-derivation).
+
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
     `/nix/store`.
@@ -44,6 +52,16 @@
     derivation outputs (objects produced by running a build action), or
     derivations (files describing a build action).
 
+  - [input-addressed store object]{#gloss-input-addressed-store-object}\
+    Store objects produced by building a
+    non-[content-addressed](#gloss-content-addressed-derivation)
+    derivation.
+
+  - [output-addressed store object]{#gloss-output-addressed-store-object}\
+    A store object whose store path hashes its content.  This
+    includes derivations and the outputs of
+    [content-addressed derivations](#gloss-content-addressed-derivation)
+
   - [substitute]{#gloss-substitute}\
     A substitute is a command invocation stored in the Nix database that
     describes how to build a store object, bypassing the normal build
@@ -59,9 +77,7 @@
     - the store object is signed by one of the `trusted-public-keys`
     - the substituter is in the `trusted-substituters` list
     - the `no-require-sigs` option has been set to disable signature checking
-    - the store object is *output-addressed*; this includes
-      derivations, the outputs of content-addressed derivations, and
-      the outputs of fixed-output derivations.
+    - the store object is [output-addressed](#gloss-output-addressed-store-object)
 
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
-- 
cgit v1.2.3


From 0a98d564b3d8d195c023429e5f7faf63e20b5d93 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 14:41:27 -0700
Subject: glossary: resolve FIXME in #gloss-fixed-output-derivation

---
 doc/manual/src/glossary.md | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 8dff4646c..473aef03c 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -7,13 +7,14 @@
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
-  - [content-addressed derivation]{#gloss-fixed-output-derivation}
-    FIXME
+  - [content-addressed derivation]{#gloss-content-addressed-derivation}\
+    A derivation which has the
+    [`__contentAddressed`](language/advanced-attributes.md#contentAddressed)
+    attribute set to `true`.
 
-  - [fixed-output derivation]{#gloss-fixed-output-derivation}
-    A derivation which includes the `__outHash` attribute; the output
-    of such derivations must exactly match the hash.  All fixed-output
-    derivations are [content-addressed derivations](#gloss-content-addressed-derivation).
+  - [fixed-output derivation]{#gloss-fixed-output-derivation}\
+    A derivation which includes the `__outputHash` attribute; the output
+    of such derivations must exactly match the hash.
 
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
@@ -59,8 +60,10 @@
 
   - [output-addressed store object]{#gloss-output-addressed-store-object}\
     A store object whose store path hashes its content.  This
-    includes derivations and the outputs of
-    [content-addressed derivations](#gloss-content-addressed-derivation)
+    includes derivations, the outputs of
+    [content-addressed derivations](#gloss-content-addressed-derivation),
+    and the outputs of
+    [fixed-output derivations](#gloss-fixed-output-derivation).
 
   - [substitute]{#gloss-substitute}\
     A substitute is a command invocation stored in the Nix database that
-- 
cgit v1.2.3


From 1b2b8c39fd64871b3df261c05ed001fcd1057a6c Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 14:47:17 -0700
Subject: fix link to language/advanced-attributes.md#adv-attr-contentAddressed

---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 473aef03c..bf1d0cf05 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -9,7 +9,7 @@
 
   - [content-addressed derivation]{#gloss-content-addressed-derivation}\
     A derivation which has the
-    [`__contentAddressed`](language/advanced-attributes.md#contentAddressed)
+    [`__contentAddressed`](language/advanced-attributes.md#adv-attr-contentAddressed)
     attribute set to `true`.
 
   - [fixed-output derivation]{#gloss-fixed-output-derivation}\
-- 
cgit v1.2.3


From def4fb9a0f73046efbf9fdb4f1e35898fb27ca34 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 14:47:33 -0700
Subject: __outputHash: add link

---
 doc/manual/src/glossary.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index bf1d0cf05..d61cfc823 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -13,8 +13,8 @@
     attribute set to `true`.
 
   - [fixed-output derivation]{#gloss-fixed-output-derivation}\
-    A derivation which includes the `__outputHash` attribute; the output
-    of such derivations must exactly match the hash.
+    A derivation which includes the
+    [`__outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute.
 
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
-- 
cgit v1.2.3


From 8139bbe2ba767458cba4158627ee3d58f4a35d7d Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 15:01:07 -0700
Subject: implement
 https://github.com/NixOS/nix/pull/6870#pullrequestreview-1093700220

---
 doc/manual/src/glossary.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index d61cfc823..b30633833 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -74,8 +74,8 @@
 
   - [substituter]{#gloss-substituter}\
     A *substituter* is an additional store from which Nix will
-    copy store objects it doesn't have. Nix will not copy a store
-    path from a remote store unless one of the following is true:
+    copy store objects it doesn't have. Nix will copy a store
+    path from a remote store only if one of the following is true:
 
     - the store object is signed by one of the `trusted-public-keys`
     - the substituter is in the `trusted-substituters` list
-- 
cgit v1.2.3


From 57f12df5e4cde436566d3c4f0226d329e6eedf1a Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 15:09:10 -0700
Subject: input-addressed store object: include FODOs

---
 doc/manual/src/glossary.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index b30633833..89a9b94a1 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -54,8 +54,9 @@
     derivations (files describing a build action).
 
   - [input-addressed store object]{#gloss-input-addressed-store-object}\
-    Store objects produced by building a
-    non-[content-addressed](#gloss-content-addressed-derivation)
+    A store object produced by building a
+    non-[content-addressed](#gloss-content-addressed-derivation),
+    non-[fixed-output](#gloss-fixed-output-derivation),
     derivation.
 
   - [output-addressed store object]{#gloss-output-addressed-store-object}\
-- 
cgit v1.2.3


From d5e064d8162e377556dc9daba99868085561a080 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 17:46:31 -0700
Subject: glossary: fix broken link

---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 89a9b94a1..1aebdaa67 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -9,7 +9,7 @@
 
   - [content-addressed derivation]{#gloss-content-addressed-derivation}\
     A derivation which has the
-    [`__contentAddressed`](language/advanced-attributes.md#adv-attr-contentAddressed)
+    [`__contentAddressed`](language/advanced-attributes.md#adv-attr-__contentAddressed)
     attribute set to `true`.
 
   - [fixed-output derivation]{#gloss-fixed-output-derivation}\
-- 
cgit v1.2.3


From 887e922be29d37d377ef766c7fe7a2103f43ca21 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 17:47:13 -0700
Subject: glossary: outputHash, not __outputHash

---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 1aebdaa67..73e209103 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -14,7 +14,7 @@
 
   - [fixed-output derivation]{#gloss-fixed-output-derivation}\
     A derivation which includes the
-    [`__outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute.
+    [`outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute.
 
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
-- 
cgit v1.2.3


From f6c750e8b2f299e9876fd8f2578f9093682f6d7f Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 17:48:34 -0700
Subject: glossary: remove extraneous comma

---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 73e209103..7ba595ba0 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -56,7 +56,7 @@
   - [input-addressed store object]{#gloss-input-addressed-store-object}\
     A store object produced by building a
     non-[content-addressed](#gloss-content-addressed-derivation),
-    non-[fixed-output](#gloss-fixed-output-derivation),
+    non-[fixed-output](#gloss-fixed-output-derivation)
     derivation.
 
   - [output-addressed store object]{#gloss-output-addressed-store-object}\
-- 
cgit v1.2.3


From 59dc8346ca53f49ccdbbd6709b12a479376d1464 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 17:51:56 -0700
Subject: move substituter signature-checking conditions to configuration file
 documentation

---
 doc/manual/src/glossary.md | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 7ba595ba0..6bf041e7c 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -75,13 +75,8 @@
 
   - [substituter]{#gloss-substituter}\
     A *substituter* is an additional store from which Nix will
-    copy store objects it doesn't have. Nix will copy a store
-    path from a remote store only if one of the following is true:
-
-    - the store object is signed by one of the `trusted-public-keys`
-    - the substituter is in the `trusted-substituters` list
-    - the `no-require-sigs` option has been set to disable signature checking
-    - the store object is [output-addressed](#gloss-output-addressed-store-object)
+    copy store objects it doesn't have.  For details, see the
+    [`substituters` option](command-ref/conf-file.html#conf-substituters).
 
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
-- 
cgit v1.2.3


From e6f5352e71a1811eb2eb3bfb989e109de590c7a7 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 18:27:00 -0700
Subject: #binary-cache -> #gloss-binary-cache

---
 doc/manual/src/glossary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 6bf041e7c..a34b8a60c 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -34,7 +34,7 @@
       directory on another machine,  accessed via `ssh` or
       served by the `nix-serve` Perl script.
 
-  - [binary cache]{#binary-cache}\
+  - [binary cache]{#gloss-binary-cache}\
     A *binary cache* is a Nix store which uses a different format: its
     metadata and signatures are kept in `.narinfo` files rather than in a
     Nix database.  This different format simplifies serving store objects
-- 
cgit v1.2.3


From e90f2fcfc71ca997f254c86f8ed12fc143374752 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Thu, 1 Sep 2022 18:28:05 -0700
Subject: glossary: add entry for `chroot store` (used 11 times in nix)

---
 doc/manual/src/glossary.md | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index a34b8a60c..70a0eb994 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -34,6 +34,9 @@
       directory on another machine,  accessed via `ssh` or
       served by the `nix-serve` Perl script.
 
+  - [chroot store]{#gloss-chroot-store}\
+    A local store whose canonical path is anything other than `/nix/store`.
+
   - [binary cache]{#gloss-binary-cache}\
     A *binary cache* is a Nix store which uses a different format: its
     metadata and signatures are kept in `.narinfo` files rather than in a
-- 
cgit v1.2.3


From 47fa1087c8864654f6cfae84e25ac6db318ed1d4 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 16 Sep 2022 09:36:20 +0200
Subject: Update doc/manual/src/contributing/hacking.md

---
 doc/manual/src/contributing/hacking.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index d8a8c8591..628744bf2 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -142,8 +142,8 @@ After the CI run completes, you can check the output to extract the installer ur
 1. Click into the detailed view of the CI run.
 2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them).
 3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`)
-4. Copy the install_url
-5. To generate an install command, plug this install_url and your github username into this template:
+4. Copy the value of `install_url`
+5. To generate an install command, plug this `install_url` and your GitHub username into this template:
 
     ```console
     sh <(curl -L <install_url>) --tarball-url-prefix https://<github-username>-nix-install-tests.cachix.org/serve
-- 
cgit v1.2.3


From 0a4bd9fe88807cbae51b8b8b51c4897a76991d20 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 16 Sep 2022 09:36:30 +0200
Subject: Update doc/manual/src/contributing/hacking.md

---
 doc/manual/src/contributing/hacking.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 628744bf2..9e4e679e6 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -138,7 +138,7 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed
 
 ### Using the CI-generated installer for manual testing
 
-After the CI run completes, you can check the output to extract the installer url:
+After the CI run completes, you can check the output to extract the installer URL:
 1. Click into the detailed view of the CI run.
 2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them).
 3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`)
-- 
cgit v1.2.3


From 1ae974120a24f70eba12e073dbba4b7bac73eedf Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 16 Sep 2022 09:36:37 +0200
Subject: Update doc/manual/src/contributing/hacking.md

---
 doc/manual/src/contributing/hacking.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 9e4e679e6..7f3905d38 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -121,7 +121,7 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed
   - `x86_64-darwin`.
   
   While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
-- the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`.
+- The `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`.
 
 ### One-time setup
 
-- 
cgit v1.2.3


From dc8c0b173c2cc5bd0fe4273f741fda5591ba4133 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 16 Sep 2022 09:36:55 +0200
Subject: Update doc/manual/src/contributing/hacking.md

---
 doc/manual/src/contributing/hacking.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 7f3905d38..f4aeda871 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -130,7 +130,7 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed
     - Create or log in to an account.
     - Create a Cachix cache using the format `<github-username>-nix-install-tests`.
     - Navigate to the new cache > Settings > Auth Tokens.
-    - Generate a new cachix auth token and copy the generated value.
+    - Generate a new Cachix auth token and copy the generated value.
 4. At github.com:
     - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret.
     - Name the secret `CACHIX_AUTH_TOKEN`
-- 
cgit v1.2.3


From ad5b09423aa7e5112de06667e28e78a9e4d1ff33 Mon Sep 17 00:00:00 2001
From: Adam Joseph <adam@westernsemico.com>
Date: Fri, 16 Sep 2022 01:59:24 -0700
Subject: release-notes/rl-next.md: note new argument to fetchurl.nix

---
 doc/manual/src/release-notes/rl-next.md | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 78ae99f4b..68f7d1a9d 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,2 +1,7 @@
 # Release X.Y (202?-??-??)
 
+* `<nix/fetchurl.nix>` now accepts an additional argument `impure` which
+  defaults to `false`.  If it is set to `true`, the `hash` and `sha256`
+  arguments will be ignored and the resulting derivation will have
+  `__impure` set to `true`, making it an impure derivation.
+
-- 
cgit v1.2.3


From 4bd52bf6c4c88e2f8a9b703d75c3db5ad062353c Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Sat, 17 Sep 2022 13:20:11 -0500
Subject: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/contributing/hacking.md | 2 --
 1 file changed, 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index f4aeda871..5fad34763 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -85,8 +85,6 @@ $ nix develop
 
 ## Testing Nix
 
-Nix comes with three different flavors of tests: unit, functional and integration.
-
 ### Unit-tests
 
 The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined
-- 
cgit v1.2.3


From 84bdb0e3ade70be722087b95beb7f460e0d3da8d Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Sun, 18 Sep 2022 12:58:28 -0500
Subject: address review feedback

Mainly:
- Try to triangulate between narrative that framed this as
  a new/easy process and the need for a reference that will
  not quickly grow stale.
- Fix a ~continuity issue where the text was talking about
  "your Cachix cache" before saying that you'd need to make
  a Cachix cache to enable the installer tests.
- Adopt suggestion on titling, and nest subtitles in the
  installer test section.
---
 doc/manual/src/contributing/hacking.md | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 5fad34763..f67660ab2 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -83,7 +83,7 @@ by:
 $ nix develop
 ```
 
-## Testing Nix
+## Running tests
 
 ### Unit-tests
 
@@ -107,21 +107,21 @@ Because these tests are expensive and require more than what the standard github
 
 You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}`
 
-## Testing the install scripts
+### Installer tests
 
-Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports).
+With just a little one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can easily test the installer each time you push to a branch.
 
-If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped `installer` and `installer_test` jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs.
-- The `installer` job will generate installers for these platforms:
+Creating a Cachix cache for your installer tests and adding its authorization token to GitHub enables [two installer-specific jobs in the CI workflow](https://github.com/NixOS/nix/blob/88a45d6149c0e304f6eb2efcc2d7a4d0d569f8af/.github/workflows/ci.yml#L50-L91):
+
+- The `installer` job generates installers for the platforms below and uploads them to your Cachix cache:
   - `x86_64-linux`
   - `armv6l-linux`
   - `armv7l-linux`
-  - `x86_64-darwin`.
-  
-  While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms.
-- The `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`.
+  - `x86_64-darwin`
+
+- The `installer_test` job (which runs on `ubuntu-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command.
 
-### One-time setup
+#### One-time setup
 
 1. Have a GitHub account with a fork of the Nix repo.
 2. At cachix.org:
@@ -129,12 +129,12 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed
     - Create a Cachix cache using the format `<github-username>-nix-install-tests`.
     - Navigate to the new cache > Settings > Auth Tokens.
     - Generate a new Cachix auth token and copy the generated value.
-4. At github.com:
+3. At github.com:
     - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret.
-    - Name the secret `CACHIX_AUTH_TOKEN`
+    - Name the secret `CACHIX_AUTH_TOKEN`.
     - Paste the copied value of the Cachix cache auth token.
 
-### Using the CI-generated installer for manual testing
+#### Using the CI-generated installer for manual testing
 
 After the CI run completes, you can check the output to extract the installer URL:
 1. Click into the detailed view of the CI run.
@@ -147,7 +147,7 @@ After the CI run completes, you can check the output to extract the installer UR
     sh <(curl -L <install_url>) --tarball-url-prefix https://<github-username>-nix-install-tests.cachix.org/serve
     ```
 
-<!-- ### Manually generating test installers
+<!-- #### Manually generating test installers
 
 There's obviously a manual way to do this, and it's still the only way for
 platforms that lack GA runners.
-- 
cgit v1.2.3


From e04b38f789ff2fb3a93f4cf5783b23430e5d2797 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sol=C3=A8ne=20Rapenne?= <solene.rapenne@tweag.io>
Date: Fri, 23 Sep 2022 11:21:19 +0200
Subject: add ccacheStdenv

when using ccache, rebuild time has been measured
89% faster while not slowing the speed of cold builds
---
 doc/manual/src/contributing/hacking.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 59ce5cac7..e97b40cdd 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -42,7 +42,7 @@ $ nix develop
 ```
 
 To get a shell with a different compilation environment (e.g. stdenv,
-gccStdenv, clangStdenv, clang11Stdenv):
+gccStdenv, clangStdenv, clang11Stdenv, ccacheStdenv):
 
 ```console
 $ nix-shell -A devShells.x86_64-linux.clang11StdenvPackages
@@ -54,6 +54,9 @@ or if you have a flake-enabled nix:
 $ nix develop .#clang11StdenvPackages
 ```
 
+Note: you can use `ccacheStdenv` to drastically improve rebuild
+time. By default, ccache keeps artifacts in `~/.cache/ccache/`.
+
 To build Nix itself in this shell:
 
 ```console
-- 
cgit v1.2.3


From 847cd49909d24dde08f004ba1fb7a72c7f7a7b8c Mon Sep 17 00:00:00 2001
From: Solene Rapenne <solene@perso.pw>
Date: Wed, 28 Sep 2022 01:03:46 +0200
Subject: nix-copy-closure: improve wording

---
 doc/manual/src/command-ref/nix-copy-closure.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md
index 7047d3012..9a29030bd 100644
--- a/doc/manual/src/command-ref/nix-copy-closure.md
+++ b/doc/manual/src/command-ref/nix-copy-closure.md
@@ -30,8 +30,8 @@ Since `nix-copy-closure` calls `ssh`, you may be asked to type in the
 appropriate password or passphrase.  In fact, you may be asked _twice_
 because `nix-copy-closure` currently connects twice to the remote
 machine, first to get the set of paths missing on the target machine,
-and second to send the dump of those paths.  If this bothers you, use
-`ssh-agent`.
+and second to send the dump of those paths.  When using public key
+authentication, you can avoid typing the passphrase with `ssh-agent`.
 
 # Options
 
-- 
cgit v1.2.3


From e1418430ac57767906b617a8a558d305ca651980 Mon Sep 17 00:00:00 2001
From: "Travis A. Everett" <travis.a.everett@gmail.com>
Date: Wed, 5 Oct 2022 09:52:53 -0500
Subject: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/contributing/hacking.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index f67660ab2..5bee7932b 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -109,7 +109,7 @@ You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-
 
 ### Installer tests
 
-With just a little one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can easily test the installer each time you push to a branch.
+After a one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can test the installer each time you push to a branch.
 
 Creating a Cachix cache for your installer tests and adding its authorization token to GitHub enables [two installer-specific jobs in the CI workflow](https://github.com/NixOS/nix/blob/88a45d6149c0e304f6eb2efcc2d7a4d0d569f8af/.github/workflows/ci.yml#L50-L91):
 
@@ -123,7 +123,7 @@ Creating a Cachix cache for your installer tests and adding its authorization to
 
 #### One-time setup
 
-1. Have a GitHub account with a fork of the Nix repo.
+1. Have a GitHub account with a fork of the [Nix repository](https://github.com/NixOS/nix).
 2. At cachix.org:
     - Create or log in to an account.
     - Create a Cachix cache using the format `<github-username>-nix-install-tests`.
-- 
cgit v1.2.3


From 1ec8810687859e0af96d844da67ab6c6d6e69f9d Mon Sep 17 00:00:00 2001
From: Johan Herland <johan@herland.net>
Date: Wed, 19 Oct 2022 11:50:58 +0200
Subject: Explain how Nix handles antiquotation of paths

Specifically, explain why Nix does not _re_evaluate paths during a
`nix repl` session. This is a thing that bit me while playing around
with paths and antiquotation in `nix repl` while reading the Nix
language tutorial at https://nix.dev/tutorials/nix-language.

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/language/values.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index f09400d02..6fc8c0369 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -150,6 +150,20 @@
   recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
   operation. `./a.${foo}/b.${bar}` is a path.
 
+  When a path appears in an antiquotation, and is thus coerced into a string,
+  the path is first copied into the Nix store and the resulting string is
+  the Nix store path. For instance `"${./foo.txt}" will cause `foo.txt` in
+  the current directory to be copied into the Nix store and result in the
+  string `"/nix/store/<HASH>-foo.txt"`.
+
+  Note that the Nix language assumes that all input files will remain
+  _unchanged_ during the course of the Nix expression evaluation.
+  If you for example antiquote a file path during a `nix repl` session, and
+  then later in the same session, after having changed the file contents,
+  evaluate the antiquotation with the file path again, then Nix will still
+  return the first store path. It will _not_ reread the file contents to
+  produce a different Nix store path.
+
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 
   *Booleans* with values `true` and `false`.
-- 
cgit v1.2.3


From 2a7348f986f8c2c9d6419ea44f7a6b19a667c7d4 Mon Sep 17 00:00:00 2001
From: Guillaume Maudoux <guillaume.maudoux@tweag.io>
Date: Sat, 22 Oct 2022 23:38:50 +0200
Subject: Fixup merge typo

---
 doc/manual/src/release-notes/rl-next.md | 2 --
 1 file changed, 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 9c43132d4..a08dc9c9b 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -7,5 +7,3 @@
 * Error traces have been reworked to provide detailed explanations and more
   accurate error locations. A short excerpt of the trace is now shown by
   default when an error occurs.
-
->>>>>>> origin/master
-- 
cgit v1.2.3


From f7ab93b0685b653c60b86540639a42b03389c90b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Sun, 6 Nov 2022 12:25:21 +0100
Subject: manual: build action -> build task

after discussing this with multiple people, I'm convinced that "build
task" is more precise: a derivation is not an action, but inert until it
is built. also it's easier to pronounce.

proposal: use "build task" for the generic concept "description of how
to derive new files from the contents of existing files". then it will
be easier to distinguish what we mean by "derivation" (a specific data
structure and Nix language value type) and "store derivation" (a
serialisation of a derivation into a file in the Nix store).
---
 doc/manual/src/command-ref/nix-daemon.md | 4 ++--
 doc/manual/src/command-ref/nix-store.md  | 2 +-
 doc/manual/src/glossary.md               | 6 +++---
 doc/manual/src/introduction.md           | 2 +-
 doc/manual/src/language/derivations.md   | 2 +-
 5 files changed, 8 insertions(+), 8 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/nix-daemon.md b/doc/manual/src/command-ref/nix-daemon.md
index e91cb01dd..04b483be3 100644
--- a/doc/manual/src/command-ref/nix-daemon.md
+++ b/doc/manual/src/command-ref/nix-daemon.md
@@ -8,6 +8,6 @@
 
 # Description
 
-The Nix daemon is necessary in multi-user Nix installations. It performs
-build actions and other operations on the Nix store on behalf of
+The Nix daemon is necessary in multi-user Nix installations. It runs
+build tasks and other operations on the Nix store on behalf of
 unprivileged users.
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index ecd838e8d..1251888e9 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -71,7 +71,7 @@ paths. Realisation is a somewhat overloaded term:
     outputs are already valid, in which case we are done
     immediately. Otherwise, there may be [substitutes](../glossary.md)
     that produce the outputs (e.g., by downloading them). Finally, the
-    outputs can be produced by performing the build action described
+    outputs can be produced by running the build task described
     by the derivation.
 
   - If the store path is not a derivation, realisation ensures that the
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 70a0eb994..b13709f8a 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -1,7 +1,7 @@
 # Glossary
 
   - [derivation]{#gloss-derivation}\
-    A description of a build action. The result of a derivation is a
+    A description of a build task. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
     using the [`derivation` primitive](language/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
@@ -53,8 +53,8 @@
     A file that is an immediate child of the Nix store directory. These
     can be regular files, but also entire directory trees. Store objects
     can be sources (objects copied from outside of the store),
-    derivation outputs (objects produced by running a build action), or
-    derivations (files describing a build action).
+    derivation outputs (objects produced by running a build task), or
+    derivations (files describing a build task).
 
   - [input-addressed store object]{#gloss-input-addressed-store-object}\
     A store object produced by building a
diff --git a/doc/manual/src/introduction.md b/doc/manual/src/introduction.md
index d87487a07..b54346db8 100644
--- a/doc/manual/src/introduction.md
+++ b/doc/manual/src/introduction.md
@@ -104,7 +104,7 @@ a currently running program.
 
 Packages are built from _Nix expressions_, which is a simple
 functional language.  A Nix expression describes everything that goes
-into a package build action (a “derivation”): other packages, sources,
+into a package build task (a “derivation”): other packages, sources,
 the build script, environment variables for the build script, etc.
 Nix tries very hard to ensure that Nix expressions are
 _deterministic_: building a Nix expression twice should yield the same
diff --git a/doc/manual/src/language/derivations.md b/doc/manual/src/language/derivations.md
index 3391ec0d8..043a38191 100644
--- a/doc/manual/src/language/derivations.md
+++ b/doc/manual/src/language/derivations.md
@@ -1,7 +1,7 @@
 # Derivations
 
 The most important built-in function is `derivation`, which is used to
-describe a single derivation (a build action). It takes as input a set,
+describe a single derivation (a build task). It takes as input a set,
 the attributes of which specify the inputs of the build.
 
   - There must be an attribute named [`system`]{#attr-system} whose value must be a
-- 
cgit v1.2.3


From d8781c4fc5143153812e056df23183bcab505253 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 9 Nov 2022 01:11:47 +0100
Subject: add removing users to uninstall instructions

---
 doc/manual/src/installation/installing-binary.md | 27 ++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 2d007ca1b..615d862a4 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -88,10 +88,24 @@ extension. The installer will also create `/etc/profile.d/nix.sh`.
 
 ### Linux
 
+Remove files created by Nix:
+
+```console
+sudo rm -rf /nix /etc/nix /etc/profile/nix.sh ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
+```
+
+Remove build users and their group:
+
 ```console
-sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
+for i in $(seq 30001 30032); do
+  sudo userdel $i
+done
+sudo groupdel 30000
+```
+
+If you are on Linux with systemd, remove the Nix daemon service:
 
-# If you are on Linux with systemd, you will need to run:
+```console
 sudo systemctl stop nix-daemon.socket
 sudo systemctl stop nix-daemon.service
 sudo systemctl disable nix-daemon.socket
@@ -99,8 +113,13 @@ sudo systemctl disable nix-daemon.service
 sudo systemctl daemon-reload
 ```
 
-There may also be references to Nix in `/etc/profile`, `/etc/bashrc`,
-and `/etc/zshrc` which you may remove.
+There may also be references to Nix in
+
+- `/etc/profile`
+- `/etc/bashrc`,
+- `/etc/zshrc`
+
+which you may remove.
 
 ### macOS
 
-- 
cgit v1.2.3


From be8744f937150c65ffa5d98ffdc74c502dbcdd5e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 19 Sep 2022 22:21:40 +0200
Subject: manual: architecture overview

these changes were not merged properly and had to be reverted.

see merge commit d8e54d19f71f78540dd967b2e42be6a5d8a0b1bb for full
history leading up to here.
---
 doc/manual/src/SUMMARY.md.in                |  1 +
 doc/manual/src/architecture/architecture.md | 77 +++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 doc/manual/src/architecture/architecture.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 908e7e3d9..b386aa14b 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -59,6 +59,7 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
+- [Architecture](architecture/architecture.md)
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
new file mode 100644
index 000000000..24150fc2b
--- /dev/null
+++ b/doc/manual/src/architecture/architecture.md
@@ -0,0 +1,77 @@
+# Architecture
+
+This chapter describes how Nix works.
+It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
+
+## Overview
+
+Nix consists of [hierarchical layers].
+
+[hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
+
+```
++---------------------------------------------------------------+
+| Nix                                                           |
+|                 [ commmand line interface ]------,            |
+|                              |                   |            |
+|                          evaluates               |            |
+|                              |                manages         |
+|                              V                   |            |
+|                 [ configuration language  ]      |            |
+|                              |                   |            |
+| +----------------------------|-------------------V----------+ |
+| | store                 evaluates to                        | |
+| |                            |                              | |
+| |            referenced by   V       builds                 | |
+| | [ build input ] ---> [ build plan ] ---> [ build result ] | |
+| |                                                           | |
+| +-----------------------------------------------------------+ |
++---------------------------------------------------------------+
+```
+
+At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
+
+Below that is the [Nix language](../language/index.md), a [purely functional] configuration language.
+It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+
+[purely functional]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
+
+Command line interface and Nix language are what users interact with most.
+
+> **Note**
+> The Nix language itself does not have a notion of *packages* or *configurations*.
+> As far as we are concerned here, the inputs and results of a build plan are just data.
+
+Underlying these is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data.
+
+A build plan is a series of *build tasks*.
+Each build task has a special build input, which is used as *build instructions*.
+The result of a build task can be input to another build task.
+
+> **Important**
+> A build task in Nix is called [derivation](../glossary#gloss-derivation).
+
+```
++----------------------------------------------------------------------------------+
+| store           ..............................................                   |
+|                 : build plan                                 :                   |
+|                 :                                            :                   |
+| [ build input ]---instructions-,                             :                   |
+|                 :              |                             :                   |
+|                 :              v                             :                   |
+| [ build input ]--------->[ build task ]-instructions-,       :                   |
+|                 :                                    |       :                   |
+|                 :                                    v       :                   |
+| [ build input ]---instructions-,              [ build task ]--->[ build result ] |
+|                 :              |                     ^       :                   |
+|                 :              v                     |       :                   |
+| [ build input ]--------->[ build task ]--------------'       :                   |
+|                 :              ^                             :                   |
+|                 :              |                             :                   |
+| [ build input ]----------------'                             :                   |
+|                 :                                            :                   |
+|                 :............................................:                   |
++----------------------------------------------------------------------------------+
+```
+
-- 
cgit v1.2.3


From b5728ace5d5250a6d52df05802c9fc325153dc2c Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 23 Sep 2022 14:48:54 +0200
Subject: add articles

---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 24150fc2b..972ff2d58 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -36,7 +36,7 @@ It is used to compose expressions which ultimately evaluate to self-contained *b
 
 [purely functional]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
 
-Command line interface and Nix language are what users interact with most.
+The command line interface and the Nix language are what users interact with most.
 
 > **Note**
 > The Nix language itself does not have a notion of *packages* or *configurations*.
-- 
cgit v1.2.3


From 98447c1a7f1538f4d3132c0b79ad5b67e136af85 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 23 Sep 2022 14:49:47 +0200
Subject: clarify subject of sentence

Co-authored-by: Bryan Honof <bryan.honof@tweag.io>
---
 doc/manual/src/architecture/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 972ff2d58..f113cbf4d 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -42,7 +42,7 @@ The command line interface and the Nix language are what users interact with mos
 > The Nix language itself does not have a notion of *packages* or *configurations*.
 > As far as we are concerned here, the inputs and results of a build plan are just data.
 
-Underlying these is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+Underlying the command line interface and the Nix language is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
 It can also execute build plans to produce new data.
 
 A build plan is a series of *build tasks*.
-- 
cgit v1.2.3


From 3d716df7ce0639e61170ea1e18a370138dce8e5b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Sat, 15 Oct 2022 23:46:32 +0200
Subject: make diagrams compatible with svgbob

this will at some point enable rendering them nicely for the web
---
 doc/manual/src/architecture/architecture.md | 53 +++++++++++++++++------------
 1 file changed, 31 insertions(+), 22 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index f113cbf4d..0df4fbc68 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -11,20 +11,25 @@ Nix consists of [hierarchical layers].
 
 ```
 +---------------------------------------------------------------+
-| Nix                                                           |
-|                 [ commmand line interface ]------,            |
+| Nix             .-------------------------.                   |
+|                 | commmand line interface |------.            |
+|                 '-------------------------'      |            |
 |                              |                   |            |
 |                          evaluates               |            |
 |                              |                manages         |
 |                              V                   |            |
-|                 [ configuration language  ]      |            |
+|                 .-------------------------.      |            |
+|                 | configuration language  |      |            |
+|                 '-------------------------'      |            |
 |                              |                   |            |
-| +----------------------------|-------------------V----------+ |
-| | store                 evaluates to                        | |
-| |                            |                              | |
+|                         evaluates to             |            |
+|                              |                   V            |
+| +----------------------------|------------------------------+ |
+| | store                      |                              | |
 | |            referenced by   V       builds                 | |
-| | [ build input ] ---> [ build plan ] ---> [ build result ] | |
-| |                                                           | |
+| | .-------------.      .------------.      .--------------. | |
+| | | build input |----->| build plan | ---->| build result | | |
+| | '-------------'      '------------'      '--------------' | |
 | +-----------------------------------------------------------+ |
 +---------------------------------------------------------------+
 ```
@@ -54,24 +59,28 @@ The result of a build task can be input to another build task.
 
 ```
 +----------------------------------------------------------------------------------+
-| store           ..............................................                   |
+| store            - - - - - - - - - - -  - - - - - - - - - - -                    |
 |                 : build plan                                 :                   |
-|                 :                                            :                   |
-| [ build input ]---instructions-,                             :                   |
-|                 :              |                             :                   |
+| .-------------. :                                            :                   |
+| | build input |---instructions-.                             :                   |
+| '-------------' :              |                             :                   |
 |                 :              v                             :                   |
-| [ build input ]--------->[ build task ]-instructions-,       :                   |
-|                 :                                    |       :                   |
+| .-------------. :        .------------.                      :                   |
+| | build input |--------->| build task |-instructions-.       :                   |
+| '-------------' :        '------------'              |       :                   |
 |                 :                                    v       :                   |
-| [ build input ]---instructions-,              [ build task ]--->[ build result ] |
-|                 :              |                     ^       :                   |
-|                 :              v                     |       :                   |
-| [ build input ]--------->[ build task ]--------------'       :                   |
+| .-------------. :                             .------------. :  .--------------. |
+| | build input |---instructions-.              | build task |--->| build result | |
+| '-------------' :              |              '------------' :  '--------------' |
+|                 :              v                     ^       :                   |
+| .-------------. :        .------------.              |       :                   |
+| | build input |--------->| build task |--------------'       :                   |
+| '-------------' :        '------------'                      :                   |
 |                 :              ^                             :                   |
-|                 :              |                             :                   |
-| [ build input ]----------------'                             :                   |
-|                 :                                            :                   |
-|                 :............................................:                   |
+| .-------------. :              |                             :                   |
+| | build input |----------------'                             :                   |
+| '-------------' :                                            :                   |
+|                 :_ _ _ _ _ _ _ _ _ _ _  _ _ _ _ _ _ _ _ _ _ _:                   |
 +----------------------------------------------------------------------------------+
 ```
 
-- 
cgit v1.2.3


From 9d20a056c82b129ab2584169e692c7f3e324fa29 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 9 Nov 2022 01:36:17 +0100
Subject: remove external link

the language has its own overview page where its properties are
described in sufficient detail.
---
 doc/manual/src/architecture/architecture.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 0df4fbc68..4b0704894 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -36,10 +36,8 @@ Nix consists of [hierarchical layers].
 
 At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
 
-Below that is the [Nix language](../language/index.md), a [purely functional] configuration language.
-It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
-
-[purely functional]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
+Below that is the [Nix language](../language/index.md), the configuration language for Nix.
+Its expressions ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
 
 The command line interface and the Nix language are what users interact with most.
 
-- 
cgit v1.2.3


From 2af036e5a378c711d8e58d01bdefe5c634c25921 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 11 Nov 2022 14:01:13 +0100
Subject: remove stray comma

---
 doc/manual/src/installation/installing-binary.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 615d862a4..31faeadc2 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -116,7 +116,7 @@ sudo systemctl daemon-reload
 There may also be references to Nix in
 
 - `/etc/profile`
-- `/etc/bashrc`,
+- `/etc/bashrc`
 - `/etc/zshrc`
 
 which you may remove.
-- 
cgit v1.2.3


From 6bf873651740b1552dea6f30c7778dff11bc52ed Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?=
 <theophane.hufschmitt@tweag.io>
Date: Mon, 14 Nov 2022 15:03:53 +0100
Subject: Add release-notes for the context-restriction in readFile

---
 doc/manual/src/release-notes/rl-next.md | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 68f7d1a9d..2069e4578 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -5,3 +5,8 @@
   arguments will be ignored and the resulting derivation will have
   `__impure` set to `true`, making it an impure derivation.
 
+* If `builtins.readFile` is called on a file with context, then only the parts
+  of that context that appear in the content of the file are retained.
+  This avoids a lot of spurious errors where some benign strings end-up having
+  a context just because they are read from a store path
+  ([#7260](https://github.com/NixOS/nix/pull/7260)).
-- 
cgit v1.2.3


From cc620d961f1fa68038ef44f5947fc053708ab3ad Mon Sep 17 00:00:00 2001
From: Liu Xiaoyi <circuitcoder0@gmail.com>
Date: Sun, 20 Nov 2022 20:04:22 +0800
Subject: Updated uninstall guide involving systemd

Co-authored-by: sequencer <liu@jiuyang.me>
---
 doc/manual/src/installation/installing-binary.md | 32 ++++++++++++++++--------
 1 file changed, 22 insertions(+), 10 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 31faeadc2..1b7db59cd 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -88,6 +88,28 @@ extension. The installer will also create `/etc/profile.d/nix.sh`.
 
 ### Linux
 
+To begin, if you are on Linux with systemd, remove the Nix daemon service:
+
+```console
+sudo systemctl stop nix-daemon.socket
+sudo systemctl stop nix-daemon.service
+sudo systemctl disable nix-daemon.socket
+sudo systemctl disable nix-daemon.service
+sudo systemctl daemon-reload
+```
+
+Then you can remove systemd service files:
+
+```console
+sudo rm -f /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
+```
+
+Also, the installer script uses systemd-tmpfiles (if presents) to create the socket directory. You may also want to remove the configuration for that:
+
+```console
+sudo rm -f /etc/tmpfiles.d/nix-daemon.conf
+```
+
 Remove files created by Nix:
 
 ```console
@@ -103,16 +125,6 @@ done
 sudo groupdel 30000
 ```
 
-If you are on Linux with systemd, remove the Nix daemon service:
-
-```console
-sudo systemctl stop nix-daemon.socket
-sudo systemctl stop nix-daemon.service
-sudo systemctl disable nix-daemon.socket
-sudo systemctl disable nix-daemon.service
-sudo systemctl daemon-reload
-```
-
 There may also be references to Nix in
 
 - `/etc/profile`
-- 
cgit v1.2.3


From 4d55acf5154639cd1a54435ace28cd497b5a9eb8 Mon Sep 17 00:00:00 2001
From: Liu Xiaoyi <circuitcoder0@gmail.com>
Date: Mon, 21 Nov 2022 13:46:22 +0800
Subject: Apply suggestions from code review

Co-authored-by: Sandro <sandro.jaeckel@gmail.com>
---
 doc/manual/src/installation/installing-binary.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 1b7db59cd..8cdd64df6 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -91,23 +91,21 @@ extension. The installer will also create `/etc/profile.d/nix.sh`.
 To begin, if you are on Linux with systemd, remove the Nix daemon service:
 
 ```console
-sudo systemctl stop nix-daemon.socket
 sudo systemctl stop nix-daemon.service
-sudo systemctl disable nix-daemon.socket
-sudo systemctl disable nix-daemon.service
+sudo systemctl disable nix-daemon.socket nix-daemon.service
 sudo systemctl daemon-reload
 ```
 
 Then you can remove systemd service files:
 
 ```console
-sudo rm -f /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
+sudo rm /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
 ```
 
 Also, the installer script uses systemd-tmpfiles (if presents) to create the socket directory. You may also want to remove the configuration for that:
 
 ```console
-sudo rm -f /etc/tmpfiles.d/nix-daemon.conf
+sudo rm /etc/tmpfiles.d/nix-daemon.conf
 ```
 
 Remove files created by Nix:
-- 
cgit v1.2.3


From 52f0c809173fe977ac0b46a8506d0c9af208a197 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 22 Nov 2022 10:36:20 +0100
Subject: fix error in language overview

it is not possible to antiquote numbers.
---
 doc/manual/src/language/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md
index f9e9b9781..db34fde75 100644
--- a/doc/manual/src/language/index.md
+++ b/doc/manual/src/language/index.md
@@ -93,7 +93,7 @@ This is an incomplete overview of language features, by example.
 
    `"hello ${ { a = "world" }.a }"`
 
-   `"1 2 ${3}"`
+   `"1 2 ${toString 3}"`
 
    `"${pkgs.bash}/bin/sh"`
 
-- 
cgit v1.2.3


From 989fc8a8b9cf98addbef85bf909be7b00b0462db Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 23 Nov 2022 15:24:50 +0100
Subject: Add release notes

---
 doc/manual/src/release-notes/rl-next.md | 40 +++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 2069e4578..47181fd39 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -10,3 +10,43 @@
   This avoids a lot of spurious errors where some benign strings end-up having
   a context just because they are read from a store path
   ([#7260](https://github.com/NixOS/nix/pull/7260)).
+
+* Nix can now automatically pick UIDs for builds, removing the need to
+  create `nixbld*` user accounts. these UIDs are allocated starting at
+  872415232 on Linux and 56930 on macOS.
+
+  This is an experimental feature. To enable it, add the following to
+  `nix.conf`:
+
+  ```
+  extra-experimental-features = auto-allocate-uids
+  auto-allocate-uids = true
+  ```
+
+* On Linux, Nix can now run builds in a user namespace where the build
+  runs as root (UID 0) and has 65,536 UIDs available. This is
+  primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build.
+
+  A build can enable this by requiring the `uid-range` system feature,
+  i.e. by setting the derivation attribute
+
+  ```
+  requiredSystemFeatures = [ "uid-range" ];
+  ```
+
+  The `uid-range` system feature requires the `auto-allocate-uids`
+  setting to be enabled (see above).
+
+* On Linux, Nix has experimental support for running builds inside a
+  cgroup. It can be enabled by adding
+
+  ```
+  extra-experimental-features = cgroups
+  ```
+
+  to `nix.conf`. It is also automatically enabled for builds that
+  require the `uid-range` system feature.
+
+* `nix build --json` now prints some statistics about top-level
+  derivations, such as CPU statistics when cgroups are enabled.
-- 
cgit v1.2.3


From 2aa3f2e81020c1c780be6329e1133068779c8f08 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 23 Nov 2022 17:07:59 +0100
Subject: Include UID in hex

---
 doc/manual/src/release-notes/rl-next.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 47181fd39..4c91002fb 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -12,8 +12,8 @@
   ([#7260](https://github.com/NixOS/nix/pull/7260)).
 
 * Nix can now automatically pick UIDs for builds, removing the need to
-  create `nixbld*` user accounts. these UIDs are allocated starting at
-  872415232 on Linux and 56930 on macOS.
+  create `nixbld*` user accounts. These UIDs are allocated starting at
+  872415232 (0x34000000) on Linux and 56930 on macOS.
 
   This is an experimental feature. To enable it, add the following to
   `nix.conf`:
-- 
cgit v1.2.3


From c4ce89f772d85e2a39727927903ca105a8c6a168 Mon Sep 17 00:00:00 2001
From: Liu Xiaoyi <circuitcoder0@gmail.com>
Date: Sat, 26 Nov 2022 22:01:51 +0800
Subject: Clarify uninstallation steps on Linux

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/installation/installing-binary.md | 31 +++++++++++++-----------
 1 file changed, 17 insertions(+), 14 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index 8cdd64df6..a9378681d 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -88,25 +88,28 @@ extension. The installer will also create `/etc/profile.d/nix.sh`.
 
 ### Linux
 
-To begin, if you are on Linux with systemd, remove the Nix daemon service:
+If you are on Linux with systemd:
 
-```console
-sudo systemctl stop nix-daemon.service
-sudo systemctl disable nix-daemon.socket nix-daemon.service
-sudo systemctl daemon-reload
-```
+1. Remove the Nix daemon service:
 
-Then you can remove systemd service files:
+   ```console
+   sudo systemctl stop nix-daemon.service
+   sudo systemctl disable nix-daemon.socket nix-daemon.service
+   sudo systemctl daemon-reload
+   ```
 
-```console
-sudo rm /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
-```
+1. Remove systemd service files:
 
-Also, the installer script uses systemd-tmpfiles (if presents) to create the socket directory. You may also want to remove the configuration for that:
+   ```console
+   sudo rm /etc/systemd/system/nix-daemon.service /etc/systemd/system/nix-daemon.socket
+   ```
 
-```console
-sudo rm /etc/tmpfiles.d/nix-daemon.conf
-```
+1. The installer script uses systemd-tmpfiles to create the socket directory.
+    You may also want to remove the configuration for that:
+
+   ```console
+   sudo rm /etc/tmpfiles.d/nix-daemon.conf
+   ```
 
 Remove files created by Nix:
 
-- 
cgit v1.2.3


From 67bcb99700a0da1395fa063d7c6586740b304598 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 28 Nov 2022 21:54:02 +0100
Subject: Add a setting for enabling cgroups

---
 doc/manual/src/release-notes/rl-next.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 4c91002fb..db2bd7419 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -43,10 +43,11 @@
 
   ```
   extra-experimental-features = cgroups
+  use-cgroups = true
   ```
 
-  to `nix.conf`. It is also automatically enabled for builds that
-  require the `uid-range` system feature.
+  to `nix.conf`. Cgroups are required for derivations that require the
+  `uid-range` system feature.
 
 * `nix build --json` now prints some statistics about top-level
   derivations, such as CPU statistics when cgroups are enabled.
-- 
cgit v1.2.3


From 7dd3e1fec47b9dd6aa6a0b9a58962078a8499453 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 28 Nov 2022 22:04:51 +0100
Subject: Add example

---
 doc/manual/src/release-notes/rl-next.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index db2bd7419..8b314b5f6 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -26,7 +26,8 @@
 * On Linux, Nix can now run builds in a user namespace where the build
   runs as root (UID 0) and has 65,536 UIDs available. This is
   primarily useful for running containers such as `systemd-nspawn`
-  inside a Nix build.
+  inside a Nix build. For an example, see
+  https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
 
   A build can enable this by requiring the `uid-range` system feature,
   i.e. by setting the derivation attribute
-- 
cgit v1.2.3


From 0ea62670eda39ebeaff5335fd8225707ec27e7a3 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 1 Dec 2022 04:40:02 +0100
Subject: move documentation on `auto-allocate-uids` to options docs

this is where it belongs and can be found together with the other
options.
---
 doc/manual/src/release-notes/rl-next.md | 42 ++++++++++++++-------------------
 1 file changed, 18 insertions(+), 24 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 8b314b5f6..bf51aa1f7 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -12,43 +12,37 @@
   ([#7260](https://github.com/NixOS/nix/pull/7260)).
 
 * Nix can now automatically pick UIDs for builds, removing the need to
-  create `nixbld*` user accounts. These UIDs are allocated starting at
-  872415232 (0x34000000) on Linux and 56930 on macOS.
+  create `nixbld*` user accounts.
 
-  This is an experimental feature. To enable it, add the following to
-  `nix.conf`:
+  See [`auto-allocate-uids`].
 
-  ```
-  extra-experimental-features = auto-allocate-uids
-  auto-allocate-uids = true
-  ```
+  [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids)
 
 * On Linux, Nix can now run builds in a user namespace where the build
-  runs as root (UID 0) and has 65,536 UIDs available. This is
-  primarily useful for running containers such as `systemd-nspawn`
-  inside a Nix build. For an example, see
-  https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+  runs as root (UID 0) and has 65,536 UIDs available.
+
+  <!-- FIXME: move this to its own section about system features -->
+
+  This is primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
+
+  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
 
-  A build can enable this by requiring the `uid-range` system feature,
-  i.e. by setting the derivation attribute
+  A build can enable this by by setting the derivation attribute:
 
   ```
   requiredSystemFeatures = [ "uid-range" ];
   ```
 
-  The `uid-range` system feature requires the `auto-allocate-uids`
-  setting to be enabled (see above).
+  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
+  setting to be enabled.
 
-* On Linux, Nix has experimental support for running builds inside a
-  cgroup. It can be enabled by adding
+  [system feature]: (../command-ref/conf-file.md#conf-system-features),
 
-  ```
-  extra-experimental-features = cgroups
-  use-cgroups = true
-  ```
+* On Linux, Nix has experimental support for running builds inside a
+  cgroup.
 
-  to `nix.conf`. Cgroups are required for derivations that require the
-  `uid-range` system feature.
+  See [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
 
 * `nix build --json` now prints some statistics about top-level
   derivations, such as CPU statistics when cgroups are enabled.
-- 
cgit v1.2.3


From 5b4b2eefa1e0f59f02844cacf06077cc21336e17 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Tue, 6 Dec 2022 13:55:09 +0100
Subject: Release notes

---
 doc/manual/src/SUMMARY.md.in            |  1 +
 doc/manual/src/release-notes/rl-2.12.md | 43 ++++++++++++++++++++++++++++++
 doc/manual/src/release-notes/rl-next.md | 46 ---------------------------------
 3 files changed, 44 insertions(+), 46 deletions(-)
 create mode 100644 doc/manual/src/release-notes/rl-2.12.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 908e7e3d9..6a514fa2c 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -65,6 +65,7 @@
   - [CLI guideline](contributing/cli-guideline.md)
 - [Release Notes](release-notes/release-notes.md)
   - [Release X.Y (202?-??-??)](release-notes/rl-next.md)
+  - [Release 2.12 (2022-12-06)](release-notes/rl-2.12.md)
   - [Release 2.11 (2022-08-25)](release-notes/rl-2.11.md)
   - [Release 2.10 (2022-07-11)](release-notes/rl-2.10.md)
   - [Release 2.9 (2022-05-30)](release-notes/rl-2.9.md)
diff --git a/doc/manual/src/release-notes/rl-2.12.md b/doc/manual/src/release-notes/rl-2.12.md
new file mode 100644
index 000000000..82de22cb4
--- /dev/null
+++ b/doc/manual/src/release-notes/rl-2.12.md
@@ -0,0 +1,43 @@
+# Release 2.12 (2022-12-06)
+
+* On Linux, Nix can now run builds in a user namespace where they run
+  as root (UID 0) and have 65,536 UIDs available.
+  <!-- FIXME: move this to its own section about system features -->
+  This is primarily useful for running containers such as `systemd-nspawn`
+  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
+
+  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
+
+  A build can enable this by setting the derivation attribute:
+
+  ```
+  requiredSystemFeatures = [ "uid-range" ];
+  ```
+
+  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
+  setting to be enabled.
+
+  [system feature]: (../command-ref/conf-file.md#conf-system-features)
+
+* Nix can now automatically pick UIDs for builds, removing the need to
+  create `nixbld*` user accounts. See [`auto-allocate-uids`].
+
+  [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids)
+
+* On Linux, Nix has experimental support for running builds inside a
+  cgroup. See
+  [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
+
+* `<nix/fetchurl.nix>` now accepts an additional argument `impure` which
+  defaults to `false`.  If it is set to `true`, the `hash` and `sha256`
+  arguments will be ignored and the resulting derivation will have
+  `__impure` set to `true`, making it an impure derivation.
+
+* If `builtins.readFile` is called on a file with context, then only
+  the parts of the context that appear in the content of the file are
+  retained.  This avoids a lot of spurious errors where strings end up
+  having a context just because they are read from a store path
+  ([#7260](https://github.com/NixOS/nix/pull/7260)).
+
+* `nix build --json` now prints some statistics about top-level
+  derivations, such as CPU statistics when cgroups are enabled.
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index bf51aa1f7..78ae99f4b 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -1,48 +1,2 @@
 # Release X.Y (202?-??-??)
 
-* `<nix/fetchurl.nix>` now accepts an additional argument `impure` which
-  defaults to `false`.  If it is set to `true`, the `hash` and `sha256`
-  arguments will be ignored and the resulting derivation will have
-  `__impure` set to `true`, making it an impure derivation.
-
-* If `builtins.readFile` is called on a file with context, then only the parts
-  of that context that appear in the content of the file are retained.
-  This avoids a lot of spurious errors where some benign strings end-up having
-  a context just because they are read from a store path
-  ([#7260](https://github.com/NixOS/nix/pull/7260)).
-
-* Nix can now automatically pick UIDs for builds, removing the need to
-  create `nixbld*` user accounts.
-
-  See [`auto-allocate-uids`].
-
-  [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids)
-
-* On Linux, Nix can now run builds in a user namespace where the build
-  runs as root (UID 0) and has 65,536 UIDs available.
-
-  <!-- FIXME: move this to its own section about system features -->
-
-  This is primarily useful for running containers such as `systemd-nspawn`
-  inside a Nix build. For an example, see [`tests/systemd-nspawn/nix`][nspawn].
-
-  [nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix.
-
-  A build can enable this by by setting the derivation attribute:
-
-  ```
-  requiredSystemFeatures = [ "uid-range" ];
-  ```
-
-  The `uid-range` [system feature] requires the [`auto-allocate-uids`]
-  setting to be enabled.
-
-  [system feature]: (../command-ref/conf-file.md#conf-system-features),
-
-* On Linux, Nix has experimental support for running builds inside a
-  cgroup.
-
-  See [`use-cgroups`](../command-ref/conf-file.md#conf-use-cgroups).
-
-* `nix build --json` now prints some statistics about top-level
-  derivations, such as CPU statistics when cgroups are enabled.
-- 
cgit v1.2.3


From 8e0946e8df968391d1430af8377bdb51204e4666 Mon Sep 17 00:00:00 2001
From: Linus Heckemann <git@sphalerite.org>
Date: Mon, 26 Sep 2022 20:55:56 +0200
Subject: Remove repeat and enforce-determinism options

These only functioned if a very narrow combination of conditions held:

- The result path does not yet exist (--check did not result in
  repeated builds), AND
- The result path is not available from any configured substituters, AND
- No remote builders that can build the path are available.

If any of these do not hold, a derivation would be built 0 or 1 times
regardless of the repeat option. Thus, remove it to avoid confusion.
---
 doc/manual/src/advanced-topics/diff-hook.md | 34 -----------------------------
 doc/manual/src/command-ref/nix-store.md     |  4 ----
 doc/manual/src/release-notes/rl-next.md     |  3 +++
 3 files changed, 3 insertions(+), 38 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/advanced-topics/diff-hook.md b/doc/manual/src/advanced-topics/diff-hook.md
index 161e64b2a..4a742c160 100644
--- a/doc/manual/src/advanced-topics/diff-hook.md
+++ b/doc/manual/src/advanced-topics/diff-hook.md
@@ -121,37 +121,3 @@ error:
     are not valid, so checking is not possible
 
 Run the build without `--check`, and then try with `--check` again.
-
-# Automatic and Optionally Enforced Determinism Verification
-
-Automatically verify every build at build time by executing the build
-multiple times.
-
-Setting `repeat` and `enforce-determinism` in your `nix.conf` permits
-the automated verification of every build Nix performs.
-
-The following configuration will run each build three times, and will
-require the build to be deterministic:
-
-    enforce-determinism = true
-    repeat = 2
-
-Setting `enforce-determinism` to false as in the following
-configuration will run the build multiple times, execute the build
-hook, but will allow the build to succeed even if it does not build
-reproducibly:
-
-    enforce-determinism = false
-    repeat = 1
-
-An example output of this configuration:
-
-```console
-$ nix-build ./test.nix -A unstable
-this derivation will be built:
-  /nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv
-building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 1/2)...
-building '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' (round 2/2)...
-output '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable' of '/nix/store/ch6llwpr2h8c3jmnf3f2ghkhx59aa97f-unstable.drv' differs from '/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable.check' from previous round
-/nix/store/6xg356v9gl03hpbbg8gws77n19qanh02-unstable
-```
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index 1251888e9..9102aff2d 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -104,10 +104,6 @@ The following flags are available:
     previous build, the new output path is left in
     `/nix/store/name.check.`
 
-    See also the `build-repeat` configuration option, which repeats a
-    derivation a number of times and prevents its outputs from being
-    registered as “valid” in the Nix store unless they are identical.
-
 Special exit codes:
 
   - `100`\
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index bf51aa1f7..faead26c2 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -46,3 +46,6 @@
 
 * `nix build --json` now prints some statistics about top-level
   derivations, such as CPU statistics when cgroups are enabled.
+
+* The `repeat` and `enforce-determinism` options have been removed
+  since they had been broken under many circumstances for a long time.
-- 
cgit v1.2.3


From c710aa1abd51231ce45fc419de2e0e82c8957fbd Mon Sep 17 00:00:00 2001
From: endgame <endgame@users.noreply.github.com>
Date: Wed, 7 Dec 2022 22:55:02 +1000
Subject: Post build hook signing (#7408)

* docs: Use secret-key-files when demonstrating post-build-hooks

The docs used to recommend calling `nix store sign` in a post-build
hook, but on more recent versions of nix, this results in unsigned
store paths being copied into binary caches. See
https://github.com/NixOS/nix/issues/6960 for details.

Instead, use the `secret-key-files` config option, which signs all
locally-built derivations with the private key.

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/advanced-topics/post-build-hook.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/advanced-topics/post-build-hook.md b/doc/manual/src/advanced-topics/post-build-hook.md
index fcb52d878..1479cc3a4 100644
--- a/doc/manual/src/advanced-topics/post-build-hook.md
+++ b/doc/manual/src/advanced-topics/post-build-hook.md
@@ -33,12 +33,17 @@ distribute the public key for verifying the authenticity of the paths.
 example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
 ```
 
-Then, add the public key and the cache URL to your `nix.conf`'s
-`trusted-public-keys` and `substituters` options:
+Then update [`nix.conf`](../command-ref/conf-file.md) on any machine that will access the cache.
+Add the cache URL to [`substituters`](../command-ref/conf-file.md#conf-substituters) and the public key to [`trusted-public-keys`](../command-ref/conf-file.md#conf-trusted-public-keys):
 
     substituters = https://cache.nixos.org/ s3://example-nix-cache
     trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= example-nix-cache-1:1/cKDz3QCCOmwcztD2eV6Coggp6rqc9DGjWv7C0G+rM=
 
+Machines that build for the cache must sign derivations using the private key.
+On those machines, add the path to the key file to the [`secret-key-files`](../command-ref/conf-file.md#conf-secret-key-files) field in their [`nix.conf`](../command-ref/conf-file.md):
+
+    secret-key-files = /etc/nix/key.private
+
 We will restart the Nix daemon in a later step.
 
 # Implementing the build hook
@@ -52,14 +57,12 @@ set -eu
 set -f # disable globbing
 export IFS=' '
 
-echo "Signing paths" $OUT_PATHS
-nix store sign --key-file /etc/nix/key.private $OUT_PATHS
 echo "Uploading paths" $OUT_PATHS
-exec nix copy --to 's3://example-nix-cache' $OUT_PATHS
+exec nix copy --to "s3://example-nix-cache" $OUT_PATHS
 ```
 
 > **Note**
-> 
+>
 > The `$OUT_PATHS` variable is a space-separated list of Nix store
 > paths. In this case, we expect and want the shell to perform word
 > splitting to make each output path its own argument to `nix
-- 
cgit v1.2.3


From 703d863a48f549b2626382eda407ffae779f8725 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 7 Dec 2022 12:58:58 +0100
Subject: Trivial changes from the lazy-trees branch

---
 doc/manual/src/command-ref/env-common.md | 39 ++++----------------------------
 1 file changed, 4 insertions(+), 35 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 3f3eb6915..6947dbf4c 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -8,41 +8,10 @@ Most Nix commands interpret the following environment variables:
 
   - [`NIX_PATH`]{#env-NIX_PATH}\
     A colon-separated list of directories used to look up Nix
-    expressions enclosed in angle brackets (i.e., `<path>`). For
-    instance, the value
-
-        /home/eelco/Dev:/etc/nixos
-
-    will cause Nix to look for paths relative to `/home/eelco/Dev` and
-    `/etc/nixos`, in this order. It is also possible to match paths
-    against a prefix. For example, the value
-
-        nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos
-
-    will cause Nix to search for `<nixpkgs/path>` in
-    `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`.
-
-    If a path in the Nix search path starts with `http://` or
-    `https://`, it is interpreted as the URL of a tarball that will be
-    downloaded and unpacked to a temporary location. The tarball must
-    consist of a single top-level directory. For example, setting
-    `NIX_PATH` to
-
-        nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz
-
-    tells Nix to download and use the current contents of the
-    `master` branch in the `nixpkgs` repository.
-
-    The URLs of the tarballs from the official nixos.org channels (see
-    [the manual for `nix-channel`](nix-channel.md)) can be abbreviated
-    as `channel:<channel-name>`.  For instance, the following two
-    values of `NIX_PATH` are equivalent:
-
-        nixpkgs=channel:nixos-21.05
-        nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz
-
-    The Nix search path can also be extended using the `-I` option to
-    many Nix commands, which takes precedence over `NIX_PATH`.
+    expressions enclosed in angle brackets (i.e., `<path>`),
+     e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
+    `-I` option. For more information about the semantics of the Nix
+    search path, see the documentation for `-I`.
 
   - [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
     Normally, the Nix store directory (typically `/nix/store`) is not
-- 
cgit v1.2.3


From b8a1ff98c1019f36a6425f639bf4c694f42c7edf Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 7 Dec 2022 16:12:26 +0100
Subject: use HTML anchors for config parameters

this avoids incorrect rendering on the man pages, since `lowdown`
neither parses the anchor syntax nor HTML.

this should rather be fixed in lowdown, as adding more anchors
would otherwise produce ever more noise and error-prone repetition.
---
 doc/manual/src/command-ref/nix-build.md | 12 +++++++-----
 doc/manual/src/command-ref/nix-store.md |  3 ++-
 2 files changed, 9 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index 49c6f3f55..3a47feaae 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -53,16 +53,18 @@ All options not listed here are passed to `nix-store
 --realise`, except for `--arg` and `--attr` / `-A` which are passed to
 `nix-instantiate`.
 
-  - [`--no-out-link`]{#opt-no-out-link}\
+  - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
+
     Do not create a symlink to the output path. Note that as a result
     the output does not become a root of the garbage collector, and so
-    might be deleted by `nix-store
-                    --gc`.
+    might be deleted by `nix-store --gc`.
+
+  - <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
 
-  - [`--dry-run`]{#opt-dry-run}\
     Show what store paths would be built or downloaded.
 
-  - [`--out-link`]{#opt-out-link} / `-o` *outlink*\
+  - <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink*
+
     Change the name of the symlink to the output path created from
     `result` to *outlink*.
 
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index 1251888e9..ec1da72a4 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -22,7 +22,8 @@ This section lists the options that are common to all operations. These
 options are allowed for every subcommand, though they may not always
 have an effect.
 
-  - [`--add-root`]{#opt-add-root} *path*\
+  - <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
+
     Causes the result of a realisation (`--realise` and
     `--force-realise`) to be registered as a root of the garbage
     collector. *path* will be created as a symlink to the resulting
-- 
cgit v1.2.3


From 037d5c4299354508cd33c0c5e5c382d7dd2431e4 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 12 Dec 2022 12:43:44 +0100
Subject: Manual improvements

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/command-ref/env-common.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 6947dbf4c..34a3179a8 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -7,7 +7,7 @@ Most Nix commands interpret the following environment variables:
     `nix-shell`. It can have the values `pure` or `impure`.
 
   - [`NIX_PATH`]{#env-NIX_PATH}\
-    A colon-separated list of directories used to look up Nix
+    A colon-separated list of directories used to look up the location of Nix
     expressions enclosed in angle brackets (i.e., `<path>`),
      e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
     `-I` option. For more information about the semantics of the Nix
-- 
cgit v1.2.3


From add417ec147c50b12231741684ccc08a95024744 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 12 Dec 2022 12:46:54 +0100
Subject: Fix indentation

---
 doc/manual/src/command-ref/env-common.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index 34a3179a8..be5797252 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -9,7 +9,7 @@ Most Nix commands interpret the following environment variables:
   - [`NIX_PATH`]{#env-NIX_PATH}\
     A colon-separated list of directories used to look up the location of Nix
     expressions enclosed in angle brackets (i.e., `<path>`),
-     e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
+    e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
     `-I` option. For more information about the semantics of the Nix
     search path, see the documentation for `-I`.
 
-- 
cgit v1.2.3


From c66c904a057fa66c5d5c0d9fdf79196efb28f4b6 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 12 Dec 2022 12:54:15 +0100
Subject: Tweak NIX_PATH description

---
 doc/manual/src/command-ref/env-common.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
index be5797252..5845bdc43 100644
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@@ -8,10 +8,10 @@ Most Nix commands interpret the following environment variables:
 
   - [`NIX_PATH`]{#env-NIX_PATH}\
     A colon-separated list of directories used to look up the location of Nix
-    expressions enclosed in angle brackets (i.e., `<path>`),
+    expressions using [paths](../language/values.md#type-path)
+    enclosed in angle brackets (i.e., `<path>`),
     e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
-    `-I` option. For more information about the semantics of the Nix
-    search path, see the documentation for `-I`.
+    [`-I` option](./opt-common#opt-I).
 
   - [`NIX_IGNORE_SYMLINK_STORE`]{#env-NIX_IGNORE_SYMLINK_STORE}\
     Normally, the Nix store directory (typically `/nix/store`) is not
-- 
cgit v1.2.3


From fd0ed7511818ba871dc3e28796ec1d0ca57b22ec Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 7 Dec 2022 15:23:01 +0100
Subject: Support flake references in the old CLI

Fixes #7026.
---
 doc/manual/src/release-notes/rl-next.md | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index c1f4de76f..160537f41 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -2,3 +2,12 @@
 
 * The `repeat` and `enforce-determinism` options have been removed
   since they had been broken under many circumstances for a long time.
+
+* You can now use flake references in the old CLI, e.g.
+
+  ```
+  # nix-build flake:nixpkgs -A hello
+  # nix-build -I nixpkgs=flake:github:NixOS/nixpkgs/nixos-22.05 \
+      '<nixpkgs>' -A hello
+  # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello
+  ```
-- 
cgit v1.2.3


From fa409131cd74b3eb1bd37230e74f9a9314b34066 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Wed, 7 Dec 2022 17:13:16 +0100
Subject: Add links to the manual

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/release-notes/rl-next.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 160537f41..f9a0063ee 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -3,7 +3,10 @@
 * The `repeat` and `enforce-determinism` options have been removed
   since they had been broken under many circumstances for a long time.
 
-* You can now use flake references in the old CLI, e.g.
+* You can now use [flake references] in the [old command line interface], e.g.
+
+   [flake references]: ../command-ref/new-cli/nix3-flake.md#flake-references
+   [old command line interface]: ../command-ref/main-commands.md
 
   ```
   # nix-build flake:nixpkgs -A hello
-- 
cgit v1.2.3


From 4ed8bb1cb132a6671a51e96abbd8241fbe01d6ef Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 12 Dec 2022 14:29:02 +0100
Subject: suggestions from review

---
 doc/manual/src/architecture/architecture.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 4b0704894..3a7d1d6f5 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -15,14 +15,14 @@ Nix consists of [hierarchical layers].
 |                 | commmand line interface |------.            |
 |                 '-------------------------'      |            |
 |                              |                   |            |
-|                          evaluates               |            |
+|                            calls                 |            |
 |                              |                manages         |
 |                              V                   |            |
 |                 .-------------------------.      |            |
-|                 | configuration language  |      |            |
+|                 |    language evaluator   |      |            |
 |                 '-------------------------'      |            |
 |                              |                   |            |
-|                         evaluates to             |            |
+|                           produces               |            |
 |                              |                   V            |
 | +----------------------------|------------------------------+ |
 | | store                      |                              | |
@@ -36,7 +36,7 @@ Nix consists of [hierarchical layers].
 
 At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
 
-Below that is the [Nix language](../language/index.md), the configuration language for Nix.
+Below that is the evaluator for the [Nix language](../language/index.md), the configuration language for Nix.
 Its expressions ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
 
 The command line interface and the Nix language are what users interact with most.
-- 
cgit v1.2.3


From c7cce3e4e1dc82c504bb4d717e55dce3b1ae008a Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Mon, 12 Dec 2022 16:29:29 -0500
Subject: Improve release notes

---
 doc/manual/src/release-notes/rl-next.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index a56dc25a2..15c309bdb 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -3,4 +3,13 @@
 * The `repeat` and `enforce-determinism` options have been removed
   since they had been broken under many circumstances for a long time.
 
-* Allow explicitly selecting outputs with *store derivations* installable syntax too.
\ No newline at end of file
+* Allow explicitly selecting outputs in a store derivation installable, just like we can do with other sorts of installables.
+  For example,
+  ```shell-session
+  $ nix-build /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^dev`
+  ```
+  now works just as
+  ```shell-session
+  $ nix-build glibc^dev`
+  ```
+  does already.
-- 
cgit v1.2.3


From 129ece7ce9b88fb79d3f68d030df4e06c4e291cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Na=C3=AFm=20Favier?= <n@monade.li>
Date: Tue, 13 Dec 2022 15:49:40 +0100
Subject: doc: fix links

---
 doc/manual/src/release-notes/rl-2.12.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-2.12.md b/doc/manual/src/release-notes/rl-2.12.md
index 82de22cb4..e2045d7bf 100644
--- a/doc/manual/src/release-notes/rl-2.12.md
+++ b/doc/manual/src/release-notes/rl-2.12.md
@@ -17,12 +17,12 @@
   The `uid-range` [system feature] requires the [`auto-allocate-uids`]
   setting to be enabled.
 
-  [system feature]: (../command-ref/conf-file.md#conf-system-features)
+  [system feature]: ../command-ref/conf-file.md#conf-system-features
 
 * Nix can now automatically pick UIDs for builds, removing the need to
   create `nixbld*` user accounts. See [`auto-allocate-uids`].
 
-  [`auto-allocate-uids`]: (../command-ref/conf-file.md#conf-auto-allocate-uids)
+  [`auto-allocate-uids`]: ../command-ref/conf-file.md#conf-auto-allocate-uids
 
 * On Linux, Nix has experimental support for running builds inside a
   cgroup. See
-- 
cgit v1.2.3


From c162c90b432590e1dbdeb5f4361bf4b48de82bac Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 20 Dec 2022 09:59:59 +0100
Subject: add more explanation to diagrams

this is to help reading the diagrams, otherwise arrows and labels were
reported as being ambiguous.
---
 doc/manual/src/architecture/architecture.md | 125 +++++++++++++++++-----------
 1 file changed, 78 insertions(+), 47 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 3a7d1d6f5..2d1b26558 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -9,18 +9,29 @@ Nix consists of [hierarchical layers].
 
 [hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
 
+The following [concept map] shows its main components (rectangles), the objects they operate on (rounded rectangles), and their interactions (connecting phrases):
+
+[concept map]: https://en.m.wikipedia.org/wiki/Concept_map
+
 ```
-+---------------------------------------------------------------+
-| Nix             .-------------------------.                   |
-|                 | commmand line interface |------.            |
-|                 '-------------------------'      |            |
-|                              |                   |            |
-|                            calls                 |            |
-|                              |                manages         |
-|                              V                   |            |
-|                 .-------------------------.      |            |
-|                 |    language evaluator   |      |            |
-|                 '-------------------------'      |            |
+
+   .----------------.
+   | Nix expression |----------.
+   '----------------'          |
+           |              passed to
+           |                   |
++----------|-------------------|--------------------------------+
+| Nix      |                   V                                |
+|          |      +-------------------------+                   |
+|          |      | commmand line interface |------.            |
+|          |      +-------------------------+      |            |
+|          |                   |                   |            |
+|    evaluated by            calls              manages         |
+|          |                   |                   |            |
+|          |                   V                   |            |
+|          |         +--------------------+        |            |
+|          '-------->| language evaluator |        |            |
+|                    +--------------------+        |            |
 |                              |                   |            |
 |                           produces               |            |
 |                              |                   V            |
@@ -28,57 +39,77 @@ Nix consists of [hierarchical layers].
 | | store                      |                              | |
 | |            referenced by   V       builds                 | |
 | | .-------------.      .------------.      .--------------. | |
-| | | build input |----->| build plan | ---->| build result | | |
+| | | build input |----->| build plan |----->| build result | | |
 | | '-------------'      '------------'      '--------------' | |
-| +-----------------------------------------------------------+ |
-+---------------------------------------------------------------+
+| +-------------------------------------------------|---------+ |
++---------------------------------------------------|-----------+
+                                                    |
+                                              represented as
+                                                    |
+                                                    V
+                                            .---------------.
+                                            |     file      |
+                                            '---------------'
 ```
 
-At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
+At the top is the [command line interface](../command-ref/command-ref.md) that drives the underlying layers.
 
-Below that is the evaluator for the [Nix language](../language/index.md), the configuration language for Nix.
-Its expressions ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+The [Nix language](../language/index.md) evaluator transforms Nix expressions into self-contained *build plans*, which are used to derive *build results* from referenced *build inputs*.
 
-The command line interface and the Nix language are what users interact with most.
+The command line interface and Nix expressions are what users deal with most.
 
 > **Note**
 > The Nix language itself does not have a notion of *packages* or *configurations*.
 > As far as we are concerned here, the inputs and results of a build plan are just data.
 
-Underlying the command line interface and the Nix language is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
-It can also execute build plans to produce new data.
+Underlying the command line interface and the Nix language evaluator is the [Nix store](../glossary.md#gloss-store), a mechanism to keep track of build plans, data, and references between them.
+It can also execute build plans to produce new data, which are made available to the operating system as files.
 
-A build plan is a series of *build tasks*.
-Each build task has a special build input, which is used as *build instructions*.
-The result of a build task can be input to another build task.
+A build plan itself is a series of *build tasks*, together with their build inputs.
 
 > **Important**
 > A build task in Nix is called [derivation](../glossary#gloss-derivation).
 
+Each build task has a special build input executed as *build instructions* in order to perform the build.
+The result of a build task can be input to another build task.
+
+The following [data flow diagram] shows a build plan for illustration.
+Build inputs used as instructions to a build task are marked accordingly:
+
+[data flow diagram]: https://en.m.wikipedia.org/wiki/Data-flow_diagram
+
 ```
-+----------------------------------------------------------------------------------+
-| store            - - - - - - - - - - -  - - - - - - - - - - -                    |
-|                 : build plan                                 :                   |
-| .-------------. :                                            :                   |
-| | build input |---instructions-.                             :                   |
-| '-------------' :              |                             :                   |
-|                 :              v                             :                   |
-| .-------------. :        .------------.                      :                   |
-| | build input |--------->| build task |-instructions-.       :                   |
-| '-------------' :        '------------'              |       :                   |
-|                 :                                    v       :                   |
-| .-------------. :                             .------------. :  .--------------. |
-| | build input |---instructions-.              | build task |--->| build result | |
-| '-------------' :              |              '------------' :  '--------------' |
-|                 :              v                     ^       :                   |
-| .-------------. :        .------------.              |       :                   |
-| | build input |--------->| build task |--------------'       :                   |
-| '-------------' :        '------------'                      :                   |
-|                 :              ^                             :                   |
-| .-------------. :              |                             :                   |
-| | build input |----------------'                             :                   |
-| '-------------' :                                            :                   |
-|                 :_ _ _ _ _ _ _ _ _ _ _  _ _ _ _ _ _ _ _ _ _ _:                   |
-+----------------------------------------------------------------------------------+
++--------------------------------------------------------------------+
+| build plan                                                         |
+|                                                                    |
+| .-------------.                                                    |
+| | build input |---------.                                          |
+| '-------------'         |                                          |
+|                    instructions                                    |
+|                         |                                          |
+|                         v                                          |
+| .-------------.    .----------.                                    |
+| | build input |-->( build task )-------.                           |
+| '-------------'    '----------'        |                           |
+|                                  instructions                      |
+|                                        |                           |
+|                                        v                           |
+| .-------------.                  .----------.     .--------------. |
+| | build input |---------.       ( build task )--->| build result | |
+| '-------------'         |        '----------'     '--------------' |
+|                    instructions        ^                           |
+|                         |              |                           |
+|                         v              |                           |
+| .-------------.    .----------.        |                           |
+| | build input |-->( build task )-------'                           |
+| '-------------'    '----------'                                    |
+|                         ^                                          |
+|                         |                                          |
+|                         |                                          |
+| .-------------.         |                                          |
+| | build input |---------'                                          |
+| '-------------'                                                    |
+|                                                                    |
++--------------------------------------------------------------------+
 ```
 
-- 
cgit v1.2.3


From 7e31a991db9fbc7881e5f96a10eea0c030bc8f6e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 20 Dec 2022 14:28:43 +0100
Subject: make relative links explicit

---
 doc/manual/src/glossary.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index b13709f8a..aa775b163 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -3,18 +3,18 @@
   - [derivation]{#gloss-derivation}\
     A description of a build task. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
-    using the [`derivation` primitive](language/derivations.md). These are
+    using the [`derivation` primitive](./language/derivations.md). These are
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
   - [content-addressed derivation]{#gloss-content-addressed-derivation}\
     A derivation which has the
-    [`__contentAddressed`](language/advanced-attributes.md#adv-attr-__contentAddressed)
+    [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
     attribute set to `true`.
 
   - [fixed-output derivation]{#gloss-fixed-output-derivation}\
     A derivation which includes the
-    [`outputHash`](language/advanced-attributes.md#adv-attr-outputHash) attribute.
+    [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute.
 
   - [store]{#gloss-store}\
     The location in the file system where store objects live. Typically
@@ -79,7 +79,7 @@
   - [substituter]{#gloss-substituter}\
     A *substituter* is an additional store from which Nix will
     copy store objects it doesn't have.  For details, see the
-    [`substituters` option](command-ref/conf-file.html#conf-substituters).
+    [`substituters` option](./command-ref/conf-file.md#conf-substituters).
 
   - [purity]{#gloss-purity}\
     The assumption that equal Nix derivations when run always produce
@@ -139,7 +139,7 @@
     An automatically generated store object that consists of a set of
     symlinks to “active” applications, i.e., other store paths. These
     are generated automatically by
-    [`nix-env`](command-ref/nix-env.md). See *profiles*.
+    [`nix-env`](./command-ref/nix-env.md). See *profiles*.
 
   - [profile]{#gloss-profile}\
     A symlink to the current *user environment* of a user, e.g.,
@@ -150,7 +150,9 @@
     store. It can contain regular files, directories and symbolic
     links.  NARs are generated and unpacked using `nix-store --dump`
     and `nix-store --restore`.
+
   - [`∅`]{#gloss-emtpy-set}\
     The empty set symbol. In the context of profile history, this denotes a package is not present in a particular version of the profile.
+
   - [`ε`]{#gloss-epsilon}\
     The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute.
-- 
cgit v1.2.3


From 0251d44cc2e991608ea39f2274ad2d197c668468 Mon Sep 17 00:00:00 2001
From: John Ericson <John.Ericson@Obsidian.Systems>
Date: Thu, 15 Dec 2022 20:17:08 -0500
Subject: Make `./mk/run-test.sh` work by itself; add `mk/debug-test.sh`

First, logic is consolidated in the shell script instead of being spread
between them and makefiles. That makes understanding what is going on a
little easier.

This would not be super interesting by itself, but it gives us a way to
debug tests more easily. *That* in turn I hope is much more compelling.
See the updated manual for details.

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
---
 doc/manual/src/contributing/hacking.md | 75 +++++++++++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 2 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index 9f7d5057b..b75d2554c 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -99,8 +99,79 @@ You can run the whole testsuite with `make check`, or the tests for a specific c
 ### Functional tests
 
 The functional tests reside under the `tests` directory and are listed in `tests/local.mk`.
-The whole testsuite can be run with `make install && make installcheck`.
-Individual tests can be run with `make tests/{testName}.sh.test`.
+Each test is a bash script.
+
+The whole testsuite can be run with:
+
+```shell-session
+$ make install && make installcheck
+ran test tests/foo.sh... [PASS]
+ran test tests/bar.sh... [PASS]
+...
+```
+
+Individual tests can be run with `make`:
+
+```shell-session
+$ make tests/${testName}.sh.test
+ran test tests/${testName}.sh... [PASS]
+```
+
+or without `make`:
+
+```shell-session
+$ ./mk/run-test.sh tests/${testName}.sh
+ran test tests/${testName}.sh... [PASS]
+```
+
+To see the complet eoutput, one can also run:
+
+```shell-session
+$ ./mk/debug-test.sh tests/${testName}.sh
++ foo
+output from foo
++ bar
+output from bar
+...
+```
+
+The test script will be traced with `set -x` and the output displayed as it happens, regardless of whether the test succeeds or fails.
+
+#### Debugging failing functional tests
+
+When a functional test fails, it usually does so somewhere in the middle of the script.
+
+To figure out what's wrong, it is convenient to run the test regularly up to the failing `nix` command, and then run that command with a debugger like GDB.
+
+For example, if the script looks like:
+
+```bash
+foo
+nix blah blub
+bar
+```
+one would could edit it like so:
+
+```diff
+ foo
+-nix blah blub
++gdb --args nix blah blub
+ bar
+```
+
+Then, when one runs the script with `./mk/debug-test.sh`, it will drop them into GDB once the script reaches that point:
+
+```shell-session
+$ ./mk/debug-test.sh tests/${testName}.sh
+...
++ gdb blash blub
+GNU gdb (GDB) 12.1
+...
+(gdb)
+```
+
+One can debug the Nix invocation in all the usual ways.
+(For exampling running `run` will run the Nix invocation.)
 
 ### Integration tests
 
-- 
cgit v1.2.3


From 62f4f883a7f63380be578ebb6167641ec111b59e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 20 Dec 2022 15:11:31 +0100
Subject: define "store derivation"

---
 doc/manual/src/glossary.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index aa775b163..117b43a88 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -7,6 +7,18 @@
     translated into low-level *store derivations* (implicitly by
     `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
 
+    [derivation]: #gloss-derivation
+
+  - [store derivation]{#gloss-store-derivation}\
+    A [derivation] represented as a `.drv` file in the [store].
+    It has a [store path], like any [store object].
+
+    Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
+
+    See [`nix show-derivation`](./command-ref/new-cli/nix3-show-derivation.md) (experimental) for displaying the contents of store derivations.
+
+    [store derivation]: #gloss-store-derivation
+
   - [content-addressed derivation]{#gloss-content-addressed-derivation}\
     A derivation which has the
     [`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
@@ -34,6 +46,8 @@
       directory on another machine,  accessed via `ssh` or
       served by the `nix-serve` Perl script.
 
+    [store]: #gloss-store
+
   - [chroot store]{#gloss-chroot-store}\
     A local store whose canonical path is anything other than `/nix/store`.
 
@@ -49,6 +63,10 @@
     The location in the file system of a store object, i.e., an
     immediate child of the Nix store directory.
 
+    Example: `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1`
+
+    [store path]: #gloss-store-path
+
   - [store object]{#gloss-store-object}\
     A file that is an immediate child of the Nix store directory. These
     can be regular files, but also entire directory trees. Store objects
@@ -56,6 +74,8 @@
     derivation outputs (objects produced by running a build task), or
     derivations (files describing a build task).
 
+    [store object]: #gloss-store-object
+
   - [input-addressed store object]{#gloss-input-addressed-store-object}\
     A store object produced by building a
     non-[content-addressed](#gloss-content-addressed-derivation),
-- 
cgit v1.2.3


From 3a66d82e1da1302586055a70903de2f9a7425087 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 20 Dec 2022 15:26:05 +0100
Subject: update description of "store derivation" in installables section

a store derivation is not a store path itself, it has a store path.
---
 doc/manual/src/glossary.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 117b43a88..0fcc2b07b 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -144,7 +144,9 @@
     references `R` then `R` is also in the closure of `P`.
 
   - [output path]{#gloss-output-path}\
-    A store path produced by a derivation.
+    A [store path] produced by a [derivation].
+
+    [output path]: #gloss-output-path
 
   - [deriver]{#gloss-deriver}\
     The deriver of an *output path* is the store
-- 
cgit v1.2.3


From 7797661a70bcd6a7caf756964785ea7727ed1be0 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Tue, 20 Dec 2022 15:37:40 +0100
Subject: link "store derivation" to glossary definition

---
 doc/manual/src/command-ref/nix-build.md        |  4 +++-
 doc/manual/src/command-ref/nix-copy-closure.md |  4 +++-
 doc/manual/src/command-ref/nix-env.md          |  8 +++++---
 doc/manual/src/command-ref/nix-instantiate.md  | 10 +++++-----
 doc/manual/src/command-ref/nix-store.md        | 14 ++++++++------
 5 files changed, 24 insertions(+), 16 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index 3a47feaae..937b046b8 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -37,10 +37,12 @@ directory containing at least a file named `default.nix`.
 
 `nix-build` is essentially a wrapper around
 [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix
-expression to a low-level store derivation) and [`nix-store
+expression to a low-level [store derivation]) and [`nix-store
 --realise`](nix-store.md#operation---realise) (to build the store
 derivation).
 
+[store derivation]: ../glossary.md#gloss-store-derivation
+
 > **Warning**
 >
 > The result of the build is automatically registered as a root of the
diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md
index 9a29030bd..83e8a2936 100644
--- a/doc/manual/src/command-ref/nix-copy-closure.md
+++ b/doc/manual/src/command-ref/nix-copy-closure.md
@@ -47,7 +47,9 @@ authentication, you can avoid typing the passphrase with `ssh-agent`.
     Enable compression of the SSH connection.
 
   - `--include-outputs`\
-    Also copy the outputs of store derivations included in the closure.
+    Also copy the outputs of [store derivation]s included in the closure.
+
+    [store derivation]: ../../glossary.md#gloss-store-derivation
 
   - `--use-substitutes` / `-s`\
     Attempt to download missing paths on the target machine using Nix’s
diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index a5df35d77..f4fa5b50c 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -205,10 +205,12 @@ a number of possible ways:
     unambiguous way, which is necessary if there are multiple
     derivations with the same name.
 
-  - If *args* are store derivations, then these are
+  - If *args* are [store derivation]s, then these are
     [realised](nix-store.md#operation---realise), and the resulting output paths
     are installed.
 
+    [store derivation]: ../glossary.md#gloss-store-derivation
+
   - If *args* are store paths that are not store derivations, then these
     are [realised](nix-store.md#operation---realise) and installed.
 
@@ -280,7 +282,7 @@ To copy the store path with symbolic name `gcc` from another profile:
 $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
 ```
 
-To install a specific store derivation (typically created by
+To install a specific [store derivation] (typically created by
 `nix-instantiate`):
 
 ```console
@@ -665,7 +667,7 @@ derivation is shown unless `--no-name` is specified.
     Print the `system` attribute of the derivation.
 
   - `--drv-path`\
-    Print the path of the store derivation.
+    Print the path of the [store derivation].
 
   - `--out-path`\
     Print the output path of the derivation.
diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md
index 8f143729e..432fb2608 100644
--- a/doc/manual/src/command-ref/nix-instantiate.md
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -17,13 +17,14 @@
 
 # Description
 
-The command `nix-instantiate` generates [store
-derivations](../glossary.md) from (high-level) Nix expressions. It
-evaluates the Nix expressions in each of *files* (which defaults to
+The command `nix-instantiate` produces [store derivation]s from (high-level) Nix expressions.
+It evaluates the Nix expressions in each of *files* (which defaults to
 *./default.nix*). Each top-level expression should evaluate to a
 derivation, a list of derivations, or a set of derivations. The paths
 of the resulting store derivations are printed on standard output.
 
+[store derivation]: ../glossary.md#gloss-store-derivation
+
 If *files* is the character `-`, then a Nix expression will be read from
 standard input.
 
@@ -79,8 +80,7 @@ standard input.
 
 # Examples
 
-Instantiating store derivations from a Nix expression, and building them
-using `nix-store`:
+Instantiate [store derivation]s from a Nix expression, and build them using `nix-store`:
 
 ```console
 $ nix-instantiate test.nix (instantiate)
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index b712a7463..acf29e4aa 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -137,8 +137,10 @@ or.
 
 ## Examples
 
-This operation is typically used to build store derivations produced by
-[`nix-instantiate`](nix-instantiate.md):
+This operation is typically used to build [store derivation]s produced by
+[`nix-instantiate`](./nix-instantiate.md):
+
+[store derivation]: ../glossary.md#gloss-store-derivation
 
 ```console
 $ nix-store -r $(nix-instantiate ./test.nix)
@@ -298,7 +300,7 @@ symlink.
 ## Common query options
 
   - `--use-output`; `-u`\
-    For each argument to the query that is a store derivation, apply the
+    For each argument to the query that is a [store derivation], apply the
     query to the output path of the derivation instead.
 
   - `--force-realise`; `-f`\
@@ -318,7 +320,7 @@ symlink.
     This query has one option:
 
       - `--include-outputs`
-        Also include the existing output paths of store derivations,
+        Also include the existing output paths of [store derivation]s,
         and their closures.
 
     This query can be used to implement various kinds of deployment. A
@@ -372,12 +374,12 @@ symlink.
     Prints the references graph of the store paths *paths* in the
     [GraphML](http://graphml.graphdrawing.org/) file format. This can be
     used to visualise dependency graphs. To obtain a build-time
-    dependency graph, apply this to a store derivation. To obtain a
+    dependency graph, apply this to a [store derivation]. To obtain a
     runtime dependency graph, apply it to an output path.
 
   - `--binding` *name*; `-b` *name*\
     Prints the value of the attribute *name* (i.e., environment
-    variable) of the store derivations *paths*. It is an error for a
+    variable) of the [store derivation]s *paths*. It is an error for a
     derivation to not have the specified attribute.
 
   - `--hash`\
-- 
cgit v1.2.3


From a3a0e414c2d3b06e23b3ad83a2bc90ad09376090 Mon Sep 17 00:00:00 2001
From: Akhil <akhilgodvsdemon@gmail.com>
Date: Fri, 23 Dec 2022 14:06:51 +0530
Subject: Deletes build users and group

---
 doc/manual/src/installation/installing-binary.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index a9378681d..53fdbe31a 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -120,10 +120,10 @@ sudo rm -rf /nix /etc/nix /etc/profile/nix.sh ~root/.nix-profile ~root/.nix-defe
 Remove build users and their group:
 
 ```console
-for i in $(seq 30001 30032); do
-  sudo userdel $i
+for i in $(seq 1 32); do
+  sudo userdel nixbld$i
 done
-sudo groupdel 30000
+sudo groupdel nixbld
 ```
 
 There may also be references to Nix in
-- 
cgit v1.2.3


From c164d304f3cd6c5e536e33435084c030f018c2ab Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Fri, 23 Dec 2022 16:28:26 +0100
Subject: nix develop: Set personality

This makes 'nix develop' set the Linux personality in the same way
that the actual build does, allowing a command like 'nix develop
nix#devShells.i686-linux.default' on x86_64-linux to work correctly.
---
 doc/manual/src/release-notes/rl-next.md | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 6c169bd09..906b048f1 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -25,3 +25,9 @@
   $ nix-build glibc^dev`
   ```
   does already.
+
+* On Linux, `nix develop` now sets the
+  [*personality*](https://man7.org/linux/man-pages/man2/personality.2.html)
+  for the development shell in the same way as the actual build of the
+  derivation. This makes shells for `i686-linux` derivations work
+  correctly on `x86_64-linux`.
-- 
cgit v1.2.3


From efbd1d15c64a10068bdb8aed92b408a05f3b69a8 Mon Sep 17 00:00:00 2001
From: John Ericson <git@JohnEricson.me>
Date: Fri, 23 Dec 2022 08:59:36 -0800
Subject: Apply suggestions from code review

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
---
 doc/manual/src/contributing/hacking.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md
index b75d2554c..c9da1962f 100644
--- a/doc/manual/src/contributing/hacking.md
+++ b/doc/manual/src/contributing/hacking.md
@@ -101,7 +101,7 @@ You can run the whole testsuite with `make check`, or the tests for a specific c
 The functional tests reside under the `tests` directory and are listed in `tests/local.mk`.
 Each test is a bash script.
 
-The whole testsuite can be run with:
+The whole test suite can be run with:
 
 ```shell-session
 $ make install && make installcheck
@@ -124,7 +124,7 @@ $ ./mk/run-test.sh tests/${testName}.sh
 ran test tests/${testName}.sh... [PASS]
 ```
 
-To see the complet eoutput, one can also run:
+To see the complete output, one can also run:
 
 ```shell-session
 $ ./mk/debug-test.sh tests/${testName}.sh
@@ -135,7 +135,7 @@ output from bar
 ...
 ```
 
-The test script will be traced with `set -x` and the output displayed as it happens, regardless of whether the test succeeds or fails.
+The test script will then be traced with `set -x` and the output displayed as it happens, regardless of whether the test succeeds or fails.
 
 #### Debugging failing functional tests
 
@@ -150,7 +150,7 @@ foo
 nix blah blub
 bar
 ```
-one would could edit it like so:
+edit it like so:
 
 ```diff
  foo
@@ -159,7 +159,7 @@ one would could edit it like so:
  bar
 ```
 
-Then, when one runs the script with `./mk/debug-test.sh`, it will drop them into GDB once the script reaches that point:
+Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
 
 ```shell-session
 $ ./mk/debug-test.sh tests/${testName}.sh
@@ -171,7 +171,7 @@ GNU gdb (GDB) 12.1
 ```
 
 One can debug the Nix invocation in all the usual ways.
-(For exampling running `run` will run the Nix invocation.)
+For example, enter `run` to start the Nix invocation.
 
 ### Integration tests
 
-- 
cgit v1.2.3


From e0c4a95611db4fde942b4e3ee4b6f8e07f956248 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 9 Nov 2022 00:31:48 +0100
Subject: antiquotation -> string interpolation

as proposed by @mkaito[1] and @tazjin[2] and discussed with @edolstra
and Nix maintainers

[1]: https://github.com/NixOS/nix.dev/pull/267#issuecomment-1270076332
[2]: https://github.com/NixOS/nix.dev/pull/267#issuecomment-1270201979

Co-authored-by: John Ericson <git@JohnEricson.me>
Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
---
 doc/manual/src/SUMMARY.md.in                    |   1 +
 doc/manual/src/glossary.md                      |  11 ++-
 doc/manual/src/language/string-interpolation.md |  82 +++++++++++++++++++
 doc/manual/src/language/values.md               | 103 +++++++++---------------
 doc/manual/src/release-notes/rl-next.md         |  17 +---
 5 files changed, 134 insertions(+), 80 deletions(-)
 create mode 100644 doc/manual/src/language/string-interpolation.md

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 6a514fa2c..24dbb739f 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -29,6 +29,7 @@
 - [Nix Language](language/index.md)
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)
+    - [String interpolation](language/string-interpolation.md)
   - [Operators](language/operators.md)
   - [Derivations](language/derivations.md)
     - [Advanced Attributes](language/advanced-attributes.md)
diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md
index 0fcc2b07b..e63f6becc 100644
--- a/doc/manual/src/glossary.md
+++ b/doc/manual/src/glossary.md
@@ -60,7 +60,7 @@
     cache](https://cache.nixos.org).
 
   - [store path]{#gloss-store-path}\
-    The location in the file system of a store object, i.e., an
+    The location of a [store object] in the file system, i.e., an
     immediate child of the Nix store directory.
 
     Example: `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1`
@@ -178,3 +178,12 @@
 
   - [`ε`]{#gloss-epsilon}\
     The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute.
+
+  - [string interpolation]{#gloss-string-interpolation}\
+    Expanding expressions enclosed in `${ }` within a [string], [path], or [attribute name].
+
+    See [String interpolation](./language/string-interpolation.md) for details.
+
+    [string]: ./language/values.md#type-string
+    [path]: ./language/values.md#type-path
+    [attribute name]: ./language/values.md#attribute-set
diff --git a/doc/manual/src/language/string-interpolation.md b/doc/manual/src/language/string-interpolation.md
new file mode 100644
index 000000000..ddc6b8230
--- /dev/null
+++ b/doc/manual/src/language/string-interpolation.md
@@ -0,0 +1,82 @@
+# String interpolation
+
+String interpolation is a language feature where a [string], [path], or [attribute name] can contain expressions enclosed in `${ }` (dollar-sign with curly brackets).
+
+Such a string is an *interpolated string*, and an expression inside is an *interpolated expression*.
+
+Interpolated expressions must evaluate to one of the following:
+
+- a [string]
+- a [path]
+- a [derivation]
+
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[attribute name]: ./values.md#attribute-set
+[derivation]: ../glossary.md#gloss-derivation
+
+## Examples
+
+### String
+
+Rather than writing
+
+```nix
+"--with-freetype2-library=" + freetype + "/lib"
+```
+
+(where `freetype` is a [derivation]), you can instead write
+
+```nix
+"--with-freetype2-library=${freetype}/lib"
+```
+
+The latter is automatically translated to the former.
+
+A more complicated example (from the Nix expression for [Qt](http://www.trolltech.com/products/qt)):
+
+```nix
+configureFlags = "
+  -system-zlib -system-libpng -system-libjpeg
+  ${if openglSupport then "-dlopen-opengl
+    -L${mesa}/lib -I${mesa}/include
+    -L${libXmu}/lib -I${libXmu}/include" else ""}
+  ${if threadSupport then "-thread" else "-no-thread"}
+";
+```
+
+Note that Nix expressions and strings can be arbitrarily nested;
+in this case the outer string contains various interpolated expressions that themselves contain strings (e.g., `"-thread"`), some of which in turn contain interpolated expressions (e.g., `${mesa}`).
+
+### Path
+
+Rather than writing
+
+```nix
+./. + "/" + foo + "-" + bar + ".nix"
+```
+
+or
+
+```nix
+./. + "/${foo}-${bar}.nix"
+```
+
+you can instead write
+
+```nix
+./${foo}-${bar}.nix
+```
+
+### Attribute name
+
+Attribute names can be created dynamically with string interpolation:
+
+```nix
+let name = "foo"; in
+{
+  ${name} = "bar";
+}
+```
+
+    { foo = "bar"; }
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index 6fc8c0369..08baa8f95 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -13,41 +13,9 @@
   returns and tabs can be written as `\n`, `\r` and `\t`,
   respectively.
 
-  You can include the result of an expression into a string by
-  enclosing it in `${...}`, a feature known as *antiquotation*. The
-  enclosed expression must evaluate to something that can be coerced
-  into a string (meaning that it must be a string, a path, or a
-  derivation). For instance, rather than writing
+  You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation].
 
-  ```nix
-  "--with-freetype2-library=" + freetype + "/lib"
-  ```
-
-  (where `freetype` is a derivation), you can instead write the more
-  natural
-
-  ```nix
-  "--with-freetype2-library=${freetype}/lib"
-  ```
-
-  The latter is automatically translated to the former. A more
-  complicated example (from the Nix expression for
-  [Qt](http://www.trolltech.com/products/qt)):
-
-  ```nix
-  configureFlags = "
-    -system-zlib -system-libpng -system-libjpeg
-    ${if openglSupport then "-dlopen-opengl
-      -L${mesa}/lib -I${mesa}/include
-      -L${libXmu}/lib -I${libXmu}/include" else ""}
-    ${if threadSupport then "-thread" else "-no-thread"}
-  ";
-  ```
-
-  Note that Nix expressions and strings can be arbitrarily nested; in
-  this case the outer string contains various antiquotations that
-  themselves contain strings (e.g., `"-thread"`), some of which in
-  turn contain expressions (e.g., `${mesa}`).
+  [string interpolation]: ./string-interpolation.md
 
   The second way to write string literals is as an *indented string*,
   which is enclosed between pairs of *double single-quotes*, like so:
@@ -75,7 +43,7 @@
   Note that the whitespace and newline following the opening `''` is
   ignored if there is no non-whitespace text on the initial line.
 
-  Antiquotation (`${expr}`) is supported in indented strings.
+  Indented strings support [string interpolation].
 
   Since `${` and `''` have special meaning in indented strings, you
   need a way to quote them. `$` can be escaped by prefixing it with
@@ -143,26 +111,23 @@
   environment variable `NIX_PATH` will be searched for the given file
   or directory name.
 
-  Antiquotation is supported in any paths except those in angle brackets.
-  `./${foo}-${bar}.nix` is a more convenient way of writing
-  `./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
-  least one slash must appear *before* any antiquotations for this to be
-  recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
-  operation. `./a.${foo}/b.${bar}` is a path.
-
-  When a path appears in an antiquotation, and is thus coerced into a string,
-  the path is first copied into the Nix store and the resulting string is
-  the Nix store path. For instance `"${./foo.txt}" will cause `foo.txt` in
-  the current directory to be copied into the Nix store and result in the
-  string `"/nix/store/<HASH>-foo.txt"`.
-
-  Note that the Nix language assumes that all input files will remain
-  _unchanged_ during the course of the Nix expression evaluation.
-  If you for example antiquote a file path during a `nix repl` session, and
-  then later in the same session, after having changed the file contents,
-  evaluate the antiquotation with the file path again, then Nix will still
-  return the first store path. It will _not_ reread the file contents to
-  produce a different Nix store path.
+  When an [interpolated string][string interpolation] evaluates to a path, the path is first copied into the Nix store and the resulting string is the [store path] of the newly created [store object].
+
+  [store path]: ../glossary.md#gloss-store-path
+  [store object]: ../glossary.md#gloss-store-object
+
+  For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/<hash>-foo.txt"`.
+
+  Note that the Nix language assumes that all input files will remain _unchanged_ while  evaluating a Nix expression.
+  For example, assume you used a file path in an interpolated string during a `nix repl` session.
+  Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new store path, since Nix might not re-read the file contents.
+
+  Paths themselves, except those in angle brackets (`< >`), support [string interpolation].
+
+  At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.
+
+  `a.${foo}/b.${bar}` is a syntactically valid division operation.
+  `./a.${foo}/b.${bar}` is a path.
 
 - <a id="type-boolean" href="#type-boolean">Boolean</a>
 
@@ -235,23 +200,33 @@ will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
 You can use arbitrary double-quoted strings as attribute names:
 
 ```nix
-{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}"
+{ "$!@#?" = 123; }."$!@#?"
+```
+
+```nix
+let bar = "bar";
+{ "foo ${bar}" = 123; }."foo ${bar}"
 ```
 
-This will evaluate to `123` (Assuming `bar` is antiquotable). In the
-case where an attribute name is just a single antiquotation, the quotes
-can be dropped:
+Both will evaluate to `123`.
+
+Attribute names support [string interpolation]:
+
+```nix
+let bar = "foo"; in
+{ foo = 123; }.${bar}
+```
 
 ```nix
-{ foo = 123; }.${bar} or 456
+let bar = "foo"; in
+{ ${bar} = 123; }.foo
 ```
 
-This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced
-to a string and `456` otherwise (again assuming `bar` is antiquotable).
+Both will evaluate to `123`.
 
 In the special case where an attribute name inside of a set declaration
-evaluates to `null` (which is normally an error, as `null` is not
-antiquotable), that attribute is simply not added to the set:
+evaluates to `null` (which is normally an error, as `null` cannot be coerced to
+a string), that attribute is simply not added to the set:
 
 ```nix
 { ${if foo then "bar" else null} = true; }
diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md
index 906b048f1..8119b7c31 100644
--- a/doc/manual/src/release-notes/rl-next.md
+++ b/doc/manual/src/release-notes/rl-next.md
@@ -15,19 +15,6 @@
   # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello
   ```
 
-* Allow explicitly selecting outputs in a store derivation installable, just like we can do with other sorts of installables.
-  For example,
-  ```shell-session
-  $ nix-build /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^dev`
-  ```
-  now works just as
-  ```shell-session
-  $ nix-build glibc^dev`
-  ```
-  does already.
+* Instead of "antiquotation", the more common term [string interpolation](../language/string-interpolation.md) is now used consistently.
+  Historical release notes were not changed.
 
-* On Linux, `nix develop` now sets the
-  [*personality*](https://man7.org/linux/man-pages/man2/personality.2.html)
-  for the development shell in the same way as the actual build of the
-  derivation. This makes shells for `i686-linux` derivations work
-  correctly on `x86_64-linux`.
-- 
cgit v1.2.3


From caebe4112eb491d0168cf423174bccba918330f6 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 22 Dec 2022 21:18:05 +0100
Subject: reorder columns

this is for a simpler transformation into a series of subsections
---
 doc/manual/src/language/operators.md | 46 ++++++++++++++++++------------------
 1 file changed, 23 insertions(+), 23 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index 32398189d..e06e73b2d 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -3,26 +3,26 @@
 The table below lists the operators in the Nix language, in
 order of precedence (from strongest to weakest binding).
 
-| Name                     | Syntax                              | Associativity | Description                                                                                                                                                                                                                   | Precedence |
-| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Select                   | *e* `.` *attrpath* \[ `or` *def* \] | none          | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | 1          |
-| Application              | *e1* *e2*                           | left          | Call function *e1* with argument *e2*.                                                                                                                                                                                        | 2          |
-| Arithmetic Negation      | `-` *e*                             | none          | Arithmetic negation.                                                                                                                                                                                                          | 3          |
-| Has Attribute            | *e* `?` *attrpath*                  | none          | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.                                                                                                                                  | 4          |
-| List Concatenation       | *e1* `++` *e2*                      | right         | List concatenation.                                                                                                                                                                                                           | 5          |
-| Multiplication           | *e1* `*` *e2*,                      | left          | Arithmetic multiplication.                                                                                                                                                                                                    | 6          |
-| Division                 | *e1* `/` *e2*                       | left          | Arithmetic division.                                                                                                                                                                                                          | 6          |
-| Addition                 | *e1* `+` *e2*                       | left          | Arithmetic addition.                                                                                                                                                                                                          | 7          |
-| Subtraction              | *e1* `-` *e2*                       | left          | Arithmetic subtraction.                                                                                                                                                                                                       | 7          |
-| String Concatenation     | *string1* `+` *string2*             | left          | String concatenation.                                                                                                                                                                                                         | 7          |
-| Not                      | `!` *e*                             | none          | Boolean negation.                                                                                                                                                                                                             | 8          |
-| Update                   | *e1* `//` *e2*                      | right         | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).                                                                           | 9          |
-| Less Than                | *e1* `<` *e2*,                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Less Than or Equal To    | *e1* `<=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Greater Than             | *e1* `>` *e2*                       | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Greater Than or Equal To | *e1* `>=` *e2*                      | none          | Arithmetic/lexicographic comparison.                                                                                                                                                                                                        | 10         |
-| Equality                 | *e1* `==` *e2*                      | none          | Equality.                                                                                                                                                                                                                     | 11         |
-| Inequality               | *e1* `!=` *e2*                      | none          | Inequality.                                                                                                                                                                                                                   | 11         |
-| Logical AND              | *e1* `&&` *e2*                      | left          | Logical AND.                                                                                                                                                                                                                  | 12         |
-| Logical OR               | *e1* <code>&#124;&#124;</code> *e2* | left          | Logical OR.                                                                                                                                                                                                                   | 13         |
-| Logical Implication      | *e1* `->` *e2*                      | none          | Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).                                                                                                                                                                            | 14         |
+| Name                     | Syntax                              | Description                                                                                                                                                                                                                   | Associativity | Precedence |
+| ------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------- |
+| Select                   | *e* `.` *attrpath* \[ `or` *def* \] | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | none          | 1          |
+| Application              | *e1* *e2*                           | Call function *e1* with argument *e2*.                                                                                                                                                                                        | left          | 2          |
+| Arithmetic Negation      | `-` *e*                             | Arithmetic negation.                                                                                                                                                                                                          | none          | 3          |
+| Has Attribute            | *e* `?` *attrpath*                  | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.                                                                                                                                  | none          | 4          |
+| List Concatenation       | *e1* `++` *e2*                      | List concatenation.                                                                                                                                                                                                           | right         | 5          |
+| Multiplication           | *e1* `*` *e2*,                      | Arithmetic multiplication.                                                                                                                                                                                                    | left          | 6          |
+| Division                 | *e1* `/` *e2*                       | Arithmetic division.                                                                                                                                                                                                          | left          | 6          |
+| Addition                 | *e1* `+` *e2*                       | Arithmetic addition.                                                                                                                                                                                                          | left          | 7          |
+| Subtraction              | *e1* `-` *e2*                       | Arithmetic subtraction.                                                                                                                                                                                                       | left          | 7          |
+| String Concatenation     | *string1* `+` *string2*             | String concatenation.                                                                                                                                                                                                         | left          | 7          |
+| Not                      | `!` *e*                             | Boolean negation.                                                                                                                                                                                                             | none          | 8          |
+| Update                   | *e1* `//` *e2*                      | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).                                                                           | right         | 9          |
+| Less Than                | *e1* `<` *e2*,                      | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
+| Less Than or Equal To    | *e1* `<=` *e2*                      | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
+| Greater Than             | *e1* `>` *e2*                       | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
+| Greater Than or Equal To | *e1* `>=` *e2*                      | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
+| Equality                 | *e1* `==` *e2*                      | Equality.                                                                                                                                                                                                                     | none          | 11         |
+| Inequality               | *e1* `!=` *e2*                      | Inequality.                                                                                                                                                                                                                   | none          | 11         |
+| Logical AND              | *e1* `&&` *e2*                      | Logical AND.                                                                                                                                                                                                                  | left          | 12         |
+| Logical OR               | *e1* <code>&#124;&#124;</code> *e2* | Logical OR.                                                                                                                                                                                                                   | left          | 13         |
+| Logical Implication      | *e1* `->` *e2*                      | Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).                                                                                                                                                         | none          | 14         |
-- 
cgit v1.2.3


From e07448ba6bdbbe9fb33fa0b652fef06635f1fc6d Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 22 Dec 2022 21:21:26 +0100
Subject: convert table to subsections

this form is much easier to maintain (also with minimal diffs), and
allows for more details on each operator.

this change a purely mechanical transformation, without changing any contents.
---
 doc/manual/src/language/operators.md | 236 +++++++++++++++++++++++++++++++----
 1 file changed, 210 insertions(+), 26 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index e06e73b2d..aeb77b72a 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -1,28 +1,212 @@
 # Operators
 
-The table below lists the operators in the Nix language, in
-order of precedence (from strongest to weakest binding).
-
-| Name                     | Syntax                              | Description                                                                                                                                                                                                                   | Associativity | Precedence |
-| ------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------- |
-| Select                   | *e* `.` *attrpath* \[ `or` *def* \] | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | none          | 1          |
-| Application              | *e1* *e2*                           | Call function *e1* with argument *e2*.                                                                                                                                                                                        | left          | 2          |
-| Arithmetic Negation      | `-` *e*                             | Arithmetic negation.                                                                                                                                                                                                          | none          | 3          |
-| Has Attribute            | *e* `?` *attrpath*                  | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.                                                                                                                                  | none          | 4          |
-| List Concatenation       | *e1* `++` *e2*                      | List concatenation.                                                                                                                                                                                                           | right         | 5          |
-| Multiplication           | *e1* `*` *e2*,                      | Arithmetic multiplication.                                                                                                                                                                                                    | left          | 6          |
-| Division                 | *e1* `/` *e2*                       | Arithmetic division.                                                                                                                                                                                                          | left          | 6          |
-| Addition                 | *e1* `+` *e2*                       | Arithmetic addition.                                                                                                                                                                                                          | left          | 7          |
-| Subtraction              | *e1* `-` *e2*                       | Arithmetic subtraction.                                                                                                                                                                                                       | left          | 7          |
-| String Concatenation     | *string1* `+` *string2*             | String concatenation.                                                                                                                                                                                                         | left          | 7          |
-| Not                      | `!` *e*                             | Boolean negation.                                                                                                                                                                                                             | none          | 8          |
-| Update                   | *e1* `//` *e2*                      | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).                                                                           | right         | 9          |
-| Less Than                | *e1* `<` *e2*,                      | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
-| Less Than or Equal To    | *e1* `<=` *e2*                      | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
-| Greater Than             | *e1* `>` *e2*                       | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
-| Greater Than or Equal To | *e1* `>=` *e2*                      | Arithmetic/lexicographic comparison.                                                                                                                                                                                          | none          | 10         |
-| Equality                 | *e1* `==` *e2*                      | Equality.                                                                                                                                                                                                                     | none          | 11         |
-| Inequality               | *e1* `!=` *e2*                      | Inequality.                                                                                                                                                                                                                   | none          | 11         |
-| Logical AND              | *e1* `&&` *e2*                      | Logical AND.                                                                                                                                                                                                                  | left          | 12         |
-| Logical OR               | *e1* <code>&#124;&#124;</code> *e2* | Logical OR.                                                                                                                                                                                                                   | left          | 13         |
-| Logical Implication      | *e1* `->` *e2*                      | Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).                                                                                                                                                         | none          | 14         |
+## Select
+
+> *e* `.` *attrpath* \[ `or` *def* \]
+
+Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation.
+
+Associativity: none
+
+Precedence: 1
+
+## Application
+
+> *e1* *e2*
+
+Call function *e1* with argument *e2*.
+
+Associativity: left
+
+Precedence: 2
+
+## Arithmetic Negation
+
+> `-` *e*
+
+Arithmetic negation.
+
+Associativity: none
+
+Precedence: 3
+
+## Has Attribute
+
+> *e* `?` *attrpath*
+
+Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.
+
+Associativity: none
+
+Precedence: 4
+
+## List Concatenation
+
+> *e1* `++` *e2*
+
+List concatenation.
+
+Associativity: right
+
+Precedence: 5
+
+## Multiplication
+
+> *e1* `*` *e2*,
+
+Arithmetic multiplication.
+
+Associativity: left
+
+Precedence: 6
+
+## Division
+
+> *e1* `/` *e2*
+
+Arithmetic division.
+
+Associativity: left
+
+Precedence: 6
+
+## Addition
+
+> *e1* `+` *e2*
+
+Arithmetic addition.
+
+Associativity: left
+
+Precedence: 7
+
+## Subtraction
+
+> *e1* `-` *e2*
+
+Arithmetic subtraction.
+
+Associativity: left
+
+Precedence: 7
+
+## String Concatenation
+
+> *string1* `+` *string2*
+
+String concatenation.
+
+Associativity: left
+
+Precedence: 7
+
+## Not
+
+> `!` *e*
+
+Boolean negation.
+
+Associativity: none
+
+Precedence: 8
+
+## Update
+
+> *e1* `//` *e2*
+
+Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).
+
+Associativity: right
+
+Precedence: 9
+
+## Less Than
+
+> *e1* `<` *e2*,
+
+Arithmetic/lexicographic comparison.
+
+Associativity: none
+
+Precedence: 10
+
+## Less Than or Equal To
+
+> *e1* `<=` *e2*
+
+Arithmetic/lexicographic comparison.
+
+Associativity: none
+
+Precedence: 10
+
+## Greater Than
+
+> *e1* `>` *e2*
+
+Arithmetic/lexicographic comparison.
+
+Associativity: none
+
+Precedence: 10
+
+## Greater Than or Equal To
+
+> *e1* `>=` *e2*
+
+Arithmetic/lexicographic comparison.
+
+Associativity: none
+
+Precedence: 10
+
+## Equality
+
+> *e1* `==` *e2*
+
+Equality.
+
+Associativity: none
+
+Precedence: 11
+
+## Inequality
+
+> *e1* `!=` *e2*
+
+Inequality.
+
+Associativity: none
+
+Precedence: 11
+
+## Logical AND
+
+> *e1* `&&` *e2*
+
+Logical AND.
+
+Associativity: left
+
+Precedence: 12
+
+## Logical OR
+
+> *e1* <code>&#124;&#124;</code> *e2*
+
+Logical OR.
+
+Associativity: left
+
+Precedence: 13
+
+## Logical Implication
+
+> *e1* `->` *e2*
+
+Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).
+
+Associativity: none
+
+Precedence: 14
+
-- 
cgit v1.2.3


From 63b640e0c224fb959396f287b0db0c746a06c747 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 22 Dec 2022 22:10:11 +0100
Subject: reword descriptions of operators

add notes on semantics where appropriate
---
 doc/manual/src/language/operators.md | 99 +++++++++++++++++++++---------------
 doc/manual/src/language/values.md    |  2 +
 2 files changed, 61 insertions(+), 40 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index aeb77b72a..e3a00d32b 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -1,36 +1,36 @@
 # Operators
 
-## Select
+## Attribute selection
 
 > *e* `.` *attrpath* \[ `or` *def* \]
 
-Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation.
+Select the attribute denoted by attribute path *attrpath* from attribute set *e*.
+An attribute path is a dot-separated list of attribute names.
+If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation.
 
 Associativity: none
 
 Precedence: 1
 
-## Application
+## Function application
 
-> *e1* *e2*
+> *f* *e*
 
-Call function *e1* with argument *e2*.
+Call function *f* with argument *e*.
 
 Associativity: left
 
 Precedence: 2
 
-## Arithmetic Negation
+## Arithmetic negation
 
 > `-` *e*
 
-Arithmetic negation.
-
 Associativity: none
 
 Precedence: 3
 
-## Has Attribute
+## Has attribute
 
 > *e* `?` *attrpath*
 
@@ -40,11 +40,11 @@ Associativity: none
 
 Precedence: 4
 
-## List Concatenation
+## List concatenation
 
 > *e1* `++` *e2*
 
-List concatenation.
+Concatenate lists *e1* and *e2*.
 
 Associativity: right
 
@@ -54,7 +54,7 @@ Precedence: 5
 
 > *e1* `*` *e2*,
 
-Arithmetic multiplication.
+Multiply numbers *e1* and *e2*.
 
 Associativity: left
 
@@ -64,7 +64,7 @@ Precedence: 6
 
 > *e1* `/` *e2*
 
-Arithmetic division.
+Divide numbers *e1* and *e2*.
 
 Associativity: left
 
@@ -74,7 +74,7 @@ Precedence: 6
 
 > *e1* `+` *e2*
 
-Arithmetic addition.
+Add numbers *e1* and *e2*.
 
 Associativity: left
 
@@ -84,77 +84,90 @@ Precedence: 7
 
 > *e1* `-` *e2*
 
-Arithmetic subtraction.
+Subtract numbers *e2* from *e1*.
 
 Associativity: left
 
 Precedence: 7
 
-## String Concatenation
+## String concatenation
 
 > *string1* `+` *string2*
 
-String concatenation.
+Concatenate *string1* and *string1* and merge their string contexts.
 
 Associativity: left
 
 Precedence: 7
 
-## Not
+## Logical negation (`NOT`)
 
 > `!` *e*
 
-Boolean negation.
+Negate the Boolean value *e*.
 
 Associativity: none
 
 Precedence: 8
 
-## Update
+## Merge attribute sets
 
 > *e1* `//` *e2*
 
-Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes).
+Return a set consisting of all the attributes in *e1* and *e2*.
+If an attribute name is present in both, the attribute value from the former is taken.
 
 Associativity: right
 
 Precedence: 9
 
-## Less Than
+## Less than
 
 > *e1* `<` *e2*,
 
-Arithmetic/lexicographic comparison.
+- Arithmetic comparison for numbers
+- Lexicographic comparison for strings and paths
+- Lexicographic comparison for lists:
+  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
 
 Associativity: none
 
 Precedence: 10
 
-## Less Than or Equal To
+## Less than or equal to
 
 > *e1* `<=` *e2*
 
-Arithmetic/lexicographic comparison.
+- Arithmetic comparison for numbers
+- Lexicographic comparison for strings and paths
+- Lexicographic comparison for lists:
+  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
 
 Associativity: none
 
 Precedence: 10
 
-## Greater Than
+## Greater than
 
 > *e1* `>` *e2*
 
-Arithmetic/lexicographic comparison.
+- Arithmetic comparison for numbers
+- Lexicographic comparison for strings and paths
+- Lexicographic comparison for lists:
+  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
 
 Associativity: none
 
 Precedence: 10
 
-## Greater Than or Equal To
+## Greater than or equal to
 
 > *e1* `>=` *e2*
 
-Arithmetic/lexicographic comparison.
+- Arithmetic comparison for numbers
+- Lexicographic comparison for strings and paths
+- Lexicographic comparison for lists:
+  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
 
 Associativity: none
 
@@ -164,7 +177,12 @@ Precedence: 10
 
 > *e1* `==` *e2*
 
-Equality.
+Check *e1* and *e2* for equality.
+
+- Attribute sets and lists are compared recursively, and therefore are fully evaluated.
+- Comparison of functions always returns `false`.
+- Integers are coerced to floating point numbers if compared to floating point numbers.
+- Floating point numbers only differ up to a limited precision.
 
 Associativity: none
 
@@ -174,39 +192,40 @@ Precedence: 11
 
 > *e1* `!=` *e2*
 
-Inequality.
+Equivalent to `! (`*e1* `==` *e2* `)`
 
 Associativity: none
 
 Precedence: 11
 
-## Logical AND
+## Logical conjunction (`AND`)
 
 > *e1* `&&` *e2*
 
-Logical AND.
+Return `true` if and only if both `e1` and `e2` evaluate to `true`, otherwise `false`.
 
 Associativity: left
 
 Precedence: 12
 
-## Logical OR
+## Logical disjunction (`OR`)
 
-> *e1* <code>&#124;&#124;</code> *e2*
+> *e1* `||` *e2*
 
-Logical OR.
+Return `true` if at least `e1` or `e2` evaluate to `true`, otherwise `false`.
 
 Associativity: left
 
 Precedence: 13
 
-## Logical Implication
+## Logical implication
 
-> *e1* `->` *e2*
+>  *e1* `->` *e2*
 
-Logical implication (equivalent to <code>!e1 &#124;&#124; e2</code>).
+Return `false` if *e1* evaluates to `true` and *e2* evaluates to `false`, otherwise `true`.
+
+Equivalent to `!`*e1* `||` *e2*.
 
 Associativity: none
 
 Precedence: 14
-
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index 08baa8f95..d92f287a3 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -89,6 +89,8 @@
   return integers, whereas any operation involving at least one
   floating point number will have a floating point number as a result.
 
+  Floating point numbers only differ up to a limited precision.
+
 - <a id="type-path" href="#type-path">Path</a>
 
   *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
-- 
cgit v1.2.3


From 969e5ad5bfc6527b8205182e50ba4ec216f218a0 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 22 Dec 2022 22:11:17 +0100
Subject: add semantics of overloaded `+` operator

---
 doc/manual/src/language/operators.md | 50 +++++++++++++++++++++++++++++++-----
 1 file changed, 44 insertions(+), 6 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index e3a00d32b..0c8cc6f57 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -70,21 +70,21 @@ Associativity: left
 
 Precedence: 6
 
-## Addition
+## Subtraction
 
-> *e1* `+` *e2*
+> *e1* `-` *e2*
 
-Add numbers *e1* and *e2*.
+Subtract numbers *e2* from *e1*.
 
 Associativity: left
 
 Precedence: 7
 
-## Subtraction
+## Addition
 
-> *e1* `-` *e2*
+> *e1* `+` *e2*
 
-Subtract numbers *e2* from *e1*.
+Add numbers *e1* and *e2*.
 
 Associativity: left
 
@@ -100,6 +100,44 @@ Associativity: left
 
 Precedence: 7
 
+## Path concatenation
+
+> *path1* `+` *path2*
+
+Concatenate two paths.
+The result is a path.
+
+## Path and string concatenation
+
+> *path* `+` *string*
+
+Concatenate *path* with *string*.
+The result is a path.
+
+> **Note**
+>
+> The string must not have a string context that refers to a store path.
+
+Associativity: left
+
+Precedence: 7
+
+## String and path concatenation
+
+> *string* `+` *path*
+
+Concatenate *string* with *path*.
+The result is a string.
+
+> **Important**
+>
+> The file or directory at *path* must exist and is copied to the store
+> The path appears in the result as the corresponding store path.
+
+Associativity: left
+
+Precedence: 7
+
 ## Logical negation (`NOT`)
 
 > `!` *e*
-- 
cgit v1.2.3


From 7b2b9e3648920077fb53ced4f0b3bec3e0db5729 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 22 Dec 2022 22:25:37 +0100
Subject: use more self-explanatory placeholder names

---
 doc/manual/src/language/operators.md | 105 ++++++++++++++---------------------
 1 file changed, 42 insertions(+), 63 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index 0c8cc6f57..459ea9945 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -2,11 +2,11 @@
 
 ## Attribute selection
 
-> *e* `.` *attrpath* \[ `or` *def* \]
+> *attrset* `.` *attrpath* \[ `or` *value* \]
 
-Select the attribute denoted by attribute path *attrpath* from attribute set *e*.
+Select the attribute denoted by attribute path *attrpath* from attribute set *attrset*.
 An attribute path is a dot-separated list of attribute names.
-If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation.
+If the attribute doesn’t exist, return *value* if provided, otherwise abort evaluation.
 
 Associativity: none
 
@@ -14,9 +14,9 @@ Precedence: 1
 
 ## Function application
 
-> *f* *e*
+> *f* *a*
 
-Call function *f* with argument *e*.
+Call function *f* with argument *a*.
 
 Associativity: left
 
@@ -24,7 +24,9 @@ Precedence: 2
 
 ## Arithmetic negation
 
-> `-` *e*
+> `-` *n*
+
+Flip the sign of the number *n*.
 
 Associativity: none
 
@@ -32,9 +34,9 @@ Precedence: 3
 
 ## Has attribute
 
-> *e* `?` *attrpath*
+> *attrset* `?` *attrpath*
 
-Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`.
+Test whether attribute set *attrset* contains the attribute denoted by *attrpath*; return `true` or `false`.
 
 Associativity: none
 
@@ -42,9 +44,9 @@ Precedence: 4
 
 ## List concatenation
 
-> *e1* `++` *e2*
+> *list1* `++` *list2*
 
-Concatenate lists *e1* and *e2*.
+Concatenate lists *list1* and *list2*.
 
 Associativity: right
 
@@ -52,9 +54,9 @@ Precedence: 5
 
 ## Multiplication
 
-> *e1* `*` *e2*,
+> *n1* `*` *n2*,
 
-Multiply numbers *e1* and *e2*.
+Multiply numbers *n1* and *n2*.
 
 Associativity: left
 
@@ -62,9 +64,9 @@ Precedence: 6
 
 ## Division
 
-> *e1* `/` *e2*
+> *n1* `/` *n2*
 
-Divide numbers *e1* and *e2*.
+Divide numbers *n1* and *n2*.
 
 Associativity: left
 
@@ -72,9 +74,9 @@ Precedence: 6
 
 ## Subtraction
 
-> *e1* `-` *e2*
+> *n1* `-` *n2*
 
-Subtract numbers *e2* from *e1*.
+Subtract numbers *n2* from *n1*.
 
 Associativity: left
 
@@ -82,9 +84,9 @@ Precedence: 7
 
 ## Addition
 
-> *e1* `+` *e2*
+> *n1* `+` *n2*
 
-Add numbers *e1* and *e2*.
+Add numbers *n1* and *n2*.
 
 Associativity: left
 
@@ -140,28 +142,28 @@ Precedence: 7
 
 ## Logical negation (`NOT`)
 
-> `!` *e*
+> `!` *b*
 
-Negate the Boolean value *e*.
+Negate the Boolean value *b*.
 
 Associativity: none
 
 Precedence: 8
 
-## Merge attribute sets
+## Update
+
+> *attrset1* `//` *attrset1*
 
-> *e1* `//` *e2*
+Update attribute set *attrset1* with names and values from *attrset2*.
 
-Return a set consisting of all the attributes in *e1* and *e2*.
+The returned attribute set will have of all the attributes in *e1* and *e2*.
 If an attribute name is present in both, the attribute value from the former is taken.
 
 Associativity: right
 
 Precedence: 9
 
-## Less than
-
-> *e1* `<` *e2*,
+## Comparison
 
 - Arithmetic comparison for numbers
 - Lexicographic comparison for strings and paths
@@ -172,50 +174,27 @@ Associativity: none
 
 Precedence: 10
 
-## Less than or equal to
+### Less than
 
-> *e1* `<=` *e2*
-
-- Arithmetic comparison for numbers
-- Lexicographic comparison for strings and paths
-- Lexicographic comparison for lists:
-  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
+> *e1* `<` *e2*,
 
-Associativity: none
+### Less than or equal to
 
-Precedence: 10
+> *e1* `<=` *e2*
 
-## Greater than
+### Greater than
 
 > *e1* `>` *e2*
 
-- Arithmetic comparison for numbers
-- Lexicographic comparison for strings and paths
-- Lexicographic comparison for lists:
-  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
-
-Associativity: none
-
-Precedence: 10
-
-## Greater than or equal to
+### Greater than or equal to
 
 > *e1* `>=` *e2*
 
-- Arithmetic comparison for numbers
-- Lexicographic comparison for strings and paths
-- Lexicographic comparison for lists:
-  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
-
-Associativity: none
-
-Precedence: 10
-
 ## Equality
 
 > *e1* `==` *e2*
 
-Check *e1* and *e2* for equality.
+Check expressions *e1* and *e2* for value equality.
 
 - Attribute sets and lists are compared recursively, and therefore are fully evaluated.
 - Comparison of functions always returns `false`.
@@ -238,9 +217,9 @@ Precedence: 11
 
 ## Logical conjunction (`AND`)
 
-> *e1* `&&` *e2*
+> *b1* `&&` *b2*
 
-Return `true` if and only if both `e1` and `e2` evaluate to `true`, otherwise `false`.
+Return `true` if and only if both `b1` and `b2` evaluate to `true`, otherwise `false`.
 
 Associativity: left
 
@@ -248,9 +227,9 @@ Precedence: 12
 
 ## Logical disjunction (`OR`)
 
-> *e1* `||` *e2*
+> *b1* `||` *b2*
 
-Return `true` if at least `e1` or `e2` evaluate to `true`, otherwise `false`.
+Return `true` if at least one of  `b1` or `b2` evaluate to `true`, otherwise `false`.
 
 Associativity: left
 
@@ -258,11 +237,11 @@ Precedence: 13
 
 ## Logical implication
 
->  *e1* `->` *e2*
+>  *b1* `->` *b2*
 
-Return `false` if *e1* evaluates to `true` and *e2* evaluates to `false`, otherwise `true`.
+Return `false` if *b1* evaluates to `true` and *b2* evaluates to `false`, otherwise `true`.
 
-Equivalent to `!`*e1* `||` *e2*.
+Equivalent to `!`*b1* `||` *b2*.
 
 Associativity: none
 
-- 
cgit v1.2.3


From 7da59e94ae6d5123acbca7bdbbef4d08b02fc709 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Fri, 23 Dec 2022 08:58:19 +0100
Subject: add links to documentation for data types

---
 doc/manual/src/language/operators.md | 56 +++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 23 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index 459ea9945..1f11e6ac5 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -4,7 +4,7 @@
 
 > *attrset* `.` *attrpath* \[ `or` *value* \]
 
-Select the attribute denoted by attribute path *attrpath* from attribute set *attrset*.
+Select the attribute denoted by attribute path *attrpath* from [attribute set] *attrset*.
 An attribute path is a dot-separated list of attribute names.
 If the attribute doesn’t exist, return *value* if provided, otherwise abort evaluation.
 
@@ -16,7 +16,7 @@ Precedence: 1
 
 > *f* *a*
 
-Call function *f* with argument *a*.
+Call [function] *f* with argument *a*.
 
 Associativity: left
 
@@ -26,7 +26,7 @@ Precedence: 2
 
 > `-` *n*
 
-Flip the sign of the number *n*.
+Flip the sign of the [number] *n*.
 
 Associativity: none
 
@@ -36,7 +36,7 @@ Precedence: 3
 
 > *attrset* `?` *attrpath*
 
-Test whether attribute set *attrset* contains the attribute denoted by *attrpath*; return `true` or `false`.
+Test whether [attribute set] *attrset* contains the attribute denoted by *attrpath*; return `true` or `false`.
 
 Associativity: none
 
@@ -46,7 +46,7 @@ Precedence: 4
 
 > *list1* `++` *list2*
 
-Concatenate lists *list1* and *list2*.
+Concatenate [list]s *list1* and *list2*.
 
 Associativity: right
 
@@ -56,7 +56,7 @@ Precedence: 5
 
 > *n1* `*` *n2*,
 
-Multiply numbers *n1* and *n2*.
+Multiply [number]s *n1* and *n2*.
 
 Associativity: left
 
@@ -66,7 +66,7 @@ Precedence: 6
 
 > *n1* `/` *n2*
 
-Divide numbers *n1* and *n2*.
+Divide [number]s *n1* and *n2*.
 
 Associativity: left
 
@@ -76,7 +76,7 @@ Precedence: 6
 
 > *n1* `-` *n2*
 
-Subtract numbers *n2* from *n1*.
+Subtract [number] *n2* from *n1*.
 
 Associativity: left
 
@@ -86,7 +86,7 @@ Precedence: 7
 
 > *n1* `+` *n2*
 
-Add numbers *n1* and *n2*.
+Add [number]s *n1* and *n2*.
 
 Associativity: left
 
@@ -96,7 +96,7 @@ Precedence: 7
 
 > *string1* `+` *string2*
 
-Concatenate *string1* and *string1* and merge their string contexts.
+Concatenate two [string]s and merge their string contexts.
 
 Associativity: left
 
@@ -106,19 +106,19 @@ Precedence: 7
 
 > *path1* `+` *path2*
 
-Concatenate two paths.
+Concatenate two [path]s.
 The result is a path.
 
 ## Path and string concatenation
 
 > *path* `+` *string*
 
-Concatenate *path* with *string*.
+Concatenate *[path]* with *[string]*.
 The result is a path.
 
 > **Note**
 >
-> The string must not have a string context that refers to a store path.
+> The string must not have a string context that refers to a [store path].
 
 Associativity: left
 
@@ -128,13 +128,13 @@ Precedence: 7
 
 > *string* `+` *path*
 
-Concatenate *string* with *path*.
+Concatenate *[string]* with *[path]*.
 The result is a string.
 
 > **Important**
 >
-> The file or directory at *path* must exist and is copied to the store
-> The path appears in the result as the corresponding store path.
+> The file or directory at *path* must exist and is copied to the [store].
+> The path appears in the result as the corresponding [store path].
 
 Associativity: left
 
@@ -144,7 +144,7 @@ Precedence: 7
 
 > `!` *b*
 
-Negate the Boolean value *b*.
+Negate the [Boolean] value *b*.
 
 Associativity: none
 
@@ -154,7 +154,7 @@ Precedence: 8
 
 > *attrset1* `//` *attrset1*
 
-Update attribute set *attrset1* with names and values from *attrset2*.
+Update [attribute set] *attrset1* with names and values from *attrset2*.
 
 The returned attribute set will have of all the attributes in *e1* and *e2*.
 If an attribute name is present in both, the attribute value from the former is taken.
@@ -165,9 +165,9 @@ Precedence: 9
 
 ## Comparison
 
-- Arithmetic comparison for numbers
-- Lexicographic comparison for strings and paths
-- Lexicographic comparison for lists:
+- Arithmetic comparison for [number]s
+- Lexicographic comparison for [string]s and [path]s
+- Lexicographic comparison for [list]s:
   Elements at the same index in both lists are compared according to their type and skipped if they are equal.
 
 Associativity: none
@@ -196,8 +196,8 @@ Precedence: 10
 
 Check expressions *e1* and *e2* for value equality.
 
-- Attribute sets and lists are compared recursively, and therefore are fully evaluated.
-- Comparison of functions always returns `false`.
+- [Attribute sets][attribute set] and [list]s are compared recursively, and therefore are fully evaluated.
+- Comparison of [function]s always returns `false`.
 - Integers are coerced to floating point numbers if compared to floating point numbers.
 - Floating point numbers only differ up to a limited precision.
 
@@ -246,3 +246,13 @@ Equivalent to `!`*b1* `||` *b2*.
 Associativity: none
 
 Precedence: 14
+
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[number]: ./values.md#type-number
+[Boolean]: ./values.md#type-boolean
+[list]: ./values.md#list
+[attribute set]: ./values.md#attribute-set
+[function]: ./constructs.md#functions
+[store path]: ../glossary.md#gloss-store-path
+[store]: ../glossary.md#gloss-store
-- 
cgit v1.2.3


From e57165b85a48daba3649b08cff3eab3519bc8dce Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 5 Jan 2023 15:16:16 +0100
Subject: bring back table, extract annotations

this makes the table less unwieldy, and leaves enough space for
extensive explanations.
---
 doc/manual/src/language/operators.md | 249 +++++++++++------------------------
 doc/manual/src/language/values.md    |   7 +-
 2 files changed, 82 insertions(+), 174 deletions(-)

(limited to 'doc/manual/src')

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index 1f11e6ac5..797f13bd3 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -1,117 +1,96 @@
 # Operators
 
-## Attribute selection
+| Name                                   | Syntax                                     | Associativity | Precedence |
+|----------------------------------------|--------------------------------------------|---------------|------------|
+| [Attribute selection]                  | *attrset* `.` *attrpath* \[ `or` *expr* \] | none          | 1          |
+| Function application                   | *func* *expr*                              | left          | 2          |
+| [Arithmetic negation][arithmetic]      | `-` *number*                               | none          | 3          |
+| [Has attribute]                        | *attrset* `?` *attrpath*                   | none          | 4          |
+| List concatenation                     | *list* `++` *list*                         | right         | 5          |
+| [Multiplication][arithmetic]           | *number* `*` *number*                      | left          | 6          |
+| [Division][arithmetic]                 | *number* `/` *number*                      | left          | 6          |
+| [Subtraction][arithmetic]              | *number* `-` *number*                      | left          | 7          |
+| [Addition][arithmetic]                 | *number* `+` *number*                      | left          | 7          |
+| [String concatenation]                 | *string* `+` *string*                      | left          | 7          |
+| [Path concatenation]                   | *path* `+` *path*                          | left          | 7          |
+| [Path and string concatenation]        | *path* `+` *string*                        | left          | 7          |
+| [String and path concatenation]        | *string* `+` *path*                        | left          | 7          |
+| Logical negation (`NOT`)               | `!` *bool*                                 | none          | 8          |
+| [Update]                               | *attrset* `//` *attrset*                   | right         | 9          |
+| [Less than][Comparison]                | *expr* `<` *expr*                          | none          | 10         |
+| [Less than or equal to][Comparison]    | *expr* `<=` *expr*                         | none          | 10         |
+| [Greater than][Comparison]             | *expr* `>` *expr*                          | none          | 10         |
+| [Greater than or equal to][Comparison] | *expr* `>=` *expr*                         | none          | 10         |
+| [Equality]                             | *expr* `==` *expr*                         | none          | 11         |
+| Inequality                             | *expr* `!=` *expr*                         | none          | 11         |
+| Logical conjunction (`AND`)            | *bool* `&&` *bool*                         | left          | 12         |
+| Logical disjunction (`OR`)             | *bool* `||` *bool*                         | left          | 13         |
+| [Logical implication]                  | *bool* `->` *bool*                         | none          | 14         |
 
-> *attrset* `.` *attrpath* \[ `or` *value* \]
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[number]: ./values.md#type-number
+[list]: ./values.md#list
+[attribute set]: ./values.md#attribute-set
+
+## Attribute selection
 
 Select the attribute denoted by attribute path *attrpath* from [attribute set] *attrset*.
-An attribute path is a dot-separated list of attribute names.
 If the attribute doesn’t exist, return *value* if provided, otherwise abort evaluation.
 
-Associativity: none
-
-Precedence: 1
-
-## Function application
+<!-- FIXME: the following should to into its own language syntax section, but that needs more work to fit in well -->
 
-> *f* *a*
-
-Call [function] *f* with argument *a*.
-
-Associativity: left
-
-Precedence: 2
-
-## Arithmetic negation
-
-> `-` *n*
-
-Flip the sign of the [number] *n*.
+An attribute path is a dot-separated list of attribute names.
+An attribute name can be an identifier or a string.
 
-Associativity: none
+> *attrpath* = *name* [ `.` *name* ]...
+> *name* = *identifier* | *string*
+> *identifier* ~ `[a-zA-Z_][a-zA-Z0-9_'-]*`
 
-Precedence: 3
+[Attribute selection]: #attribute-selection
 
 ## Has attribute
 
 > *attrset* `?` *attrpath*
 
-Test whether [attribute set] *attrset* contains the attribute denoted by *attrpath*; return `true` or `false`.
-
-Associativity: none
-
-Precedence: 4
-
-## List concatenation
-
-> *list1* `++` *list2*
+Test whether [attribute set] *attrset* contains the attribute denoted by *attrpath*.
+The result is a [Boolean] value.
 
-Concatenate [list]s *list1* and *list2*.
-
-Associativity: right
-
-Precedence: 5
-
-## Multiplication
-
-> *n1* `*` *n2*,
-
-Multiply [number]s *n1* and *n2*.
-
-Associativity: left
-
-Precedence: 6
-
-## Division
-
-> *n1* `/` *n2*
-
-Divide [number]s *n1* and *n2*.
-
-Associativity: left
-
-Precedence: 6
-
-## Subtraction
-
-> *n1* `-` *n2*
-
-Subtract [number] *n2* from *n1*.
-
-Associativity: left
+[Boolean]: ./values.md#type-boolean
 
-Precedence: 7
+[Has attribute]: #has-attribute
 
-## Addition
+## Arithmetic
 
-> *n1* `+` *n2*
+Numbers are type-compatible:
+Pure integer operations will always return integers, whereas any operation involving at least one floating point number return a floating point number.
 
-Add [number]s *n1* and *n2*.
+See also [Comparison] and [Equality].
 
-Associativity: left
+The `+` operator is overloaded to also work on strings and paths.
 
-Precedence: 7
+[arithmetic]: #arithmetic
 
 ## String concatenation
 
-> *string1* `+` *string2*
+> *string* `+` *string*
 
 Concatenate two [string]s and merge their string contexts.
 
-Associativity: left
-
-Precedence: 7
+[String concatenation]: #string-concatenation
 
 ## Path concatenation
 
-> *path1* `+` *path2*
+> *path* `+` *path*
 
 Concatenate two [path]s.
 The result is a path.
 
+[Path concatenation]: #path-concatenation
+
 ## Path and string concatenation
 
-> *path* `+` *string*
+> *path* + *string*
 
 Concatenate *[path]* with *[string]*.
 The result is a path.
@@ -120,13 +99,11 @@ The result is a path.
 >
 > The string must not have a string context that refers to a [store path].
 
-Associativity: left
-
-Precedence: 7
+[Path and string concatenation]: #path-and-string-concatenation
 
 ## String and path concatenation
 
-> *string* `+` *path*
+> *string* + *path*
 
 Concatenate *[string]* with *[path]*.
 The result is a string.
@@ -136,123 +113,55 @@ The result is a string.
 > The file or directory at *path* must exist and is copied to the [store].
 > The path appears in the result as the corresponding [store path].
 
-Associativity: left
-
-Precedence: 7
-
-## Logical negation (`NOT`)
-
-> `!` *b*
-
-Negate the [Boolean] value *b*.
-
-Associativity: none
+[store path]: ../glossary.md#gloss-store-path
+[store]: ../glossary.md#gloss-store
 
-Precedence: 8
+[Path and string concatenation]: #path-and-string-concatenation
 
 ## Update
 
-> *attrset1* `//` *attrset1*
+> *attrset1* + *attrset2*
 
 Update [attribute set] *attrset1* with names and values from *attrset2*.
 
 The returned attribute set will have of all the attributes in *e1* and *e2*.
 If an attribute name is present in both, the attribute value from the former is taken.
 
-Associativity: right
-
-Precedence: 9
+[Update]: #update
 
 ## Comparison
 
-- Arithmetic comparison for [number]s
-- Lexicographic comparison for [string]s and [path]s
-- Lexicographic comparison for [list]s:
-  Elements at the same index in both lists are compared according to their type and skipped if they are equal.
-
-Associativity: none
-
-Precedence: 10
-
-### Less than
-
-> *e1* `<` *e2*,
+Comparison is
 
-### Less than or equal to
+- [arithmetic] for [number]s 
+- lexicographic for [string]s and [path]s
+- item-wise lexicographic for [list]s:
+  elements at the same index in both lists are compared according to their type and skipped if they are equal.
 
-> *e1* `<=` *e2*
+All comparison operators are implemented in terms of `<`, and the following equivalencies hold:
 
-### Greater than
+| comparison   | implementation        |
+|--------------|-----------------------|
+| *a* `<=` *b* | `! (` *b* `<` *a* `)` |
+| *a* `>`  *b* |       *b* `<` *a*     |
+| *a* `>=` *b* | `! (` *a* `<` *b* `)` |
 
-> *e1* `>` *e2*
-
-### Greater than or equal to
-
-> *e1* `>=` *e2*
+[Comparison]: #comparison-operators
 
 ## Equality
 
-> *e1* `==` *e2*
-
-Check expressions *e1* and *e2* for value equality.
-
 - [Attribute sets][attribute set] and [list]s are compared recursively, and therefore are fully evaluated.
 - Comparison of [function]s always returns `false`.
-- Integers are coerced to floating point numbers if compared to floating point numbers.
+- Numbers are type-compatible, see [arithmetic] operators.
 - Floating point numbers only differ up to a limited precision.
 
-Associativity: none
-
-Precedence: 11
-
-## Inequality
-
-> *e1* `!=` *e2*
-
-Equivalent to `! (`*e1* `==` *e2* `)`
-
-Associativity: none
-
-Precedence: 11
-
-## Logical conjunction (`AND`)
-
-> *b1* `&&` *b2*
-
-Return `true` if and only if both `b1` and `b2` evaluate to `true`, otherwise `false`.
-
-Associativity: left
-
-Precedence: 12
-
-## Logical disjunction (`OR`)
-
-> *b1* `||` *b2*
-
-Return `true` if at least one of  `b1` or `b2` evaluate to `true`, otherwise `false`.
-
-Associativity: left
+[function]: ./constructs.md#functions
 
-Precedence: 13
+[Equality]: #equality
 
 ## Logical implication
 
->  *b1* `->` *b2*
-
-Return `false` if *b1* evaluates to `true` and *b2* evaluates to `false`, otherwise `true`.
-
 Equivalent to `!`*b1* `||` *b2*.
 
-Associativity: none
+[Logical implication]: #logical-implication
 
-Precedence: 14
-
-[string]: ./values.md#type-string
-[path]: ./values.md#type-path
-[number]: ./values.md#type-number
-[Boolean]: ./values.md#type-boolean
-[list]: ./values.md#list
-[attribute set]: ./values.md#attribute-set
-[function]: ./constructs.md#functions
-[store path]: ../glossary.md#gloss-store-path
-[store]: ../glossary.md#gloss-store
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index d92f287a3..3973518ca 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -85,11 +85,10 @@
   Numbers, which can be *integers* (like `123`) or *floating point*
   (like `123.43` or `.27e13`).
 
-  Numbers are type-compatible: pure integer operations will always
-  return integers, whereas any operation involving at least one
-  floating point number will have a floating point number as a result.
+  See [arithmetic] and [comparison] operators for semantics.
 
-  Floating point numbers only differ up to a limited precision.
+  [arithmetic]: ./operators.md#arithmetic
+  [comparison]: ./operators.md#comparison
 
 - <a id="type-path" href="#type-path">Path</a>
 
-- 
cgit v1.2.3