Apply suggestions from code review

2 files changed, 19 insertions, 7 deletions

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.