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.
2025-03-13 20:30:02 +00:00 · 2023-06-22 09:05:03 +01:00 · 2023-06-22 09:05:03 +01:00 · efe314cdba
commit efe314cdba
parent c2716817a8
10 changed files with 99 additions and 103 deletions
--- 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.
--- 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.
      '';
    };

--- 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.

--- 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
--- 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 = {
--- 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.
+        '';
      };
    };
  };
--- 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.
        '';
    };
--- 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
      '';
    };

--- 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".
      '';
    };

--- 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.