refactor rendering documentation of options

this makes more obvious what the code produces, and the structure of the
output easier to change

doc/manual/generate-options.nix

@@ -1,29 +1,41 @@
-with builtins;
+let
-with import ./utils.nix;
+  inherit (builtins) attrNames concatStringsSep isAttrs isBool;
+  inherit (import ./utils.nix) concatStrings squash splitLines;
+in
 
-options:
+optionsInfo:
+let
+  showOption = name:
+    let
+      inherit (optionsInfo.${name}) description documentDefault defaultValue aliases;
+      result = squash ''
+          - [`${name}`]{#conf-${name}}
 
-concatStrings (map
+          ${indent "  " body}
-  (name:
+        '';
-    let option = options.${name}; in
+      # separate body to cleanly handle indentation
-    "  - [`${name}`](#conf-${name})"
+      body = ''
-    + "<p id=\"conf-${name}\"></p>\n\n"
+          ${description}
-    + concatStrings (map (s: "    ${s}\n") (splitLines option.description)) + "\n\n"
+
-    + (if option.documentDefault
+          **Default:** ${showDefault documentDefault defaultValue}
-       then "    **Default:** " + (
+
-       if option.defaultValue == "" || option.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 option.defaultValue
+            else if isBool defaultValue then
-       then (if option.defaultValue then "`true`" else "`false`")
+              if defaultValue then "`true`" else "`false`"
-       else
+            else "`${toString defaultValue}`"
-         # n.b. a StringMap value type is specified as a string, but
+        else "*machine-specific*";
-         # this shows the value type.  The empty stringmap is "null" in
+      showAliases = aliases:
-         # JSON, but that converts to "{ }" here.
+          if aliases == [] then "" else
-         (if isAttrs option.defaultValue then "`\"\"`"
+            "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
-          else "`" + toString option.defaultValue + "`")) + "\n\n"
+      indent = prefix: s:
-       else "    **Default:** *machine-specific*\n")
+        concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
-    + (if option.aliases != []
+      in result;
-       then "    **Deprecated alias:** " + (concatStringsSep ", " (map (s: "`${s}`") option.aliases)) + "\n\n"
+in concatStrings (map showOption (attrNames optionsInfo))
-       else "")
-    )
-  (attrNames options))