From 0301b8fc7354a94dc03b57f796bfa6e853758af8 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 30 Nov 2023 21:59:08 +0100
Subject: [PATCH] reword the experimental feature notice

- put the highlight box around all the relevant instructions
- simplify the wording
- make the link more prominent by using the whole phrase for the link text
---
 doc/manual/generate-settings.nix   | 21 ++++++-------
 doc/manual/generate-store-info.nix | 48 +++++++++++++++---------------
 2 files changed, 35 insertions(+), 34 deletions(-)

diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
index 3add10075..74446b70b 100644
--- a/doc/manual/generate-settings.nix
+++ b/doc/manual/generate-settings.nix
@@ -31,18 +31,19 @@ let
 
       experimentalFeatureNote = optionalString (experimentalFeature != null) ''
           > **Warning**
+          >
           > This setting is part of an
           > [experimental feature](@docroot@/contributing/experimental-features.md).
-
-          To change this setting, you need to make sure the corresponding experimental feature,
-          [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
-          is enabled.
-          For example, include the following in [`nix.conf`](#):
-
-          ```
-          extra-experimental-features = ${experimentalFeature}
-          ${setting} = ...
-          ```
+          >
+          > To change this setting, make sure the
+          > [`${experimentalFeature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature})
+          > is enabled.
+          > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
+          >
+          > ```
+          > extra-experimental-features = ${experimentalFeature}
+          > ${setting} = ...
+          > ```
         '';
 
       showDefault = documentDefault: defaultValue:
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
index 73defcb71..8e26edb65 100644
--- a/doc/manual/generate-store-info.nix
+++ b/doc/manual/generate-store-info.nix
@@ -1,6 +1,6 @@
 let
   inherit (builtins) attrValues mapAttrs;
-  inherit (import <nix/utils.nix>) concatStrings optionalString;
+  inherit (import <nix/utils.nix>) concatStrings optionalString squash;
   showSettings = import <nix/generate-settings.nix>;
 in
 
@@ -10,36 +10,36 @@ let
 
   showStore = name: { settings, doc, experimentalFeature }:
     let
+      result = squash ''
+        # ${name}
 
-    result = ''
-      ## ${name}
+        ${doc}
 
-      ${doc}
+        ${experimentalFeatureNote}
 
-      ${experimentalFeatureNote}
+        ## Settings
 
-      ### Settings
-
-      ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
-    '';
+        ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
+      '';
 
       # markdown doesn't like spaces in URLs
       slug = builtins.replaceStrings [ " " ] [ "-" ] name;
 
-    experimentalFeatureNote = optionalString (experimentalFeature != null) ''
-      > **Warning**
-      > This store is part of an
-      > [experimental feature](@docroot@/contributing/experimental-features.md).
-
-      To use this store, you need to make sure the corresponding experimental feature,
-      [`${experimentalFeature}`](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature}),
-      is enabled.
-      For example, include the following in [`nix.conf`](#):
-
-      ```
-      extra-experimental-features = ${experimentalFeature}
-      ```
-    '';
-  in result;
+      experimentalFeatureNote = optionalString (experimentalFeature != null) ''
+        > **Warning**
+        >
+        > This store is part of an
+        > [experimental feature](@docroot@/contributing/experimental-features.md).
+        >
+        > To use this store, make sure the
+        > [`${experimentalFeature}` experimental feature](@docroot@/contributing/experimental-features.md#xp-feature-${experimentalFeature})
+        > is enabled.
+        > For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
+        >
+        > ```
+        > extra-experimental-features = ${experimentalFeature}
+        > ```
+      '';
+    in result;
 
 in concatStrings (attrValues (mapAttrs showStore storesInfo))