reword nix-env documentation (#10718)

* reword `nix-env` documentation

- added links
- added an overview of package sources
- clarified parsing and matching of package names

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

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

@@ -47,39 +47,83 @@ These pages can be viewed offline:
 
   Example: `nix-env --help --install`
 
+# Package sources
+
+`nix-env` can obtain packages from multiple sources:
+
+- An attribute set of derivations from:
+  - The [default Nix expression](@docroot@/command-ref/files/default-nix-expression.md) (by default)
+  - A Nix file, specified via `--file`
+  - A [profile](@docroot@/command-ref/files/profiles.md), specified via `--from-profile`
+  - A Nix expression that is a function which takes default expression as argument, specified via `--from-expression`
+- A [store path](@docroot@/store/store-path.md)
+
 # Selectors
 
-Several commands, such as `nix-env --query ` and `nix-env --install `, take a list of
+Several operations, such as [`nix-env --query`](./nix-env/query.md) and [`nix-env --install`](./nix-env/install.md), take a list of *arguments* that specify the packages on which to operate.
-arguments that specify the packages on which to operate. These are
-extended regular expressions that must match the entire name of the
-package. (For details on regular expressions, see **regex**(7).) The match is
-case-sensitive. The regular expression can optionally be followed by a
-dash and a version number; if omitted, any version of the package will
-match. Here are some examples:
 
-  - `firefox`\
+Packages are identified based on a `name` part and a `version` part of a [symbolic derivation name](@docroot@/language/derivations.md#attr-names):
-    Matches the package name `firefox` and any version.
 
-  - `firefox-32.0`\
+- `name`: Everything up to but not including the first dash (`-`) that is *not* followed by a letter.
-    Matches the package name `firefox` and version `32.0`.
+- `version`: The rest, excluding the separating dash.
 
-  - `gtk\\+`\
+> **Example**
-    Matches the package name `gtk+`. The `+` character must be escaped
+>
-    using a backslash to prevent it from being interpreted as a
+> `nix-env` parses the symbolic derivation name `apache-httpd-2.0.48` as:
-    quantifier, and the backslash must be escaped in turn with another
+>
-    backslash to ensure that the shell passes it on.
+> ```json
+> {
+>   "name": "apache-httpd",
+>   "version": "2.0.48"
+> }
+> ```
 
-  - `.\*`\
+> **Example**
-    Matches any package name. This is the default for most commands.
+>
+> `nix-env` parses the symbolic derivation name `firefox.*` as:
+>
+> ```json
+> {
+>   "name": "firefox.*",
+>   "version": ""
+> }
+> ```
 
-  - `'.*zip.*'`\
+The `name` parts of the *arguments* to `nix-env` are treated as extended regular expressions and matched against the `name` parts of derivation names in the package source.
-    Matches any package name containing the string `zip`. Note the dots:
+The match is case-sensitive.
-    `'*zip*'` does not work, because in a regular expression, the
+The regular expression can optionally be followed by a dash (`-`) and a version number; if omitted, any version of the package will match.
-    character `*` is interpreted as a quantifier.
+For details on regular expressions, see [**regex**(7)](https://linux.die.net/man/7/regex).
 
-  - `'.*(firefox|chromium).*'`\
+> **Example**
-    Matches any package name containing the strings `firefox` or
+>
-    `chromium`.
+> Common patterns for finding package names with `nix-env`:
+>
+> - `firefox`
+>
+>   Matches the package name `firefox` and any version.
+>
+> - `firefox-32.0`
+>
+>   Matches the package name `firefox` and version `32.0`.
+>
+> - `gtk\\+`
+>
+>   Matches the package name `gtk+`.
+>   The `+` character must be escaped using a backslash (`\`) to prevent it from being interpreted as a quantifier, and the backslash must be escaped in turn with another backslash to ensure that the shell passes it on.
+>
+> - `.\*`
+>
+>   Matches any package name.
+>   This is the default for most commands.
+>
+> - `'.*zip.*'`
+>
+>   Matches any package name containing the string `zip`.
+>   Note the dots: `'*zip*'` does not work, because in a regular expression, the character `*` is interpreted as a quantifier.
+>
+> - `'.*(firefox|chromium).*'`
+>
+>   Matches any package name containing the strings `firefox` or `chromium`.
 
 # Files
 

doc/manual/src/command-ref/nix-env/install.md

@@ -14,14 +14,13 @@
 
 # Description
 
-The install operation creates a new user environment.
+The `--install` operation creates a new user environment.
 It is based on the current generation of the active [profile](@docroot@/command-ref/files/profiles.md), to which a set of [store paths] described by *args* is added.
 
 [store paths]: @docroot@/glossary.md#gloss-store-path
 
 The arguments *args* map to store paths in a number of possible ways:
 
-
   - By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
     These are [realised], and the resulting output paths are installed.
     Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.