treewide: convert options with lists to Markdown

`nix-doc-munge` can't handle these, which is understandable as I can
barely handle them either. There are a few infelicities here: the
current processor can't handle multiple terms to one description in
a description list so they get comma-separated in one case, and one
case that should ideally render as a `<figure>` with a `<figcaption>`
in HTML is reduced to a paragraph with some `<strong>` text. (Which, in
fairness, is how it rendered in practice with the DocBook anyway.) The
docs generator has since been updated to handle figures, but we can't
use it until moving off DocBook output.

modules/programs/broot.nix

@@ -30,44 +30,33 @@ let
             }
           ]
         '';
-        description = ''
+        description = lib.mdDoc ''
           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>
+          [Verb Definition Attributes](https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes)
+          in the broot documentation.
 
-          <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
-              the arguments part)</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>leave_broot</literal> (optional)</term>
-              <listitem><para>whether to quit broot on execution
-              (default: <literal>true</literal>)</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>from_shell</literal> (optional)</term>
-              <listitem><para>whether the verb must be executed from the
-              parent shell (default:
-              <literal>false</literal>)</para></listitem>
-            </varlistentry>
-          </variablelist>
+          The possible attributes are:
+
+          `invocation` (optional)
+          : how the verb is called by the user, with placeholders for arguments
+
+          `execution` (mandatory)
+          : how the verb is executed
+
+          `key` (optional)
+          : a keyboard key triggering execution
+
+          `shortcut` (optional)
+          : an alternate way to call the verb (without
+            the arguments part)
+
+          `leave_broot` (optional)
+          : whether to quit broot on execution
+            (default: `true`)
+
+          `from_shell` (optional)</term>
+          : whether the verb must be executed from the
+            parent shell (default: `false`)
         '';
       };
 
@@ -92,38 +81,35 @@ let
             code_fg = "lightyellow";
           }
         '';
-        description = ''
+        description = lib.mdDoc ''
           Color configuration.
-          </para><para>
+
           Complete list of keys (expected to change before the v1 of broot):
 
-          <itemizedlist>
-            <listitem><para><literal>char_match</literal></para></listitem>
-            <listitem><para><literal>code</literal></para></listitem>
-            <listitem><para><literal>directory</literal></para></listitem>
-            <listitem><para><literal>exe</literal></para></listitem>
-            <listitem><para><literal>file</literal></para></listitem>
-            <listitem><para><literal>file_error</literal></para></listitem>
-            <listitem><para><literal>flag_label</literal></para></listitem>
-            <listitem><para><literal>flag_value</literal></para></listitem>
-            <listitem><para><literal>input</literal></para></listitem>
-            <listitem><para><literal>link</literal></para></listitem>
-            <listitem><para><literal>permissions</literal></para></listitem>
-            <listitem><para><literal>selected_line</literal></para></listitem>
-            <listitem><para><literal>size_bar_full</literal></para></listitem>
-            <listitem><para><literal>size_bar_void</literal></para></listitem>
-            <listitem><para><literal>size_text</literal></para></listitem>
-            <listitem><para><literal>spinner</literal></para></listitem>
-            <listitem><para><literal>status_error</literal></para></listitem>
-            <listitem><para><literal>status_normal</literal></para></listitem>
-            <listitem><para><literal>table_border</literal></para></listitem>
-            <listitem><para><literal>tree</literal></para></listitem>
-            <listitem><para><literal>unlisted</literal></para></listitem>
-          </itemizedlist></para>
+          * `char_match`
+          * `code`
+          * `directory`
+          * `exe`
+          * `file`
+          * `file_error`
+          * `flag_label`
+          * `flag_value`
+          * `input`
+          * `link`
+          * `permissions`
+          * `selected_line`
+          * `size_bar_full`
+          * `size_bar_void`
+          * `size_text`
+          * `spinner`
+          * `status_error`
+          * `status_normal`
+          * `table_border`
+          * `tree`
+          * `unlisted`
 
-          <para>
-          Add <literal>_fg</literal> for a foreground color and
-          <literal>_bg</literal> for a background colors.
+          Add `_fg` for a foreground color and
+          `_bg` for a background color.
         '';
       };
     };