From 807d963ee8d23e88f09e28365b045d322530c5aa Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 25 Jan 2021 18:19:32 +0100
Subject: [PATCH] Group subcommands by category

---
 doc/manual/generate-manpage.nix | 23 +++++++++++++++++++----
 doc/manual/utils.nix            | 10 +++++++++-
 src/libutil/args.cc             |  5 ++++-
 3 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index c2c748464..30152088d 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -13,12 +13,27 @@ let
     + showSynopsis { inherit command; args = def.args; }
     + (if def.commands or {} != {}
        then
+         let
+           categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands)));
+           listCommands = cmds:
+             concatStrings (map (name:
+               "* [`${command} ${name}`](./${appendName filename name}.md) - ${cmds.${name}.description}\n")
+               (attrNames cmds));
+         in
          "where *subcommand* is one of the following:\n\n"
          # FIXME: group by category
-         + concatStrings (map (name:
-           "* [`${command} ${name}`](./${appendName filename name}.md) - ${def.commands.${name}.description}\n")
-           (attrNames def.commands))
-         + "\n"
+         + (if length categories > 1
+            then
+              concatStrings (map
+                (cat:
+                  "**${toString cat.description}:**\n\n"
+                  + listCommands (filterAttrs (n: v: v.category == cat) def.commands)
+                  + "\n"
+                ) categories)
+              + "\n"
+            else
+              listCommands def.commands
+              + "\n")
        else "")
     + (if def ? doc
        then def.doc + "\n\n"
diff --git a/doc/manual/utils.nix b/doc/manual/utils.nix
index 50150bf3e..d4b18472f 100644
--- a/doc/manual/utils.nix
+++ b/doc/manual/utils.nix
@@ -1,7 +1,15 @@
 with builtins;
 
-{
+rec {
   splitLines = s: filter (x: !isList x) (split "\n" s);
 
   concatStrings = concatStringsSep "";
+
+  # FIXME: O(n^2)
+  unique = foldl' (acc: e: if elem e acc then acc else acc ++ [ e ]) [];
+
+  nameValuePair = name: value: { inherit name value; };
+
+  filterAttrs = pred: set:
+    listToAttrs (concatMap (name: let v = set.${name}; in if pred name v then [(nameValuePair name v)] else []) (attrNames set));
 }
diff --git a/src/libutil/args.cc b/src/libutil/args.cc
index 2f2e4bb96..6d57e1a34 100644
--- a/src/libutil/args.cc
+++ b/src/libutil/args.cc
@@ -341,7 +341,10 @@ nlohmann::json MultiCommand::toJSON()
     for (auto & [name, commandFun] : commands) {
         auto command = commandFun();
         auto j = command->toJSON();
-        j["category"] = categories[command->category()];
+        auto cat = nlohmann::json::object();
+        cat["id"] = command->category();
+        cat["description"] = categories[command->category()];
+        j["category"] = std::move(cat);
         cmds[name] = std::move(j);
     }