nix-community/home-manager
1
0
Fork 0
mirror of https://github.com/nix-community/home-manager.git synced 2025-11-23 02:39:40 +01:00
Code Activity

treewide: convert options with lists to Markdown

Browse source 
`nix-doc-munge` can't handle these, which is understandable as I can
barely handle them either. There are a few infelicities here: the
current processor can't handle multiple terms to one description in
a description list so they get comma-separated in one case, and one
case that should ideally render as a `<figure>` with a `<figcaption>`
in HTML is reduced to a paragraph with some `<strong>` text. (Which, in
fairness, is how it rendered in practice with the DocBook anyway.) The
docs generator has since been updated to handle figures, but we can't
use it until moving off DocBook output.
This commit is contained in:
Emily 2023-07-01 01:40:42 +01:00
parent 9e4a73c25e
commit 21c700d14b
13 changed files with 341 additions and 531 deletions
Download patch file Download diff file Expand all files Collapse all files

23
modules/programs/astroid.nix
View file

@ -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 <code>%1</code>, <code>%2</code>, and
<code>%3</code> to refer respectively to:
<orderedlist numeration="arabic">
<listitem><para>file name</para></listitem>
<listitem><para>server name</para></listitem>
<listitem><para>socket ID</para></listitem>
</orderedlist>
See <link xlink:href='https://github.com/astroidmail/astroid/wiki/Customizing-editor' />.
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.
'';
};

114
modules/programs/broot.nix
View file

@ -30,44 +30,33 @@ let
}
]
'';
description = ''
description = lib.mdDoc ''
Define new verbs. For more information, see
<link xlink:href="https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes"/>.
</para><para>
The possible attributes are:
</para>
[Verb Definition Attributes](https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes)
in the broot documentation.
<para>
<variablelist>
<varlistentry>
<term><literal>invocation</literal> (optional)</term>
<listitem><para>how the verb is called by the user, with placeholders for arguments</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>execution</literal> (mandatory)</term>
<listitem><para>how the verb is executed</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>key</literal> (optional)</term>
<listitem><para>a keyboard key triggering execution</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>shortcut</literal> (optional)</term>
<listitem><para>an alternate way to call the verb (without
the arguments part)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>leave_broot</literal> (optional)</term>
<listitem><para>whether to quit broot on execution
(default: <literal>true</literal>)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>from_shell</literal> (optional)</term>
<listitem><para>whether the verb must be executed from the
parent shell (default:
<literal>false</literal>)</para></listitem>
</varlistentry>
</variablelist>
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)</term>
: 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.
</para><para>
Complete list of keys (expected to change before the v1 of broot):
<itemizedlist>
<listitem><para><literal>char_match</literal></para></listitem>
<listitem><para><literal>code</literal></para></listitem>
<listitem><para><literal>directory</literal></para></listitem>
<listitem><para><literal>exe</literal></para></listitem>
<listitem><para><literal>file</literal></para></listitem>
<listitem><para><literal>file_error</literal></para></listitem>
<listitem><para><literal>flag_label</literal></para></listitem>
<listitem><para><literal>flag_value</literal></para></listitem>
<listitem><para><literal>input</literal></para></listitem>
<listitem><para><literal>link</literal></para></listitem>
<listitem><para><literal>permissions</literal></para></listitem>
<listitem><para><literal>selected_line</literal></para></listitem>
<listitem><para><literal>size_bar_full</literal></para></listitem>
<listitem><para><literal>size_bar_void</literal></para></listitem>
<listitem><para><literal>size_text</literal></para></listitem>
<listitem><para><literal>spinner</literal></para></listitem>
<listitem><para><literal>status_error</literal></para></listitem>
<listitem><para><literal>status_normal</literal></para></listitem>
<listitem><para><literal>table_border</literal></para></listitem>
<listitem><para><literal>tree</literal></para></listitem>
<listitem><para><literal>unlisted</literal></para></listitem>
</itemizedlist></para>
* `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`
<para>
Add <literal>_fg</literal> for a foreground color and
<literal>_bg</literal> for a background colors.
Add `_fg` for a foreground color and
`_bg` for a background color.
'';
};
};

100
modules/programs/gnome-terminal.nix
View file

@ -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 <emphasis>Backspace</emphasis> key.
presses the *Backspace* key.
<variablelist>
<varlistentry>
<term><literal>auto</literal></term>
<listitem><para>
Attempt to determine the right value from the terminal's IO settings.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>ascii-backspace</literal></term>
<listitem><para>
Send an ASCII backspace character (0x08).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>ascii-delete</literal></term>
<listitem><para>
Send an ASCII delete character (0x7F).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>delete-sequence</literal></term>
<listitem><para>
Send the <quote>@7</quote> control sequence.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>tty</literal></term>
<listitem><para>
Send terminal’s <quote>erase</quote> setting.
</para></listitem>
</varlistentry>
</variablelist>
`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 <emphasis>Delete</emphasis> key.
presses the *Delete* key.
<variablelist>
<varlistentry>
<term><literal>auto</literal></term>
<listitem><para>
Send the <quote>@7</quote> control sequence.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>ascii-backspace</literal></term>
<listitem><para>
Send an ASCII backspace character (0x08).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>ascii-delete</literal></term>
<listitem><para>
Send an ASCII delete character (0x7F).
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>delete-sequence</literal></term>
<listitem><para>
Send the <quote>@7</quote> control sequence.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>tty</literal></term>
<listitem><para>
Send terminal’s <quote>erase</quote> setting.
</para></listitem>
</varlistentry>
</variablelist>
`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.
'';
};

45
modules/programs/gpg.nix
View file

@ -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
<variablelist>
<varlistentry>
<term><literal>unknown</literal> or <literal>1</literal></term>
<listitem><para>I don't know or won't say.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>never</literal> or <literal>2</literal></term>
<listitem><para>I do NOT trust.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>marginal</literal> or <literal>3</literal></term>
<listitem><para>I trust marginally.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>full</literal> or <literal>4</literal></term>
<listitem><para>I trust fully.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>ultimate</literal> or <literal>5</literal></term>
<listitem><para>I trust ultimately.</para></listitem>
</varlistentry>
</variablelist>
</para><para>
See <link xlink:href="https://www.gnupg.org/gph/en/manual/x334.html"/>
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.
'';
};
};

94
modules/programs/hexchat.nix
View file

@ -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:
<variablelist>
<varlistentry>
<term><literal>null</literal></term>
<listitem><para>Default</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"nickServMsg"</literal></term>
<listitem><para>NickServ (/MSG NickServ + password)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"nickServ"</literal></term>
<listitem><para>NickServ (/NICKSERV + password)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"challengeAuth"</literal></term>
<listitem><para>Challenge Auth (username + password)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"sasl"</literal></term>
<listitem><para>SASL (username + password)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"serverPassword"</literal></term>
<listitem><para>Server password (/PASS password)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"saslExternal"</literal></term>
<listitem><para>SASL EXTERNAL (cert)</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>"customCommands"</literal></term>
<listitem>
<para>Use "commands" field for auth. For example
<programlisting language="nix">
commands = [ "/msg NickServ IDENTIFY my_password" ]
</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
`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
(<filename>hexchat.conf</filename>, <filename>servlist.conf</filename>).
Any existing HexChat configuration will be lost. Certify to back-up any
previous configuration before enabling this.
</para><para>
({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:
<orderedlist numeration="arabic">
<listitem><para>
Nix/Home Manager provided configuration to be out of sync with
actual active HexChat configuration.
</para></listitem>
<listitem><para>
Blocking Nix/Home Manager updates until configuration files are
manually removed.
</para></listitem>
</orderedlist>
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.
'';
};

156
modules/programs/qutebrowser.nix
View file

@ -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: <literal>{mode: {key: command}}</literal> If you want to map
a key to another key, check the <literal>keyMappings</literal> setting
instead. For modifiers, you can use either <literal>-</literal> or
<literal>+</literal> 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:
<itemizedlist>
<listitem><para>
Control: <literal>Control</literal>, <literal>Ctrl</literal>
</para></listitem>
<listitem><para>
Meta: <literal>Meta</literal>, <literal>Windows</literal>,
<literal>Mod4</literal>
</para></listitem>
<listitem><para>
Alt: <literal>Alt</literal>, <literal>Mod1</literal>
</para></listitem>
<listitem><para>
Shift: <literal>Shift</literal>
</para></listitem>
</itemizedlist>
Control
: `Control`, `Ctrl`
For simple keys (no <literal>&lt;&gt;</literal>-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
<literal>&lt;&gt;</literal>-signs), you need to explicitly add
<literal>Shift-</literal> to match a key pressed with shift. If you
want a binding to do nothing, bind it to the <literal>nop</literal>
`<>`-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 <literal>:</literal>help for a full list of available
completion. See `:help` for a full list of available
commands. The following modes are available:
<variablelist>
<varlistentry>
<term><literal>normal</literal></term>
<listitem><para>
Default mode, where most commands are invoked.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>insert</literal></term>
<listitem><para>
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
<literal>&lt;Ctrl-e&gt;</literal> to open an external editor.
Note that single keys can’t be bound in this mode.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>hint</literal></term>
<listitem><para>
Entered when f is pressed to select links with the keyboard. Note
that single keys can’t be bound in this mode.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>passthrough</literal></term>
<listitem><para>
Similar to insert mode, but passes through all keypresses except
<literal>&lt;Escape&gt;</literal> to leave the mode. It might be
useful to bind <literal>&lt;Escape&gt;</literal> 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.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>command</literal></term>
<listitem><para>
Entered when pressing the : key in order to enter a command. Note
that single keys can’t be bound in this mode.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>prompt</literal></term>
<listitem><para>
Entered when there’s a prompt to display, like for download
locations or when invoked from JavaScript.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>yesno</literal></term>
<listitem><para>
Entered when there’s a yes/no prompt displayed.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>caret</literal></term>
<listitem><para>
Entered when pressing the v mode, used to select text using the
keyboard.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>register</literal></term>
<listitem><para>
Entered when qutebrowser is waiting for a register name/key for
commands like <literal>:set-mark</literal>.
</para></listitem>
</varlistentry>
</variablelist>
`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`.
'';
example = literalExpression ''
{