treewide: manually convert some docs to Markdown
These files all have options that trip up the `nix-doc-munge` conversion tool for one reason or another (syntax that clashes with Markdown, options that were already using Markdown syntax despite not being marked that way, output that differs slightly after conversion, syntax too elaborate to convert with some cheap regular expressions, ...). Translate them manually and do a little copyediting to options in the vicinity while we're at it.
This commit is contained in:
Emily
parent
e2a1cb50d8
commit
3228f92b90
17 changed files with 242 additions and 213 deletions
|
|
@ -40,9 +40,10 @@ in {
|
|||
default = { };
|
||||
example = literalExpression
|
||||
''{ Work = { source = "maildir://~/Maildir/work"; }; }'';
|
||||
description = ''
|
||||
Extra lines added to <filename>$HOME/.config/aerc/accounts.conf</filename>.
|
||||
See aerc-config(5).
|
||||
description = lib.mdDoc ''
|
||||
Extra lines added to {file}`$HOME/.config/aerc/accounts.conf`.
|
||||
|
||||
See {manpage}`aerc-config(5)`.
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
@ -50,10 +51,11 @@ in {
|
|||
type = sectionsOrLines;
|
||||
default = { };
|
||||
example = literalExpression ''{ messages = { q = ":quit<Enter>"; }; }'';
|
||||
description = ''
|
||||
Extra lines added to <filename>$HOME/.config/aerc/binds.conf</filename>.
|
||||
description = lib.mdDoc ''
|
||||
Extra lines added to {file}`$HOME/.config/aerc/binds.conf`.
|
||||
Global keybindings can be set in the `global` section.
|
||||
See aerc-config(5).
|
||||
|
||||
See {manpage}`aerc-config(5)`.
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
@ -61,9 +63,10 @@ in {
|
|||
type = sectionsOrLines;
|
||||
default = { };
|
||||
example = literalExpression ''{ ui = { sort = "-r date"; }; }'';
|
||||
description = ''
|
||||
Extra lines added to <filename>$HOME/.config/aerc/aerc.conf</filename>.
|
||||
See aerc-config(5).
|
||||
description = lib.mdDoc ''
|
||||
Extra lines added to {file}`$HOME/.config/aerc/aerc.conf`.
|
||||
|
||||
See {manpage}`aerc-config(5)`.
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
@ -73,9 +76,10 @@ in {
|
|||
example = literalExpression ''
|
||||
{ default = { ui = { "tab.selected.reverse" = toggle; }; }; };
|
||||
'';
|
||||
description = ''
|
||||
Stylesets added to <filename>$HOME/.config/aerc/stylesets/</filename>.
|
||||
See aerc-stylesets(7).
|
||||
description = lib.mdDoc ''
|
||||
Stylesets added to {file}`$HOME/.config/aerc/stylesets/`.
|
||||
|
||||
See {manpage}`aerc-stylesets(7)`.
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
@ -85,9 +89,10 @@ in {
|
|||
example = literalExpression ''
|
||||
{ new_message = "Hello!"; };
|
||||
'';
|
||||
description = ''
|
||||
Templates added to <filename>$HOME/.config/aerc/templates/</filename>.
|
||||
See aerc-templates(7).
|
||||
description = lib.mdDoc ''
|
||||
Templates added to {file}`$HOME/.config/aerc/templates/`.
|
||||
|
||||
See {manpage}`aerc-templates(7)`.
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -89,10 +89,9 @@ in {
|
|||
};
|
||||
|
||||
nix-direnv = {
|
||||
enable = mkEnableOption ''
|
||||
<link
|
||||
xlink:href="https://github.com/nix-community/nix-direnv">nix-direnv</link>,
|
||||
a fast, persistent use_nix implementation for direnv'';
|
||||
enable = mkEnableOption (lib.mdDoc ''
|
||||
[nix-direnv](https://github.com/nix-community/nix-direnv),
|
||||
a fast, persistent use_nix implementation for direnv'');
|
||||
};
|
||||
|
||||
};
|
||||
|
|
|
|||
|
|
@ -442,20 +442,18 @@ in {
|
|||
privacy-badger
|
||||
]
|
||||
'';
|
||||
description = ''
|
||||
description = lib.mdDoc ''
|
||||
List of Firefox add-on packages to install for this profile.
|
||||
Some pre-packaged add-ons are accessible from NUR,
|
||||
<link xlink:href="https://github.com/nix-community/NUR"/>.
|
||||
Some pre-packaged add-ons are accessible from the
|
||||
[Nix User Repository](https://github.com/nix-community/NUR).
|
||||
Once you have NUR installed run
|
||||
|
||||
<screen language="console">
|
||||
<prompt>$</prompt> <userinput>nix-env -f '<nixpkgs>' -qaP -A nur.repos.rycee.firefox-addons</userinput>
|
||||
</screen>
|
||||
```console
|
||||
$ nix-env -f '<nixpkgs>' -qaP -A nur.repos.rycee.firefox-addons
|
||||
```
|
||||
|
||||
to list the available Firefox add-ons.
|
||||
|
||||
</para><para>
|
||||
|
||||
Note that it is necessary to manually enable these extensions
|
||||
inside Firefox after the first installation.
|
||||
'';
|
||||
|
|
|
|||
|
|
@ -218,18 +218,18 @@ in {
|
|||
backend = lib.mkOption {
|
||||
type = with lib.types; nullOr str;
|
||||
default = null;
|
||||
description = ''
|
||||
Specifying 'accounts.email.accounts.*.himalaya.backend' is deprecated,
|
||||
set 'accounts.email.accounts.*.himalaya.settings.backend' instead.
|
||||
description = lib.mdDoc ''
|
||||
Specifying {option}`accounts.email.accounts.*.himalaya.backend` is deprecated,
|
||||
set {option}`accounts.email.accounts.*.himalaya.settings.backend` instead.
|
||||
'';
|
||||
};
|
||||
|
||||
# TODO: remove me for the next release
|
||||
sender = lib.mkOption {
|
||||
type = with lib.types; nullOr str;
|
||||
description = ''
|
||||
Specifying 'accounts.email.accounts.*.himalaya.sender' is deprecated,
|
||||
set 'accounts.email.accounts.*.himalaya.settings.sender' instead.
|
||||
description = lib.mdDoc ''
|
||||
Specifying {option}`accounts.email.accounts.*.himalaya.sender` is deprecated,
|
||||
set {option}'accounts.email.accounts.*.himalaya.settings.sender' instead.
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -38,10 +38,11 @@ in {
|
|||
};
|
||||
|
||||
colors = mkOption {
|
||||
description = ''
|
||||
The colors used in colored JSON output.</para>
|
||||
description = lib.mdDoc ''
|
||||
The colors used in colored JSON output.
|
||||
|
||||
<para>See <link xlink:href="https://stedolan.github.io/jq/manual/#Colors"/>.
|
||||
See the [Colors section](https://jqlang.github.io/jq/manual/#Colors)
|
||||
of the jq manual.
|
||||
'';
|
||||
|
||||
example = literalExpression ''
|
||||
|
|
|
|||
|
|
@ -33,116 +33,123 @@ let
|
|||
(toKeyValueIfDefined (getAttrs [ "type" "color" "priority" ] value.khal))
|
||||
] ++ [ "\n" ]);
|
||||
|
||||
localeFormatOptions = let T = lib.types;
|
||||
in mapAttrs (n: v:
|
||||
v // {
|
||||
description = v.description + ''
|
||||
localeFormatOptions = let
|
||||
T = lib.types;
|
||||
suffix = ''
|
||||
Format strings are for Python `strftime`, similarly to
|
||||
{manpage}`strftime(3)`.
|
||||
'';
|
||||
in {
|
||||
dateformat = mkOption {
|
||||
type = T.str;
|
||||
default = "%x";
|
||||
description = lib.mdDoc ''
|
||||
khal will display and understand all dates in this format.
|
||||
|
||||
Format strings are for python 'strftime', similarly to man 3 strftime.
|
||||
${suffix}
|
||||
'';
|
||||
}) {
|
||||
dateformat = {
|
||||
type = T.str;
|
||||
default = "%x";
|
||||
description = ''
|
||||
khal will display and understand all dates in this format.
|
||||
'';
|
||||
};
|
||||
|
||||
timeformat = {
|
||||
type = T.str;
|
||||
default = "%X";
|
||||
description = ''
|
||||
khal will display and understand all times in this format.
|
||||
'';
|
||||
};
|
||||
|
||||
datetimeformat = {
|
||||
type = T.str;
|
||||
default = "%c";
|
||||
description = ''
|
||||
khal will display and understand all datetimes in this format.
|
||||
'';
|
||||
};
|
||||
|
||||
longdateformat = {
|
||||
type = T.str;
|
||||
default = "%x";
|
||||
description = ''
|
||||
khal will display and understand all dates in this format.
|
||||
It should contain a year (e.g. %Y).
|
||||
'';
|
||||
};
|
||||
|
||||
longdatetimeformat = {
|
||||
type = T.str;
|
||||
default = "%c";
|
||||
description = ''
|
||||
khal will display and understand all datetimes in this format.
|
||||
It should contain a year (e.g. %Y).
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
timeformat = mkOption {
|
||||
type = T.str;
|
||||
default = "%X";
|
||||
description = lib.mdDoc ''
|
||||
khal will display and understand all times in this format.
|
||||
|
||||
${suffix}
|
||||
'';
|
||||
};
|
||||
|
||||
datetimeformat = mkOption {
|
||||
type = T.str;
|
||||
default = "%c";
|
||||
description = lib.mdDoc ''
|
||||
khal will display and understand all datetimes in this format.
|
||||
|
||||
${suffix}
|
||||
'';
|
||||
};
|
||||
|
||||
longdateformat = mkOption {
|
||||
type = T.str;
|
||||
default = "%x";
|
||||
description = lib.mdDoc ''
|
||||
khal will display and understand all dates in this format.
|
||||
It should contain a year (e.g. `%Y`).
|
||||
|
||||
${suffix}
|
||||
'';
|
||||
};
|
||||
|
||||
longdatetimeformat = mkOption {
|
||||
type = T.str;
|
||||
default = "%c";
|
||||
description = lib.mdDoc ''
|
||||
khal will display and understand all datetimes in this format.
|
||||
It should contain a year (e.g. `%Y`).
|
||||
|
||||
${suffix}
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
localeOptions = let T = lib.types;
|
||||
in localeFormatOptions // {
|
||||
unicode_symbols = {
|
||||
unicode_symbols = mkOption {
|
||||
type = T.bool;
|
||||
default = true;
|
||||
description = ''
|
||||
By default khal uses some unicode symbols (as in ‘non-ascii’) as
|
||||
description = lib.mdDoc ''
|
||||
By default khal uses some Unicode symbols (as in "non-ASCII") as
|
||||
indicators for things like repeating events.
|
||||
If your font, encoding etc. does not support those symbols, set this
|
||||
to false (this will enable ascii based replacements).
|
||||
to false (this will enable ASCII-based replacements).
|
||||
'';
|
||||
};
|
||||
|
||||
default_timezone = {
|
||||
default_timezone = mkOption {
|
||||
type = T.nullOr T.str;
|
||||
default = null;
|
||||
description = ''
|
||||
description = lib.mdDoc ''
|
||||
Default for new events or if khal does not understand the timezone
|
||||
in an ical file.
|
||||
If 'null', the timezone of your computer will be used.
|
||||
If `null`, the timezone of your computer will be used.
|
||||
'';
|
||||
};
|
||||
|
||||
local_timezone = {
|
||||
local_timezone = mkOption {
|
||||
type = T.nullOr T.str;
|
||||
default = null;
|
||||
description = ''
|
||||
description = lib.mdDoc ''
|
||||
khal will show all times in this timezone.
|
||||
If 'null', the timezone of your computer will be used.
|
||||
If `null`, the timezone of your computer will be used.
|
||||
'';
|
||||
};
|
||||
|
||||
firstweekday = {
|
||||
firstweekday = mkOption {
|
||||
type = T.ints.between 0 6;
|
||||
default = 0;
|
||||
description = ''
|
||||
the first day of the week, where Monday is 0 and Sunday is 6
|
||||
description = lib.mdDoc ''
|
||||
The first day of the week, where Monday is 0 and Sunday is 6.
|
||||
'';
|
||||
};
|
||||
|
||||
weeknumbers = {
|
||||
weeknumbers = mkOption {
|
||||
type = T.enum [ "off" "left" "right" ];
|
||||
default = "off";
|
||||
description = ''
|
||||
Enable weeknumbers in calendar and interactive (ikhal) mode.
|
||||
As those are iso weeknumbers, they only work properly if firstweekday
|
||||
is set to 0.
|
||||
description = lib.mdDoc ''
|
||||
Enable week numbers in calendar and interactive (ikhal) mode.
|
||||
As those are ISO week numbers, they only work properly if
|
||||
{option}`firstweekday` is set to 0.
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
in {
|
||||
options.programs.khal = {
|
||||
enable = mkEnableOption "khal, a CLI calendar application";
|
||||
enable = mkEnableOption (lib.mdDoc "khal, a CLI calendar application");
|
||||
locale = mkOption {
|
||||
type = lib.types.submodule {
|
||||
options = mapAttrs (n: v: mkOption v) localeOptions;
|
||||
};
|
||||
description = ''
|
||||
type = lib.types.submodule { options = localeOptions; };
|
||||
description = lib.mdDoc ''
|
||||
khal locale settings.
|
||||
'';
|
||||
};
|
||||
|
|
|
|||
|
|
@ -48,11 +48,14 @@ in {
|
|||
apply = toString;
|
||||
default = "${config.xdg.dataHome}/pyenv";
|
||||
defaultText = "\${config.xdg.dataHome}/pyenv";
|
||||
description = ''
|
||||
The pyenv root directory (PYENV_ROOT).
|
||||
</para><para>
|
||||
Note: Deviating from upstream which uses `$HOME/.pyenv`,
|
||||
the default path is set according to the XDG base directory specification.
|
||||
description = lib.mdDoc ''
|
||||
The pyenv root directory ({env}`PYENV_ROOT`).
|
||||
|
||||
::: {.note}
|
||||
This deviates from upstream, which uses {file}`$HOME/.pyenv`.
|
||||
The default path in Home Manager is set according to the XDG
|
||||
base directory specification.
|
||||
:::
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -118,8 +118,8 @@ in {
|
|||
shading = mkOption {
|
||||
type = types.ints.between 0 200;
|
||||
default = 100;
|
||||
description =
|
||||
"Darken (0 .. 99) or lighten (101 .. 200) the transparent background.";
|
||||
description = lib.mdDoc
|
||||
"Darken (0 to 99) or lighten (101 to 200) the transparent background.";
|
||||
};
|
||||
|
||||
extraConfig = mkOption {
|
||||
|
|
|
|||
|
|
@ -182,12 +182,11 @@ in {
|
|||
type = types.str;
|
||||
default = "${config.xdg.dataHome}/vdirsyncer/status";
|
||||
defaultText = "$XDG_DATA_HOME/vdirsyncer/status";
|
||||
description = ''
|
||||
description = lib.mdDoc ''
|
||||
A directory where vdirsyncer will store some additional data for the next sync.
|
||||
</para>
|
||||
|
||||
<para>For more information, see
|
||||
<link xlink:href="https://vdirsyncer.pimutils.org/en/stable/config.html#general-section"/>
|
||||
For more information, see the
|
||||
[vdirsyncer manual](https://vdirsyncer.pimutils.org/en/stable/config.html#general-section).
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
|
|
|||
|
|
@ -35,12 +35,15 @@ in {
|
|||
type = types.path;
|
||||
default = defaultHieNixExe;
|
||||
defaultText = defaultHieNixExeText;
|
||||
description = ''
|
||||
description = lib.mdDoc ''
|
||||
The path to the Haskell IDE Engine executable.
|
||||
</para><para>
|
||||
|
||||
Because hie-nix is not packaged in Nixpkgs, you need to add it as an
|
||||
overlay or set this option. Example overlay configuration:
|
||||
<programlisting language="nix">${exampleOverlay}</programlisting>
|
||||
|
||||
```nix
|
||||
${exampleOverlay}
|
||||
```
|
||||
'';
|
||||
example = literalExpression ''
|
||||
(import ~/src/haskell-ide-engine {}).hies + "/bin/hie-wrapper";
|
||||
|
|
|
|||
|
|
@ -248,8 +248,8 @@ in
|
|||
|
||||
cdpath = mkOption {
|
||||
default = [];
|
||||
description = ''
|
||||
List of paths to autocomplete calls to `cd`.
|
||||
description = lib.mdDoc ''
|
||||
List of paths to autocomplete calls to {command}`cd`.
|
||||
'';
|
||||
type = types.listOf types.str;
|
||||
};
|
||||
|
|
|
|||
|
|
@ -26,14 +26,16 @@ let
|
|||
type = types.nullOr types.bool;
|
||||
default = true;
|
||||
example = false;
|
||||
description = "Color output (auto set to 'no' on dumb terminals)";
|
||||
description = lib.mdDoc ''
|
||||
Color output (automatically set to `false` on dumb terminals).
|
||||
'';
|
||||
};
|
||||
|
||||
pmoduleDirs = mkOption {
|
||||
type = types.listOf types.path;
|
||||
default = [ ];
|
||||
example = [ "$HOME/.zprezto-contrib" ];
|
||||
description = "Add additional directories to load prezto modules from";
|
||||
description = "Add additional directories to load prezto modules from.";
|
||||
};
|
||||
|
||||
extraConfig = mkOption {
|
||||
|
|
@ -48,14 +50,18 @@ let
|
|||
type = types.listOf types.str;
|
||||
default = [ ];
|
||||
example = [ "attr" "stat" ];
|
||||
description = "Set the Zsh modules to load (man zshmodules).";
|
||||
description = lib.mdDoc ''
|
||||
Set the Zsh modules to load ({manpage}`zshmodules(1)`).
|
||||
'';
|
||||
};
|
||||
|
||||
extraFunctions = mkOption {
|
||||
type = types.listOf types.str;
|
||||
default = [ ];
|
||||
example = [ "zargs" "zmv" ];
|
||||
description = "Set the Zsh functions to load (man zshcontrib).";
|
||||
description = lib.mdDoc ''
|
||||
Set the Zsh functions to load ({manpage}`zshcontrib(1)`).
|
||||
'';
|
||||
};
|
||||
|
||||
pmodules = mkOption {
|
||||
|
|
@ -86,8 +92,10 @@ let
|
|||
type = types.listOf types.str;
|
||||
default = [ ];
|
||||
example = [ "0.0.0.0" "127.0.0.1" ];
|
||||
description =
|
||||
"Set the entries to ignore in static */etc/hosts* for host completion.";
|
||||
description = lib.mdDoc ''
|
||||
Set the entries to ignore in static {file}`/etc/hosts` for
|
||||
host completion.
|
||||
'';
|
||||
};
|
||||
|
||||
editor = {
|
||||
|
|
@ -95,21 +103,25 @@ let
|
|||
type = types.nullOr (types.enum [ "emacs" "vi" ]);
|
||||
default = "emacs";
|
||||
example = "vi";
|
||||
description = "Set the key mapping style to 'emacs' or 'vi'.";
|
||||
description = lib.mdDoc ''
|
||||
Set the key mapping style to `emacs` or `vi`.
|
||||
'';
|
||||
};
|
||||
|
||||
dotExpansion = mkOption {
|
||||
type = types.nullOr types.bool;
|
||||
default = null;
|
||||
example = true;
|
||||
description = "Auto convert .... to ../..";
|
||||
description = lib.mdDoc ''
|
||||
Automatically convert `....` to `../..`
|
||||
'';
|
||||
};
|
||||
|
||||
promptContext = mkOption {
|
||||
type = types.nullOr types.bool;
|
||||
default = null;
|
||||
example = true;
|
||||
description = "Allow the zsh prompt context to be shown.";
|
||||
description = "Allow the Zsh prompt context to be shown.";
|
||||
};
|
||||
};
|
||||
|
||||
|
|
@ -117,8 +129,10 @@ let
|
|||
type = types.nullOr (types.enum [ "dirty" "untracked" "all" "none" ]);
|
||||
default = null;
|
||||
example = "all";
|
||||
description =
|
||||
"Ignore submodules when they are 'dirty', 'untracked', 'all', or 'none'.";
|
||||
description = lib.mdDoc ''
|
||||
Ignore submodules when they are `dirty`, `untracked`, `all`,
|
||||
or `none`.
|
||||
'';
|
||||
};
|
||||
|
||||
gnuUtility.prefix = mkOption {
|
||||
|
|
@ -154,8 +168,10 @@ let
|
|||
type = types.nullOr types.str;
|
||||
default = null;
|
||||
example = "manpages";
|
||||
description =
|
||||
"Set the keyword used by `mand` to open man pages in Dash.app";
|
||||
description = lib.mdDoc ''
|
||||
Set the keyword used by {command}`mand` to open man pages
|
||||
in Dash.app.
|
||||
'';
|
||||
};
|
||||
|
||||
prompt = {
|
||||
|
|
@ -163,19 +179,23 @@ let
|
|||
type = types.nullOr types.str;
|
||||
default = "sorin";
|
||||
example = "pure";
|
||||
description = ''
|
||||
Set the prompt theme to load. Setting it to 'random'
|
||||
loads a random theme. Auto set to 'off' on dumb terminals.'';
|
||||
description = lib.mdDoc ''
|
||||
Set the prompt theme to load. Setting it to `random`
|
||||
loads a random theme. Automatically set to `off` on dumb
|
||||
terminals.
|
||||
'';
|
||||
};
|
||||
|
||||
pwdLength = mkOption {
|
||||
type = types.nullOr (types.enum [ "short" "long" "full" ]);
|
||||
default = null;
|
||||
example = "short";
|
||||
description = ''
|
||||
description = lib.mdDoc ''
|
||||
Set the working directory prompt display length. By
|
||||
default, it is set to 'short'. Set it to 'long' (without '~' expansion) for
|
||||
longer or 'full' (with '~' expansion) for even longer prompt display.'';
|
||||
default, it is set to `short`. Set it to `long` (without `~`
|
||||
expansion) for longer or `full` (with `~` expansion) for
|
||||
even longer prompt display.
|
||||
'';
|
||||
};
|
||||
|
||||
showReturnVal = mkOption {
|
||||
|
|
@ -184,7 +204,8 @@ let
|
|||
example = true;
|
||||
description = ''
|
||||
Set the prompt to display the return code along with an
|
||||
indicator for non-zero return codes. This is not supported by all prompts.'';
|
||||
indicator for non-zero return codes. This is not supported by all prompts.
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
|
|
@ -244,7 +265,8 @@ let
|
|||
example = [ "main" "brackets" "pattern" "line" "cursor" "root" ];
|
||||
description = ''
|
||||
Set syntax highlighters. By default, only the main
|
||||
highlighter is enabled.'';
|
||||
highlighter is enabled.
|
||||
'';
|
||||
};
|
||||
|
||||
styles = mkOption {
|
||||
|
|
@ -332,10 +354,12 @@ let
|
|||
type = types.nullOr types.bool;
|
||||
default = null;
|
||||
example = true;
|
||||
description = ''
|
||||
Enabled safe options. This aliases cp, ln, mv and rm so
|
||||
that they prompt before deleting or overwriting files. Set to 'no' to disable
|
||||
this safer behavior.'';
|
||||
description = lib.mdDoc ''
|
||||
Enabled safe options. This aliases {command}`cp`,
|
||||
{command}`ln`, {command}`mv` and {command}`rm` so that they
|
||||
prompt before deleting or overwriting files. Set to `no` to
|
||||
disable this safer behavior.
|
||||
'';
|
||||
};
|
||||
};
|
||||
};
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue