broot: improve configuration

The `invocation` is an optional attribute, so it doesn't make sense to
use it as the key in an attribute set. See

  https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes

Actually, `invocation` should not be defined when one wants to rebind
a built-in verb to a different key.

Also added documentation for the `key` attribute.

doc/release-notes/rl-2103.adoc

@@ -9,7 +9,28 @@ section is therefore not final.
 
 This release has the following notable changes:
 
-* Nothing has happened.
+* The <<opt-programs.broot.verbs>> option is now a list rather than an
+attribute set. To migrate, move the keys of the attrset into the list
+items' `invocation` keys. For example,
++
+[source,nix]
+----
+programs.broot.verbs = {
+  "p" = { execution = ":parent"; };
+};
+----
++
+becomes
++
+[source,nix]
+----
+programs.broot.verbs = [
+  {
+    invocation = "p";
+    execution = ":parent";
+  }
+];
+----
 
 [[sec-release-21.03-state-version-changes]]
 === State Version Changes

modules/misc/news.nix

@@ -1736,6 +1736,29 @@ in
           A new module is available: 'programs.i3status-rust'.
         '';
       }
+
+      {
+        time = "2020-11-14T13:02:40+00:00";
+        condition = config.programs.broot.enable;
+        message = ''
+          The 'programs.broot.verbs' option is now a list rather than an
+          attribute set. To migrate, move the keys of the attrset into the
+          list items' 'invocation' keys. For example,
+
+            programs.broot.verbs = {
+              "p" = { execution = ":parent"; };
+            };
+
+          becomes
+
+            programs.broot.verbs = [
+              {
+                invocation = "p";
+                execution = ":parent";
+              }
+            ];
+        '';
+      }
     ];
   };
 }

modules/programs/broot.nix

@@ -18,8 +18,7 @@ let
     '';
 
   brootConf = {
-    verbs =
-      mapAttrsToList (name: value: value // { invocation = name; }) cfg.verbs;
+    verbs = cfg.verbs;
     skin = cfg.skin;
   };
 
@@ -54,41 +53,60 @@ in {
     };
 
     verbs = mkOption {
-      type = with types; attrsOf (attrsOf (either bool str));
-      default = {
-        "p" = { execution = ":parent"; };
-        "edit" = {
+      type = with types; listOf (attrsOf (either bool str));
+      default = [
+        {
+          invocation = "p";
+          execution = ":parent";
+        }
+        {
+          invocation = "edit";
           shortcut = "e";
           execution = "$EDITOR {file}";
-        };
-        "create {subpath}" = { execution = "$EDITOR {directory}/{subpath}"; };
-        "view" = { execution = "less {file}"; };
-      };
-      example = literalExample ''
+        }
         {
-          "p" = { execution = ":parent"; };
-          "edit" = { shortcut = "e"; execution = "$EDITOR {file}" ; };
-          "create {subpath}" = { execution = "$EDITOR {directory}/{subpath}"; };
-          "view" = { execution = "less {file}"; };
-          "blop {name}\\.{type}" = {
+          invocation = "create {subpath}";
+          execution = "$EDITOR {directory}/{subpath}";
+        }
+        {
+          invocation = "view";
+          execution = "less {file}";
+        }
+      ];
+      example = literalExample ''
+        [
+          { invocation = "p"; execution = ":parent"; }
+          { invocation = "edit"; shortcut = "e"; execution = "$EDITOR {file}" ; }
+          { invocation = "create {subpath}"; execution = "$EDITOR {directory}/{subpath}"; }
+          { invocation = "view"; execution = "less {file}"; }
+          {
+            invocation = "blop {name}\\.{type}";
             execution = "/bin/mkdir {parent}/{type} && /usr/bin/nvim {parent}/{type}/{name}.{type}";
             from_shell = true;
-          };
           }
+        ]
       '';
       description = ''
-        Define new verbs. The attribute name indicates how the verb is
-        called by the user, with placeholders for arguments.
+        Define new verbs. For more information, see
+        <link xlink:href="https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes"/>.
         </para><para>
         The possible attributes are:
         </para>
 
         <para>
         <variablelist>
+          <varlistentry>
+            <term><literal>invocation</literal> (optional)</term>
+            <listitem><para>how the verb is called by the user, with placeholders for arguments</para></listitem>
+          </varlistentry>
           <varlistentry>
             <term><literal>execution</literal> (mandatory)</term>
             <listitem><para>how the verb is executed</para></listitem>
           </varlistentry>
+          <varlistentry>
+            <term><literal>key</literal> (optional)</term>
+            <listitem><para>a keyboard key triggering execution</para></listitem>
+          </varlistentry>
           <varlistentry>
             <term><literal>shortcut</literal> (optional)</term>
             <listitem><para>an alternate way to call the verb (without