treewide: adjust some DocBook for conversion

The NixOS variant of Markdown doesn't make a distinction between
`<code>` and `<literal>` or `<quote>` and... quotes, and doesn't
support `<parameter>` or `<replaceable>`. These are infrequently used
(apart from `<code>`) and don't add much, so just convert them to
simpler forms to allow the options containing them to be converted
to Markdown automatically.

A few minor syntactic adjustments were also made to make
`nix-doc-munge`'s job easier.

modules/accounts/email.nix

@@ -147,7 +147,7 @@ let
           </para><para>
           If both this option and <xref
           linkend="opt-accounts.email.accounts._name_.jmap.sessionUrl"/> are specified,
-          <code>host</code> is preferred by applications when establishing a
+          <literal>host</literal> is preferred by applications when establishing a
           session.
         '';
       };
@@ -161,7 +161,7 @@ let
           </para><para>
           If both this option and <xref
           linkend="opt-accounts.email.accounts._name_.jmap.host"/> are specified,
-          <code>host</code> is preferred by applications when establishing a
+          <literal>host</literal> is preferred by applications when establishing a
           session.
         '';
       };

modules/home-environment.nix

@@ -264,11 +264,11 @@ in
         The values may refer to other environment variables using
         POSIX.2 style variable references. For example, a variable
         <varname>parameter</varname> may be referenced as
-        <code>$parameter</code> or <code>''${parameter}</code>. A
+        <literal>$parameter</literal> or <literal>''${parameter}</literal>. A
         default value <literal>foo</literal> may be given as per
-        <code>''${parameter:-foo}</code> and, similarly, an alternate
+        <literal>''${parameter:-foo}</literal> and, similarly, an alternate
         value <literal>bar</literal> can be given as per
-        <code>''${parameter:+bar}</code>.
+        <literal>''${parameter:+bar}</literal>.
         </para><para>
         Note, these variables may be set in any order so no session
         variable may have a runtime dependency on another session
@@ -314,9 +314,9 @@ in
         </para><para>
 
         These directories are added to the <envar>PATH</envar> variable in a
-        double-quoted context, so expressions like <code>$HOME</code> are
+        double-quoted context, so expressions like <literal>$HOME</literal> are
-        expanded by the shell. However, since expressions like <code>~</code> or
+        expanded by the shell. However, since expressions like <literal>~</literal> or
-        <code>*</code> are escaped, they will end up in the <envar>PATH</envar>
+        <literal>*</literal> are escaped, they will end up in the <envar>PATH</envar>
         verbatim.
       '';
     };

modules/misc/dconf.nix

@@ -37,7 +37,7 @@ in {
           Whether to enable dconf settings.
           </para><para>
           Note, if you use NixOS then you must add
-          <code>programs.dconf.enable = true</code>
+          <literal>programs.dconf.enable = true</literal>
           to your system configuration. Otherwise you will see a systemd error
           message when your configuration is activated.
         '';

modules/misc/editorconfig.nix

@@ -19,7 +19,7 @@ in {
       default = { };
       description = ''
         Configuration written to <filename>$HOME/.editorconfig</filename>.
-        <code>root = true</code> is automatically added to the file,
+        <literal>root = true</literal> is automatically added to the file,
         it must not be added here.
         See <link xlink:href="https://editorconfig.org"/> for documentation.
       '';

modules/misc/xdg-desktop-entries.nix

@@ -181,8 +181,10 @@ in {
 
   options.xdg.desktopEntries = mkOption {
     description = ''
-      Desktop Entries allow applications to be shown in your desktop environment's app launcher. </para><para>
+      Desktop Entries allow applications to be shown in your desktop environment's app launcher.
-      You can define entries for programs without entries or override existing entries. </para><para>
+
+      You can define entries for programs without entries or override existing entries.
+
       See <link xlink:href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys" /> for more information on options.
     '';
     default = { };

modules/misc/xfconf.nix

@@ -67,7 +67,7 @@ in {
         Whether to enable Xfconf settings.
         </para><para>
         Note, if you use NixOS then you must add
-        <code>programs.xfconf.enable = true</code>
+        <literal>programs.xfconf.enable = true</literal>
         to your system configuration. Otherwise you will see a systemd error
         message when your configuration is activated.
       '';

modules/programs/autorandr.nix

@@ -28,7 +28,7 @@ let
         type = types.attrsOf types.str;
         description = ''
           Output name to EDID mapping.
-          Use <code>autorandr --fingerprint</code> to get current setup values.
+          Use <literal>autorandr --fingerprint</literal> to get current setup values.
         '';
         default = { };
       };
@@ -160,9 +160,9 @@ let
             <manvolnum>1</manvolnum>
           </citerefentry>
           option
-          <parameter class="command">--scale-from</parameter>
+          <literal>--scale-from</literal>
           will be used; when using factor method the option
-          <parameter class="command">--scale</parameter>
+          <literal>--scale</literal>
           will be used.
           </para><para>
           This option is a shortcut version of the transform option and they are mutually

modules/programs/bash.nix

@@ -103,7 +103,7 @@ in {
         example = [ "extglob" "-cdspell" ];
         description = ''
           Shell options to set. Prefix an option with
-          <quote><literal>-</literal></quote> to unset.
+          "<literal>-</literal>" to unset.
         '';
       };
 

modules/programs/dircolors.nix

@@ -15,7 +15,7 @@ in {
       default = false;
       description = ''
         Whether to manage <filename>.dir_colors</filename>
-        and set <code>LS_COLORS</code>.
+        and set <literal>LS_COLORS</literal>.
       '';
     };
 

modules/programs/fzf.nix

@@ -104,7 +104,7 @@ in {
         }
       '';
       description = ''
-        Color scheme options added to <code>FZF_DEFAULT_OPTS</code>. See
+        Color scheme options added to <literal>FZF_DEFAULT_OPTS</literal>. See
         <link xlink:href="https://github.com/junegunn/fzf/wiki/Color-schemes"/>
         for documentation.
       '';

modules/programs/i3status-rust.nix

@@ -165,7 +165,7 @@ in {
         Attribute set of i3status-rust bars, each with their own configuration.
         Each bar <varname>name</varname> generates a config file suffixed with
         the bar's <varname>name</varname> from the attribute set, like so:
-        <filename>config-<replaceable>name</replaceable>.toml</filename>.
+        <filename>config-''${name}.toml</filename>.
         </para><para>
         This way, multiple config files can be generated, such as for having a
         top and a bottom bar.

modules/programs/i3status.nix

@@ -52,7 +52,7 @@ in {
       default = { };
       description = ''
         Configuration to add to i3status <filename>config</filename>
-        <code>general</code> section.
+        <literal>general</literal> section.
         See
         <citerefentry>
          <refentrytitle>i3status</refentrytitle>
@@ -84,7 +84,7 @@ in {
           position = mkOption {
             type = with types; either int float;
             description = ''
-              Position of this module in i3status <code>order</code>.
+              Position of this module in i3status <literal>order</literal>.
             '';
           };
           settings = mkOption {

modules/programs/msmtp-accounts.nix

@@ -11,13 +11,13 @@ with lib;
         Whether to enable msmtp.
         </para><para>
         If enabled then it is possible to use the
-        <parameter class="command">--account</parameter> command line
+        <literal>--account</literal> command line
         option to send a message for a given account using the
         <command>msmtp</command> or <command>msmtpq</command> tool.
         For example, <command>msmtp --account=private</command> would
         send using the account defined in
         <option>accounts.email.accounts.private</option>. If the
-        <parameter class="command">--account</parameter> option is not
+        <literal>--account</literal> option is not
         given then the primary account will be used.
       '';
     };

modules/programs/mujmap.nix

@@ -70,7 +70,7 @@ let
       default = "inbox";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Inbox</code> name attribute.
+        <literal>Inbox</literal> name attribute.
         </para><para>
         If set to an empty string, this mailbox <emphasis>and its child
         mailboxes</emphasis> are not synchronized with a tag.
@@ -82,7 +82,7 @@ let
       default = "deleted";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Trash</code> name attribute.
+        <literal>Trash</literal> name attribute.
         </para><para>
         If set to an empty string, this mailbox <emphasis>and its child
         mailboxes</emphasis> are not synchronized with a tag.
@@ -94,7 +94,7 @@ let
       default = "sent";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Sent</code> name attribute.
+        <literal>Sent</literal> name attribute.
         </para><para>
         If set to an empty string, this mailbox <emphasis>and its child
         mailboxes</emphasis> are not synchronized with a tag.
@@ -106,8 +106,8 @@ let
       default = "spam";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Junk</code> name attribute and/or with the <code>$Junk</code> keyword,
+        <literal>Junk</literal> name attribute and/or with the <literal>$Junk</literal> keyword,
-        <emphasis>except</emphasis> for messages with the <code>$NotJunk</code> keyword.
+        <emphasis>except</emphasis> for messages with the <literal>$NotJunk</literal> keyword.
         </para><para>
         If set to an empty string, this mailbox, <emphasis>its child
         mailboxes</emphasis>, and these keywords are not synchronized with a tag.
@@ -119,7 +119,7 @@ let
       default = "important";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Important</code> name attribute and/or with the <code>$Important</code>
+        <literal>Important</literal> name attribute and/or with the <literal>$Important</literal>
         keyword.
         </para><para>
         If set to an empty string, this mailbox, <emphasis>its child
@@ -131,7 +131,7 @@ let
       type = types.str;
       default = "phishing";
       description = ''
-        Tag for notmuch to use for the IANA <code>$Phishing</code> keyword.
+        Tag for notmuch to use for the IANA <literal>$Phishing</literal> keyword.
         </para><para>
         If set to an empty string, this keyword is not synchronized with a tag.
       '';

modules/programs/ncmpcpp.nix

@@ -55,7 +55,7 @@ in {
       default = pkgs.ncmpcpp;
       defaultText = literalExpression "pkgs.ncmpcpp";
       description = ''
-        Package providing the <code>ncmpcpp</code> command.
+        Package providing the <literal>ncmpcpp</literal> command.
       '';
       example =
         literalExpression "pkgs.ncmpcpp.override { visualizerSupport = true; }";
@@ -75,7 +75,7 @@ in {
           null
       '';
       description = ''
-        Value of the <code>mpd_music_dir</code> setting. On Linux platforms the
+        Value of the <literal>mpd_music_dir</literal> setting. On Linux platforms the
         value of <varname>services.mpd.musicDirectory</varname> is used as the
         default if <varname>services.mpd.enable</varname> is
         <literal>true</literal>.

modules/programs/offlineimap.nix

@@ -151,7 +151,7 @@ in {
         '';
         description = ''
           Extra configuration options added to the
-          <code>mbnames</code> section.
+          <literal>mbnames</literal> section.
         '';
       };
     };

modules/programs/rtx.nix

@@ -42,15 +42,13 @@ in {
         '';
         description = ''
           Settings written to <filename>$XDG_CONFIG_HOME/rtx/config.toml</filename>.
-          </para><para>
+
           See <link xlink:href="https://github.com/jdxcode/rtx#global-config-configrtxconfigtoml"/>
           for details on supported values.
 
           <warning>
-            <para>
+          <para>Modifying the <literal>tools</literal> section doesn't make RTX install them.
-              Modifying the <literal>tools</literal> section doesn't make RTX install them. 
+          You have to manually run <literal>rtx install</literal> to install the tools.</para>
-              You have to manually run <literal>rtx install</literal> to install the tools.
-            </para>
           </warning>
         '';
       };

modules/programs/sbt.nix

@@ -162,18 +162,18 @@ in {
       description = ''
         A list of repositories to use when resolving dependencies. Defined as a
         list of pre-defined repository or custom repository as a set of name to
-        URL. The list will be used populate the <code>~/.sbt/repositories</code>
+        URL. The list will be used populate the <literal>~/.sbt/repositories</literal>
         file in the order specified.
 
         </para><para>
 
-        Pre-defined repositories must be one of <code>local</code>,
+        Pre-defined repositories must be one of <literal>local</literal>,
-        <code>maven-local</code>, <code>maven-central</code>.
+        <literal>maven-local</literal>, <literal>maven-central</literal>.
 
         </para><para>
 
         Custom repositories are defined as
-        <code language="nix">{ name-of-repo = "https://url.to.repo.com"}</code>.
+        <literal>{ name-of-repo = "https://url.to.repo.com"}</literal>.
 
         </para><para>
 

modules/programs/waybar.nix

@@ -27,8 +27,8 @@ let
           type = nullOr (enum [ "top" "bottom" ]);
           default = null;
           description = ''
-            Decide if the bar is displayed in front (<code>"top"</code>)
+            Decide if the bar is displayed in front (<literal>"top"</literal>)
-            of the windows or behind (<code>"bottom"</code>).
+            of the windows or behind (<literal>"bottom"</literal>).
           '';
           example = "top";
         };
@@ -152,7 +152,7 @@ in {
       default = pkgs.waybar;
       defaultText = literalExpression "pkgs.waybar";
       description = ''
-        Waybar package to use. Set to <code>null</code> to use the default package.
+        Waybar package to use. Set to <literal>null</literal> to use the default package.
       '';
     };
 

modules/programs/yt-dlp.nix

@@ -41,9 +41,9 @@ in {
         Configuration written to
         <filename>$XDG_CONFIG_HOME/yt-dlp/config</filename>.
         </para><para>
-        Options must be specified in their <quote>long form</quote>, for
+        Options must be specified in their "long form", for
-        example, <code>update = true;</code> instead of <code>U = true;</code>.
+        example, <literal>update = true;</literal> instead of <literal>U = true;</literal>.
-        Short options can be specified in the <code>extraConfig</code> option.
+        Short options can be specified in the <literal>extraConfig</literal> option.
         See <link xlink:href="https://github.com/yt-dlp/yt-dlp#configuration"/>
         for explanation about possible values.
       '';

modules/services/borgmatic.nix

@@ -17,7 +17,7 @@ in {
         default = "hourly";
         description = ''
           How often to run borgmatic when
-          <code language="nix">services.borgmatic.enable = true</code>.
+          <literal>services.borgmatic.enable = true</literal>.
           This value is passed to the systemd timer configuration as
           the onCalendar option. See
           <citerefentry>

modules/services/home-manager-auto-upgrade.nix

@@ -15,7 +15,7 @@ in {
     services.home-manager.autoUpgrade = {
       enable = lib.mkEnableOption ''
         the Home Manager upgrade service that periodically updates your Nix
-        channels before running <code>home-manager switch</code>'';
+        channels before running <literal>home-manager switch</literal>'';
 
       frequency = lib.mkOption {
         type = lib.types.str;
@@ -23,7 +23,7 @@ in {
         description = ''
           The interval at which the Home Manager auto upgrade is run.
           This value is passed to the systemd timer configuration
-          as the <code>OnCalendar</code> option.
+          as the <literal>OnCalendar</literal> option.
           The format is described in
           <citerefentry>
             <refentrytitle>systemd.time</refentrytitle>

modules/services/window-managers/i3-sway/i3.nix

@@ -95,7 +95,7 @@ let
           An attribute set that assigns a key press to an action using a key symbol.
           See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
           </para><para>
-          Consider to use <code>lib.mkOptionDefault</code> function to extend or override
+          Consider to use <literal>lib.mkOptionDefault</literal> function to extend or override
           default keybindings instead of specifying all of them from scratch.
         '';
         example = literalExpression ''

modules/services/window-managers/i3-sway/sway.nix

@@ -125,7 +125,7 @@ let
           An attribute set that assigns a key press to an action using a key symbol.
           See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
           </para><para>
-          Consider to use <code>lib.mkOptionDefault</code> function to extend or override
+          Consider to use <literal>lib.mkOptionDefault</literal> function to extend or override
           default keybindings instead of specifying all of them from scratch.
         '';
         example = literalExpression ''
@@ -352,7 +352,7 @@ in {
       description = ''
         Sway package to use. Will override the options
         'wrapperFeatures', 'extraSessionCommands', and 'extraOptions'.
-        Set to <code>null</code> to not add any Sway package to your
+        Set to <literal>null</literal> to not add any Sway package to your
         path. This should be done if you want to use the NixOS Sway
         module to install Sway.
       '';

modules/services/xidlehook.nix

@@ -52,7 +52,7 @@ in {
       '';
       description = ''
         Extra environment variables to be exported in the script.
-        These options are passed unescaped as <code>export name=value</code>.
+        These options are passed unescaped as <literal>export name=value</literal>.
       '';
     };
 

modules/targets/darwin/keybindings.nix

@@ -22,10 +22,8 @@ in {
       for more details.
 
       <warning>
-        <para>
+      <para>Existing keybinding configuration will be wiped when using this
-          Existing keybinding configuration will be wiped when using this
+      option.</para>
-          option.
-        </para>
       </warning>
     '';
   };

modules/targets/darwin/user-defaults/default.nix

@@ -46,15 +46,12 @@ in {
       ignored.
 
       <warning>
-        <para>
+      <para>Some settings might require a re-login to take effect.</para>
-          Some settings might require a re-login to take effect.
-        </para>
       </warning>
+
       <warning>
-        <para>
+      <para>Some settings are only read from
-          Some settings are only read from
+      <option>targets.darwin.currentHostDefaults</option>.</para>
-          <option>targets.darwin.currentHostDefaults</option>.
-        </para>
       </warning>
     '';
   };
@@ -73,9 +70,7 @@ in {
       Values set to <literal>null</literal> are ignored.
 
       <warning>
-        <para>
+      <para>Some settings might require a re-login to take effect.</para>
-          Some settings might require a re-login to take effect.
-        </para>
       </warning>
     '';
   };

modules/targets/darwin/user-defaults/opts-allhosts.nix

@@ -123,10 +123,8 @@ in {
           Configures the web inspector.
 
           <warning>
-            <para>
+          <para>Instead of setting this option directly, set
-              Instead of setting this option directly, set
+          <option>IncludeDevelopMenu</option> instead.</para>
-              <option>IncludeDevelopMenu</option> instead.
-            </para>
           </warning>
         '';
       };
@@ -136,10 +134,8 @@ in {
           Configures the web inspector.
 
           <warning>
-            <para>
+          <para>Instead of setting this option directly, set
-              Instead of setting this option directly, set
+          <option>IncludeDevelopMenu</option> instead.</para>
-              <option>IncludeDevelopMenu</option> instead.
-            </para>
           </warning>
         '';
       };
@@ -152,10 +148,8 @@ in {
           Show the "Develop" menu in Safari's menubar.
 
           <warning>
-            <para>
+          <para>Instead of setting this option directly, set
-              Instead of setting this option directly, set
+          <option>"com.apple.Safari".IncludeDevelopMenu</option> instead.</para>
-              <option>"com.apple.Safari".IncludeDevelopMenu</option> instead.
-            </para>
           </warning>
         '';
       };

modules/xresources.nix

@@ -50,7 +50,7 @@ in {
         All other values are directly formatted using builtins.toString.
         Note, that 2-dimensional lists are not supported and specifying one will throw an exception.
         If this and all other xresources options are
-        <code>null</code>, then this feature is disabled and no
+        <literal>null</literal>, then this feature is disabled and no
         <filename>~/.Xresources</filename> link is produced.
       '';
     };
@@ -71,7 +71,7 @@ in {
       description = ''
         Additional X server resources contents.
         If this and all other xresources options are
-        <code>null</code>, then this feature is disabled and no
+        <literal>null</literal>, then this feature is disabled and no
         <filename>~/.Xresources</filename> link is produced.
       '';
     };

tests/big-test.nix

@@ -5,7 +5,7 @@
     type = lib.types.bool;
     default = true;
     description = ''
-      Whether to enable <quote>big</quote> tests. These are tests that require
+      Whether to enable "big" tests. These are tests that require
       more resources than typical tests. For example, tests that depend on large
       packages or tests that take long to run.
     '';