reword description of how realisation works

doc/manual/src/command-ref/nix-store.md

@@ -62,28 +62,28 @@ have an effect.
 
 ## Description
 
-The operation `--realise` essentially “builds” the specified store
-paths. Realisation is a somewhat overloaded term:
-
-  - If the store path is a *derivation*, realisation ensures that the
-    output paths of the derivation are [valid](../glossary.md) (i.e.,
-    the output path and its closure exist in the file system). This
-    can be done in several ways. First, it is possible that the
-    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 running the build task described
-    by the derivation.
-
-  - If the store path is not a derivation, realisation ensures that the
-    specified path is valid (i.e., it and its closure exist in the file
-    system). If the path is already valid, we are done immediately.
-    Otherwise, the path and any missing paths in its closure may be
-    produced through substitutes. If there are no (successful)
-    substitutes, realisation fails.
-
-The output path of each derivation is printed on standard output. (For
-non-derivations argument, the argument itself is printed.)
+Ensure that the given [store paths] are [valid].
+
+Realisation of a store path works as follows:
+- If the path is already valid, do nothing.
+- If the path leads to a [store derivation], realise its [output paths]:
+ - Try to fetch the associated [store objects] in the paths' [closure] from a [substituter].
+ - Produce the required store objects by first realising all dependencies and then running the derivations' build instructions.
+- Otherwise:
+ - Try to fetch the associated [store objects] in the paths' [closure] from a [substituter].
+
+If no substitutes are available and no store derivation is given, realisation fails.
+
+[store paths]: ../glossary.md#gloss-store-path
+[valid]: ../glossary.md#gloss-validity
+[store derivation]: ../glossary.md#gloss-store-derivation
+[output paths]: ../glossary.md#gloss-output-path
+[store objects]: ../glossary.md#gloss-store-object
+[closure]: ../glossary.md#gloss-closure
+[substituter]: ../glossary.md#gloss-substituter
+
+The output path of each derivation is printed on standard output.
+For non-derivation arguments, the argument itself is printed.
 
 The following flags are available:
 
@@ -295,8 +295,8 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4'
 
 ## Description
 
-The operation `--query` displays various bits of information about the
-store paths . The queries are described below. At most one query can be
+The operation `--query` displays information about [store paths].
+The queries are described below. At most one query can be
 specified. The default query is `--outputs`.
 
 The paths *paths* may also be symlinks from outside of the Nix store, to
@@ -316,12 +316,12 @@ symlink.
 ## Queries
 
   - `--outputs`\
-    Prints out the [output paths](../glossary.md) of the store
+    Prints out the [output paths] of the store
     derivations *paths*. These are the paths that will be produced when
     the derivation is built.
 
   - `--requisites`; `-R`\
-    Prints out the [closure](../glossary.md) of the store path *paths*.
+    Prints out the [closure] of the given *paths*.
 
     This query has one option:
 
@@ -338,10 +338,12 @@ symlink.
     derivation and specifying the option `--include-outputs`.
 
   - `--references`\
-    Prints the set of [references](../glossary.md) of the store paths
+    Prints the set of [references] of the store paths
     *paths*, that is, their immediate dependencies. (For *all*
     dependencies, use `--requisites`.)
 
+    [references]: ../glossary.md#gloss-reference
+
   - `--referrers`\
     Prints the set of *referrers* of the store paths *paths*, that is,
     the store paths currently existing in the Nix store that refer to
@@ -356,11 +358,13 @@ symlink.
     in the Nix store that are dependent on *paths*.
 
   - `--deriver`; `-d`\
-    Prints the [deriver](../glossary.md) of the store paths *paths*. If
+    Prints the [deriver] of the store paths *paths*. If
     the path has no deriver (e.g., if it is a source file), or if the
     deriver is not known (e.g., in the case of a binary-only
     deployment), the string `unknown-deriver` is printed.
 
+    [deriver]: ../glossary.md#gloss-deriver
+
   - `--graph`\
     Prints the references graph of the store paths *paths* in the format
     of the `dot` tool of AT\&T's [Graphviz

doc/manual/src/glossary.md

@@ -101,6 +101,8 @@
     copy store objects it doesn't have.  For details, see the
     [`substituters` option](./command-ref/conf-file.md#conf-substituters).
 
+    [substituter]: #gloss-substituter
+
   - [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