refactor rendering command documentation to markdown

idea:
- make document structure visible, like in a template
- order functions by descending abstraction
- avoid nested let bindings

doc/manual/generate-manpage.nix

@@ -5,60 +5,42 @@ with import ./utils.nix;
 
 let
 
-  showCommand =
+  showCommand = { command, def, filename }:
-    { command, def, filename }:
-    ''
-      > **Warning**
-      > This program is **experimental** and its interface is subject to change.
-
-      # Name
-
-      `${command}` - ${def.description}
-
-      # Synopsis
-
-      ${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)));
+      showSynopsis = command: args:
-           listCommands = cmds:
+        let
-             concatStrings (map (name:
+          showArgument = arg: "*${arg.label}*" + (if arg ? arity then "" else "...");
-               "* "
+          arguments = concatStringsSep " " (map showArgument args);
-               + "[`${command} ${name}`](./${appendName filename name}.md)"
-               + " - ${cmds.${name}.description}\n")
-               (attrNames cmds));
         in ''
+         `${command}` [*option*...] ${arguments}
+        '';
+      maybeSubcommands = if def ? commands && def.commands != {}
+        then ''
            where *subcommand* is one of the following:
 
+           ${subcommands}
          ''
-         # FIXME: group by category
+        else "";
-         + (if length categories > 1
+      subcommands = if length categories > 1
-            then
+        then listCategories
-              concatStrings (map
+        else listSubcommands def.commands;
-                (cat:
+      categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands)));
-                  "**${toString cat.description}:**\n\n"
+      listCategories = concatStrings (map showCategory categories);
-                  + listCommands (filterAttrs (n: v: v.category == cat) def.commands)
+      showCategory = cat: ''
-                  + "\n"
+        **${toString cat.description}:**
-                ) categories)
-              + "\n"
-            else
-              listCommands def.commands
-              + "\n")
-       else "")
-    + (if def ? doc
-       then def.doc + "\n\n"
-       else "")
-    + (let s = showOptions def.flags; in
-       if s != ""
-       then "# Options\n\n${s}"
-       else "")
-  ;
 
-  appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
+        ${listSubcommands (filterAttrs (n: v: v.category == cat) def.commands)}
+      '';
+      listSubcommands = cmds: concatStrings (attrValues (mapAttrs showSubcommand cmds));
+      showSubcommand = name: subcmd: ''
+        * [`${command} ${name}`](./${appendName filename name}.md) - ${subcmd.description}
+      '';
+      maybeDocumentation = if def ? doc then def.doc else "";
+      maybeOptions = if def.flags == {} then "" else ''
+        # Options
 
+        ${showOptions def.flags}
+      '';
       showOptions = flags:
         let
           categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags)));
@@ -80,11 +62,31 @@ let
                     + "    " + flag.description + "\n\n"
                 ) (attrNames (filterAttrs (n: v: v.category == cat) flags))))
             categories);
+      squash = string: # squash more than two repeated newlines
+        let
+          replaced = replaceStrings [ "\n\n\n" ] [ "\n\n" ] string;
+        in
+          if replaced == string then string else squash replaced;
+    in squash ''
+      > **Warning** \
+      > This program is **experimental** and its interface is subject to change.
 
-  showSynopsis =
+      # Name
-    { command, args }:
+
-    "`${command}` [*option*...] ${concatStringsSep " "
+      `${command}` - ${def.description}
-      (map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}";
+
+      # Synopsis
+
+      ${showSynopsis command def.args}
+
+      ${maybeSubcommands}
+
+      ${maybeDocumentation}
+
+      ${maybeOptions}
+    '';
+
+  appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
 
   processCommand = { command, def, filename }:
     [ { name = filename + ".md"; value = showCommand { inherit command def filename; }; inherit command; } ]