Document file system object content addressing

In addition:

- Take the opportunity to add a bunch more missing hyperlinks, too.

- Remove some glossary entries that are now subsumed by dedicated pages.
  We used to not be able to do this without breaking link fragments, but
  now we can, so pick up where we left off.

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

src/libcmd/misc-store-flags.cc

@@ -81,9 +81,15 @@ Args::Flag fileIngestionMethod(FileIngestionMethod * method)
     How to compute the hash of the input.
     One of:
 
-    - `nar` (the default): Serialises the input as an archive (following the [_Nix Archive Format_](https://edolstra.github.io/pubs/phd-thesis.pdf#page=101)) and passes that to the hash function.
+    - `nar` (the default):
+      Serialises the input as a
+      [Nix Archive](@docroot@/store/file-system-object/content-address.md#serial-nix-archive)
+      and passes that to the hash function.
 
-    - `flat`: Assumes that the input is a single file and directly passes it to the hash function;
+    - `flat`:
+      Assumes that the input is a single file and
+      [directly passes](@docroot@/store/file-system-object/content-address.md#serial-flat)
+      it to the hash function.
         )",
         .labels = {"file-ingestion-method"},
         .handler = {[method](std::string s) {
@@ -97,16 +103,24 @@ Args::Flag contentAddressMethod(ContentAddressMethod * method)
     return Args::Flag {
         .longName  = "mode",
         // FIXME indentation carefully made for context, this is messed up.
+        /* FIXME link to store object content-addressing not file system
+           object content addressing once we have that page. */
         .description = R"(
     How to compute the content-address of the store object.
     One of:
 
-    - `nar` (the default): Serialises the input as an archive (following the [_Nix Archive Format_](https://edolstra.github.io/pubs/phd-thesis.pdf#page=101)) and passes that to the hash function.
+    - `nar` (the default):
+      Serialises the input as a
+      [Nix Archive](@docroot@/store/file-system-object/content-address.md#serial-nix-archive)
+      and passes that to the hash function.
 
-    - `flat`: Assumes that the input is a single file and directly passes it to the hash function;
+    - `flat`:
+      Assumes that the input is a single file and
+      [directly passes](@docroot@/store/file-system-object/content-address.md#serial-flat)
+      it to the hash function.
 
     - `text`: Like `flat`, but used for
-      [derivations](@docroot@/glossary.md#store-derivation) serialized in store object and 
+      [derivations](@docroot@/glossary.md#store-derivation) serialized in store object and
       [`builtins.toFile`](@docroot@/language/builtins.html#builtins-toFile).
       For advanced use-cases only;
       for regular usage prefer `nar` and `flat.

src/libexpr/primops.cc

@@ -4515,7 +4515,7 @@ void EvalState::createBaseEnv()
           1683705525
           ```
 
-          The [store path](@docroot@/glossary.md#gloss-store-path) of a derivation depending on `currentTime` will differ for each evaluation, unless both evaluate `builtins.currentTime` in the same second.
+          The [store path](@docroot@/store/store-path.md) of a derivation depending on `currentTime` will differ for each evaluation, unless both evaluate `builtins.currentTime` in the same second.
         )",
         .impureOnly = true,
     });

src/libexpr/primops/fetchTree.cc

@@ -200,8 +200,8 @@ static RegisterPrimOp primop_fetchTree({
     .doc = R"(
       Fetch a file system tree or a plain file using one of the supported backends and return an attribute set with:
 
-      - the resulting fixed-output [store path](@docroot@/glossary.md#gloss-store-path)
-      - the corresponding [NAR](@docroot@/glossary.md#gloss-nar) hash
+      - the resulting fixed-output [store path](@docroot@/store/store-path.md)
+      - the corresponding [NAR](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) hash
       - backend-specific metadata (currently not documented). <!-- TODO: document output attributes -->
 
       *input* must be an attribute set with the following attributes:

src/libstore/globals.hh

@@ -910,7 +910,7 @@ public:
         "substituters",
         R"(
           A list of [URLs of Nix stores](@docroot@/store/types/index.md#store-url-format) to be used as substituters, separated by whitespace.
-          A substituter is an additional [store](@docroot@/glossary.md#gloss-store) from which Nix can obtain [store objects](@docroot@/glossary.md#gloss-store-object) instead of building them.
+          A substituter is an additional [store](@docroot@/glossary.md#gloss-store) from which Nix can obtain [store objects](@docroot@/store/store-object.md) instead of building them.
 
           Substituters are tried based on their priority value, which each substituter can set independently.
           Lower value means higher priority.

src/libstore/path.hh

@@ -13,7 +13,7 @@ struct Hash;
  * \ref StorePath "Store path" is the fundamental reference type of Nix.
  * A store paths refers to a Store object.
  *
- * See glossary.html#gloss-store-path for more information on a
+ * See store/store-path.html for more information on a
  * conceptual level.
  */
 class StorePath

src/libutil/file-content-address.hh

@@ -12,16 +12,28 @@ struct SourcePath;
 /**
  * An enumeration of the ways we can serialize file system
  * objects.
+ *
+ * See `file-system-object/content-address.md#serial` in the manual for
+ * a user-facing description of this concept, but note that this type is also
+ * used for storing or sending copies; not just for addressing.
+ * Note also that there are other content addressing methods that don't
+ * correspond to a serialisation method.
  */
 enum struct FileSerialisationMethod : uint8_t {
     /**
      * Flat-file. The contents of a single file exactly.
+     *
+     * See `file-system-object/content-address.md#serial-flat` in the
+     * manual.
      */
     Flat,
 
     /**
      * Nix Archive. Serializes the file-system object in
      * Nix Archive format.
+     *
+     * See `file-system-object/content-address.md#serial-nix-archive` in
+     * the manual.
      */
     Recursive,
 };
@@ -81,33 +93,32 @@ HashResult hashPath(
 /**
  * An enumeration of the ways we can ingest file system
  * objects, producing a hash or digest.
+ *
+ * See `file-system-object/content-address.md` in the manual for a
+ * user-facing description of this concept.
  */
 enum struct FileIngestionMethod : uint8_t {
     /**
      * Hash `FileSerialisationMethod::Flat` serialisation.
+     *
+     * See `file-system-object/content-address.md#serial-flat` in the
+     * manual.
      */
     Flat,
 
     /**
-     * Hash `FileSerialisationMethod::Git` serialisation.
+     * Hash `FileSerialisationMethod::Recursive` serialisation.
+     *
+     * See `file-system-object/content-address.md#serial-flat` in the
+     * manual.
      */
     Recursive,
 
     /**
-     * Git hashing. In particular files are hashed as git "blobs", and
-     * directories are hashed as git "trees".
+     * Git hashing.
      *
-     * Unlike `Flat` and `Recursive`, this is not a hash of a single
-     * serialisation but a [Merkle
-     * DAG](https://en.wikipedia.org/wiki/Merkle_tree) of multiple
-     * rounds of serialisation and hashing.
-     *
-     * @note Git's data model is slightly different, in that a plain
-     * file doesn't have an executable bit, directory entries do
-     * instead. We decide treat a bare file as non-executable by fiat,
-     * as we do with `FileIngestionMethod::Flat` which also lacks this
-     * information. Thus, Git can encode some but all of Nix's "File
-     * System Objects", and this sort of hashing is likewise partial.
+     * See `file-system-object/content-address.md#serial-git` in the
+     * manual.
      */
     Git,
 };

src/nix/derivation-show.md

@@ -50,7 +50,7 @@ By default, this command only shows top-level derivations, but with
 
 `nix derivation show` outputs a JSON map of [store path]s to derivations in the following format:
 
-[store path]: @docroot@/glossary.md#gloss-store-path
+[store path]: @docroot@/store/store-path.md
 
 {{#include ../../protocols/json/derivation.md}}
 

src/nix/unix/daemon.cc

@@ -58,7 +58,7 @@ struct AuthorizationSettings : Config {
         this, {"root"}, "trusted-users",
         R"(
           A list of user names, separated by whitespace.
-          These users will have additional rights when connecting to the Nix daemon, such as the ability to specify additional [substituters](#conf-substituters), or to import unsigned [NARs](@docroot@/glossary.md#gloss-nar).
+          These users will have additional rights when connecting to the Nix daemon, such as the ability to specify additional [substituters](#conf-substituters), or to import unsigned realisations or unsigned input-addressed store objects.
 
           You can also specify groups by prefixing names with `@`.
           For instance, `@wheel` means all users in the `wheel` group.