reword description of how realisation works

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

@@ -1,6 +1,6 @@
-# Options
+# Command options
 
-The following options are allowed for all `nix-store` operations, but may not always have an effect.
+The following options are allowed for all operations in the `nix-store` command, but may not always have an effect.
 
 - <span id="opt-add-root">[`--add-root`](#opt-add-root)</span> *path*
 

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

@@ -8,53 +8,35 @@
 
 # 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.
-
-[valid]: @docroot@/glossary.md#gloss-validity
-[substitutes]: @docroot@/glossary.md#gloss-substitute
-
-The output path of each derivation is printed on standard output. (For
-non-derivations argument, the argument itself is printed.)
-
-The following flags are available:
+Ensure that the given [store paths] are [valid].
 
-  - `--dry-run`\
-    Print on standard error a description of what packages would be
-    built or downloaded, without actually performing the operation.
+Realisation of a store path works as follows:
 
-  - `--ignore-unknown`\
-    If a non-derivation path does not have a substitute, then silently
-    ignore it.
+- If the path is already valid, do nothing.
+- If the path leads to a [store derivation]:
+  1. Realise the store derivation file itself, as a regular store path.
+  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 build certificates in the [Nix database].
+    - For any store paths that cannot be substituted, produce the required store objects by first realising all outputs of the derivation's dependencies and then running the derivation's build instructions.
+- Otherwise: Try to fetch the associated [store objects] in the paths' [closure] from the [substituters].
 
-  - `--check`\
-    This option allows you to check whether a derivation is
-    deterministic. It rebuilds the specified derivation and checks
-    whether the result is bitwise-identical with the existing outputs,
-    printing an error if that’s not the case. The outputs of the
-    specified derivation must already exist. When used with `-K`, if an
-    output path is not identical to the corresponding output from the
-    previous build, the new output path is left in
-    `/nix/store/name.check.`
+If no substitutes are available and no store derivation is given, realisation fails.
 
-Special exit codes:
+[store paths]: ../glossary.md#gloss-store-path
+[valid]: ../glossary.md#gloss-validity
+[store derivation]: @docroot@/glossary.md#gloss-store-derivation
+[output paths]: ../glossary.md#gloss-output-path
+[store objects]: ../glossary.md#gloss-store-object
+[closure]: ../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.
+
+## Special exit codes
 
   - `100`\
     Generic build failure, the builder process returned with a non-zero
@@ -84,6 +66,25 @@ or.
        |`--- build failure
        `---- not deterministic
 
+# Options
+
+  - `--dry-run`\
+    Print on standard error a description of what packages would be
+    built or downloaded, without actually performing the operation.
+
+  - `--ignore-unknown`\
+    If a non-derivation path does not have a substitute, then silently
+    ignore it.
+
+  - `--check`\
+    This option allows you to check whether a derivation is
+    deterministic. It rebuilds the specified derivation and checks
+    whether the result is bitwise-identical with the existing outputs,
+    printing an error if that’s not the case. The outputs of the
+    specified derivation must already exist. When used with `-K`, if an
+    output path is not identical to the corresponding output from the
+    previous build, the new output path is left in
+    `/nix/store/name.check.`
 
 {{#include ./opt-common.md}}
 
@@ -96,8 +97,6 @@ or.
 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 -r $(nix-instantiate ./test.nix)
 /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1