docs: document the cursed file syntax for new CLI

This documents that all installables in the nix3 commands, in their
--file/-f form accept an extended syntax for the file argument,
which is the same as it is for nix-build and friends, some of which were
well known in their nix-build forms (e.g. `nix-build '<nixpkgs>' -A hello)
but are not well known in their nix3 forms (people rarely know that you
can `nix build -f '<nixpkgs>' firefox`).

Like the old CLI syntax, as documented in [1], file arguments also
accept https:// tarball URLs, `flake:` prefixed flakerefs, and the
cursed `channel:` prefixed hardened URLs.

[1]: Ib6d68594a16132805ba5d97526e16f7b3633117e

Change-Id: Ib81a5db1f60d5916f0f792d82054f3ac65717121

doc/manual/src/command-ref/fileish-summary.md

@@ -4,6 +4,7 @@
   this also links to nix-build.md for the full explanation.
 
   This include file is manually duplicated in nix-env/opt-common.md because list indentation sadness.
+  It is also manually duplicated in src/nix/nix.md, because those files don't support include?? busted.
 -->
 - A normal filesystem path, like `/home/meow/nixfiles/default.nix`
   - Or a directory, like `/home/meow/nixfiles`, equivalent to above

src/nix/nix.md

@@ -158,16 +158,61 @@ Example: `/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv^*`
 
 Example: `--file /path/to/nixpkgs hello`
 
-When the option `-f` / `--file` *path* \[*attrpath*...\] is given, installables are interpreted as the value of the expression in the Nix file at *path*.
+When the option `-f` / `--file` *fileish* \[*attrpath*...\] is given, installables are interpreted as the value of the Nix file specified by *fileish*.
 If attribute paths are provided, commands will operate on the corresponding values accessible at these paths.
 The Nix expression in that file, or any selected attribute, must evaluate to a derivation.
 
+The *fileish* itself may take one of a few different forms, the first being a simple filesystem path, e.g. `nix build -f /tmp/some-file.nix`.
+Like the [import builtin](../../language/builtins.md#builtins-import), specifying a directory is equivalent to specify `default.nix` within that directory.
+It may also be a [search path](../env-common.md#env-NIX_PATH) (also known as a lookup path), like `<nixpkgs>`.
+Unlike using `<nixpkgs>` in a `--expr` argument, this does not require `--impure`.
+
 To emulate the `nix-build '<nixpkgs>' -A hello` pattern, use:
 
 ```console
 $ nix build -f '<nixpkgs>' hello
 ```
 
+If a *fileish* 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 a 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 -f "https://github.com/NixOS/nixpkgs/archive/refs/heads/release-23.11.tar.gz" firefox
+```
+
+If a *fileish* starts with `flake:`, the rest of the argument is interpreted as a [flakeref](./nix3-flake.md#flake-reference) (see `nix flake --help` or `man nix3-flake`), which requires the "flakes" experimental feature to be enabled.
+This is is *not quite* the same as specifying a [flake output attrpath](#flake-output-attribute).
+It does *not* access the flake directly, but instead fetches it and `import`s the unpacked directory.
+In other words, it assumes that the flake has a `default.nix` file, and then interprets the attribute path relative to what `default.nix` evaluates to.
+
+For many flakes — including Nixpkgs — this will end up evaluating to the same thing.
+These two commands build the same derivation, but one from the flake, and the other from `default.nix`:
+
+```console
+$ nix build 'nixpkgs#firefox' # from flake.nix
+$ nix build -f flake:nixpkgs firefox # from default.nix in the flake directory
+```
+
+Finally, for legacy reasons, if a *fileish* 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.gz`.
+This is a **hard coded URL** pattern and is *not* related to the subscribed channels managed by the [nix-channel](../nix-channel.md) command.
+
+> **Note**: any of the special syntaxes may always be disambiguated by prefixing the path.
+> For example: a file in the current directory literally called `<nixpkgs>` can be addressed as `./<nixpkgs>`, to escape the special interpretation.
+
+<!--
+  NOTE: this summary is manually duplicated from doc/manual/src/command-ref/fileish-summary.md, because includes don't work in this file?? busted.
+-->
+In summary, a file path argument may be one of:
+
+- A normal filesystem path, like `/home/meow/nixfiles/default.nix`
+  - Or a directory, like `/home/meow/nixfiles`, equivalent to above
+- A single lookup path, like `<nixpkgs>` or `<nixos>`
+- A URL to a tarball, like `https://github.com/NixOS/nixpkgs/archive/refs/heads/release-23.11.tar.gz`
+- A [flakeref](@docroot@/command-ref/new-cli/nix3-flake.md#flake-references), introduced by the prefix `flake:`, like `flake:git+https://git.lix.systems/lix-project/lix`
+- A channel name, introduced by the prefix `channel:`, like `channel:nixpkgs-unstable`.
+  - This uses a hard-coded URL pattern and is *not* related to the subscribed channels managed by the [nix-channel](@docroot@/command-ref/nix-channel.md) command.
+
 ### Nix expression
 
 Example: `--expr 'import <nixpkgs> {}' hello`