reword description of how realisation works

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

@@ -1,40 +1,42 @@
 # Name
 
-`nix-store --realise` - realise specified store paths
+`nix-store --realise` - build or fetch store objects
 
 # Synopsis
 
 `nix-store` {`--realise` | `-r`} *paths…* [`--dry-run`]
 
 # 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] (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]
-    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.
 
+Each of *paths* is processed as follows:
+
+- If the path leads to a [store derivation]:
+  1. If it is not [valid], substitute the store derivation file itself.
+  2. Realise its [output paths]:
+    - Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure].
+      - With [content-addressed derivations] (experimental): Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database].
+    - For any store paths that cannot be substituted, produce the required store objects. This involves first realising all outputs of the derivation's dependencies and then running the derivation's [`builder`](@docroot@/language/derivations.md#attr-builder) executable. <!-- TODO: Link to build process page #8888 -->
+- Otherwise, and if the path is not already valid: Try to fetch the associated [store objects] in the path's [closure] from [substituters].
+
+If no substitutes are available and no store derivation is given, realisation fails.
+
+[store paths]: @docroot@/glossary.md#gloss-store-path
 [valid]: @docroot@/glossary.md#gloss-validity
-[substitutes]: @docroot@/glossary.md#gloss-substitute
+[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[output paths]: @docroot@/glossary.md#gloss-output-path
+[store objects]: @docroot@/glossary.md#gloss-store-object
+[closure]: @docroot@/glossary.md#gloss-closure
+[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
+[content-addressed derivations]: @docroot@/contributing/experimental-features.md#xp-feature-ca-derivations
+[Nix database]: @docroot@/glossary.md#gloss-nix-database
+
+The resulting paths are printed on standard output.
+For non-derivation arguments, the argument itself is printed.
 
-The output path of each derivation is printed on standard output. (For
-non-derivations argument, the argument itself is printed.)
+{{#include ../status-build-failure.md}}
 
-The following flags are available:
+# Options
 
   - `--dry-run`\
     Print on standard error a description of what packages would be
@@ -54,8 +56,6 @@ The following flags are available:
     previous build, the new output path is left in
     `/nix/store/name.check.`
 
-{{#include ../status-build-failure.md}}
-
 {{#include ./opt-common.md}}
 
 {{#include ../opt-common.md}}
@@ -67,8 +67,6 @@ The following flags are available:
 This operation is typically used to build [store derivation]s produced by
 [`nix-instantiate`](@docroot@/command-ref/nix-instantiate.md):
 
-[store derivation]: @docroot@/glossary.md#gloss-store-derivation
-
 ```console
 $ nix-store --realise $(nix-instantiate ./test.nix)
 /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1

doc/manual/src/glossary.md

@@ -33,7 +33,7 @@
 
   Ensure a [store path] is [valid][validity].
 
-  This means either running the `builder` executable as specified in the corresponding [derivation] or fetching a pre-built [store object] from a [substituter].
+  This means either running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation], or fetching a pre-built [store object] from a [substituter], or delegating to a [remote builder](@docroot@/advanced-topics/distributed-builds.html) and retrieving the outputs. <!-- TODO: link [running] to build process page, #8888 -->
 
   See [`nix-build`](./command-ref/nix-build.md) and [`nix-store --realise`](@docroot@/command-ref/nix-store/realise.md).
 

doc/manual/src/language/derivations.md

@@ -17,7 +17,7 @@ the attributes of which specify the inputs of the build.
     string. This is used as a symbolic name for the package by
     `nix-env`, and it is appended to the output paths of the derivation.
 
-  - There must be an attribute named `builder` that identifies the
+  - There must be an attribute named [`builder`]{#attr-builder} that identifies the
     program that is executed to perform the build. It can be either a
     derivation or a source (a local file reference, e.g.,
     `./builder.sh`).