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

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

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

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

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 = { };

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

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

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

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

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

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.

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 {

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

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

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

View file

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

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

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>

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

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

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>

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>

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

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

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

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

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

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

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

View file

@ -5,7 +5,7 @@
type = lib.types.bool;
default = true;
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
packages or tests that take long to run.
'';