doc/build-helpers: refactor the paragraph about `runCommandLocal`

1 files changed, 14 insertions, 13 deletions

diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md
index 42e36821d9ec..6471395f78a0 100644
--- a/doc/build-helpers/trivial-build-helpers.chapter.md
+++ b/doc/build-helpers/trivial-build-helpers.chapter.md
@@ -29,11 +29,12 @@ runCommandWith :: {
 :   The derivation's name, which Nix will append to the store path; see [`mkDerivation`](#sec-using-stdenv).
 
 `runLocal` (Boolean)
-:   If set to `true` this forces the derivation to be built locally. Remote substitutes and distributed builds, won't be used.
+:   If set to `true` this forces the derivation to be built locally, not using [substitutes] nor remote builds.
+    This is intended for very cheap commands (<1s execution time) which can be sped up by avoiding the network round-trip(s).
     Its effect is to set [`preferLocalBuild = true`][preferLocalBuild] and [`allowSubstitutes = false`][allowSubstitutes].
 
    ::: {.note}
-   This prevents the use of substitutors, so only set `runLocal` (or use `runCommandLocal`) when certain the user will
+   This prevents the use of [substituters][substituter], so only set `runLocal` (or use `runCommandLocal`) when certain the user will
    always have a builder for the `system` of the derivation. This should be true for most trivial use cases
    (e.g., just copying some files to a different location or adding symlinks) because there the `system`
    is usually the same as `builtins.currentSystem`.
@@ -54,6 +55,8 @@ runCommandWith :: {
 
 [allowSubstitutes]: https://nixos.org/nix/manual/#adv-attr-allowSubstitutes
 [preferLocalBuild]: https://nixos.org/nix/manual/#adv-attr-preferLocalBuild
+[substituter]: https://nix.dev/manual/nix/latest/glossary#gloss-substituter
+[substitutes]: https://nix.dev/manual/nix/2.23/glossary#gloss-substitute
 
 ::: {.example #ex-runcommandwith}
 # Invocation of `runCommandWith`
@@ -80,16 +83,22 @@ The function `runCommand` returns a derivation built using the specified command
 `runCommandCC` is similar but uses the default compiler environment. To minimize dependencies, `runCommandCC`
 should only be used when the build command needs a C compiler.
 
+`runCommandLocal` is also similar to `runCommand`, but forces the derivation to be built locally.
+See the note on [`runCommandWith`] about `runLocal`.
+
+[`runCommandWith`]: #trivial-builder-runCommandWith
+
 ### Type {#trivial-builder-runCommand-Type}
 
 ```
-runCommand   :: String -> AttrSet -> String -> Derivation
-runCommandCC :: String -> AttrSet -> String -> Derivation
+runCommand      :: String -> AttrSet -> String -> Derivation
+runCommandCC    :: String -> AttrSet -> String -> Derivation
+runCommandLocal :: String -> AttrSet -> String -> Derivation
 ```
 
 ### Input {#trivial-builder-runCommand-Input}
 
-While the type signature(s) differ from `runCommandWith`, individual arguments with the same name will have the same type and meaning:
+While the type signature(s) differ from [`runCommandWith`], individual arguments with the same name will have the same type and meaning:
 
 `name` (String)
 :   The derivation's name
@@ -144,14 +153,6 @@ runCommandWith {
 :::
 
 
-## `runCommandLocal` {#trivial-builder-runCommandLocal}
-
-Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network round-trip and can speed up a build.
-
-::: {.note}
-This sets [`allowSubstitutes` to `false`][allowSubstitutes], so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g., just copying some files to a different location or adding symlinks) because there the `system` is usually the same as `builtins.currentSystem`.
-:::
-
 ## Writing text files {#trivial-builder-text-writing}
 
 Nixpkgs provides the following functions for producing derivations which write text files or executable scripts into the Nix store.