treewide: adjust some DocBook for conversion

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

View file

@ -147,7 +147,7 @@ let
</para><para> </para><para>
If both this option and <xref If both this option and <xref
linkend="opt-accounts.email.accounts._name_.jmap.sessionUrl"/> are specified, 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. session.
''; '';
}; };
@ -161,7 +161,7 @@ let
</para><para> </para><para>
If both this option and <xref If both this option and <xref
linkend="opt-accounts.email.accounts._name_.jmap.host"/> are specified, 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. session.
''; '';
}; };

View file

@ -264,11 +264,11 @@ in
The values may refer to other environment variables using The values may refer to other environment variables using
POSIX.2 style variable references. For example, a variable POSIX.2 style variable references. For example, a variable
<varname>parameter</varname> may be referenced as <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 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 value <literal>bar</literal> can be given as per
<code>''${parameter:+bar}</code>. <literal>''${parameter:+bar}</literal>.
</para><para> </para><para>
Note, these variables may be set in any order so no session Note, these variables may be set in any order so no session
variable may have a runtime dependency on another session variable may have a runtime dependency on another session
@ -314,9 +314,9 @@ in
</para><para> </para><para>
These directories are added to the <envar>PATH</envar> variable in a These directories are added to the <envar>PATH</envar> variable in a
double-quoted context, so expressions like <code>$HOME</code> are double-quoted context, so expressions like <literal>$HOME</literal> are
expanded by the shell. However, since expressions like <code>~</code> or expanded by the shell. However, since expressions like <literal>~</literal> or
<code>*</code> are escaped, they will end up in the <envar>PATH</envar> <literal>*</literal> are escaped, they will end up in the <envar>PATH</envar>
verbatim. verbatim.
''; '';
}; };

View file

@ -37,7 +37,7 @@ in {
Whether to enable dconf settings. Whether to enable dconf settings.
</para><para> </para><para>
Note, if you use NixOS then you must add 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 to your system configuration. Otherwise you will see a systemd error
message when your configuration is activated. message when your configuration is activated.
''; '';

View file

@ -19,7 +19,7 @@ in {
default = { }; default = { };
description = '' description = ''
Configuration written to <filename>$HOME/.editorconfig</filename>. 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. it must not be added here.
See <link xlink:href="https://editorconfig.org"/> for documentation. See <link xlink:href="https://editorconfig.org"/> for documentation.
''; '';

View file

@ -181,8 +181,10 @@ in {
options.xdg.desktopEntries = mkOption { options.xdg.desktopEntries = mkOption {
description = '' description = ''
Desktop Entries allow applications to be shown in your desktop environment's app launcher. </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. </para><para>
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. See <link xlink:href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys" /> for more information on options.
''; '';
default = { }; default = { };

View file

@ -67,7 +67,7 @@ in {
Whether to enable Xfconf settings. Whether to enable Xfconf settings.
</para><para> </para><para>
Note, if you use NixOS then you must add 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 to your system configuration. Otherwise you will see a systemd error
message when your configuration is activated. message when your configuration is activated.
''; '';

View file

@ -28,7 +28,7 @@ let
type = types.attrsOf types.str; type = types.attrsOf types.str;
description = '' description = ''
Output name to EDID mapping. 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 = { }; default = { };
}; };
@ -160,9 +160,9 @@ let
<manvolnum>1</manvolnum> <manvolnum>1</manvolnum>
</citerefentry> </citerefentry>
option option
<parameter class="command">--scale-from</parameter> <literal>--scale-from</literal>
will be used; when using factor method the option will be used; when using factor method the option
<parameter class="command">--scale</parameter> <literal>--scale</literal>
will be used. will be used.
</para><para> </para><para>
This option is a shortcut version of the transform option and they are mutually This option is a shortcut version of the transform option and they are mutually

View file

@ -103,7 +103,7 @@ in {
example = [ "extglob" "-cdspell" ]; example = [ "extglob" "-cdspell" ];
description = '' description = ''
Shell options to set. Prefix an option with Shell options to set. Prefix an option with
<quote><literal>-</literal></quote> to unset. "<literal>-</literal>" to unset.
''; '';
}; };

View file

@ -15,7 +15,7 @@ in {
default = false; default = false;
description = '' description = ''
Whether to manage <filename>.dir_colors</filename> Whether to manage <filename>.dir_colors</filename>
and set <code>LS_COLORS</code>. and set <literal>LS_COLORS</literal>.
''; '';
}; };

View file

@ -104,7 +104,7 @@ in {
} }
''; '';
description = '' 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"/> <link xlink:href="https://github.com/junegunn/fzf/wiki/Color-schemes"/>
for documentation. for documentation.
''; '';

View file

@ -165,7 +165,7 @@ in {
Attribute set of i3status-rust bars, each with their own configuration. Attribute set of i3status-rust bars, each with their own configuration.
Each bar <varname>name</varname> generates a config file suffixed with Each bar <varname>name</varname> generates a config file suffixed with
the bar's <varname>name</varname> from the attribute set, like so: 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> </para><para>
This way, multiple config files can be generated, such as for having a This way, multiple config files can be generated, such as for having a
top and a bottom bar. top and a bottom bar.

View file

@ -52,7 +52,7 @@ in {
default = { }; default = { };
description = '' description = ''
Configuration to add to i3status <filename>config</filename> Configuration to add to i3status <filename>config</filename>
<code>general</code> section. <literal>general</literal> section.
See See
<citerefentry> <citerefentry>
<refentrytitle>i3status</refentrytitle> <refentrytitle>i3status</refentrytitle>
@ -84,7 +84,7 @@ in {
position = mkOption { position = mkOption {
type = with types; either int float; type = with types; either int float;
description = '' description = ''
Position of this module in i3status <code>order</code>. Position of this module in i3status <literal>order</literal>.
''; '';
}; };
settings = mkOption { settings = mkOption {

View file

@ -11,13 +11,13 @@ with lib;
Whether to enable msmtp. Whether to enable msmtp.
</para><para> </para><para>
If enabled then it is possible to use the 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 option to send a message for a given account using the
<command>msmtp</command> or <command>msmtpq</command> tool. <command>msmtp</command> or <command>msmtpq</command> tool.
For example, <command>msmtp --account=private</command> would For example, <command>msmtp --account=private</command> would
send using the account defined in send using the account defined in
<option>accounts.email.accounts.private</option>. If the <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. given then the primary account will be used.
''; '';
}; };

View file

@ -70,7 +70,7 @@ let
default = "inbox"; default = "inbox";
description = '' description = ''
Tag for notmuch to use for messages stored in the mailbox labeled with the 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> </para><para>
If set to an empty string, this mailbox <emphasis>and its child If set to an empty string, this mailbox <emphasis>and its child
mailboxes</emphasis> are not synchronized with a tag. mailboxes</emphasis> are not synchronized with a tag.
@ -82,7 +82,7 @@ let
default = "deleted"; default = "deleted";
description = '' description = ''
Tag for notmuch to use for messages stored in the mailbox labeled with the 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> </para><para>
If set to an empty string, this mailbox <emphasis>and its child If set to an empty string, this mailbox <emphasis>and its child
mailboxes</emphasis> are not synchronized with a tag. mailboxes</emphasis> are not synchronized with a tag.
@ -94,7 +94,7 @@ let
default = "sent"; default = "sent";
description = '' description = ''
Tag for notmuch to use for messages stored in the mailbox labeled with the 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> </para><para>
If set to an empty string, this mailbox <emphasis>and its child If set to an empty string, this mailbox <emphasis>and its child
mailboxes</emphasis> are not synchronized with a tag. mailboxes</emphasis> are not synchronized with a tag.
@ -106,8 +106,8 @@ let
default = "spam"; default = "spam";
description = '' description = ''
Tag for notmuch to use for messages stored in the mailbox labeled with the 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, <literal>Junk</literal> name attribute and/or with the <literal>$Junk</literal> keyword,
<emphasis>except</emphasis> for messages with the <code>$NotJunk</code> keyword. <emphasis>except</emphasis> for messages with the <literal>$NotJunk</literal> keyword.
</para><para> </para><para>
If set to an empty string, this mailbox, <emphasis>its child If set to an empty string, this mailbox, <emphasis>its child
mailboxes</emphasis>, and these keywords are not synchronized with a tag. mailboxes</emphasis>, and these keywords are not synchronized with a tag.
@ -119,7 +119,7 @@ let
default = "important"; default = "important";
description = '' description = ''
Tag for notmuch to use for messages stored in the mailbox labeled with the 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. keyword.
</para><para> </para><para>
If set to an empty string, this mailbox, <emphasis>its child If set to an empty string, this mailbox, <emphasis>its child
@ -131,7 +131,7 @@ let
type = types.str; type = types.str;
default = "phishing"; default = "phishing";
description = '' 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> </para><para>
If set to an empty string, this keyword is not synchronized with a tag. If set to an empty string, this keyword is not synchronized with a tag.
''; '';

View file

@ -55,7 +55,7 @@ in {
default = pkgs.ncmpcpp; default = pkgs.ncmpcpp;
defaultText = literalExpression "pkgs.ncmpcpp"; defaultText = literalExpression "pkgs.ncmpcpp";
description = '' description = ''
Package providing the <code>ncmpcpp</code> command. Package providing the <literal>ncmpcpp</literal> command.
''; '';
example = example =
literalExpression "pkgs.ncmpcpp.override { visualizerSupport = true; }"; literalExpression "pkgs.ncmpcpp.override { visualizerSupport = true; }";
@ -75,7 +75,7 @@ in {
null null
''; '';
description = '' 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 value of <varname>services.mpd.musicDirectory</varname> is used as the
default if <varname>services.mpd.enable</varname> is default if <varname>services.mpd.enable</varname> is
<literal>true</literal>. <literal>true</literal>.

View file

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

View file

@ -42,15 +42,13 @@ in {
''; '';
description = '' description = ''
Settings written to <filename>$XDG_CONFIG_HOME/rtx/config.toml</filename>. 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"/> See <link xlink:href="https://github.com/jdxcode/rtx#global-config-configrtxconfigtoml"/>
for details on supported values. for details on supported values.
<warning> <warning>
<para> <para>Modifying the <literal>tools</literal> section doesn't make RTX install them.
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>
You have to manually run <literal>rtx install</literal> to install the tools.
</para>
</warning> </warning>
''; '';
}; };

View file

@ -162,18 +162,18 @@ in {
description = '' description = ''
A list of repositories to use when resolving dependencies. Defined as a 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 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. file in the order specified.
</para><para> </para><para>
Pre-defined repositories must be one of <code>local</code>, Pre-defined repositories must be one of <literal>local</literal>,
<code>maven-local</code>, <code>maven-central</code>. <literal>maven-local</literal>, <literal>maven-central</literal>.
</para><para> </para><para>
Custom repositories are defined as 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> </para><para>

View file

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

View file

@ -41,9 +41,9 @@ in {
Configuration written to Configuration written to
<filename>$XDG_CONFIG_HOME/yt-dlp/config</filename>. <filename>$XDG_CONFIG_HOME/yt-dlp/config</filename>.
</para><para> </para><para>
Options must be specified in their <quote>long form</quote>, for Options must be specified in their "long form", for
example, <code>update = true;</code> instead of <code>U = true;</code>. example, <literal>update = true;</literal> instead of <literal>U = true;</literal>.
Short options can be specified in the <code>extraConfig</code> option. Short options can be specified in the <literal>extraConfig</literal> option.
See <link xlink:href="https://github.com/yt-dlp/yt-dlp#configuration"/> See <link xlink:href="https://github.com/yt-dlp/yt-dlp#configuration"/>
for explanation about possible values. for explanation about possible values.
''; '';

View file

@ -17,7 +17,7 @@ in {
default = "hourly"; default = "hourly";
description = '' description = ''
How often to run borgmatic when 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 This value is passed to the systemd timer configuration as
the onCalendar option. See the onCalendar option. See
<citerefentry> <citerefentry>

View file

@ -15,7 +15,7 @@ in {
services.home-manager.autoUpgrade = { services.home-manager.autoUpgrade = {
enable = lib.mkEnableOption '' enable = lib.mkEnableOption ''
the Home Manager upgrade service that periodically updates your Nix 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 { frequency = lib.mkOption {
type = lib.types.str; type = lib.types.str;
@ -23,7 +23,7 @@ in {
description = '' description = ''
The interval at which the Home Manager auto upgrade is run. The interval at which the Home Manager auto upgrade is run.
This value is passed to the systemd timer configuration 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 The format is described in
<citerefentry> <citerefentry>
<refentrytitle>systemd.time</refentrytitle> <refentrytitle>systemd.time</refentrytitle>

View file

@ -95,7 +95,7 @@ let
An attribute set that assigns a key press to an action using a key symbol. 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"/>. See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
</para><para> </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. default keybindings instead of specifying all of them from scratch.
''; '';
example = literalExpression '' example = literalExpression ''

View file

@ -125,7 +125,7 @@ let
An attribute set that assigns a key press to an action using a key symbol. 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"/>. See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
</para><para> </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. default keybindings instead of specifying all of them from scratch.
''; '';
example = literalExpression '' example = literalExpression ''
@ -352,7 +352,7 @@ in {
description = '' description = ''
Sway package to use. Will override the options Sway package to use. Will override the options
'wrapperFeatures', 'extraSessionCommands', and 'extraOptions'. '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 path. This should be done if you want to use the NixOS Sway
module to install Sway. module to install Sway.
''; '';

View file

@ -52,7 +52,7 @@ in {
''; '';
description = '' description = ''
Extra environment variables to be exported in the script. 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>.
''; '';
}; };

View file

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

View file

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

View file

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

View file

@ -50,7 +50,7 @@ in {
All other values are directly formatted using builtins.toString. All other values are directly formatted using builtins.toString.
Note, that 2-dimensional lists are not supported and specifying one will throw an exception. Note, that 2-dimensional lists are not supported and specifying one will throw an exception.
If this and all other xresources options are 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. <filename>~/.Xresources</filename> link is produced.
''; '';
}; };
@ -71,7 +71,7 @@ in {
description = '' description = ''
Additional X server resources contents. Additional X server resources contents.
If this and all other xresources options are 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. <filename>~/.Xresources</filename> link is produced.
''; '';
}; };

View file

@ -5,7 +5,7 @@
type = lib.types.bool; type = lib.types.bool;
default = true; default = true;
description = '' description = ''
Whether to enable <quote>big</quote> 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 more resources than typical tests. For example, tests that depend on large
packages or tests that take long to run. packages or tests that take long to run.
''; '';