From 589fd897fb8414561b7b328e864e998876ff822b Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 6 Sep 2023 09:14:56 +0200
Subject: [PATCH 1/4] add todo on store docs

---
 doc/manual/generate-manpage.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index bc4d2c5bc..0f91a9742 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -70,6 +70,7 @@ let
         * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
       '';
 
+      # TODO: move this confusing special case out of here when implementing #8496
       maybeDocumentation = optionalString
         (details ? doc)
         (replaceStrings ["@stores@"] [storeDocs] details.doc);

From b0fe7f560ddb31fea55546a79a89c44a63cd56ce Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 6 Sep 2023 09:15:03 +0200
Subject: [PATCH 2/4] add missing link

---
 doc/manual/generate-manpage.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 0f91a9742..705fc0b69 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -148,7 +148,7 @@ let
             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`](#):
+            For example, include the following in [`nix.conf`](@docroot@/command-ref/conf-file.md):
 
             ```
             extra-experimental-features = ${experimentalFeature}

From 09eb7f1ef653822616e7371c906ef1ae34b3ba09 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 6 Sep 2023 09:30:32 +0200
Subject: [PATCH 3/4] do not show configuration override flags for each command

this removes a lot of noise from the web search, which precludes finding
the actual documentation.

some configuration settings have enough documentation to warrant
individual pages, so the alternative of including full setting
documentation in each command page doesn't make much sense here.

this change technically means that the command line flags to override
settings are "invisible", and not exported as JSON. this may or may not
be desirable. a more explicit approach would be adding a `hidden` field
to the flag's JSON output, but would also require adjusting
post-processing of that JSON for manual rendering.
---
 doc/manual/generate-manpage.nix | 4 ++++
 src/libutil/args.cc             | 1 +
 2 files changed, 5 insertions(+)

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 705fc0b69..87891fa7a 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -79,6 +79,10 @@ let
         # Options
 
         ${showOptions details.flags toplevel.flags}
+
+        > **Note**
+        >
+        > See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
       '';
 
       showOptions = options: commonOptions:
diff --git a/src/libutil/args.cc b/src/libutil/args.cc
index 00281ce6f..8db293762 100644
--- a/src/libutil/args.cc
+++ b/src/libutil/args.cc
@@ -236,6 +236,7 @@ nlohmann::json Args::toJSON()
 
     for (auto & [name, flag] : longFlags) {
         auto j = nlohmann::json::object();
+        if (hiddenCategories.count(flag->category)) continue;
         if (flag->aliases.count(name)) continue;
         if (flag->shortName)
             j["shortName"] = std::string(1, flag->shortName);

From aa46f536e80ca20e0fc45664af867b47597a87f3 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 6 Sep 2023 09:40:51 +0200
Subject: [PATCH 4/4] add note on overriding settings for stable commands

---
 doc/manual/src/command-ref/opt-common.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md
index 0647228c2..114b292f9 100644
--- a/doc/manual/src/command-ref/opt-common.md
+++ b/doc/manual/src/command-ref/opt-common.md
@@ -203,3 +203,7 @@ Most Nix commands accept the following command-line options:
   Fix corrupted or missing store paths by redownloading or rebuilding them.
   Note that this is slow because it requires computing a cryptographic hash of the contents of every path in the closure of the build.
   Also note the warning under `nix-store --repair-path`.
+
+> **Note**
+>
+> See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.