diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index 41725aed6..d81eac182 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -2,10 +2,11 @@ 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:
+inlineHTML: commandDump:
let
@@ -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
- maybeDocumentation = optionalString
- (details ? doc)
- (replaceStrings ["@stores@"] [storeDocs] details.doc);
+ # FIXME: this is a hack.
+ # store parameters should not be part of command documentation to begin
+ # with, but instead be rendered on separate pages.
+ maybeStoreDocs = optionalString (details ? doc)
+ (replaceStrings [ "@stores@" ] [ (showStoreDocs inlineHTML commandInfo.stores) ] details.doc);
maybeOptions = let
allVisibleOptions = filterAttrs
@@ -82,14 +84,14 @@ let
in optionalString (allVisibleOptions != {}) ''
# Options
- ${showOptions allVisibleOptions}
+ ${showOptions inlineHTML allVisibleOptions}
> **Note**
>
> See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
'';
- showOptions = allOptions:
+ showOptions = inlineHTML: allOptions:
let
showCategory = cat: opts: ''
${optionalString (cat != "") "## ${cat}"}
@@ -98,17 +100,21 @@ let
'';
showOption = name: option:
let
+ result = trim ''
+ - ${item}
+
+ ${option.description}
+ '';
+ item = if inlineHTML
+ then ''[`--${name}`](#opt-${name}) ${shortName} ${labels}''
+ else "`--${name}` ${shortName} ${labels}";
shortName = optionalString
(option ? shortName)
("/ `-${option.shortName}`");
labels = optionalString
(option ? labels)
(concatStringsSep " " (map (s: "*${s}*") option.labels));
- in trim ''
- - [`--${name}`](#opt-${name}) ${shortName} ${labels}
-
- ${option.description}
- '';
+ in result;
categories = mapAttrs
# Convert each group from a list of key-value pairs back to an attrset
(_: listToAttrs)
@@ -147,35 +153,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; }
diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
new file mode 100644
index 000000000..8736bb793
--- /dev/null
+++ b/doc/manual/generate-settings.nix
@@ -0,0 +1,66 @@
+let
+ inherit (builtins) attrValues concatStringsSep isAttrs isBool mapAttrs;
+ inherit (import ./utils.nix) concatStrings indent optionalString squash;
+in
+
+# `inlineHTML` is a hack to accommodate inconsistent output from `lowdown`
+{ prefix, inlineHTML ? true }: settingsInfo:
+
+let
+
+ showSetting = prefix: setting: { description, documentDefault, defaultValue, aliases, value, experimentalFeature }:
+ let
+ result = squash ''
+ - ${item}
+
+ ${indent " " body}
+ '';
+ item = if inlineHTML
+ then ''[`${setting}`](#${prefix}-${setting})''
+ else "`${setting}`";
+ # 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))
diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
new file mode 100644
index 000000000..36215aadf
--- /dev/null
+++ b/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
+
+inlineHTML: storesInfo:
+
+let
+
+ showStore = name: { settings, doc, experimentalFeature }:
+ let
+
+ result = ''
+ ## ${name}
+
+ ${doc}
+
+ ${experimentalFeatureNote}
+
+ ### 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;
+
+in concatStrings (attrValues (mapAttrs showStore storesInfo))
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index ab95af53c..702fb1ff8 100644
--- a/doc/manual/local.mk
+++ b/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 $<)'
+ $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (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 { prefix = "opt-"; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
@mv $@.tmp $@
$(d)/nix.json: $(bindir)/nix
diff --git a/doc/manual/utils.nix b/doc/manual/utils.nix
index 9043dd8cd..849832b2c 100644
--- a/doc/manual/utils.nix
+++ b/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 ''[`${name}`](#conf-${name})''
- 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));
}
diff --git a/src/nix/local.mk b/src/nix/local.mk
index 20ea29d10..57f8259c4 100644
--- a/src/nix/local.mk
+++ b/src/nix/local.mk
@@ -31,7 +31,7 @@ src/nix/develop.cc: src/nix/get-env.sh.gen.hh
src/nix-channel/nix-channel.cc: src/nix-channel/unpack-channel.nix.gen.hh
-src/nix/main.cc: doc/manual/generate-manpage.nix.gen.hh doc/manual/utils.nix.gen.hh
+src/nix/main.cc: doc/manual/generate-manpage.nix.gen.hh doc/manual/utils.nix.gen.hh doc/manual/generate-settings.nix.gen.hh doc/manual/generate-store-info.nix.gen.hh
src/nix/doc/files/%.md: doc/manual/src/command-ref/files/%.md
@mkdir -p $$(dirname $@)
diff --git a/src/nix/main.cc b/src/nix/main.cc
index d05bac68e..879baa5f5 100644
--- a/src/nix/main.cc
+++ b/src/nix/main.cc
@@ -214,11 +214,28 @@ static void showHelp(std::vector subcommand, NixArgs & toplevel)
, CanonPath::root),
*vUtils);
+ auto vSettingsInfo = state.allocValue();
+ state.cacheFile(
+ CanonPath("/generate-settings.nix"), CanonPath("/generate-settings.nix"),
+ state.parseExprFromString(
+ #include "generate-settings.nix.gen.hh"
+ , CanonPath::root),
+ *vSettingsInfo);
+
+ auto vStoreInfo = state.allocValue();
+ state.cacheFile(
+ CanonPath("/generate-store-info.nix"), CanonPath("/generate-store-info.nix"),
+ state.parseExprFromString(
+ #include "generate-store-info.nix.gen.hh"
+ , CanonPath::root),
+ *vStoreInfo);
+
auto vDump = state.allocValue();
vDump->mkString(toplevel.dumpCli());
auto vRes = state.allocValue();
- state.callFunction(*vGenerateManpage, *vDump, *vRes, noPos);
+ state.callFunction(*vGenerateManpage, state.getBuiltin("false"), *vRes, noPos);
+ state.callFunction(*vRes, *vDump, *vRes, noPos);
auto attr = vRes->attrs->get(state.symbols.create(mdName + ".md"));
if (!attr)