Move the bits on relocating store entires to the end

They are too advanced for up front.

4 files changed, 31 insertions, 17 deletions

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.\]