Expand documentation for `experimental-features`

Adds examples and additional information to the `impure-derivations`,
`recursive-nix`, and `no-url-literals` experimental feature
documentation.

1 files changed, 97 insertions, 14 deletions

diff --git a/src/libutil/experimental-features.cc b/src/libutil/experimental-features.cc
index 010ab1d68..b7879ff69 100644
--- a/src/libutil/experimental-features.cc
+++ b/src/libutil/experimental-features.cc
@@ -17,9 +17,9 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
         .tag = Xp::CaDerivations,
         .name = "ca-derivations",
         .description = R"(
-            Allow derivations to be content-addressed in order to prevent rebuilds
-            when changes to the derivation do not result in changes to the
-            derivation's output. See
+            Allow derivations to be content-addressed in order to prevent
+            rebuilds when changes to the derivation do not result in changes to
+            the derivation's output. See
             [__contentAddressed](@docroot@/language/advanced-attributes.md#adv-attr-__contentAddressed)
             for details.
         )",
@@ -28,17 +28,36 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
         .tag = Xp::ImpureDerivations,
         .name = "impure-derivations",
         .description = R"(
-            Allows derivations to produce non-fixed outputs by setting the `__impure`
-            derivation attribute to `true`. See [these release
-            notes](../release-notes/rl-2.8.md) for an example.
+            Allow derivations to produce non-fixed outputs by setting the
+            `__impure` derivation attribute to `true`. An impure derivation can
+            have differing outputs each time it is built.
+
+            Example:
+
+            ```
+            derivation {
+              name = "impure";
+              builder = /bin/sh;
+              __impure = true; # mark this derivation as impure
+              args = [ "-c" "read -n 10 random < /dev/random; echo $random > $out" ];
+              system = builtins.currentSystem;
+            }
+            ```
+
+            Each time this derivation is built, it can produce a different
+            output (as the builder outputs random bytes to `$out`).  Impure
+            derivations also have access to the network, and only fixed-output
+            or other impure derivations can rely on impure derivations. Finally,
+            an impure derivation cannot also be
+            [content-addressed](#xp-feature-ca-derivations).
         )",
     },
     {
         .tag = Xp::Flakes,
         .name = "flakes",
         .description = R"(
-            Enable flakes. See the manual entry for
-            [`nix flake`](../command-ref/new-cli/nix3-flake.md) for details.
+            Enable flakes. See the manual entry for [`nix
+            flake`](../command-ref/new-cli/nix3-flake.md) for details.
         )",
     },
     {
@@ -53,18 +72,82 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
         .tag = Xp::RecursiveNix,
         .name = "recursive-nix",
         .description = R"(
-            Allow Nix derivations to call Nix in order to recursively build derivations.
-            See [this
-            commit](https://github.com/edolstra/nix/commit/1a27aa7d64ffe6fc36cfca4d82bdf51c4d8cf717)
-            for more info.
+            Allow derivation builders to call Nix, and thus build derivations
+            recursively.
+
+            Example:
+
+            ```
+            with import <nixpkgs> {};
+
+            runCommand "foo"
+              {
+                 buildInputs = [ nix jq ];
+                 NIX_PATH = "nixpkgs=${<nixpkgs>}";
+              }
+              ''
+                hello=$(nix-build -E '(import <nixpkgs> {}).hello.overrideDerivation (args: { name = "recursive-hello"; })')
+
+                mkdir -p $out/bin
+                ln -s $hello/bin/hello $out/bin/hello
+              ''
+            ```
+
+            An important restriction on recursive builders is disallowing
+            arbitrary substitutions. For example, running
+
+            ```
+            nix-store -r /nix/store/kmwd1hq55akdb9sc7l3finr175dajlby-hello-2.10
+            ```
+
+            in the above `runCommand` script would be disallowed, as this could
+            lead to derivations with hidden dependencies or breaking
+            reproducibility by relying on the current state of the Nix store. An
+            exception would be if
+            `/nix/store/kmwd1hq55akdb9sc7l3finr175dajlby-hello-2.10` were
+            already in the build inputs or built by a previous recursive Nix
+            call.
         )",
     },
     {
         .tag = Xp::NoUrlLiterals,
         .name = "no-url-literals",
         .description = R"(
-            Disallows unquoted URLs as part of the Nix language syntax. See [RFC
-            45](https://github.com/NixOS/rfcs/pull/45) for more info.
+            Disallow unquoted URLs as part of the Nix language syntax. The Nix
+            language allows for URL literals, like so:
+
+            ```
+            $ nix repl
+            Welcome to Nix 2.15.0. Type :? for help.
+
+            nix-repl> http://foo
+            "http://foo"
+            ```
+
+            But enabling this experimental feature will cause the Nix parser to
+            throw an error when encountering a URL literal:
+
+            ```
+            $ nix repl --extra-experimental-features 'no-url-literals'
+            Welcome to Nix 2.15.0. Type :? for help.
+
+            nix-repl> http://foo
+            error: URL literals are disabled
+
+            at «string»:1:1:
+
+            1| http://bar
+             | ^
+
+            ```
+
+            While this is currently an experimental feature, unquoted URLs are
+            being deprecated and their usage is discouraged.
+
+            The reason is that, as opposed to path literals, URLs have no
+            special properties that distinguish them from regular strings, URLs
+            containing parameters have to be quoted anyway, and unquoted URLs
+            may confuse external tooling.
         )",
     },
     {