reword documentation on nix-path config option (#7772)

* docs: unify documentation on search paths

- put all the information on search path semantics into `builtins.findFile`
- put all the information on determining the value of `builtins.nixPath` into the
  `nix-path` setting

  maybe `builtins.nixPath` is a better place for this, but those bits
  can still be moved around now that it's all next to each other.
- link to the syntax page for lookup paths from all places that are
  concerned with it
- add or clarify examples
- add a test verifying a claim from documentation

doc/manual/src/command-ref/env-common.md

@@ -9,22 +9,26 @@ Most Nix commands interpret the following environment variables:
 
 - <span id="env-NIX_PATH">[`NIX_PATH`](#env-NIX_PATH)</span>
 
-  A colon-separated list of directories used to look up the location of Nix
-  expressions using [paths](@docroot@/language/types.md#type-path)
-  enclosed in angle brackets (i.e., `<path>`),
-  e.g. `/home/eelco/Dev:/etc/nixos`. It can be extended using the
-  [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
+  A colon-separated list of search path entries used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
 
-  If `NIX_PATH` is not set at all, Nix will fall back to the following list in [impure](@docroot@/command-ref/conf-file.md#conf-pure-eval) and [unrestricted](@docroot@/command-ref/conf-file.md#conf-restrict-eval) evaluation mode:
+  This environment variable overrides the value of the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path).
 
-  1. `$HOME/.nix-defexpr/channels`
-  2. `nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixpkgs`
-  3. `/nix/var/nix/profiles/per-user/root/channels`
+  It can be extended using the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I).
+
+  > **Example**
+  >
+  > ```bash
+  > $ export NIX_PATH=`/home/eelco/Dev:nixos-config=/etc/nixos
+  > ```
 
   If `NIX_PATH` is set to an empty string, resolving search paths will always fail.
-  For example, attempting to use `<nixpkgs>` will produce:
 
-      error: file 'nixpkgs' was not found in the Nix search path
+  > **Example**
+  >
+  > ```bash
+  > $ NIX_PATH= nix-instantiate --eval '<nixpkgs>'
+  > error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)
+  > ```
 
 - <span id="env-NIX_IGNORE_SYMLINK_STORE">[`NIX_IGNORE_SYMLINK_STORE`](#env-NIX_IGNORE_SYMLINK_STORE)</span>
 

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

@@ -37,7 +37,7 @@ Most Nix commands accept the following command-line options:
     Print even more informational messages.
 
   - `4` “Debug”
-   
+
     Print debug information.
 
   - `5` “Vomit”
@@ -187,11 +187,12 @@ Most Nix commands accept the following command-line options:
   For `nix-shell`, this option is commonly used to give you a shell in which you can build the packages returned by the expression.
   If you want to get a shell which contain the *built* packages ready for use, give your expression to the `nix-shell --packages ` convenience flag instead.
 
-- <span id="opt-I">[`-I`](#opt-I)</span> *path*
+- <span id="opt-I">[`-I` / `--include`](#opt-I)</span> *path*
 
-  Add an entry to the [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path).
+  Add an entry to the list of search paths used to resolve [lookup paths](@docroot@/language/constructs/lookup-path.md).
   This option may be given multiple times.
-  Paths added through `-I` take precedence over [`NIX_PATH`](@docroot@/command-ref/env-common.md#env-NIX_PATH).
+
+  Paths added through `-I` take precedence over the [`nix-path` configuration setting](@docroot@/command-ref/conf-file.md#conf-nix-path) and the [`NIX_PATH` environment variable](@docroot@/command-ref/env-common.md#env-NIX_PATH).
 
 - <span id="opt-option">[`--option`](#opt-option)</span> *name* *value*