make descriptions of each installable type an own subsection

this is easier to edit, provides anchors for free, and renders correctly
on the terminal without additional effort.

1 files changed, 89 insertions, 77 deletions

diff --git a/src/nix/nix.md b/src/nix/nix.md
index db60c59ff..14407428e 100644
--- a/src/nix/nix.md
+++ b/src/nix/nix.md
@@ -50,100 +50,112 @@ manual](https://nixos.org/manual/nix/stable/).
 
 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`
-
-  These have the form *flakeref*[`#`*attrpath*], where *flakeref* is a
-  flake reference 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
-  (e.g. `/path/to/my-flake` or `.` or `../foo`), or a full URL
-  (e.g. `github:nixos/nixpkgs` or `path:.`)
-
-  When the flake reference is a raw path (a path without any URL
-  scheme), it is interpreted as a `path:` or `git+file:` url in the following
-  way:
-  
-  - If the path is within a Git repository, then the url will be of the form
-    `git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
-    where `GIT_REPO_ROOT` is the path to the root of the git repository,
-    and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
-    root) of the closest parent of the given path that contains a `flake.nix` within
-    the git repository.
-    If no such directory exists, then Nix will error-out.
-    
-    Note that the search will only include files indexed by git. In particular, files
-    which are matched by `.gitignore` or have never been `git add`-ed will not be
-    available in the flake. If this is undesirable, specify `path:<directory>` explicitly;
-    
-    For example, if `/foo/bar` is a git repository with the following structure:
-    ```
-    .
-    └── baz
-        ├── blah
-        │   └── file.txt
-        └── flake.nix
-    ```
+the Nix store.
+
+For most commands, if no installable is specified, the default is `.`,
+i.e. Nix will operate on the default flake output attribute of the
+flake in the current directory.
+
+Here are the recognised types of installables:
+
+## 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
+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
+(e.g. `/path/to/my-flake` or `.` or `../foo`), or a full URL
+(e.g. `github:nixos/nixpkgs` or `path:.`)
+
+When the flake reference is a raw path (a path without any URL
+scheme), it is interpreted as a `path:` or `git+file:` url in the following
+way:
+
+- If the path is within a Git repository, then the url will be of the form
+  `git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]`
+  where `GIT_REPO_ROOT` is the path to the root of the git repository,
+  and `RELATIVE_FLAKE_DIR_PATH` is the path (relative to the directory
+  root) of the closest parent of the given path that contains a `flake.nix` within
+  the git repository.
+  If no such directory exists, then Nix will error-out.
+
+  Note that the search will only include files indexed by git. In particular, files
+  which are matched by `.gitignore` or have never been `git add`-ed will not be
+  available in the flake. If this is undesirable, specify `path:<directory>` explicitly;
+
+  For example, if `/foo/bar` is a git repository with the following structure:
+  ```
+  .
+  └── baz
+      ├── blah
+      │   └── file.txt
+      └── flake.nix
+  ```
 
   Then `/foo/bar/baz/blah` will resolve to `git+file:///foo/bar?dir=baz`
 
-  - If the supplied path is not a git repository, then the url will have the form
-    `path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
-    of the supplied path that contains a `flake.nix` file (within the same file-system).
-    If no such directory exists, then Nix will error-out.
-    
-    For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
-   `path:/foo/bar`
+- If the supplied path is not a git repository, then the url will have the form
+  `path:FLAKE_DIR_PATH` where `FLAKE_DIR_PATH` is the closest parent
+  of the supplied path that contains a `flake.nix` file (within the same file-system).
+  If no such directory exists, then Nix will error-out.
 
-  If *attrpath* is omitted, Nix tries some default values; for most
-  subcommands, the default is `packages.`*system*`.default`
-  (e.g. `packages.x86_64-linux.default`), but some subcommands have
-  other defaults. If *attrpath* *is* specified, *attrpath* is
-  interpreted as relative to one or more prefixes; for most
-  subcommands, these are `packages.`*system*,
-  `legacyPackages.*system*` and the empty prefix. Thus, on
-  `x86_64-linux` `nix build nixpkgs#hello` will try to build the
-  attributes `packages.x86_64-linux.hello`,
-  `legacyPackages.x86_64-linux.hello` and `hello`.
+  For example, if `/foo/bar/flake.nix` exists, then `/foo/bar/baz/` will resolve to
+ `path:/foo/bar`
 
-* **Store paths**: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
+If *attrpath* is omitted, Nix tries some default values; for most
+subcommands, the default is `packages.`*system*`.default`
+(e.g. `packages.x86_64-linux.default`), but some subcommands have
+other defaults. If *attrpath* *is* specified, *attrpath* is
+interpreted as relative to one or more prefixes; for most
+subcommands, these are `packages.`*system*,
+`legacyPackages.*system*` and the empty prefix. Thus, on
+`x86_64-linux` `nix build nixpkgs#hello` will try to build the
+attributes `packages.x86_64-linux.hello`,
+`legacyPackages.x86_64-linux.hello` and `hello`.
 
-  These are paths inside the Nix store, or symlinks that resolve to a
-  path in the Nix store.
+## Store paths
 
-* **Store derivations**: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
+Example: `/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10`
 
-  By default, if you pass a [store derivation] path to a `nix` subcommand, the command will operate on the [output path]s of the derivation.
+These are paths inside the Nix store, or symlinks that resolve to a
+path in the Nix store.
 
-  [output path]: ../../glossary.md#gloss-output-path
+## Store derivations
 
-  For example, `nix path-info` prints information about the output paths:
+Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv`
 
-  ```console
-  # nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
-  [{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
-  ```
+By default, if you pass a [store derivation] path to a `nix` subcommand, the command will operate on the [output path]s of the derivation.
 
-  If you want to operate on the store derivation itself, pass the
-  `--derivation` flag.
+[output path]: ../../glossary.md#gloss-output-path
 
-* **Nix attributes**: `--file /path/to/nixpkgs hello`
+For example, `nix path-info` prints information about the output paths:
 
-  When the `-f` / `--file` *path* option is given, installables are
-  interpreted as attribute paths referencing a value returned by
-  evaluating the Nix file *path*.
+```console
+# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
+[{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
+```
 
-* **Nix expressions**: `--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'`.
+If you want to operate on the store derivation itself, pass the
+`--derivation` flag.
 
-  When the `--expr` option is given, all installables are interpreted
-  as Nix expressions. You may need to specify `--impure` if the
-  expression references impure inputs (such as `<nixpkgs>`).
+## Nix attributes
 
-For most commands, if no installable is specified, the default is `.`,
-i.e. Nix will operate on the default flake output attribute of the
-flake in the current directory.
+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
+
+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
+expression references impure inputs (such as `<nixpkgs>`).
 
 ## Derivation output selection