document the store concept (#9206)

* document the store concept and its purpose

reword the glossary to link to more existing information instead of
repeating it.

move the store documentation to the top of the table of contents, in
front of the Nix language. this will provide a natural place to
document other aspects of the store as well as the various store types.

move the package management section after the Nix language and before
Advanced Topics to follow the pattern to layer more complex concepts on
top of each other.

this structure of the manual will also nudge beginners to learn Nix
bottom-up and hopefully make more likely that they understand underlying
concepts first before delving into complex use cases that may or may not
be easy to implement with what's currently there.

[John adds this note] The sort of beginner who likes to dive straight into reference documentation should prefer this approach. Conversely, the sort of beginner who would prefer the opposite top-down approach of trying to solve problems before they understand everything that is going on is better off reading other tutorial/guide material anyways, and will just "random-access" the reference manual as a last resort. For such random-access the order doesn't matter, so this restructure doesn't make them any worse off.

Co-authored-by: John Ericson <git@JohnEricson.me>

doc/manual/src/SUMMARY.md.in

@@ -16,14 +16,8 @@
   - [Environment Variables](installation/env-variables.md)
   - [Upgrading Nix](installation/upgrading.md)
   - [Uninstalling Nix](installation/uninstall.md)
-- [Package Management](package-management/package-management.md)
+- [Nix Store](store/index.md)
-  - [Profiles](package-management/profiles.md)
+  - [File System Object](store/file-system-object.md)
-  - [Garbage Collection](package-management/garbage-collection.md)
-    - [Garbage Collector Roots](package-management/garbage-collector-roots.md)
-  - [Sharing Packages Between Machines](package-management/sharing-packages.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)
 - [Nix Language](language/index.md)
   - [Data Types](language/values.md)
   - [Language Constructs](language/constructs.md)
@@ -35,7 +29,16 @@
     - [Import From Derivation](language/import-from-derivation.md)
   - [Built-in Constants](language/builtin-constants.md)
   - [Built-in Functions](language/builtins.md)
+- [Package Management](package-management/package-management.md)
+  - [Profiles](package-management/profiles.md)
+  - [Garbage Collection](package-management/garbage-collection.md)
+    - [Garbage Collector Roots](package-management/garbage-collector-roots.md)
 - [Advanced Topics](advanced-topics/advanced-topics.md)
+  - [Sharing Packages Between Machines](package-management/sharing-packages.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)
+    - [Serving a Nix store via S3](package-management/s3-substituter.md)
   - [Remote Builds](advanced-topics/distributed-builds.md)
   - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
   - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
@@ -97,7 +100,6 @@
     - [Channels](command-ref/files/channels.md)
     - [Default Nix expression](command-ref/files/default-nix-expression.md)
 - [Architecture and Design](architecture/architecture.md)
-  - [File System Object](architecture/file-system-object.md)
 - [Protocols](protocols/protocols.md)
   - [Serving Tarball Flakes](protocols/tarball-fetcher.md)
   - [Derivation "ATerm" file format](protocols/derivation-aterm.md)

doc/manual/src/architecture/architecture.md

@@ -59,6 +59,7 @@ The [Nix language](../language/index.md) evaluator transforms Nix expressions in
 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.
 

doc/manual/src/glossary.md

@@ -58,22 +58,16 @@
 
 - [store]{#gloss-store}
 
-  The location in the file system where store objects live. Typically
+  A collection of store objects, with operations to manipulate that collection.
-  `/nix/store`.
+  See [Nix Store] for details.
 
-  From   the  perspective   of   the  location   where  Nix   is
+  There are many types of stores.
-  invoked, the  Nix store can be  referred to
+  See [`nix help-stores`](@docroot@/command-ref/new-cli/nix3-help-stores.md) for a complete list.
-  as a "_local_" or a "_remote_" one:
 
-  + A [local store]{#gloss-local-store} exists on the filesystem of
+  From the perspective of the location where Nix is invoked, the Nix store can be  referred to _local_ or _remote_.
-    the machine where Nix is  invoked. You can use other
+  Only a [local store]{#gloss-local-store} exposes a location in the file system of the machine where Nix is invoked that allows access to store objects, typically `/nix/store`.
-    local stores  by passing  the `--store` flag  to the
+  Local stores can be used for building [derivations](#derivation).
-    `nix` command.  Local stores can be used for building derivations.
+  See [Local Store](@docroot@/command-ref/new-cli/nix3-help-stores.md#local-store) for details.
-
-  + 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.
 
   [store]: #gloss-store
   [local store]: #gloss-local-store
@@ -103,15 +97,19 @@
 
   The Nix data model for representing simplified file system data.
 
-  See [File System Object](@docroot@/architecture/file-system-object.md) for details.
+  See [File System Object](@docroot@/store/file-system-object.md) for details.
 
   [file system object]: #gloss-file-system-object
 
 - [store object]{#gloss-store-object}
 
-  A store object consists of a [file system object], [reference]s to other store objects, and other metadata.
+  Part of the contents of a [store].
+
+  A store object consists of a [file system object], [references][reference] to other store objects, and other metadata.
   It can be referred to by a [store path].
 
+  See [Store Object](@docroot@/store/index.md#store-object) for details.
+
   [store object]: #gloss-store-object
 
 - [IFD]{#gloss-ifd}

doc/manual/src/store/index.md

@@ -0,0 +1,4 @@
+# Nix Store
+
+The *Nix store* is an abstraction used by Nix to store immutable filesystem artifacts (such as software packages) that can have dependencies (*references*) between them.
+There are multiple implementations of the Nix store, such as the actual filesystem (`/nix/store`) and binary caches.