From e558e089badf2592d1e4540b2fc884a8001a7c06 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 12 Dec 2022 12:51:23 +0100
Subject: [PATCH] -I description: Use -I examples

---
 src/libcmd/common-eval-args.cc | 36 +++++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/src/libcmd/common-eval-args.cc b/src/libcmd/common-eval-args.cc
index 53595cea6..dc0de4b9f 100644
--- a/src/libcmd/common-eval-args.cc
+++ b/src/libcmd/common-eval-args.cc
@@ -36,21 +36,29 @@ MixEvalArgs::MixEvalArgs()
   Add *path* to the Nix search path. The Nix search path is
   initialized from the colon-separated [`NIX_PATH`](./env-common.md#env-NIX_PATH) environment
   variable, and is used to look up the location of Nix expressions using [paths](../language/values.md#type-path) enclosed in angle
-  brackets (i.e., `<nixpkgs>`). For instance, if the Nix search path
-  consists of the entries
+  brackets (i.e., `<nixpkgs>`).
+
+  For instance, passing
 
   ```
-  /home/eelco/Dev
-  /etc/nixos
+  -I /home/eelco/Dev
+  -I /etc/nixos
   ```
 
-  Nix will look for paths relative to `/home/eelco/Dev` and
-  `/etc/nixos`, in this order. It is also possible to match paths
-  against a prefix. For example, the search path
+  will cause Nix to look for paths relative to `/home/eelco/Dev` and
+  `/etc/nixos`, in that order. This is equivalent to setting the
+  `NIX_PATH` environment variable to
 
   ```
-  nixpkgs=/home/eelco/Dev/nixpkgs-branch
-  /etc/nixos
+  /home/eelco/Dev:/etc/nixos
+  ```
+
+  It is also possible to match paths against a prefix. For example,
+  passing
+
+  ```
+  -I nixpkgs=/home/eelco/Dev/nixpkgs-branch
+  -I /etc/nixos
   ```
 
   will cause Nix to search for `<nixpkgs/path>` in
@@ -59,10 +67,10 @@ MixEvalArgs::MixEvalArgs()
   If a path in the Nix search path starts with `http://` or `https://`,
   it is interpreted as the URL of a tarball that will be downloaded and
   unpacked to a temporary location. The tarball must consist of a single
-  top-level directory. For example, setting `NIX_PATH` to
+  top-level directory. For example, passing
 
   ```
-  nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz
+  -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/master.tar.gz
   ```
 
   tells Nix to download and use the current contents of the `master`
@@ -71,11 +79,11 @@ MixEvalArgs::MixEvalArgs()
   The URLs of the tarballs from the official `nixos.org` channels
   (see [the manual page for `nix-channel`](nix-channel.md)) can be
   abbreviated as `channel:<channel-name>`.  For instance, the
-  following two values of `NIX_PATH` are equivalent:
+  following two flags are equivalent:
 
   ```
-  nixpkgs=channel:nixos-21.05
-  nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz
+  -I nixpkgs=channel:nixos-21.05
+  -I nixpkgs=https://nixos.org/channels/nixos-21.05/nixexprs.tar.xz
   ```
   )",
         .category = category,