From 1796c9fb20b808c89a8f167157a9bbf64cef0960 Mon Sep 17 00:00:00 2001
From: Qyriad <qyriad@qyriad.me>
Date: Mon, 20 May 2024 22:21:14 -0600
Subject: [PATCH] docs: document lookupFileArg syntax in nix-build

Change-Id: Ib6d68594a16132805ba5d97526e16f7b3633117e
---
 doc/manual/src/command-ref/nix-build.md | 38 ++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index 92e642ddd..5baa86e47 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -29,10 +29,40 @@ created (`result`, `result-2`, and so on).
 If no *paths* are specified, then `nix-build` will use `default.nix` in
 the current directory, if it exists.
 
-If an element of *paths* 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 include a single top-level
-directory containing at least a file named `default.nix`.
+## Path Syntax
+
+A given element of *paths* may take one of a few different forms, the first being a simple filesystem path, e.g. `nix-build /tmp/some-file.nix`.
+It may also be a [search path](./env-common.html#env-NIX_PATH) like `<nixpkgs>`, which is convenient to use with `--attr`/`-A`:
+
+```console
+$ nix-build '<nixpkgs>' -A firefox
+```
+
+(Note the quotation marks around `<nixpkgs>`, which will be necessary in most Unix shells.)
+
+If an element of *paths* starts with `http://` or `https://`, it is interpreted as the URL of a tarball which will be fetched and unpacked.
+Lix will then `import` the unpacked directory, so these tarballs must include at least single top-level directory with a file called `default.nix`
+For example, you could build from a specific version of Nixpkgs with something like:
+
+```console
+$ nix-build "https://github.com/NixOS/nixpkgs/archive/refs/heads/release-23.11.tar.gz" -A firefox
+```
+
+If a path starts with `flake:`, the rest of the argument is interpreted as a [flakeref](./new-cli/nix3-flake.html#flake-references) (see `nix flake --help` or `man nix3-flake`), which requires the "flakes" experimental feature to be enabled.
+Lix will fetch the flake, and then `import` its unpacked directory, so the flake must include a file called `default.nix`.
+For example, the flake analogue to the above `nix-build` commands are:
+
+```console
+$ nix-build flake:nixpkgs -A firefox
+$ nix-build flake:github:NixOS/nixpkgs/release-23.11 -A firefox
+```
+
+Finally, for legacy reasons, if a path starts with `channel:`, the rest of the argument is interpreted as the name of a channel to fetch from `https://nixos.org/channels/$CHANNEL_NAME/nixexprs.tar.xz`.
+
+> **NOTE:**: any of the special syntaxes may always be disambiguated by prefixing the path.
+> For example: a file in the current directory called `<nixpkgs>'` can be addressed as `./<nixpkgs>`, to escape the special interpretation.
+
+## Notes
 
 `nix-build` is essentially a wrapper around
 [`nix-instantiate`](nix-instantiate.md) (to translate a high-level Nix