Improve nix.1 manpage generator

doc/manual/generate-manpage.jq

@@ -1,5 +1,4 @@
 def show_flags:
-
   .flags
   | map_values(select(.category != "config"))
   | to_entries
@@ -13,30 +12,29 @@ def show_flags:
   ;
 
 def show_synopsis:
-
-"`" + .command + "` " + (.args | map("*" + .label + "*" + (if has("arity") then "" else "..." end)) | join(" ")) + "\n"
-
+  "`" + .command + "` " + (.args | map("*" + .label + "*" + (if has("arity") then "" else "..." end)) | join(" ")) + "\n\n"
   ;
 
-"# Synopsis\n\n"
-+ ({"command": "nix", "args": .args} | show_synopsis)
-+ "\n"
-+ "# Common flags\n\n"
-+ show_flags
-+ (.commands | to_entries | map(
-    "# Operation `" + .key + "`\n\n"
-    + "## Synopsis\n\n"
-    + ({"command": ("nix " + .key), "args": .value.args} | show_synopsis)
-    + "\n"
-    + "## Description\n\n"
-    + .value.description + "\n\n"
-    + (if (.value.flags | length) > 0 then
-        "## Flags\n\n"
-        + (.value | show_flags)
+def show_command:
+  . as $top |
+  .section + " Name\n\n"
+  + "`" + .command + "` - " + .def.description + "\n\n"
+  + .section + " Synopsis\n\n"
+  + ({"command": .command, "args": .def.args} | show_synopsis)
+  + (if (.def.flags | length) > 0 then
+      .section + " Flags\n\n"
+      + (.def | show_flags)
     else "" end)
-    + (if (.value.examples | length) > 0 then
-        "## Examples\n\n"
-        + (.value.examples | map("- " + .description + "\n\n  ```console\n  " + .command + "\n  ```\n" ) | join("\n"))
+  + (if (.def.examples | length) > 0 then
+      .section + " Examples\n\n"
+      + (.def.examples | map(.description + "\n\n```console\n" + .command + "\n```\n" ) | join("\n"))
       + "\n"
      else "" end)
-  ) | join(""))
+  + (if .def.commands then .def.commands | to_entries | map(
+      "# Subcommand `" + ($top.command + " " + .key) + "`\n\n"
+      + ({"command": ($top.command + " " + .key), "section": "##", "def": .value} | show_command)
+    ) | join("") else "" end)
+  ;
+
+"Title: nix\n\n"
++ ({"command": "nix", "section": "#", "def": .} | show_command)

src/nix/main.cc

@@ -142,6 +142,11 @@ struct NixArgs : virtual MultiCommand, virtual MixCommonArgs
         printHelp(programName, std::cout);
         throw Exit();
     }
+
+    std::string description() override
+    {
+        return "a tool for reproducible and declarative configuration management";
+    }
 };
 
 void mainWrapped(int argc, char * * argv)