nix/2.home-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

treewide: adjust some DocBook for conversion

Browse source 
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.
This commit is contained in:
Emily 2023-06-30 05:48:21 +01:00
parent b5a65b91fb
commit c1d8d2a3d1
30 changed files with 72 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

4
modules/accounts/email.nix
View file

@ -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.
'';
};

12
modules/home-environment.nix
View file

@ -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
expanded by the shell. However, since expressions like <code>~</code> or
<code>*</code> are escaped, they will end up in the <envar>PATH</envar>
double-quoted context, so expressions like <literal>$HOME</literal> are
expanded by the shell. However, since expressions like <literal>~</literal> or
<literal>*</literal> are escaped, they will end up in the <envar>PATH</envar>
verbatim.
'';
};

2
modules/misc/dconf.nix
View file

@ -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.
'';

2
modules/misc/editorconfig.nix
View file

@ -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.
'';

6
modules/misc/xdg-desktop-entries.nix
View file

@ -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>
You can define entries for programs without entries or override existing entries. </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.
See <link xlink:href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys" /> for more information on options.
'';
default = { };

2
modules/misc/xfconf.nix
View file

@ -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.
'';

6
modules/programs/autorandr.nix
View file

@ -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

2
modules/programs/bash.nix
View file

@ -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.
'';
};

2
modules/programs/dircolors.nix
View file

@ -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>.
'';
};

2
modules/programs/fzf.nix
View file

@ -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.
'';

2
modules/programs/i3status-rust.nix
View file

@ -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.

4
modules/programs/i3status.nix
View file

@ -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 {

4
modules/programs/msmtp-accounts.nix
View file

@ -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.
'';
};

14
modules/programs/mujmap.nix
View file

@ -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,
<emphasis>except</emphasis> for messages with the <code>$NotJunk</code> keyword.
<literal>Junk</literal> name attribute and/or with the <literal>$Junk</literal> 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.
'';

4
modules/programs/ncmpcpp.nix
View file

@ -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>.

2
modules/programs/offlineimap.nix
View file

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

8
modules/programs/rtx.nix
View file

@ -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>
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>
<para>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>
</warning>
'';
};

8
modules/programs/sbt.nix
View file

@ -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>,
<code>maven-local</code>, <code>maven-central</code>.
Pre-defined repositories must be one of <literal>local</literal>,
<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>

6
modules/programs/waybar.nix
View file

@ -27,8 +27,8 @@ let
type = nullOr (enum [ "top" "bottom" ]);
default = null;
description = ''
Decide if the bar is displayed in front (<code>"top"</code>)
of the windows or behind (<code>"bottom"</code>).
Decide if the bar is displayed in front (<literal>"top"</literal>)
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.
'';
};

6
modules/programs/yt-dlp.nix
View file

@ -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
example, <code>update = true;</code> instead of <code>U = true;</code>.
Short options can be specified in the <code>extraConfig</code> option.
Options must be specified in their "long form", for
example, <literal>update = true;</literal> instead of <literal>U = true;</literal>.
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.
'';

2
modules/services/borgmatic.nix
View file

@ -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>

4
modules/services/home-manager-auto-upgrade.nix
View file

@ -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>

2
modules/services/window-managers/i3-sway/i3.nix
View file

@ -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 ''

4
modules/services/window-managers/i3-sway/sway.nix
View file

@ -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.
'';

2
modules/services/xidlehook.nix
View file

@ -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>.
'';
};

6
modules/targets/darwin/keybindings.nix
View file

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

15
modules/targets/darwin/user-defaults/default.nix
View file

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

18
modules/targets/darwin/user-defaults/opts-allhosts.nix
View file

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

4
modules/xresources.nix
View file

@ -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.
'';
};