remove the misleading warning on using `nix-env` for split outputs (#255947)

The text was originally added [0] following an apparently incomplete
research on how everything plays together. In fact, Nix propagates
`outputs` to the corresponding nested derivations, and there is some
messy behavior in Nixpkgs that only seems to propagate
`meta.outputsToInstall` in `buildEnv`[1].

This change moves the hints on how to use NixOS specifics to NixOS
module documentation (which is hopefully easier to find through
search.nixos.org), describes the default behavior in Nixpkgs (updating
a the link to the source), and removes the confusing mention of
`nix-env`.

the last of them should not be there to begin with. we don't want
beginners to use `nix-env`, as this is known to run them into trouble
eventually.

[0]: https://github.com/NixOS/nixpkgs/pull/76794
[1]: https://github.com/NixOS/nixpkgs/blob/1774d07242995050d2d8a91cb4da0855eac2e472/pkgs/build-support/buildenv/default.nix#L66

1 files changed, 8 insertions, 2 deletions

diff --git a/nixos/modules/config/system-path.nix b/nixos/modules/config/system-path.nix
index e8bbeac4f72..222da3e02e8 100644
--- a/nixos/modules/config/system-path.nix
+++ b/nixos/modules/config/system-path.nix
@@ -116,8 +116,14 @@ in
       extraOutputsToInstall = mkOption {
         type = types.listOf types.str;
         default = [ ];
-        example = [ "doc" "info" "devdoc" ];
-        description = lib.mdDoc "List of additional package outputs to be symlinked into {file}`/run/current-system/sw`.";
+        example = [ "dev" "info" ];
+        description = lib.mdDoc ''
+          Entries listed here will be appended to the `meta.outputsToInstall` attribute for each package in `environment.systemPackages`, and the files from the corresponding derivation outputs symlinked into {file}`/run/current-system/sw`.
+
+          For example, this can be used to install the `dev` and `info` outputs for all packages in the system environment, if they are available.
+
+          To use specific outputs instead of configuring them globally, select the corresponding attribute on the package derivation, e.g. `libxml2.dev` or `coreutils.info`.
+        '';
       };
 
       extraSetup = mkOption {