From 5d78dc41760c504240101e77eb38c47fec58bdbd Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 3 May 2023 09:16:29 +0200
Subject: [PATCH] doc rendering: add functions to scope explicitly (#7378)

* doc rendering: add functions to scope explicitly

this especially helps beginners with code readability, since the origin
of names is always immediately visible.
---
 doc/manual/generate-builtins.nix | 12 ++++++++----
 doc/manual/generate-manpage.nix  | 22 +++++++++++++---------
 2 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 115bb3f94..71f96153f 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -1,8 +1,12 @@
-builtinsDump:
+let
+  inherit (builtins) concatStringsSep attrNames;
+in
+
+builtinsInfo:
 let
   showBuiltin = name:
     let
-      inherit (builtinsDump.${name}) doc args;
+      inherit (builtinsInfo.${name}) doc args;
     in
     ''
       <dt id="builtins-${name}">
@@ -14,7 +18,7 @@ let
 
       </dd>
     '';
-  listArgs = args: builtins.concatStringsSep " " (map (s: "<var>${s}</var>") args);
+  listArgs = args: concatStringsSep " " (map (s: "<var>${s}</var>") args);
 in
-with builtins; concatStringsSep "\n" (map showBuiltin (attrNames builtinsDump))
+concatStringsSep "\n" (map showBuiltin (attrNames builtinsInfo))
 
diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index d04eecf55..fb34898f3 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -1,10 +1,16 @@
-cliDumpStr:
+let
+  inherit (builtins)
+    attrNames attrValues fromJSON listToAttrs mapAttrs
+    concatStringsSep concatMap length lessThan replaceStrings sort;
+  inherit (import ./utils.nix) concatStrings optionalString filterAttrs trim squash unique showSettings;
+in
 
-with builtins;
-with import ./utils.nix;
+commandDump:
 
 let
 
+  commandInfo = fromJSON commandDump;
+
   showCommand = { command, details, filename, toplevel }:
     let
 
@@ -96,7 +102,7 @@ let
 
                 ${option.description}
             '';
-          categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues allOptions)));
+          categories = sort lessThan (unique (map (cmd: cmd.category) (attrValues allOptions)));
         in concatStrings (map showCategory categories);
     in squash result;
 
@@ -117,13 +123,11 @@ let
       };
     in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
 
-  cliDump = builtins.fromJSON cliDumpStr;
-
   manpages = processCommand {
     command = "nix";
-    details = cliDump.args;
+    details = commandInfo.args;
     filename = "nix";
-    toplevel = cliDump.args;
+    toplevel = commandInfo.args;
   };
 
   tableOfContents = let
@@ -143,6 +147,6 @@ let
 
           ${showSettings { useAnchors = false; } settings}
         '';
-    in concatStrings (attrValues (mapAttrs showStore cliDump.stores));
+    in concatStrings (attrValues (mapAttrs showStore commandInfo.stores));
 
 in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }