Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

nixos/doc: documentation angle bracket syntax #63033

Closed
wants to merge 2 commits into from
Closed

nixos/doc: documentation angle bracket syntax #63033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
760c02d
nixos doc: add angle brackets syntax in summary.
Jun 12, 2019
bd1373a
nixos docs: add link to nixos.org/nixos/options.html
Jun 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
5 changes: 3 additions & 2 deletions nixos/doc/manual/administration/imperative-containers.xml
View file
Open in desktop
Expand Up @@ -30,8 +30,9 @@
<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
'
</screen>
By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen
as container IP. This behavior can be altered by setting <literal>--host-address</literal> and
By default the next free address in the <literal>10.233.0.0/16</literal>
subnet will be chosen as container IP. This behavior can be altered by
setting <literal>--host-address</literal> and
<literal>--local-address</literal>:
<screen>
# nixos-container create test --config-file test-container.nix \
Expand Down
5 changes: 4 additions & 1 deletion nixos/doc/manual/configuration/customizing-packages.xml
View file
Open in desktop
Expand Up @@ -17,7 +17,10 @@
<warning>
<para>
Unfortunately, Nixpkgs currently lacks a way to query available
configuration options.
configuration options from command line. You can however go to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are different options than the section is talking about.

You are describing NixOS module options but this is talking about package options (that is the attribute set you pass as config when creating nixpkgs, or through nixpkgs.config NixOS option. There still is not a way to query those as far as I am aware.

And for NixOS options, you can actually use man configuration.nix or nixos-option commands.

<link xlink:href="https://nixos.org/nixos/options.html"> this page</link> to
get the available options for the last stable version, or directly read the
module sources.
</para>
</warning>

Expand Down
7 changes: 4 additions & 3 deletions nixos/doc/manual/configuration/declarative-packages.xml
View file
Open in desktop
Expand Up @@ -29,11 +29,12 @@ nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded
The first column in the output is the <emphasis>attribute name</emphasis>,
such as <literal>nixos.thunderbird</literal>.
</para>

<para>
Note: the <literal>nixos</literal> prefix tells us that we want to get the
package from the <literal>nixos</literal> channel and works only in CLI tools.

In declarative configuration use <literal>pkgs</literal> prefix (variable).
package from the <literal>nixos</literal> channel and works only in CLI
tools. In declarative configuration use <literal>pkgs</literal> prefix
(variable).
</para>

<para>
Expand Down
11 changes: 11 additions & 0 deletions nixos/doc/manual/configuration/summary.xml
View file
Open in desktop
Expand Up @@ -215,6 +215,17 @@ xlink:href="http://nixos.org/nix/manual/#chap-writing-nix-expressions">Nix
</entry>
<entry>Apply a function to every element of a list (evaluates to <literal>[ 2 4 6 ]</literal>)</entry>
</row>
<row>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also this should probably go to basic values group, not the builtin functions.

<entry><literal>&lt;foo/bar&gt;</literal>
</entry>
<entry>Search in the environment variable <envar>NIX_PATH</envar> a
path containing <filename>foo/bar</filename> and returns the absolute
path of the <filename>foo/bar</filename> file/folder. If
<envar>NIX_PATH</envar> contains an entry
<literal>foo=/mypath/</literal>, it will instead try the path
<filename>/mypath/bar</filename>. Fore more details, see
<link xlink:href="https://nixos.org/nix/manual/#sec-common-env"><envar>NIX_PATH</envar> documentation</link>.</entry>
</row>
<!--
<row>
<entry><literal>throw "Urgh"</literal></entry>
Expand Down
18 changes: 9 additions & 9 deletions nixos/doc/manual/configuration/x-windows.xml
View file
Open in desktop
Expand Up @@ -70,23 +70,23 @@
<simplesect xml:id="sec-x11-auto-login">
<title>Auto-login</title>
<para>
The x11 login screen can be skipped entirely, automatically logging you into
your window manager and desktop environment when you boot your computer.
The x11 login screen can be skipped entirely, automatically logging you into
your window manager and desktop environment when you boot your computer.
</para>
<para>
This is especially helpful if you have disk encryption enabled. Since you
already have to provide a password to decrypt your disk, entering a second
password to login can be redundant.
This is especially helpful if you have disk encryption enabled. Since you
already have to provide a password to decrypt your disk, entering a second
password to login can be redundant.
</para>
<para>
To enable auto-login, you need to define your default window manager and
desktop environment. If you wanted no desktop environment and i3 as your your
window manager, you'd define:
To enable auto-login, you need to define your default window manager and
desktop environment. If you wanted no desktop environment and i3 as your
your window manager, you'd define:
<programlisting>
<xref linkend="opt-services.xserver.desktopManager.default"/> = "none";
<xref linkend="opt-services.xserver.windowManager.default"/> = "i3";
</programlisting>
And, finally, to enable auto-login for a user <literal>johndoe</literal>:
And, finally, to enable auto-login for a user <literal>johndoe</literal>:
<programlisting>
<xref linkend="opt-services.xserver.displayManager.auto.enable"/> = true;
<xref linkend="opt-services.xserver.displayManager.auto.user"/> = "johndoe";
Expand Down
4 changes: 2 additions & 2 deletions nixos/doc/manual/development/releases.xml
View file
Open in desktop
Expand Up @@ -177,8 +177,8 @@
</listitem>
<listitem>
<para>
Update "Chapter 4. Upgrading NixOS" section of the manual to match
new stable release version.
Update "Chapter 4. Upgrading NixOS" section of the manual to match new
stable release version.
</para>
</listitem>
<listitem>
Expand Down
24 changes: 12 additions & 12 deletions nixos/doc/manual/man-nixos-build-vms.xml
View file
Open in desktop
Expand Up @@ -24,14 +24,12 @@

<arg>
<option>--help</option>
</arg>

<arg>
<option>--option</option>
<replaceable>name</replaceable>
<replaceable>value</replaceable>
</arg>

</arg>

<arg>
<option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
</arg>

<arg choice="plain">
<replaceable>network.nix</replaceable>
</arg>
Expand Down Expand Up @@ -126,10 +124,12 @@
<option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable>
</term>
<listitem>
<para>Set the Nix configuration option
<replaceable>name</replaceable> to <replaceable>value</replaceable>.
This overrides settings in the Nix configuration file (see
<citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
<para>
Set the Nix configuration option <replaceable>name</replaceable> to
<replaceable>value</replaceable>. This overrides settings in the Nix
configuration file (see <citerefentry>
<refentrytitle>nix.conf</refentrytitle>
<manvolnum>5</manvolnum></citerefentry>).
</para>
</listitem>
</varlistentry>
Expand Down
34 changes: 17 additions & 17 deletions nixos/doc/manual/release-notes/rl-1903.xml
View file
Open in desktop
Expand Up @@ -63,15 +63,14 @@
</para>
</listitem>
<listitem>
<para>
There is now a set of <option>confinement</option> options for
<option>systemd.services</option>, which allows to restrict services
into a <citerefentry>
<refentrytitle>chroot</refentrytitle>
<manvolnum>2</manvolnum>
</citerefentry>ed environment that only contains the store paths from
the runtime closure of the service.
</para>
<para>
There is now a set of <option>confinement</option> options for
<option>systemd.services</option>, which allows to restrict services into
a <citerefentry>
<refentrytitle>chroot</refentrytitle>
<manvolnum>2</manvolnum> </citerefentry>ed environment that only contains
the store paths from the runtime closure of the service.
</para>
</listitem>
</itemizedlist>
</section>
Expand Down Expand Up @@ -523,17 +522,18 @@
</listitem>
<listitem>
<para>
The option <literal>users.ldap.bind.password</literal> was renamed to <literal>users.ldap.bind.passwordFile</literal>,
and needs to be readable by the <literal>nslcd</literal> user.
Same applies to the new <literal>users.ldap.daemon.rootpwmodpwFile</literal> option.
The option <literal>users.ldap.bind.password</literal> was renamed to
<literal>users.ldap.bind.passwordFile</literal>, and needs to be readable
by the <literal>nslcd</literal> user. Same applies to the new
<literal>users.ldap.daemon.rootpwmodpwFile</literal> option.
</para>
</listitem>
<listitem>
<para>
<literal>nodejs-6_x</literal> is end-of-life.
<literal>nodejs-6_x</literal>, <literal>nodejs-slim-6_x</literal> and
<literal>nodePackages_6_x</literal> are removed.
</para>
<para>
<literal>nodejs-6_x</literal> is end-of-life.
<literal>nodejs-6_x</literal>, <literal>nodejs-slim-6_x</literal> and
<literal>nodePackages_6_x</literal> are removed.
</para>
</listitem>
</itemizedlist>
</section>
Expand Down
128 changes: 67 additions & 61 deletions nixos/doc/manual/release-notes/rl-1909.xml
View file
Open in desktop
Expand Up @@ -41,7 +41,6 @@
<para>
The following new services were added since the last release:
</para>

</section>

<section xmlns="http://docbook.org/ns/docbook"
Expand All @@ -66,55 +65,57 @@
</listitem>
<listitem>
<para>
PostgreSQL now uses
<filename class="directory">/run/postgresql</filename> as its socket
directory instead of <filename class="directory">/tmp</filename>. So
if you run an application like eg. Nextcloud, where you need to use
the Unix socket path as the database host name, you need to change it
accordingly.
PostgreSQL now uses <filename class="directory">/run/postgresql</filename>
as its socket directory instead of
<filename class="directory">/tmp</filename>. So if you run an application
like eg. Nextcloud, where you need to use the Unix socket path as the
database host name, you need to change it accordingly.
</para>
</listitem>
<listitem>
<para>
The options <option>services.prometheus.alertmanager.user</option> and
<option>services.prometheus.alertmanager.group</option> have been removed
because the alertmanager service is now using systemd's <link
The options <option>services.prometheus.alertmanager.user</option> and
<option>services.prometheus.alertmanager.group</option> have been removed
because the alertmanager service is now using systemd's
<link
xlink:href="http://0pointer.net/blog/dynamic-users-with-systemd.html">
DynamicUser mechanism</link> which obviates these options.
DynamicUser mechanism</link> which obviates these options.
</para>
</listitem>
<listitem>
<para>
The NetworkManager systemd unit was renamed back from network-manager.service to
NetworkManager.service for better compatibility with other applications expecting this name.
The same applies to ModemManager where modem-manager.service is now called ModemManager.service again.
The NetworkManager systemd unit was renamed back from
network-manager.service to NetworkManager.service for better compatibility
with other applications expecting this name. The same applies to
ModemManager where modem-manager.service is now called
ModemManager.service again.
</para>
</listitem>
<listitem>
<para>
The <option>services.nzbget.configFile</option> and <option>services.nzbget.openFirewall</option>
options were removed as they are managed internally by the nzbget. The
<option>services.nzbget.dataDir</option> option hadn't actually been used by
the module for some time and so was removed as cleanup.
The <option>services.nzbget.configFile</option> and
<option>services.nzbget.openFirewall</option> options were removed as they
are managed internally by the nzbget. The
<option>services.nzbget.dataDir</option> option hadn't actually been used
by the module for some time and so was removed as cleanup.
</para>
</listitem>
<listitem>
<para>
The <option>services.mysql.pidDir</option> option was removed, as it was only used by the wordpress
apache-httpd service to wait for mysql to have started up.
This can be accomplished by either describing a dependency on mysql.service (preferred)
or waiting for the (hardcoded) <filename>/run/mysqld/mysql.sock</filename> file to appear.
The <option>services.mysql.pidDir</option> option was removed, as it was
only used by the wordpress apache-httpd service to wait for mysql to have
started up. This can be accomplished by either describing a dependency on
mysql.service (preferred) or waiting for the (hardcoded)
<filename>/run/mysqld/mysql.sock</filename> file to appear.
</para>
</listitem>
<listitem>
<para>
The <option>services.emby.enable</option> module has been removed, see
<option>services.jellyfin.enable</option> instead for a free software fork of Emby.

See the Jellyfin documentation:
<link xlink:href="https://jellyfin.readthedocs.io/en/latest/administrator-docs/migrate-from-emby/">
Migrating from Emby to Jellyfin
</link>
The <option>services.emby.enable</option> module has been removed, see
<option>services.jellyfin.enable</option> instead for a free software fork
of Emby. See the Jellyfin documentation:
<link xlink:href="https://jellyfin.readthedocs.io/en/latest/administrator-docs/migrate-from-emby/">
Migrating from Emby to Jellyfin </link>
</para>
</listitem>
<listitem>
Expand All @@ -131,15 +132,19 @@
</listitem>
<listitem>
<para>
The limesurvey apache subservice was replaced with a full NixOS module.
One can configure it using the <option>services.limesurvey.enable</option>
and <option>services.limesurvey.virtualHost</option> options.
The limesurvey apache subservice was replaced with a full NixOS module.
One can configure it using the <option>services.limesurvey.enable</option>
and <option>services.limesurvey.virtualHost</option> options.
</para>
</listitem>
<listitem>
<para>
The setopt declarations will be evaluated at the end of <literal>/etc/zshrc</literal>, so any code in <xref linkend="opt-programs.zsh.interactiveShellInit" />,
<xref linkend="opt-programs.zsh.loginShellInit" /> and <xref linkend="opt-programs.zsh.promptInit" /> may break if it relies on those options being set.
The setopt declarations will be evaluated at the end of
<literal>/etc/zshrc</literal>, so any code in
<xref linkend="opt-programs.zsh.interactiveShellInit" />,
<xref linkend="opt-programs.zsh.loginShellInit" /> and
<xref linkend="opt-programs.zsh.promptInit" /> may break if it relies on
those options being set.
</para>
</listitem>
</itemizedlist>
Expand Down Expand Up @@ -196,44 +201,45 @@
</listitem>
<listitem>
<para>
The <literal>hunspellDicts.fr-any</literal> dictionary now ships with <literal>fr_FR.{aff,dic}</literal>
which is linked to <literal>fr-toutesvariantes.{aff,dic}</literal>.
The <literal>hunspellDicts.fr-any</literal> dictionary now ships with
<literal>fr_FR.{aff,dic}</literal> which is linked to
<literal>fr-toutesvariantes.{aff,dic}</literal>.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
The <literal>mysql</literal> service now runs as <literal>mysql</literal>
user. Previously, systemd did execute it as root, and mysql dropped privileges
itself.
This includes <literal>ExecStartPre=</literal> and
<literal>ExecStartPost=</literal> phases.
To accomplish that, runtime and data directory setup was delegated to
RuntimeDirectory and tmpfiles.
The <literal>mysql</literal> service now runs as <literal>mysql</literal>
user. Previously, systemd did execute it as root, and mysql dropped
privileges itself. This includes <literal>ExecStartPre=</literal> and
<literal>ExecStartPost=</literal> phases. To accomplish that, runtime and
data directory setup was delegated to RuntimeDirectory and tmpfiles.
</para>
</listitem>
<listitem>
<listitem>
<para>
Since version 0.1.19, <literal>cargo-vendor</literal> honors package
includes that are specified in the <filename>Cargo.toml</filename>
file of Rust crates. <literal>rustPlatform.buildRustPackage</literal> uses
<literal>cargo-vendor</literal> to collect and build dependent crates.
Since this change in <literal>cargo-vendor</literal> changes the set of
vendored files for most Rust packages, the hash that use used to verify
the dependencies, <literal>cargoSha256</literal>, also changes.
Since version 0.1.19, <literal>cargo-vendor</literal> honors package
includes that are specified in the <filename>Cargo.toml</filename> file of
Rust crates. <literal>rustPlatform.buildRustPackage</literal> uses
<literal>cargo-vendor</literal> to collect and build dependent crates.
Since this change in <literal>cargo-vendor</literal> changes the set of
vendored files for most Rust packages, the hash that use used to verify
the dependencies, <literal>cargoSha256</literal>, also changes.
</para>

<para>
The <literal>cargoSha256</literal> hashes of all in-tree derivations that
use <literal>buildRustPackage</literal> have been updated to reflect this
change. However, third-party derivations that use
<literal>buildRustPackage</literal> may have to be updated as well.
The <literal>cargoSha256</literal> hashes of all in-tree derivations that
use <literal>buildRustPackage</literal> have been updated to reflect this
change. However, third-party derivations that use
<literal>buildRustPackage</literal> may have to be updated as well.
</para>
</listitem>
<listitem>
<para>
The default resample-method for PulseAudio has been changed from the upstream default <literal>speex-float-1</literal>
to <literal>speex-float-5</literal>. Be aware that low-powered ARM-based and MIPS-based boards will struggle with this
so you'll need to set <option>hardware.pulseaudio.daemon.config.resample-method</option> back to <literal>speex-float-1</literal>.
The default resample-method for PulseAudio has been changed from the
upstream default <literal>speex-float-1</literal> to
<literal>speex-float-5</literal>. Be aware that low-powered ARM-based and
MIPS-based boards will struggle with this so you'll need to set
<option>hardware.pulseaudio.daemon.config.resample-method</option> back to
<literal>speex-float-1</literal>.
</para>
</listitem>
</itemizedlist>
Expand Down
5 changes: 3 additions & 2 deletions nixos/modules/services/web-apps/nextcloud.xml
View file
Open in desktop
Expand Up @@ -113,8 +113,9 @@
</para>

<para>
Right now app installation and configuration is done imperatively in the nextcloud web ui or via the <literal>nextcloud-occ</literal> command line utility.
You can activate auto updates for your apps via
Right now app installation and configuration is done imperatively in the
nextcloud web ui or via the <literal>nextcloud-occ</literal> command line
utility. You can activate auto updates for your apps via
<literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>.
</para>
</section>
Expand Down