add "installable" to glossary, link from occurrences

the term is hard to discover, as its definition and explanation is in
a very long document. search does not help because it occurs so often.

doc/manual/src/glossary.md

@@ -1,5 +1,15 @@
 # Glossary
 
+  - [installable]{#gloss-installable}\
+    Argument type that can be passed to [`nix-build`](./command-ref/nix-build.md) or [`nix build`](./command-ref/new-cli/nix3-build.md) (experimental):
+
+    - path to Nix expression
+    - store derivation path
+    - [store path]
+    - [flake reference](./command-ref/new-cli/nix3-flake.md#flake-references) (only for [`nix build`](./command-ref/new-cli/nix3-build.md), experimental)
+
+    See [`nix` Installables](./command-ref/new-cli/nix3.md#installables) for details.
+
   - [derivation]{#gloss-derivation}\
     A description of a build task. The result of a derivation is a
     store object. Derivations are typically specified in Nix expressions
@@ -49,6 +59,8 @@
     The location in the file system of a store object, i.e., an
     immediate child of the Nix store directory.
 
+    [store path]: #gloss-store-path
+
   - [store object]{#gloss-store-object}\
     A file that is an immediate child of the Nix store directory. These
     can be regular files, but also entire directory trees. Store objects

src/libcmd/command.hh

@@ -22,7 +22,7 @@ static constexpr Command::Category catSecondary = 100;
 static constexpr Command::Category catUtility = 101;
 static constexpr Command::Category catNixInstallation = 102;
 
-static constexpr auto installablesCategory = "Options that change the interpretation of installables";
+static constexpr auto installablesCategory = "Options that change the interpretation of [installables](../../glossary.md#gloss-installable)";
 
 struct NixMultiCommand : virtual MultiCommand, virtual Command
 {

src/nix/build.md

@@ -82,7 +82,7 @@ R""(
 
 # Description
 
-`nix build` builds the specified *installables*. Installables that
+`nix build` builds the specified *installables*. [Installables](../../glossary.md#gloss-installable) that
 resolve to derivations are built (or substituted if possible). Store
 path installables are substituted.
 

src/nix/bundle.md

@@ -29,7 +29,7 @@ R""(
 
 # Description
 
-`nix bundle`, by default, packs the closure of the *installable* into a single
+`nix bundle`, by default, packs the closure of the [*installable*](../../glossary.md#gloss-installable) into a single
 self-extracting executable. See the [`bundlers`
 homepage](https://github.com/NixOS/bundlers) for more details.
 

src/nix/develop.md

@@ -76,7 +76,7 @@ R""(
 
 `nix develop` starts a `bash` shell that provides an interactive build
 environment nearly identical to what Nix would use to build
-*installable*. Inside this shell, environment variables and shell
+[*installable*](../../glossary.md#gloss-installable). Inside this shell, environment variables and shell
 functions are set up so that you can interactively and incrementally
 build your package.
 

src/nix/eval.md

@@ -50,7 +50,7 @@ R""(
 
 # Description
 
-This command evaluates the Nix expression *installable* and prints the
+This command evaluates the Nix expression [*installable*](../../glossary.md#gloss-installable) and prints the
 result on standard output.
 
 # Output format

src/nix/flake.md

@@ -270,8 +270,8 @@ Currently the `type` attribute can be one of the following:
 # Flake format
 
 As an example, here is a simple `flake.nix` that depends on the
-Nixpkgs flake and provides a single package (i.e. an installable
-derivation):
+Nixpkgs flake and provides a single package (i.e. an
+[installable](../../glossary.md#gloss-installable) derivation):
 
 ```nix
 {

src/nix/log.md

@@ -23,7 +23,7 @@ R""(
 # Description
 
 This command prints the log of a previous build of the derivation
-*installable* on standard output.
+[*installable*](../../glossary.md#gloss-installable) on standard output.
 
 Nix looks for build logs in two places:
 

src/nix/make-content-addressed.md

@@ -35,7 +35,9 @@ R""(
 # Description
 
 This command converts the closure of the store paths specified by
-*installables* to content-addressed form. Nix store paths are usually
+[*installables*](../../glossary.md#gloss-installable) to content-addressed form.
+
+Nix store paths are usually
 *input-addressed*, meaning that the hash part of the store path is
 computed from the contents of the derivation (i.e., the build-time
 dependency graph). Input-addressed paths need to be signed by a

src/nix/nix.md

@@ -52,10 +52,12 @@ Many `nix` subcommands operate on one or more *installables*. These are
 command line arguments that represent something that can be built in
 the Nix store. Here are the recognised types of installables:
 
-* **Flake output attributes**: `nixpkgs#hello`
+* **Flake output attributes**
+
+  Example: `nixpkgs#hello`
 
   These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
-  flake reference and *attrpath* is an optional attribute path. For
+  [flake reference](./nix3-flake.md#flake-references) and *attrpath* is an optional attribute path. For
   more information on flakes, see [the `nix flake` manual
   page](./nix3-flake.md).  Flake references are most commonly a flake
   identifier in the flake registry (e.g. `nixpkgs`), or a raw path
@@ -108,12 +110,16 @@ the Nix store. Here are the recognised types of installables:
   attributes `packages.x86_64-linux.hello`,
   `legacyPackages.x86_64-linux.hello` and `hello`.
 
-* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
+* **Store paths**
+
+  Example: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
 
   These are paths inside the Nix store, or symlinks that resolve to a
   path in the Nix store.
 
-* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
+* **Store derivations**
+
+  Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
 
   Store derivations are store paths with extension `.drv` and are a
   low-level representation of a build-time dependency graph used
@@ -130,13 +136,17 @@ the Nix store. Here are the recognised types of installables:
   If you want to operate on the store derivation itself, pass the
   `--derivation` flag.
 
-* **Nix attributes**: `--file /path/to/nixpkgs hello`
+* **Nix attributes**
+
+  Example: `--file /path/to/nixpkgs hello`
 
   When the `-f` / `--file` *path* option is given, installables are
   interpreted as attribute paths referencing a value returned by
   evaluating the Nix file *path*.
 
-* **Nix expressions**: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
+* **Nix expressions**
+
+  Example: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
 
   When the `--expr` option is given, all installables are interpreted
   as Nix expressions. You may need to specify `--impure` if the

src/nix/path-info.md

@@ -78,7 +78,7 @@ R""(
 # Description
 
 This command shows information about the store paths produced by
-*installables*, or about all paths in the store if you pass `--all`.
+[*installables*](../../glossary.md#gloss-installable), or about all paths in the store if you pass `--all`.
 
 By default, this command only prints the store paths. You can get
 additional information by passing flags such as `--closure-size`,

src/nix/print-dev-env.md

@@ -40,7 +40,7 @@ R""(
 
 This command prints a shell script that can be sourced by `bash` and
 that sets the variables and shell functions defined by the build
-process of *installable*. This allows you to get a similar build
+process of [*installable*](../../glossary.md#gloss-installable). This allows you to get a similar build
 environment in your current shell rather than in a subshell (as with
 `nix develop`).
 

src/nix/profile-install.md

@@ -29,6 +29,6 @@ R""(
 
 # Description
 
-This command adds *installables* to a Nix profile.
+This command adds [*installables*](../../glossary.md#gloss-installable) to a Nix profile.
 
 )""

src/nix/run.md

@@ -35,7 +35,7 @@ R""(
 
 # Description
 
-`nix run` builds and runs *installable*, which must evaluate to an
+`nix run` builds and runs [*installable*](../../glossary.md#gloss-installable), which must evaluate to an
 *app* or a regular Nix derivation.
 
 If *installable* evaluates to an *app* (see below), it executes the

src/nix/search.md

@@ -62,10 +62,10 @@ R""(
 
 # Description
 
-`nix search` searches *installable* (which must be evaluatable, e.g. a
-flake) for packages whose name or description matches all of the
+`nix search` searches [*installable*](../../glossary.md#gloss-installable) (which can be evaluated, that is, a
+flake or Nix expression, but not a store path or store derivation path) for packages whose name or description matches all of the
 regular expressions *regex*.  For each matching package, It prints the
-full attribute name (from the root of the installable), the version
+full attribute name (from the root of the [installable](../../glossary.md#gloss-installable)), the version
 and the `meta.description` field, highlighting the substrings that
 were matched by the regular expressions. If no regular expressions are
 specified, all packages are shown.

src/nix/shell.md

@@ -48,7 +48,7 @@ R""(
 # Description
 
 `nix shell` runs a command in an environment in which the `$PATH` variable
-provides the specified *installables*. If no command is specified, it starts the
+provides the specified [*installables*](../../glossary.md#gloss-installable). If no command is specified, it starts the
 default shell of your user account specified by `$SHELL`.
 
 )""

src/nix/show-derivation.md

@@ -37,7 +37,7 @@ R""(
 # Description
 
 This command prints on standard output a JSON representation of the
-store derivations to which *installables* evaluate. Store derivations
+store derivations to which [*installables*](../../glossary.md#gloss-installable) evaluate. Store derivations
 are used internally by Nix. They are store paths with extension `.drv`
 that represent the build-time dependency graph to which a Nix
 expression evaluates.

src/nix/store-delete.md

@@ -10,7 +10,7 @@ R""(
 
 # Description
 
-This command deletes the store paths specified by *installables*. ,
+This command deletes the store paths specified by [*installables*](../../glossary.md#gloss-installable),
 but only if it is safe to do so; that is, when the path is not
 reachable from a root of the garbage collector. This means that you
 can only delete paths that would also be deleted by `nix store

src/nix/store-dump-path.md

@@ -18,6 +18,6 @@ R""(
 # Description
 
 This command generates a NAR file containing the serialisation of the
-store path *installable*. The NAR is written to standard output.
+store path [*installable*](../../glossary.md#gloss-installable). The NAR is written to standard output.
 
 )""

src/nix/store-repair.md

@@ -17,7 +17,7 @@ R""(
 # Description
 
 This command attempts to "repair" the store paths specified by
-*installables* by redownloading them using the available
+[*installables*](../../glossary.md#gloss-installable) by redownloading them using the available
 substituters. If no substitutes are available, then repair is not
 possible.
 

src/nix/verify.md

@@ -24,7 +24,7 @@ R""(
 
 # Description
 
-This command verifies the integrity of the store paths *installables*,
+This command verifies the integrity of the store paths [*installables*](../../glossary.md#gloss-installable),
 or, if `--all` is given, the entire Nix store. For each path, it
 checks that