From c1d8d2a3d1cc7b5ee5849d486140c15e7d82d336 Mon Sep 17 00:00:00 2001 From: Emily Date: Fri, 30 Jun 2023 05:48:21 +0100 Subject: [PATCH] treewide: adjust some DocBook for conversion The NixOS variant of Markdown doesn't make a distinction between `` and `` or `` and... quotes, and doesn't support `` or ``. These are infrequently used (apart from ``) 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 | 4 ++-- modules/home-environment.nix | 12 ++++++------ modules/misc/dconf.nix | 2 +- modules/misc/editorconfig.nix | 2 +- modules/misc/xdg-desktop-entries.nix | 6 ++++-- modules/misc/xfconf.nix | 2 +- modules/programs/autorandr.nix | 6 +++--- modules/programs/bash.nix | 2 +- modules/programs/dircolors.nix | 2 +- modules/programs/fzf.nix | 2 +- modules/programs/i3status-rust.nix | 2 +- modules/programs/i3status.nix | 4 ++-- modules/programs/msmtp-accounts.nix | 4 ++-- modules/programs/mujmap.nix | 14 +++++++------- modules/programs/ncmpcpp.nix | 4 ++-- modules/programs/offlineimap.nix | 2 +- modules/programs/rtx.nix | 8 +++----- modules/programs/sbt.nix | 8 ++++---- modules/programs/waybar.nix | 6 +++--- modules/programs/yt-dlp.nix | 6 +++--- modules/services/borgmatic.nix | 2 +- modules/services/home-manager-auto-upgrade.nix | 4 ++-- .../services/window-managers/i3-sway/i3.nix | 2 +- .../services/window-managers/i3-sway/sway.nix | 4 ++-- modules/services/xidlehook.nix | 2 +- modules/targets/darwin/keybindings.nix | 6 ++---- .../targets/darwin/user-defaults/default.nix | 15 +++++---------- .../darwin/user-defaults/opts-allhosts.nix | 18 ++++++------------ modules/xresources.nix | 4 ++-- tests/big-test.nix | 2 +- 30 files changed, 72 insertions(+), 85 deletions(-) diff --git a/modules/accounts/email.nix b/modules/accounts/email.nix index 897aef6dd..ed7ae55ec 100644 --- a/modules/accounts/email.nix +++ b/modules/accounts/email.nix @@ -147,7 +147,7 @@ let If both this option and are specified, - host is preferred by applications when establishing a + host is preferred by applications when establishing a session. ''; }; @@ -161,7 +161,7 @@ let If both this option and are specified, - host is preferred by applications when establishing a + host is preferred by applications when establishing a session. ''; }; diff --git a/modules/home-environment.nix b/modules/home-environment.nix index 12fd9f39d..c2ea3f87d 100644 --- a/modules/home-environment.nix +++ b/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 parameter may be referenced as - $parameter or ''${parameter}. A + $parameter or ''${parameter}. A default value foo may be given as per - ''${parameter:-foo} and, similarly, an alternate + ''${parameter:-foo} and, similarly, an alternate value bar can be given as per - ''${parameter:+bar}. + ''${parameter:+bar}. 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 These directories are added to the PATH variable in a - double-quoted context, so expressions like $HOME are - expanded by the shell. However, since expressions like ~ or - * are escaped, they will end up in the PATH + double-quoted context, so expressions like $HOME are + expanded by the shell. However, since expressions like ~ or + * are escaped, they will end up in the PATH verbatim. ''; }; diff --git a/modules/misc/dconf.nix b/modules/misc/dconf.nix index 8aa8e8d83..cd66d4d5b 100644 --- a/modules/misc/dconf.nix +++ b/modules/misc/dconf.nix @@ -37,7 +37,7 @@ in { Whether to enable dconf settings. Note, if you use NixOS then you must add - programs.dconf.enable = true + programs.dconf.enable = true to your system configuration. Otherwise you will see a systemd error message when your configuration is activated. ''; diff --git a/modules/misc/editorconfig.nix b/modules/misc/editorconfig.nix index 579ef1f81..2c9764af8 100644 --- a/modules/misc/editorconfig.nix +++ b/modules/misc/editorconfig.nix @@ -19,7 +19,7 @@ in { default = { }; description = '' Configuration written to $HOME/.editorconfig. - root = true is automatically added to the file, + root = true is automatically added to the file, it must not be added here. See for documentation. ''; diff --git a/modules/misc/xdg-desktop-entries.nix b/modules/misc/xdg-desktop-entries.nix index c538eda33..6fbcd79a3 100644 --- a/modules/misc/xdg-desktop-entries.nix +++ b/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. - You can define entries for programs without entries or override existing entries. + 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. + See for more information on options. ''; default = { }; diff --git a/modules/misc/xfconf.nix b/modules/misc/xfconf.nix index f9858c5fa..2eda5efd2 100644 --- a/modules/misc/xfconf.nix +++ b/modules/misc/xfconf.nix @@ -67,7 +67,7 @@ in { Whether to enable Xfconf settings. Note, if you use NixOS then you must add - programs.xfconf.enable = true + programs.xfconf.enable = true to your system configuration. Otherwise you will see a systemd error message when your configuration is activated. ''; diff --git a/modules/programs/autorandr.nix b/modules/programs/autorandr.nix index 9e7c6fcc4..47c810f52 100644 --- a/modules/programs/autorandr.nix +++ b/modules/programs/autorandr.nix @@ -28,7 +28,7 @@ let type = types.attrsOf types.str; description = '' Output name to EDID mapping. - Use autorandr --fingerprint to get current setup values. + Use autorandr --fingerprint to get current setup values. ''; default = { }; }; @@ -160,9 +160,9 @@ let 1 option - --scale-from + --scale-from will be used; when using factor method the option - --scale + --scale will be used. This option is a shortcut version of the transform option and they are mutually diff --git a/modules/programs/bash.nix b/modules/programs/bash.nix index 0c0643da8..e3c937df6 100644 --- a/modules/programs/bash.nix +++ b/modules/programs/bash.nix @@ -103,7 +103,7 @@ in { example = [ "extglob" "-cdspell" ]; description = '' Shell options to set. Prefix an option with - - to unset. + "-" to unset. ''; }; diff --git a/modules/programs/dircolors.nix b/modules/programs/dircolors.nix index 655d71e57..6953ab159 100644 --- a/modules/programs/dircolors.nix +++ b/modules/programs/dircolors.nix @@ -15,7 +15,7 @@ in { default = false; description = '' Whether to manage .dir_colors - and set LS_COLORS. + and set LS_COLORS. ''; }; diff --git a/modules/programs/fzf.nix b/modules/programs/fzf.nix index fe1e720d9..b572d0a55 100644 --- a/modules/programs/fzf.nix +++ b/modules/programs/fzf.nix @@ -104,7 +104,7 @@ in { } ''; description = '' - Color scheme options added to FZF_DEFAULT_OPTS. See + Color scheme options added to FZF_DEFAULT_OPTS. See for documentation. ''; diff --git a/modules/programs/i3status-rust.nix b/modules/programs/i3status-rust.nix index 237afd818..39146d55a 100644 --- a/modules/programs/i3status-rust.nix +++ b/modules/programs/i3status-rust.nix @@ -165,7 +165,7 @@ in { Attribute set of i3status-rust bars, each with their own configuration. Each bar name generates a config file suffixed with the bar's name from the attribute set, like so: - config-name.toml. + config-''${name}.toml. This way, multiple config files can be generated, such as for having a top and a bottom bar. diff --git a/modules/programs/i3status.nix b/modules/programs/i3status.nix index d6abf27c1..f3006f2c6 100644 --- a/modules/programs/i3status.nix +++ b/modules/programs/i3status.nix @@ -52,7 +52,7 @@ in { default = { }; description = '' Configuration to add to i3status config - general section. + general section. See i3status @@ -84,7 +84,7 @@ in { position = mkOption { type = with types; either int float; description = '' - Position of this module in i3status order. + Position of this module in i3status order. ''; }; settings = mkOption { diff --git a/modules/programs/msmtp-accounts.nix b/modules/programs/msmtp-accounts.nix index 894cef517..fc5273472 100644 --- a/modules/programs/msmtp-accounts.nix +++ b/modules/programs/msmtp-accounts.nix @@ -11,13 +11,13 @@ with lib; Whether to enable msmtp. If enabled then it is possible to use the - --account command line + --account command line option to send a message for a given account using the msmtp or msmtpq tool. For example, msmtp --account=private would send using the account defined in . If the - --account option is not + --account option is not given then the primary account will be used. ''; }; diff --git a/modules/programs/mujmap.nix b/modules/programs/mujmap.nix index 291b96566..a9467820e 100644 --- a/modules/programs/mujmap.nix +++ b/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 - Inbox name attribute. + Inbox name attribute. If set to an empty string, this mailbox and its child mailboxes 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 - Trash name attribute. + Trash name attribute. If set to an empty string, this mailbox and its child mailboxes 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 - Sent name attribute. + Sent name attribute. If set to an empty string, this mailbox and its child mailboxes 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 - Junk name attribute and/or with the $Junk keyword, - except for messages with the $NotJunk keyword. + Junk name attribute and/or with the $Junk keyword, + except for messages with the $NotJunk keyword. If set to an empty string, this mailbox, its child mailboxes, 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 - Important name attribute and/or with the $Important + Important name attribute and/or with the $Important keyword. If set to an empty string, this mailbox, its child @@ -131,7 +131,7 @@ let type = types.str; default = "phishing"; description = '' - Tag for notmuch to use for the IANA $Phishing keyword. + Tag for notmuch to use for the IANA $Phishing keyword. If set to an empty string, this keyword is not synchronized with a tag. ''; diff --git a/modules/programs/ncmpcpp.nix b/modules/programs/ncmpcpp.nix index 5f9bd36eb..117828557 100644 --- a/modules/programs/ncmpcpp.nix +++ b/modules/programs/ncmpcpp.nix @@ -55,7 +55,7 @@ in { default = pkgs.ncmpcpp; defaultText = literalExpression "pkgs.ncmpcpp"; description = '' - Package providing the ncmpcpp command. + Package providing the ncmpcpp command. ''; example = literalExpression "pkgs.ncmpcpp.override { visualizerSupport = true; }"; @@ -75,7 +75,7 @@ in { null ''; description = '' - Value of the mpd_music_dir setting. On Linux platforms the + Value of the mpd_music_dir setting. On Linux platforms the value of services.mpd.musicDirectory is used as the default if services.mpd.enable is true. diff --git a/modules/programs/offlineimap.nix b/modules/programs/offlineimap.nix index 954dab193..439c40d42 100644 --- a/modules/programs/offlineimap.nix +++ b/modules/programs/offlineimap.nix @@ -151,7 +151,7 @@ in { ''; description = '' Extra configuration options added to the - mbnames section. + mbnames section. ''; }; }; diff --git a/modules/programs/rtx.nix b/modules/programs/rtx.nix index b78000784..7400448e5 100644 --- a/modules/programs/rtx.nix +++ b/modules/programs/rtx.nix @@ -42,15 +42,13 @@ in { ''; description = '' Settings written to $XDG_CONFIG_HOME/rtx/config.toml. - + See for details on supported values. - - Modifying the tools section doesn't make RTX install them. - You have to manually run rtx install to install the tools. - + Modifying the tools section doesn't make RTX install them. + You have to manually run rtx install to install the tools. ''; }; diff --git a/modules/programs/sbt.nix b/modules/programs/sbt.nix index 3e8dbc102..ce0e73bf6 100644 --- a/modules/programs/sbt.nix +++ b/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 ~/.sbt/repositories + URL. The list will be used populate the ~/.sbt/repositories file in the order specified. - Pre-defined repositories must be one of local, - maven-local, maven-central. + Pre-defined repositories must be one of local, + maven-local, maven-central. Custom repositories are defined as - { name-of-repo = "https://url.to.repo.com"}. + { name-of-repo = "https://url.to.repo.com"}. diff --git a/modules/programs/waybar.nix b/modules/programs/waybar.nix index d82b673da..7a5f11f14 100644 --- a/modules/programs/waybar.nix +++ b/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 ("top") - of the windows or behind ("bottom"). + Decide if the bar is displayed in front ("top") + of the windows or behind ("bottom"). ''; example = "top"; }; @@ -152,7 +152,7 @@ in { default = pkgs.waybar; defaultText = literalExpression "pkgs.waybar"; description = '' - Waybar package to use. Set to null to use the default package. + Waybar package to use. Set to null to use the default package. ''; }; diff --git a/modules/programs/yt-dlp.nix b/modules/programs/yt-dlp.nix index 11398bd9d..8febb0595 100644 --- a/modules/programs/yt-dlp.nix +++ b/modules/programs/yt-dlp.nix @@ -41,9 +41,9 @@ in { Configuration written to $XDG_CONFIG_HOME/yt-dlp/config. - Options must be specified in their long form, for - example, update = true; instead of U = true;. - Short options can be specified in the extraConfig option. + Options must be specified in their "long form", for + example, update = true; instead of U = true;. + Short options can be specified in the extraConfig option. See for explanation about possible values. ''; diff --git a/modules/services/borgmatic.nix b/modules/services/borgmatic.nix index c2f2963a2..62c834a8c 100644 --- a/modules/services/borgmatic.nix +++ b/modules/services/borgmatic.nix @@ -17,7 +17,7 @@ in { default = "hourly"; description = '' How often to run borgmatic when - services.borgmatic.enable = true. + services.borgmatic.enable = true. This value is passed to the systemd timer configuration as the onCalendar option. See diff --git a/modules/services/home-manager-auto-upgrade.nix b/modules/services/home-manager-auto-upgrade.nix index 2f975ef1b..d4851322f 100644 --- a/modules/services/home-manager-auto-upgrade.nix +++ b/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 home-manager switch''; + channels before running home-manager switch''; 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 OnCalendar option. + as the OnCalendar option. The format is described in systemd.time diff --git a/modules/services/window-managers/i3-sway/i3.nix b/modules/services/window-managers/i3-sway/i3.nix index 23627aedd..4f08d4f3c 100644 --- a/modules/services/window-managers/i3-sway/i3.nix +++ b/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 . - Consider to use lib.mkOptionDefault function to extend or override + Consider to use lib.mkOptionDefault function to extend or override default keybindings instead of specifying all of them from scratch. ''; example = literalExpression '' diff --git a/modules/services/window-managers/i3-sway/sway.nix b/modules/services/window-managers/i3-sway/sway.nix index 165738a94..9f412c9c3 100644 --- a/modules/services/window-managers/i3-sway/sway.nix +++ b/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 . - Consider to use lib.mkOptionDefault function to extend or override + Consider to use lib.mkOptionDefault 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 null to not add any Sway package to your + Set to null 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. ''; diff --git a/modules/services/xidlehook.nix b/modules/services/xidlehook.nix index d769ccafb..9c90fd9fe 100644 --- a/modules/services/xidlehook.nix +++ b/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 export name=value. + These options are passed unescaped as export name=value. ''; }; diff --git a/modules/targets/darwin/keybindings.nix b/modules/targets/darwin/keybindings.nix index 824daa572..60582d62e 100644 --- a/modules/targets/darwin/keybindings.nix +++ b/modules/targets/darwin/keybindings.nix @@ -22,10 +22,8 @@ in { for more details. - - Existing keybinding configuration will be wiped when using this - option. - + Existing keybinding configuration will be wiped when using this + option. ''; }; diff --git a/modules/targets/darwin/user-defaults/default.nix b/modules/targets/darwin/user-defaults/default.nix index c44d4f9c4..c397740da 100644 --- a/modules/targets/darwin/user-defaults/default.nix +++ b/modules/targets/darwin/user-defaults/default.nix @@ -46,15 +46,12 @@ in { ignored. - - Some settings might require a re-login to take effect. - + Some settings might require a re-login to take effect. + - - Some settings are only read from - . - + Some settings are only read from + . ''; }; @@ -73,9 +70,7 @@ in { Values set to null are ignored. - - Some settings might require a re-login to take effect. - + Some settings might require a re-login to take effect. ''; }; diff --git a/modules/targets/darwin/user-defaults/opts-allhosts.nix b/modules/targets/darwin/user-defaults/opts-allhosts.nix index a604c55f0..7f0c5df7b 100644 --- a/modules/targets/darwin/user-defaults/opts-allhosts.nix +++ b/modules/targets/darwin/user-defaults/opts-allhosts.nix @@ -123,10 +123,8 @@ in { Configures the web inspector. - - Instead of setting this option directly, set - instead. - + Instead of setting this option directly, set + instead. ''; }; @@ -136,10 +134,8 @@ in { Configures the web inspector. - - Instead of setting this option directly, set - instead. - + Instead of setting this option directly, set + instead. ''; }; @@ -152,10 +148,8 @@ in { Show the "Develop" menu in Safari's menubar. - - Instead of setting this option directly, set - instead. - + Instead of setting this option directly, set + instead. ''; }; diff --git a/modules/xresources.nix b/modules/xresources.nix index 31eb6eaad..4d9e70c32 100644 --- a/modules/xresources.nix +++ b/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 - null, then this feature is disabled and no + null, then this feature is disabled and no ~/.Xresources link is produced. ''; }; @@ -71,7 +71,7 @@ in { description = '' Additional X server resources contents. If this and all other xresources options are - null, then this feature is disabled and no + null, then this feature is disabled and no ~/.Xresources link is produced. ''; }; diff --git a/tests/big-test.nix b/tests/big-test.nix index 421eaebbd..5396f170e 100644 --- a/tests/big-test.nix +++ b/tests/big-test.nix @@ -5,7 +5,7 @@ type = lib.types.bool; default = true; description = '' - Whether to enable big 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. '';