diff --git a/modules/i18n/input-method/default.nix b/modules/i18n/input-method/default.nix index e0d95e6f..70310e17 100644 --- a/modules/i18n/input-method/default.nix +++ b/modules/i18n/input-method/default.nix @@ -31,47 +31,33 @@ in { (types.enum [ "fcitx" "fcitx5" "nabi" "uim" "hime" "kime" ]); default = null; example = "fcitx5"; - description = '' - Select the enabled input method. Input methods is a software to input + description = lib.mdDoc '' + Select the enabled input method. Input methods are software to input symbols that are not available on standard input devices. - - Input methods are specially used to input Chinese, Japanese and Korean - characters. - + + Input methods are especially used to input Chinese, Japanese and + Korean characters. + Currently the following input methods are available in Home Manager: - - - fcitx5 - - A customizable lightweight input method. - The next generation of fcitx, - addons (including engines, dictionaries, skins) can be added using - i18n.inputMethod.fcitx5.addons. - - - - nabi - - A Korean input method based on XIM. Nabi doesn't support Qt 5. - - - - uim - - The universal input method, is a library with a XIM bridge. - uim mainly support Chinese, Japanese and Korean. - - - - hime - An extremely easy-to-use input method framework. - - - kime - A Korean IME. - - + `fcitx5` + : A customizable lightweight input method. + The next generation of fcitx. + Addons (including engines, dictionaries, skins) can be added using + [](#opt-i18n.inputMethod.fcitx5.addons). + + `nabi` + : A Korean input method based on XIM. Nabi doesn't support Qt 5. + + `uim` + : The "universal input method" is a library with an XIM bridge. + uim mainly supports Chinese, Japanese and Korean. + + `hime` + : An extremely easy-to-use input method framework. + + `kime` + : A Korean IME. ''; }; diff --git a/modules/misc/news.nix b/modules/misc/news.nix index ef1bc741..7228f18d 100644 --- a/modules/misc/news.nix +++ b/modules/misc/news.nix @@ -57,46 +57,25 @@ in display = mkOption { type = types.enum [ "silent" "notify" "show" ]; default = "notify"; - description = '' + description = lib.mdDoc '' How unread and relevant news should be presented when - running home-manager build and - home-manager switch. - - + running {command}`home-manager build` and + {command}`home-manager switch`. The options are - - - silent - - - Do not print anything during build or switch. The - home-manager news command still - works for viewing the entries. - - - - - notify - - - The number of unread and relevant news entries will be - printed to standard output. The home-manager - news command can later be used to view the - entries. - - - - - show - - - A pager showing unread news entries is opened. - - - - + `silent` + : Do not print anything during build or switch. The + {command}`home-manager news` command still + works for viewing the entries. + + `notify` + : The number of unread and relevant news entries will be + printed to standard output. The {command}`home-manager + news` command can later be used to view the entries. + + `show` + : A pager showing unread news entries is opened. ''; }; diff --git a/modules/misc/qt.nix b/modules/misc/qt.nix index d009b3e6..d90f8493 100644 --- a/modules/misc/qt.nix +++ b/modules/misc/qt.nix @@ -55,35 +55,27 @@ in { [ "libsForQt5" "plasma-integration" ] [ "libsForQt5" "systemsettings" ] ]; - description = '' - Platform theme to use for Qt applications. - The options are - - - gtk - Use GTK theme with - qtstyleplugins - - - - gnome - Use GNOME theme with - qgnomeplatform - - - - qtct - Use Qt style set using - qt5ct - and - qt6ct - applications - - - kde - Use Qt settings from Plasma - - + description = lib.mdDoc '' + Platform theme to use for Qt applications. + + The options are + + `gtk` + : Use GTK theme with + [`qtstyleplugins`](https://github.com/qt/qtstyleplugins) + + `gnome` + : Use GNOME theme with + [`qgnomeplatform`](https://github.com/FedoraQt/QGnomePlatform) + + `qtct` + : Use Qt style set using + [`qt5ct`](https://github.com/desktop-app/qt5ct) + and [`qt6ct`](https://github.com/trialuser02/qt6ct) + applications + + `kde` + : Use Qt settings from Plasma ''; }; @@ -100,45 +92,26 @@ in { [ "libsForQt5" "qtstyleplugin-kvantum" ] [ "qt6Packages" "qtstyleplugin-kvantum" ] ]; - description = '' + description = lib.mdDoc '' Style to use for Qt5/Qt6 applications. Case-insensitive. - - Some examples are - - - adwaita - adwaita-dark - adwaita-highcontrast - adwaita-highcontrastinverse - Use the Adwaita style from - adwaita - - - - breeze - Use the Breeze style from - breeze - - - - bb10bright - bb10dark - cde - cleanlooks - gtk2 - motif - plastique - Use styles from - qtstyleplugins - - - - kvantum - Use styles from - kvantum - - - + + Some examples are + + `adwaita`, `adwaita-dark`, `adwaita-highcontrast`, `adwaita-highcontrastinverse` + : Use the Adwaita style from + [`adwaita-qt`](https://github.com/FedoraQt/adwaita-qt) + + `breeze` + : Use the Breeze style from + [`breeze`](https://github.com/KDE/breeze) + + `bb10bright`, `bb10dark`, `cde`, `cleanlooks`, `gtk2`, `motif`, `plastique` + : Use styles from + [`qtstyleplugins`](https://github.com/qt/qtstyleplugins) + + `kvantum` + : Use styles from + [`kvantum`](https://github.com/tsujan/Kvantum) ''; }; diff --git a/modules/programs/astroid.nix b/modules/programs/astroid.nix index 4e79ea4d..f40797dd 100644 --- a/modules/programs/astroid.nix +++ b/modules/programs/astroid.nix @@ -79,15 +79,20 @@ in { }; example = "nvim-qt -- -c 'set ft=mail' '+set fileencoding=utf-8' '+set ff=unix' '+set enc=utf-8' '+set fo+=w' %1"; - description = '' - You can use %1, %2, and - %3 to refer respectively to: - - file name - server name - socket ID - - See . + description = lib.mdDoc '' + You can use the following variables: + + `%1` + : file name + + `%2` + : server name + + `%3` + : socket ID + + See [Customizing editor](https://github.com/astroidmail/astroid/wiki/Customizing-editor) + on the Astroid wiki. ''; }; diff --git a/modules/programs/broot.nix b/modules/programs/broot.nix index f90ed308..361dcfc6 100644 --- a/modules/programs/broot.nix +++ b/modules/programs/broot.nix @@ -30,44 +30,33 @@ let } ] ''; - description = '' + description = lib.mdDoc '' Define new verbs. For more information, see - . - - The possible attributes are: - + [Verb Definition Attributes](https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes) + in the broot documentation. - - - - 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) - whether the verb must be executed from the - parent shell (default: - false) - - + 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) + : 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. - + Complete list of keys (expected to change before the v1 of broot): - - 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 - + * `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` - - Add _fg for a foreground color and - _bg for a background colors. + Add `_fg` for a foreground color and + `_bg` for a background color. ''; }; }; diff --git a/modules/programs/gnome-terminal.nix b/modules/programs/gnome-terminal.nix index a9e3b5a7..8ff161c6 100644 --- a/modules/programs/gnome-terminal.nix +++ b/modules/programs/gnome-terminal.nix @@ -148,42 +148,24 @@ let backspaceBinding = mkOption { default = "ascii-delete"; type = eraseBinding; - description = '' + description = lib.mdDoc '' Which string the terminal should send to an application when the user - presses the Backspace key. + presses the *Backspace* key. - - - auto - - Attempt to determine the right value from the terminal's IO settings. - - - - ascii-backspace - - Send an ASCII backspace character (0x08). - - - - ascii-delete - - Send an ASCII delete character (0x7F). - - - - delete-sequence - - Send the @7 control sequence. - - - - tty - - Send terminal’s erase setting. - - - + `auto` + : Attempt to determine the right value from the terminal's IO settings. + + `ascii-backspace` + : Send an ASCII backspace character (`0x08`). + + `ascii-delete` + : Send an ASCII delete character (`0x7F`). + + `delete-sequence` + : Send the `@7` control sequence. + + `tty` + : Send terminal's "erase" setting. ''; }; @@ -196,42 +178,24 @@ let deleteBinding = mkOption { default = "delete-sequence"; type = eraseBinding; - description = '' + description = lib.mdDoc '' Which string the terminal should send to an application when the user - presses the Delete key. + presses the *Delete* key. - - - auto - - Send the @7 control sequence. - - - - ascii-backspace - - Send an ASCII backspace character (0x08). - - - - ascii-delete - - Send an ASCII delete character (0x7F). - - - - delete-sequence - - Send the @7 control sequence. - - - - tty - - Send terminal’s erase setting. - - - + `auto` + : Send the `@7` control sequence. + + `ascii-backspace` + : Send an ASCII backspace character (`0x08`). + + `ascii-delete` + : Send an ASCII delete character (`0x7F`). + + `delete-sequence` + : Send the `@7` control sequence. + + `tty` + : Send terminal's "erase" setting. ''; }; diff --git a/modules/programs/gpg.nix b/modules/programs/gpg.nix index 0b75931d..3e62995c 100644 --- a/modules/programs/gpg.nix +++ b/modules/programs/gpg.nix @@ -62,34 +62,27 @@ let }.${v} else v; - description = '' + description = lib.mdDoc '' The amount of trust you have in the key ownership and the care the owner puts into signing other keys. The available levels are - - - unknown or 1 - I don't know or won't say. - - - never or 2 - I do NOT trust. - - - marginal or 3 - I trust marginally. - - - full or 4 - I trust fully. - - - ultimate or 5 - I trust ultimately. - - - - See - for more. + + `unknown` or `1` + : I don't know or won't say. + + `never` or `2` + : I do **not** trust. + + `marginal` or `3` + : I trust marginally. + + `full` or `4` + : I trust fully. + + `ultimate` or `5` + : I trust ultimately. + + See the [Key Management chapter](https://www.gnupg.org/gph/en/manual/x334.html) + of the GNU Privacy Handbook for more. ''; }; }; diff --git a/modules/programs/hexchat.nix b/modules/programs/hexchat.nix index 4eda0755..17e66974 100644 --- a/modules/programs/hexchat.nix +++ b/modules/programs/hexchat.nix @@ -73,48 +73,35 @@ let loginMethod = mkOption { type = nullOr (enum (attrNames loginMethodMap)); default = null; - description = '' + description = lib.mdDoc '' The login method. The allowed options are: - - - null - Default - - - "nickServMsg" - NickServ (/MSG NickServ + password) - - - "nickServ" - NickServ (/NICKSERV + password) - - - "challengeAuth" - Challenge Auth (username + password) - - - "sasl" - SASL (username + password) - - - "serverPassword" - Server password (/PASS password) - - - "saslExternal" - SASL EXTERNAL (cert) - - - "customCommands" - - Use "commands" field for auth. For example - - commands = [ "/msg NickServ IDENTIFY my_password" ] - - - - - + + `null` + : Default + + `"nickServMsg"` + : NickServ (`/MSG NickServ` + password) + + `"nickServ"` + : NickServ (`/NICKSERV` + password) + + `"challengeAuth"` + : Challenge Auth (username + password) + + `"sasl"` + : SASL (username + password) + + `"serverPassword"` + : Server password (`/PASS` password) + + `"saslExternal"` + : SASL EXTERNAL (cert) + + `"customCommands"` + : Use "commands" field for auth. For example + ```nix + commands = [ "/msg NickServ IDENTIFY my_password" ] + ``` ''; }; @@ -293,25 +280,20 @@ in { overwriteConfigFiles = mkOption { type = nullOr bool; default = false; - description = '' + description = lib.mdDoc '' Enables overwriting HexChat configuration files - (hexchat.conf, servlist.conf). - Any existing HexChat configuration will be lost. Certify to back-up any - previous configuration before enabling this. - + ({file}`hexchat.conf`, {file}`servlist.conf`). + Any existing HexChat configuration will be lost. Make sure to back up + any previous configuration before enabling this. + Enabling this setting is recommended, because everytime HexChat application is closed it overwrites Nix/Home Manager provided configuration files, causing: - - - Nix/Home Manager provided configuration to be out of sync with - actual active HexChat configuration. - - - Blocking Nix/Home Manager updates until configuration files are - manually removed. - - + + 1. Nix/Home Manager provided configuration to be out of sync with + actual active HexChat configuration. + 2. Nix/Home Manager updates to be blocked until configuration files are + manually removed. ''; }; diff --git a/modules/programs/qutebrowser.nix b/modules/programs/qutebrowser.nix index 4c391f94..e3c17cc3 100644 --- a/modules/programs/qutebrowser.nix +++ b/modules/programs/qutebrowser.nix @@ -133,111 +133,77 @@ in { keyBindings = mkOption { type = with types; attrsOf (attrsOf (separatedString " ;; ")); default = { }; - description = '' + description = lib.mdDoc '' Key bindings mapping keys to commands in different modes. This setting is a dictionary containing mode names and dictionaries mapping keys to - commands: {mode: {key: command}} If you want to map - a key to another key, check the keyMappings setting - instead. For modifiers, you can use either - or - + as delimiters, and these names: + commands: `{mode: {key: command}}` If you want to map + a key to another key, check the `keyMappings` setting + instead. For modifiers, you can use either `-` or + `+` as delimiters, and these names: - - - Control: Control, Ctrl - - - Meta: Meta, Windows, - Mod4 - - - Alt: Alt, Mod1 - - - Shift: Shift - - + Control + : `Control`, `Ctrl` - For simple keys (no <>-signs), a capital + Meta + : `Meta`, `Windows`, `Mod4` + + Alt + : `Alt`, `Mod1` + + Shift + : `Shift` + + For simple keys (no `<>`-signs), a capital letter means the key is pressed with Shift. For special keys (with - <>-signs), you need to explicitly add - Shift- to match a key pressed with shift. If you - want a binding to do nothing, bind it to the nop + `<>`-signs), you need to explicitly add + `Shift-` to match a key pressed with shift. If you + want a binding to do nothing, bind it to the `nop` command. If you want a default binding to be passed through to the website, bind it to null. Note that some commands which are only useful for bindings (but not used interactively) are hidden from the command - completion. See :help for a full list of available + completion. See `:help` for a full list of available commands. The following modes are available: - - - normal - - Default mode, where most commands are invoked. - - - - insert - - Entered when an input field is focused on a website, or by - pressing i in normal mode. Passes through almost all keypresses - to the website, but has some bindings like - <Ctrl-e> to open an external editor. - Note that single keys can’t be bound in this mode. - - - - hint - - Entered when f is pressed to select links with the keyboard. Note - that single keys can’t be bound in this mode. - - - - passthrough - - Similar to insert mode, but passes through all keypresses except - <Escape> to leave the mode. It might be - useful to bind <Escape> to some other - key in this mode if you want to be able to send an Escape key to - the website as well. Note that single keys can’t be bound in this - mode. - - - - command - - Entered when pressing the : key in order to enter a command. Note - that single keys can’t be bound in this mode. - - - - prompt - - Entered when there’s a prompt to display, like for download - locations or when invoked from JavaScript. - - - - yesno - - Entered when there’s a yes/no prompt displayed. - - - - caret - - Entered when pressing the v mode, used to select text using the - keyboard. - - - - register - - Entered when qutebrowser is waiting for a register name/key for - commands like :set-mark. - - - + `normal` + : Default mode, where most commands are invoked. + + `insert` + : Entered when an input field is focused on a website, or by + pressing `i` in normal mode. Passes through almost all keypresses + to the website, but has some bindings like + `` to open an external editor. + Note that single keys can't be bound in this mode. + + `hint` + : Entered when `f` is pressed to select links with the keyboard. Note + that single keys can't be bound in this mode. + + `passthrough` + : Similar to insert mode, but passes through all keypresses except + `` to leave the mode. It might be + useful to bind `` to some other + key in this mode if you want to be able to send an Escape key to + the website as well. Note that single keys can't be bound in this + mode. + + `command` + : Entered when pressing the `:` key in order to enter a command. Note + that single keys can't be bound in this mode. + + `prompt` + : Entered when there's a prompt to display, like for download + locations or when invoked from JavaScript. + + `yesno` + : Entered when there's a yes/no prompt displayed. + + `caret` + : Entered when pressing the `v` mode, used to select text using the + keyboard. + + `register` + : Entered when qutebrowser is waiting for a register name/key for + commands like `:set-mark`. ''; example = literalExpression '' { diff --git a/modules/services/udiskie.nix b/modules/services/udiskie.nix index 28cb4c24..19f4eae7 100644 --- a/modules/services/udiskie.nix +++ b/modules/services/udiskie.nix @@ -72,26 +72,19 @@ in { tray = mkOption { type = types.enum [ "always" "auto" "never" ]; default = "auto"; - description = '' + description = lib.mdDoc '' Whether to display tray icon. - + The options are - - - always - Always show tray icon. - - - auto - - Show tray icon only when there is a device available. - - - - never - Never show tray icon. - - + + `always` + : Always show tray icon. + + `auto` + : Show tray icon only when there is a device available. + + `never` + : Never show tray icon. ''; }; }; diff --git a/modules/services/window-managers/i3-sway/sway.nix b/modules/services/window-managers/i3-sway/sway.nix index 5568d6ab..165738a9 100644 --- a/modules/services/window-managers/i3-sway/sway.nix +++ b/modules/services/window-managers/i3-sway/sway.nix @@ -363,18 +363,16 @@ in { type = types.bool; default = pkgs.stdenv.isLinux; example = false; - description = '' - Whether to enable sway-session.target on + description = lib.mdDoc '' + Whether to enable {file}`sway-session.target` on sway startup. This links to - graphical-session.target. + {file}`graphical-session.target`. Some important environment variables will be imported to systemd and dbus user environment before reaching the target, including - - DISPLAY - WAYLAND_DISPLAY - SWAYSOCK - XDG_CURRENT_DESKTOP - + * {env}`DISPLAY` + * {env}`WAYLAND_DISPLAY` + * {env}`SWAYSOCK` + * {env}`XDG_CURRENT_DESKTOP` ''; }; diff --git a/modules/systemd.nix b/modules/systemd.nix index 4762c18d..0f8f1018 100644 --- a/modules/systemd.nix +++ b/modules/systemd.nix @@ -164,40 +164,29 @@ in { type = with types; either bool (enum [ "suggest" "legacy" "sd-switch" ]); apply = p: if isBool p then if p then "legacy" else "suggest" else p; - description = '' + description = lib.mdDoc '' Whether new or changed services that are wanted by active targets should be started. Additionally, stop obsolete services from the previous generation. - + The alternatives are - - - suggest (or false) - - Use a very simple shell script to print suggested - systemctl commands to run. You will have to - manually run those commands after the switch. - - - - legacy (or true) - - Use a Ruby script to, in a more robust fashion, determine the - necessary changes and automatically run the - systemctl commands. - - - - sd-switch - - Use sd-switch, a third party application, to perform the service - updates. This tool offers more features while having a small - closure size. Note, it requires a fully functional user D-Bus - session. Once tested and deemed sufficiently robust, this will - become the default. - - - + + `suggest` (or `false`) + : Use a very simple shell script to print suggested + {command}`systemctl` commands to run. You will have to + manually run those commands after the switch. + + `legacy` (or `true`) + : Use a Ruby script to, in a more robust fashion, determine the + necessary changes and automatically run the + {command}`systemctl` commands. + + `sd-switch` + : Use sd-switch, a third party application, to perform the service + updates. This tool offers more features while having a small + closure size. Note, it requires a fully functional user D-Bus + session. Once tested and deemed sufficiently robust, this will + become the default. ''; }; diff --git a/modules/targets/darwin/user-defaults/opts-allhosts.nix b/modules/targets/darwin/user-defaults/opts-allhosts.nix index 832318a9..a604c55f 100644 --- a/modules/targets/darwin/user-defaults/opts-allhosts.nix +++ b/modules/targets/darwin/user-defaults/opts-allhosts.nix @@ -174,23 +174,19 @@ in { OpenTmuxWindowsIn = mkNullableOption { type = types.int; example = 2; - description = '' + description = lib.mdDoc '' Configures how to restore tmux windows when attaching to a session. - Possible Values - - 0 - Native windows - - - 1 - Native tabs in a new window - - - 2 - Tabs in the attaching window - - + **Possible Values** + + `0` + : Native windows + + `1` + : Native tabs in a new window + + `2` + : Tabs in the attaching window ''; };