always show anchors on setting listings

refactor the templates for readability

doc/manual/generate-manpage.nix

@@ -2,7 +2,8 @@ let
   inherit (builtins)
     attrNames attrValues fromJSON listToAttrs mapAttrs groupBy
     concatStringsSep concatMap length lessThan replaceStrings sort;
-  inherit (import ./utils.nix) attrsToList concatStrings optionalString filterAttrs trim squash unique showSettings;
+  inherit (import ./utils.nix) attrsToList concatStrings optionalString filterAttrs trim squash unique;
+  showStoreDocs = import ./generate-store-info.nix;
 in
 
 commandDump:
@@ -30,7 +31,7 @@ let
 
         ${maybeSubcommands}
 
-        ${maybeDocumentation}
+        ${maybeStoreDocs}
 
         ${maybeOptions}
       '';
@@ -40,15 +41,15 @@ let
           showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
           arguments = concatStringsSep " " (map showArgument args);
         in ''
-         `${command}` [*option*...] ${arguments}
+          `${command}` [*option*...] ${arguments}
         '';
 
       maybeSubcommands = optionalString (details ? commands && details.commands != {})
-         ''
+        ''
-           where *subcommand* is one of the following:
+          where *subcommand* is one of the following:
 
-           ${subcommands}
+          ${subcommands}
-         '';
+        '';
 
       subcommands = if length categories > 1
         then listCategories
@@ -70,10 +71,11 @@ let
         * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
       '';
 
-      # TODO: move this confusing special case out of here when implementing #8496
+      # FIXME: this is a hack.
-      maybeDocumentation = optionalString
+      # store parameters should not be part of command documentation to begin
-        (details ? doc)
+      # with, but instead be rendered on separate pages.
-        (replaceStrings ["@stores@"] [storeDocs] details.doc);
+      maybeStoreDocs = optionalString (details ? doc)
+        (replaceStrings [ "@stores@" ] [ (showStoreDocs commandInfo.stores) ] details.doc);
 
       maybeOptions = let
         allVisibleOptions = filterAttrs
@@ -147,35 +149,4 @@ let
       "    - [${page.command}](command-ref/new-cli/${page.name})";
     in concatStringsSep "\n" (map showEntry manpages) + "\n";
 
-  storeDocs =
-    let
-      showStore = name: { settings, doc, experimentalFeature }:
-        let
-          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`](@docroot@/command-ref/conf-file.md):
-
-            ```
-            extra-experimental-features = ${experimentalFeature}
-            ```
-          '';
-        in ''
-          ## ${name}
-
-          ${doc}
-
-          ${experimentalFeatureNote}
-
-          **Settings**:
-
-          ${showSettings { useAnchors = false; } settings}
-        '';
-    in concatStrings (attrValues (mapAttrs showStore commandInfo.stores));
-
 in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }

doc/manual/generate-settings.nix

@@ -0,0 +1,63 @@
+let
+  inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
+  inherit (import ./utils.nix) concatStrings indent optionalString squash;
+in
+
+prefix: settingsInfo:
+
+let
+
+  showSetting = prefix: setting: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
+    let
+      result = squash ''
+          - <span id="${prefix}-${setting}">[`${setting}`](#${prefix}-${setting})</span>
+
+          ${indent "  " body}
+        '';
+
+      # separate body to cleanly handle indentation
+      body = ''
+          ${description}
+
+          ${experimentalFeatureNote}
+
+          **Default:** ${showDefault documentDefault defaultValue}
+
+          ${showAliases aliases}
+        '';
+
+      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} = ...
+          ```
+        '';
+
+      showDefault = documentDefault: defaultValue:
+        if documentDefault then
+          # a StringMap value type is specified as a string, but
+          # this shows the value type. The empty stringmap is `null` in
+          # JSON, but that converts to `{ }` here.
+          if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
+            then "*empty*"
+            else if isBool defaultValue then
+              if defaultValue then "`true`" else "`false`"
+            else "`${toString defaultValue}`"
+        else "*machine-specific*";
+
+      showAliases = aliases:
+          optionalString (aliases != [])
+            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
+
+    in result;
+
+in concatStrings (attrValues (mapAttrs (showSetting prefix) settingsInfo))

doc/manual/generate-store-info.nix

@@ -0,0 +1,45 @@
+let
+  inherit (builtins) attrValues mapAttrs;
+  inherit (import ./utils.nix) concatStrings optionalString;
+  showSettings = import ./generate-settings.nix;
+in
+
+storesInfo:
+
+let
+
+  showStore = name: { settings, doc, experimentalFeature }:
+    let
+
+    result = ''
+      ## ${name}
+
+      ${doc}
+
+      ${experimentalFeatureNote}
+
+      ### Settings
+
+      ${showSettings "store-${slug}" 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;
+
+in concatStrings (attrValues (mapAttrs showStore storesInfo))

doc/manual/local.mk

@@ -96,14 +96,14 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/sr
 	@cp $< $@
 	@$(call process-includes,$@,$@)
 
-$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(bindir)/nix
+$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(d)/generate-settings.nix $(d)/generate-store-info.nix $(bindir)/nix
 	@rm -rf $@ $@.tmp
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)'
 	@mv $@.tmp $@
 
-$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(bindir)/nix
+$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/generate-settings.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(bindir)/nix
 	@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-settings.nix "opt-" (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
 	@mv $@.tmp $@
 
 $(d)/nix.json: $(bindir)/nix

doc/manual/utils.nix

@@ -44,63 +44,6 @@ rec {
 
   optionalString = cond: string: if cond then string else "";
 
-  showSetting = { useAnchors }: name: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
-    let
-      result = squash ''
-          - ${if useAnchors
-              then ''<span id="conf-${name}">[`${name}`](#conf-${name})</span>''
-              else ''`${name}`''}
-
-          ${indent "  " body}
-        '';
-
-      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}
-          ${name} = ...
-          ```
-        '';
-
-      # separate body to cleanly handle indentation
-      body = ''
-          ${description}
-
-          ${experimentalFeatureNote}
-
-          **Default:** ${showDefault documentDefault defaultValue}
-
-          ${showAliases aliases}
-        '';
-
-      showDefault = documentDefault: defaultValue:
-        if documentDefault then
-          # a StringMap value type is specified as a string, but
-          # this shows the value type. The empty stringmap is `null` in
-          # JSON, but that converts to `{ }` here.
-          if defaultValue == "" || defaultValue == [] || isAttrs defaultValue
-            then "*empty*"
-            else if isBool defaultValue then
-              if defaultValue then "`true`" else "`false`"
-            else "`${toString defaultValue}`"
-        else "*machine-specific*";
-
-      showAliases = aliases:
-          optionalString (aliases != [])
-            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
-
-    in result;
-
   indent = prefix: s:
     concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
-
-  showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo));
 }