treewide: manually convert some docs to Markdown

These all use DocBook markup too complex for `nix-doc-munge` to handle,
have syntax that clashes with Markdown, or already contain Markdown
syntax that currently isn't rendering correctly.

Converting DocBook list syntax makes me think that maybe Markdown
isn't so bad after all.

10 files changed, 99 insertions, 103 deletions

diff --git a/modules/launchd/default.nix b/modules/launchd/default.nix
index f82df2a..ed85509 100644
--- a/modules/launchd/default.nix
+++ b/modules/launchd/default.nix
@@ -137,7 +137,7 @@ in
     launchd.agents = mkOption {
       default = {};
       type = types.attrsOf (types.submodule serviceOptions);
-      description = ''
+      description = lib.mdDoc ''
         Definition of per-user launchd agents.
 
         When a user logs in, a per-user launchd is started.
@@ -153,7 +153,7 @@ in
     launchd.daemons = mkOption {
       default = {};
       type = types.attrsOf (types.submodule serviceOptions);
-      description = ''
+      description = lib.mdDoc ''
         Definition of launchd daemons.
 
         After the system is booted and the kernel is running, launchd is run to finish the system initialization.
@@ -169,7 +169,7 @@ in
     launchd.user.agents = mkOption {
       default = {};
       type = types.attrsOf (types.submodule serviceOptions);
-      description = ''
+      description = lib.mdDoc ''
         Definition of per-user launchd agents.
 
         When a user logs in, a per-user launchd is started.
diff --git a/modules/launchd/launchd.nix b/modules/launchd/launchd.nix
index 727db95..61a78d9 100644
--- a/modules/launchd/launchd.nix
+++ b/modules/launchd/launchd.nix
@@ -633,27 +633,27 @@ with lib;
       type = types.nullOr (types.enum [ "Background" "Standard" "Adaptive" "Interactive" ]);
       default = null;
       example = "Background";
-      description = ''
+      description = lib.mdDoc ''
         This optional key describes, at a high level, the intended purpose of the job.  The system will apply
         resource limits based on what kind of job it is. If left unspecified, the system will apply light
         resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values:
 
-           Background
-           Background jobs are generally processes that do work that was not directly requested by the user.
-           The resource limits applied to Background jobs are intended to prevent them from disrupting the
-           user experience.
+        Background
+        : Background jobs are generally processes that do work that was not directly requested by the user.
+          The resource limits applied to Background jobs are intended to prevent them from disrupting the
+          user experience.
 
-           Standard
-           Standard jobs are equivalent to no ProcessType being set.
+        Standard
+        : Standard jobs are equivalent to no ProcessType being set.
 
-           Adaptive
-           Adaptive jobs move between the Background and Interactive classifications based on activity over
-           XPC connections. See <literal>xpc_transaction_begin(3)</literal> for details.
+        Adaptive
+        : Adaptive jobs move between the Background and Interactive classifications based on activity over
+          XPC connections. See `xpc_transaction_begin(3)` for details.
 
-           Interactive
-           Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive
-           jobs are critical to maintaining a responsive user experience, and this key should only be
-           used if an app's ability to be responsive depends on it, and cannot be made Adaptive.
+        Interactive
+        : Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive
+          jobs are critical to maintaining a responsive user experience, and this key should only be
+          used if an app's ability to be responsive depends on it, and cannot be made Adaptive.
       '';
     };
 
diff --git a/modules/networking/default.nix b/modules/networking/default.nix
index 46cd982..727933f 100644
--- a/modules/networking/default.nix
+++ b/modules/networking/default.nix
@@ -29,7 +29,7 @@ in
       type = types.nullOr types.str;
       default = null;
       example = "John’s MacBook Pro";
-      description = ''
+      description = lib.mdDoc ''
         The user-friendly name for the system, set in System Preferences > Sharing > Computer Name.
 
         Setting this option is equivalent to running `scutil --set ComputerName`.
@@ -42,7 +42,7 @@ in
       type = types.nullOr (types.strMatching hostnameRegEx);
       default = null;
       example = "Johns-MacBook-Pro";
-      description = ''
+      description = lib.mdDoc ''
         The hostname of your system, as visible from the command line and used by local and remote
         networks when connecting through SSH and Remote Login.
 
@@ -56,7 +56,7 @@ in
       type = types.nullOr (types.strMatching hostnameRegEx);
       default = cfg.hostName;
       example = "Johns-MacBook-Pro";
-      description = ''
+      description = lib.mdDoc ''
         The local hostname, or local network name, is displayed beneath the computer's name at the
         top of the Sharing preferences pane. It identifies your Mac to Bonjour-compatible services.
 
diff --git a/modules/nix/default.nix b/modules/nix/default.nix
index 6c61acc..cf71401 100644
--- a/modules/nix/default.nix
+++ b/modules/nix/default.nix
@@ -277,7 +277,7 @@ in
               type = types.nullOr types.str;
               default = null;
               example = "/root/.ssh/id_buildhost_builduser";
-              description = ''
+              description = lib.mdDoc ''
                 The path to the SSH private key with which to authenticate on
                 the build machine. The private key must not have a passphrase.
                 If null, the building user (root on NixOS machines) must have an
diff --git a/modules/security/pam.nix b/modules/security/pam.nix
index ac7603f..0061fba 100644
--- a/modules/security/pam.nix
+++ b/modules/security/pam.nix
@@ -39,7 +39,7 @@ in
 
 {
   options = {
-    security.pam.enableSudoTouchIdAuth = mkEnableOption ''
+    security.pam.enableSudoTouchIdAuth = mkEnableOption (lib.mdDoc ''
       Enable sudo authentication with Touch ID
 
       When enabled, this option adds the following line to /etc/pam.d/sudo:
@@ -49,7 +49,7 @@ in
       (Note that macOS resets this file when doing a system update. As such, sudo
       authentication with Touch ID won't work after a system update until the nix-darwin
       configuration is reapplied.)
-    '';
+    '');
   };
 
   config = {
diff --git a/modules/services/wg-quick.nix b/modules/services/wg-quick.nix
index 40725ff..1456823 100644
--- a/modules/services/wg-quick.nix
+++ b/modules/services/wg-quick.nix
@@ -113,8 +113,12 @@ let
       table = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description =
-          "Controls the routing table to which routes are added. There are two special values:  `off' disables  the  creation  of routes altogether, and `auto' (the default) adds routes to the default table and enables special handling of default routes.";
+        description = lib.mdDoc ''
+          Controls the routing table to which routes are added. There are two
+          special values: `off` disables the creation of routes altogether,
+          and `auto` (the default) adds routes to the default table and
+          enables special handling of default routes.
+        '';
       };
     };
   };
diff --git a/modules/system/defaults/ActivityMonitor.nix b/modules/system/defaults/ActivityMonitor.nix
index d57c6c0..270c678 100644
--- a/modules/system/defaults/ActivityMonitor.nix
+++ b/modules/system/defaults/ActivityMonitor.nix
@@ -8,16 +8,16 @@ with lib;
     system.defaults.ActivityMonitor.ShowCategory = mkOption {
       type = types.nullOr (types.enum [100 101 102 103 104 105 106 107]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Change which processes to show.
-            100: All Processes
-            101: All Processes, Hierarchally
-            102: My Processes
-            103: System Processes
-            104: Other User Processes
-            105: Active Processes
-            106: Inactive Processes
-            107: Windowed Processes
+          * 100: All Processes
+          * 101: All Processes, Hierarchally
+          * 102: My Processes
+          * 103: System Processes
+          * 104: Other User Processes
+          * 105: Active Processes
+          * 106: Inactive Processes
+          * 107: Windowed Processes
           Default is 100.
         '';
     };
@@ -25,13 +25,13 @@ with lib;
     system.defaults.ActivityMonitor.IconType = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Change the icon in the dock when running.
-            0: Application Icon
-            2: Network Usage
-            3: Disk Activity
-            5: CPU Usage
-            6: CPU History
+          * 0: Application Icon
+          * 2: Network Usage
+          * 3: Disk Activity
+          * 5: CPU Usage
+          * 6: CPU History
           Default is null.
         '';
     };
diff --git a/modules/system/defaults/dock.nix b/modules/system/defaults/dock.nix
index ba62e7a..82c8bef 100644
--- a/modules/system/defaults/dock.nix
+++ b/modules/system/defaults/dock.nix
@@ -166,92 +166,84 @@ in {
     system.defaults.dock.wvous-tl-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for top left corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
     system.defaults.dock.wvous-bl-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for bottom left corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
     system.defaults.dock.wvous-tr-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for top right corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
     system.defaults.dock.wvous-br-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for bottom right corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
diff --git a/modules/system/defaults/loginwindow.nix b/modules/system/defaults/loginwindow.nix
index 5f0491a..0fb7096 100644
--- a/modules/system/defaults/loginwindow.nix
+++ b/modules/system/defaults/loginwindow.nix
@@ -38,8 +38,8 @@ with lib;
     system.defaults.loginwindow.LoginwindowText = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
-        Text to be shown on the login window. Default is "\\U03bb".
+      description = lib.mdDoc ''
+        Text to be shown on the login window. Default is "\\\\U03bb".
       '';
     };
 
diff --git a/modules/system/defaults/universalaccess.nix b/modules/system/defaults/universalaccess.nix
index 6d6a974..bb4bec9 100644
--- a/modules/system/defaults/universalaccess.nix
+++ b/modules/system/defaults/universalaccess.nix
@@ -37,7 +37,7 @@ with lib;
     system.defaults.universalaccess.closeViewZoomFollowsFocus = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Follow the keyboard focus while zoomed in.
         Without setting `closeViewScrollWheelToggle` this has no effect.
         The default is false.