accommodate inconsistent output from lowdown

the `term` output mode leaves inline HTML around verbatim, while `nroff` mode (used for `man` pages) does not. the correct solution would be to pre-render all output with a more benign tool so we have less liabilities in our own code, but this has to do for now.
NixOS · Oct 4, 2023 · e0e47c0 · e0e47c0
1 parent 8232711
commit e0e47c0
Show file tree

Hide file tree

Showing 5 changed files with 25 additions and 17 deletions.
diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
@@ -6,7 +6,7 @@ let
   showStoreDocs = import ./generate-store-info.nix;
 in
 
-commandDump:
+inlineHTML: commandDump:
 
 let
 
@@ -75,7 +75,7 @@ let
       # 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 commandInfo.stores) ] details.doc);
+        (replaceStrings [ "@stores@" ] [ (showStoreDocs inlineHTML commandInfo.stores) ] details.doc);
 
       maybeOptions = let
         allVisibleOptions = filterAttrs
@@ -84,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}"}
@@ -100,17 +100,21 @@ let
             '';
           showOption = name: option:
             let
+              result = trim ''
+                - ${item}
+
+                  ${option.description}
+              '';
+              item = if inlineHTML
+                then ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}''
+                else "`--${name}` ${shortName} ${labels}";
               shortName = optionalString
                 (option ? shortName)
                 ("/ `-${option.shortName}`");
               labels = optionalString
                 (option ? labels)
                 (concatStringsSep " " (map (s: "*${s}*") option.labels));
-            in trim ''
-              - <span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}
-
-                ${option.description}
-            '';
+            in result;
           categories = mapAttrs
             # Convert each group from a list of key-value pairs back to an attrset
             (_: listToAttrs)

diff --git a/doc/manual/generate-settings.nix b/doc/manual/generate-settings.nix
@@ -3,18 +3,21 @@ let
   inherit (import ./utils.nix) concatStrings indent optionalString squash;
 in
 
-prefix: settingsInfo:
+# `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 ''
-          - <span id="${prefix}-${setting}">[`${setting}`](#${prefix}-${setting})</span>
+          - ${item}
 
           ${indent "  " body}
         '';
-
+      item = if inlineHTML
+        then ''<span id="${prefix}-${setting}">[`${setting}`](#${prefix}-${setting})</span>''
+        else "`${setting}`";
       # separate body to cleanly handle indentation
       body = ''
           ${description}

diff --git a/doc/manual/generate-store-info.nix b/doc/manual/generate-store-info.nix
@@ -4,7 +4,7 @@ let
   showSettings = import ./generate-settings.nix;
 in
 
-storesInfo:
+inlineHTML: storesInfo:
 
 let
 
@@ -20,7 +20,7 @@ let
 
       ### Settings
 
-      ${showSettings "store-${slug}" settings}
+      ${showSettings { prefix = "store-${slug}"; inherit inlineHTML; } settings}
     '';
 
       # markdown doesn't like spaces in URLs

diff --git a/doc/manual/local.mk b/doc/manual/local.mk
@@ -98,12 +98,12 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/sr
 
 $(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)/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/generate-settings.nix "opt-" (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/src/nix/main.cc b/src/nix/main.cc
@@ -234,7 +234,8 @@ static void showHelp(std::vector<std::string> subcommand, NixArgs & toplevel)
     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)