nixos docs: run the formatting tool (no content change)

As documented in the docs themselves :-)

nixos/doc/manual/configuration/config-file.xml

@@ -200,8 +200,9 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
 <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10;
 </programlisting>
       The latter option definition changes the default PostgreSQL package used
-      by NixOS’s PostgreSQL service to 10.x. For more information on packages,
+      by NixOS’s PostgreSQL service to 10.x. For more information on
-      including how to add new ones, see <xref linkend="sec-custom-packages"/>.
+      packages, including how to add new ones, see
+      <xref linkend="sec-custom-packages"/>.
      </para>
     </listitem>
    </varlistentry>

nixos/doc/manual/configuration/kubernetes.xml

@@ -4,15 +4,13 @@
          version="5.0"
          xml:id="sec-kubernetes">
  <title>Kubernetes</title>
-
  <para>
-   The NixOS Kubernetes module is a collective term for a handful of
+  The NixOS Kubernetes module is a collective term for a handful of individual
-   individual submodules implementing the Kubernetes cluster components.
+  submodules implementing the Kubernetes cluster components.
  </para>
-
  <para>
-   There are generally two ways of enabling Kubernetes on NixOS.
+  There are generally two ways of enabling Kubernetes on NixOS. One way is to
-   One way is to enable and configure cluster components appropriately by hand:
+  enable and configure cluster components appropriately by hand:
 <programlisting>
 services.kubernetes = {
   apiserver.enable = true;
@@ -33,84 +31,72 @@ services.kubernetes = {
 <programlisting>
 <xref linkend="opt-services.kubernetes.roles"/> = [ "node" ];
 </programlisting>
-  Assigning both the master and node roles is usable if you want a single
+  Assigning both the master and node roles is usable if you want a single node
-  node Kubernetes cluster for dev or testing purposes:
+  Kubernetes cluster for dev or testing purposes:
 <programlisting>
 <xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ];
 </programlisting>
   Note: Assigning either role will also default both
   <xref linkend="opt-services.kubernetes.flannel.enable"/> and
-  <xref linkend="opt-services.kubernetes.easyCerts"/> to true.
+  <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up
-  This sets up flannel as CNI and activates automatic PKI bootstrapping.
+  flannel as CNI and activates automatic PKI bootstrapping.
  </para>
-
  <para>
-   As of kubernetes 1.10.X it has been deprecated to open
+  As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports
-   non-tls-enabled ports on kubernetes components. Thus, from NixOS 19.03 all
+  on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have
-   plain HTTP ports have been disabled by default.
+  been disabled by default. While opening insecure ports is still possible, it
-   While opening insecure ports is still possible, it is recommended not to
+  is recommended not to bind these to other interfaces than loopback. To
-   bind these to other interfaces than loopback.
+  re-enable the insecure port on the apiserver, see options:
-
+  <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and
-   To re-enable the insecure port on the apiserver, see options:
-   <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/>
-   and
   <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>
  </para>
-
  <note>
   <para>
    As of NixOS 19.03, it is mandatory to configure:
-   <xref linkend="opt-services.kubernetes.masterAddress"/>.
+   <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress
-   The masterAddress must be resolveable and routeable by all cluster nodes.
+   must be resolveable and routeable by all cluster nodes. In single node
-   In single node clusters, this can be set to <literal>localhost</literal>.
+   clusters, this can be set to <literal>localhost</literal>.
   </para>
  </note>
-
  <para>
   Role-based access control (RBAC) authorization mode is enabled by default.
   This means that anonymous requests to the apiserver secure port will
   expectedly cause a permission denied error. All cluster components must
   therefore be configured with x509 certificates for two-way tls communication.
   The x509 certificate subject section determines the roles and permissions
-   granted by the apiserver to perform clusterwide or namespaced operations.
+  granted by the apiserver to perform clusterwide or namespaced operations. See
-   See also:
+  also:
   <link
      xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">
   Using RBAC Authorization</link>.
  </para>
-
  <para>
   The NixOS kubernetes module provides an option for automatic certificate
   bootstrapping and configuration,
-    <xref linkend="opt-services.kubernetes.easyCerts"/>.
+  <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping
-   The PKI bootstrapping process involves setting up a certificate authority
+  process involves setting up a certificate authority (CA) daemon (cfssl) on
-   (CA) daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert
+  the kubernetes master node. cfssl generates a CA-cert for the cluster, and
-   for the cluster, and uses the CA-cert for signing subordinate certs issued to
+  uses the CA-cert for signing subordinate certs issued to each of the cluster
-   each of the cluster components. Subsequently, the certmgr daemon monitors
+  components. Subsequently, the certmgr daemon monitors active certificates and
-   active certificates and renews them when needed. For single node Kubernetes
+  renews them when needed. For single node Kubernetes clusters, setting
-   clusters, setting <xref linkend="opt-services.kubernetes.easyCerts"/> = true
+  <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and
-   is sufficient and no further action is required. For joining extra node
+  no further action is required. For joining extra node machines to an existing
-   machines to an existing cluster on the other hand, establishing initial trust
+  cluster on the other hand, establishing initial trust is mandatory.
-   is mandatory.
  </para>
-
  <para>
-   To add new nodes to the cluster:
+  To add new nodes to the cluster: On any (non-master) cluster node where
-   On any (non-master) cluster node where
   <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper
   script <literal>nixos-kubernetes-node-join</literal> is available on PATH.
-   Given a token on stdin, it will copy the token to the kubernetes
+  Given a token on stdin, it will copy the token to the kubernetes secrets
-   secrets directory and restart the certmgr service. As requested
+  directory and restart the certmgr service. As requested certificates are
-   certificates are issued, the script will restart kubernetes cluster
+  issued, the script will restart kubernetes cluster components as needed for
-   components as needed for them to pick up new keypairs.
+  them to pick up new keypairs.
  </para>
-
  <note>
   <para>
    Multi-master (HA) clusters are not supported by the easyCerts module.
   </para>
  </note>
-
  <para>
   In order to interact with an RBAC-enabled cluster as an administrator, one
   needs to have cluster-admin privileges. By default, when easyCerts is
@@ -123,5 +109,4 @@ services.kubernetes = {
   root. Thus, only root on the kubernetes master may obtain cluster-admin
   rights by means of this file.
  </para>
-
 </chapter>

nixos/doc/manual/configuration/matrix.xml

@@ -5,31 +5,34 @@
          xml:id="module-services-matrix">
  <title>Matrix</title>
  <para>
-  <link xlink:href="https://matrix.org/">Matrix</link>
+  <link xlink:href="https://matrix.org/">Matrix</link> is an open standard for
-  is an open standard for interoperable, decentralised, real-time communication over IP.
+  interoperable, decentralised, real-time communication over IP. It can be used
-  It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication -
+  to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things
-  or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.
+  communication - or anywhere you need a standard HTTP API for publishing and
+  subscribing to data whilst tracking the conversation history.
  </para>
  <para>
-  This chapter will show you how to set up your own, self-hosted Matrix homeserver using the Synapse reference homeserver,
+  This chapter will show you how to set up your own, self-hosted Matrix
-  and how to serve your own copy of the Riot web client.
+  homeserver using the Synapse reference homeserver, and how to serve your own
-  See the <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try Matrix Now!</link>
+  copy of the Riot web client. See the
-  overview page for links to Riot Apps for Android and iOS, desktop clients,
+  <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try
-  as well as bridges to other networks and other projects around Matrix.
+  Matrix Now!</link> overview page for links to Riot Apps for Android and iOS,
+  desktop clients, as well as bridges to other networks and other projects
+  around Matrix.
  </para>
-
  <section xml:id="module-services-matrix-synapse">
   <title>Synapse Homeserver</title>
+
   <para>
-   <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link>
+   <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is
-   is the reference homeserver implementation of Matrix from the core development team at matrix.org.
+   the reference homeserver implementation of Matrix from the core development
-   The following configuration example will set up a synapse server for the <literal>example.org</literal>
+   team at matrix.org. The following configuration example will set up a
-   domain, served from the host <literal>myhostname.example.org</literal>.
+   synapse server for the <literal>example.org</literal> domain, served from
-   For more information, please refer to the
+   the host <literal>myhostname.example.org</literal>. For more information,
+   please refer to the
    <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation">
-    installation instructions of Synapse
+   installation instructions of Synapse </link>.
-   </link>.
+<programlisting>
-   <programlisting>
     let
       fqdn =
         let
@@ -116,28 +119,29 @@
     };
    </programlisting>
   </para>
+
   <para>
-   If the <code>A</code> and <code>AAAA</code> DNS records on <literal>example.org</literal>
+   If the <code>A</code> and <code>AAAA</code> DNS records on
-   do not point on the same host as the records for <code>myhostname.example.org</code>,
+   <literal>example.org</literal> do not point on the same host as the records
-   you can easily move the <code>/.well-known</code> virtualHost section of the code
+   for <code>myhostname.example.org</code>, you can easily move the
-   to the host that is serving <literal>example.org</literal>,
+   <code>/.well-known</code> virtualHost section of the code to the host that
-   while the rest stays on <literal>myhostname.example.org</literal>
+   is serving <literal>example.org</literal>, while the rest stays on
-   with no other changes required.
+   <literal>myhostname.example.org</literal> with no other changes required.
-   This pattern also allows to seamlessly move the homeserver from <literal>myhostname.example.org</literal>
+   This pattern also allows to seamlessly move the homeserver from
-   to <literal>myotherhost.example.org</literal> by only changing the <code>/.well-known</code> redirection target.
+   <literal>myhostname.example.org</literal> to
+   <literal>myotherhost.example.org</literal> by only changing the
+   <code>/.well-known</code> redirection target.
   </para>
 
   <para>
-   If you want to run a server with public registration by anybody,
+   If you want to run a server with public registration by anybody, you can
-   you can then enable
+   then enable <option>services.matrix-synapse.enable_registration =
-   <option>services.matrix-synapse.enable_registration = true;</option>.
+   true;</option>. Otherwise, or you can generate a registration secret with
-   Otherwise, or you can generate a registration secret with <command>pwgen -s 64 1</command>
+   <command>pwgen -s 64 1</command> and set it with
-   and set it with
+   <option>services.matrix-synapse.registration_shared_secret</option>. To
-   <option>services.matrix-synapse.registration_shared_secret</option>.
+   create a new user or admin, run the following after you have set the secret
-   To create a new user or admin,
+   and have rebuilt NixOS:
-   run the following after you have set the secret and have rebuilt NixOS:
+<programlisting>
-
-   <programlisting>
     $ nix run nixpkgs.matrix-synapse
     $ register_new_matrix_user -k &lt;your-registration-shared-secret&gt; http://localhost:8008
     New user localpart: &lt;your-username&gt;
@@ -147,31 +151,32 @@
     Success!
    </programlisting>
    In the example, this would create a user with the Matrix Identifier
-   <literal>@your-username:example.org</literal>.
+   <literal>@your-username:example.org</literal>. Note that the registration
-   Note that the registration secret ends up in the nix store and therefore is world-readable
+   secret ends up in the nix store and therefore is world-readable by any user
-   by any user on your machine, so it makes sense to only temporarily activate the
+   on your machine, so it makes sense to only temporarily activate the
-   <option>registration_shared_secret</option> option until a better solution for NixOS is in place.
+   <option>registration_shared_secret</option> option until a better solution
+   for NixOS is in place.
   </para>
  </section>
-
  <section xml:id="module-services-matrix-riot-web">
   <title>Riot Web Client</title>
-  <para>
-   <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link>
-   is the reference web client for Matrix and developed by the core team at matrix.org.
-   The following snippet can be optionally added to the code before to complete the synapse
-   installation with a web client served at
-   <code>https://riot.myhostname.example.org</code> and <code>https://riot.example.org</code>.
-   Alternatively, you can use the hosted copy at
-   <link xlink:href="https://riot.im/app">https://riot.im/app</link>,
-   or use other web clients or native client applications.
-   Due to the <literal>/.well-known</literal> urls set up done above,
-   many clients should fill in the required connection details automatically
-   when you enter your Matrix Identifier.
-   See <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try Matrix Now!</link>
-   for a list of existing clients and their supported featureset.
 
-   <programlisting>
+  <para>
+   <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link> is
+   the reference web client for Matrix and developed by the core team at
+   matrix.org. The following snippet can be optionally added to the code before
+   to complete the synapse installation with a web client served at
+   <code>https://riot.myhostname.example.org</code> and
+   <code>https://riot.example.org</code>. Alternatively, you can use the hosted
+   copy at <link xlink:href="https://riot.im/app">https://riot.im/app</link>,
+   or use other web clients or native client applications. Due to the
+   <literal>/.well-known</literal> urls set up done above, many clients should
+   fill in the required connection details automatically when you enter your
+   Matrix Identifier. See
+   <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try
+   Matrix Now!</link> for a list of existing clients and their supported
+   featureset.
+<programlisting>
      services.nginx.virtualHosts."riot.${fqdn}" = {
        enableACME = true;
        forceSSL = true;
@@ -183,15 +188,16 @@
      };
    </programlisting>
   </para>
+
   <para>
-   Note that the Riot developers do not recommend running Riot and your Matrix homeserver
+   Note that the Riot developers do not recommend running Riot and your Matrix
-   on the same fully-qualified domain name for security reasons.
+   homeserver on the same fully-qualified domain name for security reasons. In
-   In the example, this means that you should not reuse the <literal>myhostname.example.org</literal>
+   the example, this means that you should not reuse the
-   virtualHost to also serve Riot, but instead serve it on a different subdomain,
+   <literal>myhostname.example.org</literal> virtualHost to also serve Riot,
-   like <literal>riot.example.org</literal> in the example.
+   but instead serve it on a different subdomain, like
-   See the
+   <literal>riot.example.org</literal> in the example. See the
-   <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot Important Security Notes</link>
+   <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot
-   for more information on this subject.
+   Important Security Notes</link> for more information on this subject.
   </para>
  </section>
 </chapter>

nixos/doc/manual/configuration/modularity.xml

@@ -112,9 +112,8 @@ true
 $ nixos-option <xref linkend="opt-boot.kernelModules"/>
 [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]
 </screen>
-  Interactive exploration of the configuration is possible using
+  Interactive exploration of the configuration is possible using <command>nix
-  <command>nix repl</command>, a read-eval-print loop for Nix expressions.
+  repl</command>, a read-eval-print loop for Nix expressions. A typical use:
-  A typical use:
 <screen>
 $ nix repl '&lt;nixpkgs/nixos>'
 
@@ -128,10 +127,9 @@ nix-repl> map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHo
 
  <para>
   While abstracting your configuration, you may find it useful to generate
-   modules using code, instead of writing files. The example
+  modules using code, instead of writing files. The example below would have
-   below would have the same effect as importing a file which sets those
+  the same effect as importing a file which sets those options.
-   options.
+<screen>
-   <screen>
      { config, pkgs, ... }:
 
      let netConfig = { hostName }: {
@@ -143,5 +141,5 @@ nix-repl> map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHo
 
     { imports = [ (netConfig "nixos.localdomain") ]; }
   </screen>
-</para>
+ </para>
 </section>

nixos/doc/manual/configuration/profiles.xml

@@ -12,14 +12,14 @@
   That is to say, expected usage is to add them to the imports list of your
   <filename>/etc/configuration.nix</filename> as such:
  </para>
- <programlisting>
+<programlisting>
   imports = [
    &lt;nixpkgs/nixos/modules/profiles/profile-name.nix&gt;
   ];
  </programlisting>
  <para>
-  Even if some of these profiles seem only useful in the context of
+  Even if some of these profiles seem only useful in the context of install
-  install media, many are actually intended to be used in real installs.
+  media, many are actually intended to be used in real installs.
  </para>
  <para>
   What follows is a brief explanation on the purpose and use-case for each

nixos/doc/manual/configuration/profiles/all-hardware.xml

@@ -1,15 +1,16 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-all-hardware">
  <title>All Hardware</title>
+
  <para>
-  Enables all hardware supported by NixOS: i.e., all firmware is
+  Enables all hardware supported by NixOS: i.e., all firmware is included, and
-  included, and all devices from which one may boot are enabled in the initrd.
+  all devices from which one may boot are enabled in the initrd. Its primary
-  Its primary use is in the NixOS installation CDs.
+  use is in the NixOS installation CDs.
  </para>
+
  <para>
   The enabled kernel modules include support for SATA and PATA, SCSI
   (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and

nixos/doc/manual/configuration/profiles/base.xml

@@ -1,15 +1,15 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-base">
  <title>Base</title>
+
  <para>
-  Defines the software packages included in the "minimal"
+  Defines the software packages included in the "minimal" installation CD. It
-  installation CD. It installs several utilities useful in a simple recovery or
+  installs several utilities useful in a simple recovery or install media, such
-  install media, such as a text-mode web browser, and tools for manipulating
+  as a text-mode web browser, and tools for manipulating block devices,
-  block devices, networking, hardware diagnostics, and filesystems (with their
+  networking, hardware diagnostics, and filesystems (with their respective
-  respective kernel modules).
+  kernel modules).
  </para>
 </section>

nixos/doc/manual/configuration/profiles/clone-config.xml

@@ -1,14 +1,14 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-clone-config">
  <title>Clone Config</title>
+
  <para>
-  This profile is used in installer images.
+  This profile is used in installer images. It provides an editable
-  It provides an editable configuration.nix that imports all the modules that
+  configuration.nix that imports all the modules that were also used when
-  were also used when creating the image in the first place.
+  creating the image in the first place. As a result it allows users to edit
-  As a result it allows users to edit and rebuild the live-system.
+  and rebuild the live-system.
  </para>
 </section>

nixos/doc/manual/configuration/profiles/demo.xml

@@ -1,13 +1,15 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-demo">
  <title>Demo</title>
+
  <para>
-  This profile just enables a <systemitem class="username">demo</systemitem> user, with password <literal>demo</literal>, uid <literal>1000</literal>, <systemitem class="groupname">wheel</systemitem>
+  This profile just enables a <systemitem class="username">demo</systemitem>
-  group and <link linkend="opt-services.xserver.displayManager.sddm.autoLogin">
+  user, with password <literal>demo</literal>, uid <literal>1000</literal>,
-   autologin in the SDDM display manager</link>.
+  <systemitem class="groupname">wheel</systemitem> group and
+  <link linkend="opt-services.xserver.displayManager.sddm.autoLogin"> autologin
+  in the SDDM display manager</link>.
  </para>
 </section>

nixos/doc/manual/configuration/profiles/docker-container.xml

@@ -1,15 +1,16 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-docker-container">
  <title>Docker Container</title>
+
  <para>
   This is the profile from which the Docker images are generated. It prepares a
-  working system by importing the <link linkend="sec-profile-minimal">Minimal</link> and
+  working system by importing the
-  <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and setting appropriate
+  <link linkend="sec-profile-minimal">Minimal</link> and
-  configuration options that are useful inside a container context, like
+  <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and
-  <xref linkend="opt-boot.isContainer"/>.
+  setting appropriate configuration options that are useful inside a container
+  context, like <xref linkend="opt-boot.isContainer"/>.
  </para>
 </section>

nixos/doc/manual/configuration/profiles/graphical.xml

@@ -1,14 +1,15 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-graphical">
  <title>Graphical</title>
+
  <para>
   Defines a NixOS configuration with the Plasma 5 desktop. It's used by the
   graphical installation CD.
  </para>
+
  <para>
   It sets <xref linkend="opt-services.xserver.enable"/>,
   <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>,

nixos/doc/manual/configuration/profiles/hardened.xml

@@ -1,21 +1,23 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-hardened">
  <title>Hardened</title>
+
  <para>
   A profile with most (vanilla) hardening options enabled by default,
   potentially at the cost of features and performance.
  </para>
+
  <para>
   This includes a hardened kernel, and limiting the system information
   available to processes through the <filename>/sys</filename> and
   <filename>/proc</filename> filesystems. It also disables the User Namespaces
   feature of the kernel, which stops Nix from being able to build anything
   (this particular setting can be overriden via
-  <xref linkend="opt-security.allowUserNamespaces"/>). See the <literal
+  <xref linkend="opt-security.allowUserNamespaces"/>). See the
+  <literal
    xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix">
   profile source</literal> for further detail on which settings are altered.
  </para>

nixos/doc/manual/configuration/profiles/headless.xml

@@ -1,18 +1,19 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-headless">
  <title>Headless</title>
+
  <para>
   Common configuration for headless machines (e.g., Amazon EC2 instances).
  </para>
+
  <para>
   Disables <link linkend="opt-sound.enable">sound</link>,
   <link linkend="opt-boot.vesa">vesa</link>, serial consoles,
   <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>,
-  <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link> and
+  <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link>
-  configures the kernel to reboot automatically on panic.
+  and configures the kernel to reboot automatically on panic.
  </para>
 </section>

nixos/doc/manual/configuration/profiles/installation-device.xml

@@ -1,10 +1,10 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-installation-device">
  <title>Installation Device</title>
+
  <para>
   Provides a basic configuration for installation devices like CDs. This means
   enabling hardware scans, using the <link linkend="sec-profile-clone-config">
@@ -13,6 +13,7 @@
   <command>nixos-rebuild</command> to work), a copy of the Nixpkgs channel
   snapshot used to create the install media.
  </para>
+
  <para>
   Additionally, documentation for <link linkend="opt-documentation.enable">
   Nixpkgs</link> and <link linkend="opt-documentation.nixos.enable">NixOS
@@ -21,11 +22,13 @@
   NixOS manual is shown automatically on TTY 8, sudo and udisks are disabled.
   Autologin is enabled as root.
  </para>
+
  <para>
-  A message is shown to the user to start a display manager if needed,
+  A message is shown to the user to start a display manager if needed, ssh with
-  ssh with <xref linkend="opt-services.openssh.permitRootLogin"/> are enabled (but
+  <xref linkend="opt-services.openssh.permitRootLogin"/> are enabled (but
   doesn't autostart). WPA Supplicant is also enabled without autostart.
  </para>
+
  <para>
   Finally, vim is installed, root is set to not have a password, the kernel is
   made more silent for remote public IP installs, and several settings are

nixos/doc/manual/configuration/profiles/minimal.xml

@@ -1,16 +1,16 @@
-
 <section xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          version="5.0"
          xml:id="sec-profile-minimal">
  <title>Minimal</title>
+
  <para>
   This profile defines a small NixOS configuration. It does not contain any
   graphical stuff. It's a very short file that enables
   <link linkend="opt-environment.noXlibs">noXlibs</link>, sets
-  <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link>
+  <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to
-  to only support the user-selected locale,
+  only support the user-selected locale,
   <link linkend="opt-documentation.enable">disables packages' documentation
   </link>, and <link linkend="opt-sound.enable">disables sound</link>.
  </para>

nixos/doc/manual/configuration/profiles/qemu-guest.xml

@@ -4,10 +4,12 @@
          version="5.0"
          xml:id="sec-profile-qemu-guest">
  <title>QEMU Guest</title>
+
  <para>
   This profile contains common configuration for virtual machines running under
   QEMU (using virtio).
  </para>
+
  <para>
   It makes virtio modules available on the initrd, sets the system time from
   the hardware clock to work around a bug in qemu-kvm, and

nixos/doc/manual/configuration/wireless.xml

@@ -28,11 +28,9 @@
   Be aware that keys will be written to the nix store in plaintext! When no
   networks are set, it will default to using a configuration file at
   <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file
-  yourself to define wireless networks, WPA keys and so on (see
+  yourself to define wireless networks, WPA keys and so on (see <citerefentry>
-  <citerefentry>
   <refentrytitle>wpa_supplicant.conf</refentrytitle>
-    <manvolnum>5</manvolnum>
+  <manvolnum>5</manvolnum> </citerefentry>).
-  </citerefentry>).
  </para>
 
  <para>

nixos/doc/manual/installation/installing-virtualbox-guest.xml

@@ -77,10 +77,10 @@
   Shared folders can be given a name and a path in the host system in the
   VirtualBox settings (Machine / Settings / Shared Folders, then click on the
   "Add" icon). Add the following to the
-  <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you 
+  <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do
-   do not add <literal>"nofail"</literal>, the system will no boot properly. 
+  not add <literal>"nofail"</literal>, the system will no boot properly. The
-   The same goes for disabling <literal>rngd</literal> which is normally used 
+  same goes for disabling <literal>rngd</literal> which is normally used to get
-   to get randomness but this does not work in virtual machines.
+  randomness but this does not work in virtual machines.
  </para>
 
 <programlisting>

nixos/doc/manual/man-nixos-rebuild.xml

@@ -70,9 +70,9 @@
    <arg>
     <option>--rollback</option>
    </arg>
+    
    <arg>
-     <option>--builders</option>
+    <option>--builders</option> <replaceable>builder-spec</replaceable>
-     <replaceable>builder-spec</replaceable>
    </arg>
    <sbr />
    <arg>
@@ -335,22 +335,20 @@ $ ./result/bin/run-*-vm
    </varlistentry>
    <varlistentry>
     <term>
-       <option>--builders</option>
+     <option>--builders</option> <replaceable>builder-spec</replaceable>
-       <replaceable>builder-spec</replaceable>
     </term>
     <listitem>
      <para>
-         Allow ad-hoc remote builders for building the new system.
+      Allow ad-hoc remote builders for building the new system. This requires
-         This requires the user executing <command>nixos-rebuild</command> (usually
+      the user executing <command>nixos-rebuild</command> (usually root) to be
-         root) to be configured as a trusted user in the Nix daemon. This can be
+      configured as a trusted user in the Nix daemon. This can be achieved by
-         achieved by using the <literal>nix.trustedUsers</literal> NixOS option.
+      using the <literal>nix.trustedUsers</literal> NixOS option. Examples
-         Examples values for that option are described in the
+      values for that option are described in the <literal>Remote builds
-		 <literal>Remote builds chapter</literal> in the Nix manual,
+      chapter</literal> in the Nix manual, (i.e. <command>--builders
-         (i.e. <command>--builders "ssh://bigbrother x86_64-linux"</command>).
+      "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string
-         By specifying an empty string existing builders specified in
+      existing builders specified in <filename>/etc/nix/machines</filename> can
-         <filename>/etc/nix/machines</filename> can be ignored:
+      be ignored: <command>--builders ""</command> for example when they are
-         <command>--builders ""</command> for example when they are not
+      not reachable due to network connectivity.
-         reachable due to network connectivity.
      </para>
     </listitem>
    </varlistentry>

nixos/doc/manual/release-notes/rl-1809.xml

@@ -639,7 +639,8 @@ $ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull'
    </listitem>
    <listitem>
     <para>
-        Groups <literal>kvm</literal> and <literal>render</literal> are introduced now, as systemd requires them.
+     Groups <literal>kvm</literal> and <literal>render</literal> are introduced
+     now, as systemd requires them.
     </para>
    </listitem>
   </itemizedlist>

nixos/doc/manual/release-notes/rl-1903.xml

@@ -20,25 +20,27 @@
   <itemizedlist>
    <listitem>
     <para>
-    The default Python 3 interpreter is now CPython 3.7 instead of CPython 3.6.
+     The default Python 3 interpreter is now CPython 3.7 instead of CPython
+     3.6.
     </para>
    </listitem>
    <listitem>
     <para>
-     Added the Pantheon desktop environment.
+     Added the Pantheon desktop environment. It can be enabled through
-     It can be enabled through <varname>services.xserver.desktopManager.pantheon.enable</varname>.
+     <varname>services.xserver.desktopManager.pantheon.enable</varname>.
     </para>
     <note>
      <para>
-      <varname>services.xserver.desktopManager.pantheon</varname> default enables lightdm
+      <varname>services.xserver.desktopManager.pantheon</varname> default
-      as a display manager and using Pantheon's greeter.
+      enables lightdm as a display manager and using Pantheon's greeter.
      </para>
      <para>
-      This is because of limitations with the screenlocking implementation, whereas the
+      This is because of limitations with the screenlocking implementation,
-      screenlocker would be non-functional without it.
+      whereas the screenlocker would be non-functional without it.
      </para>
      <para>
-      Because of that it is recommended to retain this precaution, however if you'd like to change this set:
+      Because of that it is recommended to retain this precaution, however if
+      you'd like to change this set:
      </para>
      <itemizedlist>
       <listitem>
@@ -52,7 +54,9 @@
        </para>
       </listitem>
      </itemizedlist>
-     <para>to <literal>false</literal> and enable your preferred display manager.</para>
+     <para>
+      to <literal>false</literal> and enable your preferred display manager.
+     </para>
     </note>
    </listitem>
    <listitem>
@@ -60,8 +64,8 @@
      A major refactoring of the Kubernetes module has been completed.
      Refactorings primarily focus on decoupling components and enhancing
      security. Two-way TLS and RBAC has been enabled by default for all
-       components, which slightly changes the way the module is configured.
+     components, which slightly changes the way the module is configured. See:
-       See: <xref linkend="sec-kubernetes"/> for details.
+     <xref linkend="sec-kubernetes"/> for details.
     </para>
    </listitem>
   </itemizedlist>
@@ -87,10 +91,11 @@
    <listitem>
     <para>
      There is a new <varname>security.googleOsLogin</varname> module for using
-     <link xlink:href="https://cloud.google.com/compute/docs/instances/managing-instance-access">OS Login</link>
+     <link xlink:href="https://cloud.google.com/compute/docs/instances/managing-instance-access">OS
-     to manage SSH access to Google Compute Engine instances, which supersedes
+     Login</link> to manage SSH access to Google Compute Engine instances,
-     the imperative and broken <literal>google-accounts-daemon</literal> used
+     which supersedes the imperative and broken
-     in <literal>nixos/modules/virtualisation/google-compute-config.nix</literal>.
+     <literal>google-accounts-daemon</literal> used in
+     <literal>nixos/modules/virtualisation/google-compute-config.nix</literal>.
     </para>
    </listitem>
    <listitem>
@@ -101,8 +106,9 @@
    <listitem>
     <para>
      There is a new <varname>services.cockroachdb</varname> module for running
-     CockroachDB databases. NixOS now ships with CockroachDB 2.1.x as well, available
+     CockroachDB databases. NixOS now ships with CockroachDB 2.1.x as well,
-     on <literal>x86_64-linux</literal> and <literal>aarch64-linux</literal>.
+     available on <literal>x86_64-linux</literal> and
+     <literal>aarch64-linux</literal>.
     </para>
    </listitem>
   </itemizedlist>
@@ -116,9 +122,9 @@
    <listitem>
     <para>
      The <link xlink:href="https://duo.com/docs/duounix">PAM module for Duo
-     Security</link> has been enabled for use.  One can configure it using
+     Security</link> has been enabled for use. One can configure it using the
-     the <option>security.duosec</option> options along with the
+     <option>security.duosec</option> options along with the corresponding PAM
-     corresponding PAM option in
+     option in
      <option>security.pam.services.&lt;name?&gt;.duoSecurity.enable</option>.
     </para>
    </listitem>
@@ -184,16 +190,18 @@
    </listitem>
    <listitem>
     <para>
-      The <varname>buildPythonPackage</varname> function now sets <varname>strictDeps = true</varname>
+     The <varname>buildPythonPackage</varname> function now sets
-      to help distinguish between native and non-native dependencies in order to
+     <varname>strictDeps = true</varname> to help distinguish between native
-      improve cross-compilation compatibility. Note however that this may break
+     and non-native dependencies in order to improve cross-compilation
-      user expressions.
+     compatibility. Note however that this may break user expressions.
     </para>
    </listitem>
    <listitem>
     <para>
-      The <varname>buildPythonPackage</varname> function now sets <varname>LANG = C.UTF-8</varname>
+     The <varname>buildPythonPackage</varname> function now sets <varname>LANG
-      to enable Unicode support. The <varname>glibcLocales</varname> package is no longer needed as a build input.
+     = C.UTF-8</varname> to enable Unicode support. The
+     <varname>glibcLocales</varname> package is no longer needed as a build
+     input.
     </para>
    </listitem>
    <listitem>
@@ -201,19 +209,18 @@
      The Syncthing state and configuration data has been moved from
      <varname>services.syncthing.dataDir</varname> to the newly defined
      <varname>services.syncthing.configDir</varname>, which default to
-      <literal>/var/lib/syncthing/.config/syncthing</literal>.
+     <literal>/var/lib/syncthing/.config/syncthing</literal>. This change makes
-      This change makes possible to share synced directories using ACLs
+     possible to share synced directories using ACLs without Syncthing
-      without Syncthing resetting the permission on every start.
+     resetting the permission on every start.
     </para>
    </listitem>
    <listitem>
     <para>
-      The <literal>ntp</literal> module now has sane default restrictions.
+     The <literal>ntp</literal> module now has sane default restrictions. If
-      If you're relying on the previous defaults, which permitted all queries
+     you're relying on the previous defaults, which permitted all queries and
-      and commands from all firewall-permitted sources, you can set
+     commands from all firewall-permitted sources, you can set
      <varname>services.ntp.restrictDefault</varname> and
-      <varname>services.ntp.restrictSource</varname> to
+     <varname>services.ntp.restrictSource</varname> to <literal>[]</literal>.
-      <literal>[]</literal>.
     </para>
    </listitem>
    <listitem>
@@ -242,16 +249,20 @@
    <listitem>
     <para>
      Options
-      <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal> and
+     <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal>
+     and
      <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.modulePackages</literal>
-      were removed. They were never used for anything and can therefore safely be removed.
+     were removed. They were never used for anything and can therefore safely
+     be removed.
     </para>
    </listitem>
    <listitem>
     <para>
-     Package <literal>wasm</literal> has been renamed <literal>proglodyte-wasm</literal>. The package
+     Package <literal>wasm</literal> has been renamed
-     <literal>wasm</literal> will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so
+     <literal>proglodyte-wasm</literal>. The package <literal>wasm</literal>
-     make sure to update your configuration if you want to keep <literal>proglodyte-wasm</literal>
+     will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so make
+     sure to update your configuration if you want to keep
+     <literal>proglodyte-wasm</literal>
     </para>
    </listitem>
    <listitem>
@@ -279,37 +290,41 @@
    </listitem>
    <listitem>
     <para>
-     Package <literal>consul-ui</literal> and passthrough <literal>consul.ui</literal> have been removed.
+     Package <literal>consul-ui</literal> and passthrough
-     The package <literal>consul</literal> now uses upstream releases that vendor the UI into the binary.
+     <literal>consul.ui</literal> have been removed. The package
-     See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/48714#issuecomment-433454834">#48714</link>
+     <literal>consul</literal> now uses upstream releases that vendor the UI
+     into the binary. See
+     <link xlink:href="https://github.com/NixOS/nixpkgs/pull/48714#issuecomment-433454834">#48714</link>
      for details.
     </para>
    </listitem>
    <listitem>
     <para>
      Slurm introduces the new option
-      <literal>services.slurm.stateSaveLocation</literal>,
+     <literal>services.slurm.stateSaveLocation</literal>, which is now set to
-      which is now set to <literal>/var/spool/slurm</literal> by default
+     <literal>/var/spool/slurm</literal> by default (instead of
-      (instead of <literal>/var/spool</literal>).
+     <literal>/var/spool</literal>). Make sure to move all files to the new
-      Make sure to move all files to the new directory or to set the option accordingly.
+     directory or to set the option accordingly.
     </para>
     <para>
-      The slurmctld now runs as user <literal>slurm</literal> instead of <literal>root</literal>.
+     The slurmctld now runs as user <literal>slurm</literal> instead of
-      If you want to keep slurmctld running as <literal>root</literal>, set
+     <literal>root</literal>. If you want to keep slurmctld running as
-      <literal>services.slurm.user = root</literal>.
+     <literal>root</literal>, set <literal>services.slurm.user =
+     root</literal>.
     </para>
     <para>
      The options <literal>services.slurm.nodeName</literal> and
-      <literal>services.slurm.partitionName</literal> are now sets of
+     <literal>services.slurm.partitionName</literal> are now sets of strings to
-      strings to correctly reflect that fact that each of these
+     correctly reflect that fact that each of these options can occour more
-      options can occour more than once in the configuration.
+     than once in the configuration.
     </para>
    </listitem>
    <listitem>
     <para>
-      The <literal>solr</literal> package has been upgraded from 4.10.3 to 7.5.0 and has undergone
+     The <literal>solr</literal> package has been upgraded from 4.10.3 to 7.5.0
-      some major changes. The <literal>services.solr</literal> module has been updated to reflect
+     and has undergone some major changes. The <literal>services.solr</literal>
-      these changes. Please review http://lucene.apache.org/solr/ carefully before upgrading.
+     module has been updated to reflect these changes. Please review
+     http://lucene.apache.org/solr/ carefully before upgrading.
     </para>
    </listitem>
    <listitem>
@@ -321,21 +336,24 @@
    </listitem>
    <listitem>
     <para>
-     The option <literal>services.xserver.displayManager.job.logToFile</literal> which was
+     The option
+     <literal>services.xserver.displayManager.job.logToFile</literal> which was
      previously set to <literal>true</literal> when using the display managers
-     <literal>lightdm</literal>, <literal>sddm</literal> or <literal>xpra</literal> has been
+     <literal>lightdm</literal>, <literal>sddm</literal> or
-     reset to the default value (<literal>false</literal>).
+     <literal>xpra</literal> has been reset to the default value
+     (<literal>false</literal>).
     </para>
    </listitem>
    <listitem>
     <para>
      Network interface indiscriminate NixOS firewall options
-     (<literal>networking.firewall.allow*</literal>) are now preserved when also
+     (<literal>networking.firewall.allow*</literal>) are now preserved when
-     setting interface specific rules such as <literal>networking.firewall.interfaces.en0.allow*</literal>.
+     also setting interface specific rules such as
-     These rules continue to use the pseudo device "default"
+     <literal>networking.firewall.interfaces.en0.allow*</literal>. These rules
-     (<literal>networking.firewall.interfaces.default.*</literal>), and assigning
+     continue to use the pseudo device "default"
-     to this pseudo device will override the (<literal>networking.firewall.allow*</literal>)
+     (<literal>networking.firewall.interfaces.default.*</literal>), and
-     options.
+     assigning to this pseudo device will override the
+     (<literal>networking.firewall.allow*</literal>) options.
     </para>
    </listitem>
    <listitem>
@@ -348,19 +366,19 @@
      <literal>DynamicUser=</literal> in systemd services. This was already the
      default behaviour in presence of <literal>services.sssd.enable =
      true</literal> because nscd caching would interfere with
-     <literal>sssd</literal> in unpredictable ways as well.  Because we're
+     <literal>sssd</literal> in unpredictable ways as well. Because we're using
-     using nscd not for caching, but for convincing glibc to find NSS modules
+     nscd not for caching, but for convincing glibc to find NSS modules in the
-     in the nix store instead of an absolute path, we have decided to disable
+     nix store instead of an absolute path, we have decided to disable caching
-     caching globally now, as it's usually not the behaviour the user wants and
+     globally now, as it's usually not the behaviour the user wants and can
-     can lead to surprising behaviour.  Furthermore, negative caching of host
+     lead to surprising behaviour. Furthermore, negative caching of host
      lookups is also disabled now by default. This should fix the issue of dns
      lookups failing in the presence of an unreliable network.
     </para>
     <para>
-     If the old behaviour is desired, this can be restored by setting
+     If the old behaviour is desired, this can be restored by setting the
-     the <literal>services.nscd.config</literal> option
+     <literal>services.nscd.config</literal> option with the desired caching
-     with the desired caching parameters.
+     parameters.
-     <programlisting>
+<programlisting>
      services.nscd.config =
      ''
      server-user             nscd
@@ -393,7 +411,8 @@
      shared                  hosts           yes
      '';
      </programlisting>
-     See <link xlink:href="https://github.com/NixOS/nixpkgs/pull/50316">#50316</link>
+     See
+     <link xlink:href="https://github.com/NixOS/nixpkgs/pull/50316">#50316</link>
      for details.
     </para>
    </listitem>
@@ -416,74 +435,85 @@
      The <literal>pam_unix</literal> account module is now loaded with its
      control field set to <literal>required</literal> instead of
      <literal>sufficient</literal>, so that later PAM account modules that
-     might do more extensive checks are being executed.
+     might do more extensive checks are being executed. Previously, the whole
-     Previously, the whole account module verification was exited prematurely
+     account module verification was exited prematurely in case a nss module
-     in case a nss module provided the account name to
+     provided the account name to <literal>pam_unix</literal>. The LDAP and
-     <literal>pam_unix</literal>.
+     SSSD NixOS modules already add their NSS modules when enabled. In case
-     The LDAP and SSSD NixOS modules already add their NSS modules when
+     your setup breaks due to some later PAM account module previosuly
-     enabled. In case your setup breaks due to some later PAM account module
+     shadowed, or failing NSS lookups, please file a bug. You can get back the
-     previosuly shadowed, or failing NSS lookups, please file a bug. You can
+     old behaviour by manually setting <literal>
-     get back the old behaviour by manually setting
+<![CDATA[security.pam.services.<name?>.text]]>
-     <literal><![CDATA[security.pam.services.<name?>.text]]></literal>.
+     </literal>.
     </para>
    </listitem>
    <listitem>
     <para>
      The <literal>pam_unix</literal> password module is now loaded with its
      control field set to <literal>sufficient</literal> instead of
-     <literal>required</literal>, so that password managed only
+     <literal>required</literal>, so that password managed only by later PAM
-     by later PAM password modules are being executed.
+     password modules are being executed. Previously, for example, changing an
-     Previously, for example, changing an LDAP account's password through PAM
+     LDAP account's password through PAM was not possible: the whole password
-     was not possible: the whole password module verification
+     module verification was exited prematurely by <literal>pam_unix</literal>,
-     was exited prematurely by <literal>pam_unix</literal>,
+     preventing <literal>pam_ldap</literal> to manage the password as it
-     preventing <literal>pam_ldap</literal> to manage the password as it should.
+     should.
     </para>
    </listitem>
    <listitem>
     <para>
-     <literal>fish</literal> has been upgraded to 3.0.
+     <literal>fish</literal> has been upgraded to 3.0. It comes with a number
-     It comes with a number of improvements and backwards incompatible changes.
+     of improvements and backwards incompatible changes. See the
-     See the <literal>fish</literal> <link xlink:href="https://github.com/fish-shell/fish-shell/releases/tag/3.0.0">release notes</link> for more information.
+     <literal>fish</literal>
+     <link xlink:href="https://github.com/fish-shell/fish-shell/releases/tag/3.0.0">release
+     notes</link> for more information.
     </para>
    </listitem>
    <listitem>
     <para>
      The ibus-table input method has had a change in config format, which
      causes all previous settings to be lost. See
-      <link xlink:href="https://github.com/mike-fabian/ibus-table/commit/f9195f877c5212fef0dfa446acb328c45ba5852b">this commit message</link>
+     <link xlink:href="https://github.com/mike-fabian/ibus-table/commit/f9195f877c5212fef0dfa446acb328c45ba5852b">this
-      for details.
+     commit message</link> for details.
     </para>
    </listitem>
    <listitem>
     <para>
      NixOS module system type <literal>types.optionSet</literal> and
-    <literal>lib.mkOption</literal> argument <literal>options</literal> are deprecated.
+     <literal>lib.mkOption</literal> argument <literal>options</literal> are
-    Use <literal>types.submodule</literal> instead.
+     deprecated. Use <literal>types.submodule</literal> instead.
      (<link xlink:href="https://github.com/NixOS/nixpkgs/pull/54637">#54637</link>)
     </para>
    </listitem>
    <listitem>
     <para>
-    <literal>matrix-synapse</literal> has been updated to version 0.99. It will
+     <literal>matrix-synapse</literal> has been updated to version 0.99. It
-    <link xlink:href="https://github.com/matrix-org/synapse/pull/4509">no longer generate a self-signed certificate on first launch</link>
+     will <link xlink:href="https://github.com/matrix-org/synapse/pull/4509">no
-    and will be <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the last version to accept self-signed certificates</link>.
+     longer generate a self-signed certificate on first launch</link> and will
-    As such, it is now recommended to use a proper certificate verified by a
+     be
-    root CA (for example Let's Encrypt).
+     <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the
-    The new <link linkend="module-services-matrix">manual chapter on Matrix</link> contains a working example of using nginx as a reverse proxy
+     last version to accept self-signed certificates</link>. As such, it is now
-    in front of <literal>matrix-synapse</literal>, using Let's Encrypt certificates.
+     recommended to use a proper certificate verified by a root CA (for example
+     Let's Encrypt). The new <link linkend="module-services-matrix">manual
+     chapter on Matrix</link> contains a working example of using nginx as a
+     reverse proxy in front of <literal>matrix-synapse</literal>, using Let's
+     Encrypt certificates.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>mailutils</literal> now works by default when
      <literal>sendmail</literal> is not in a setuid wrapper. As a consequence,
-     the <literal>sendmailPath</literal> argument, having lost its main use, has
+     the <literal>sendmailPath</literal> argument, having lost its main use,
-     been removed.
+     has been removed.
     </para>
    </listitem>
    <listitem>
     <para>
-     <literal>graylog</literal> has been upgraded from version 2.* to 3.*. Some setups making use of extraConfig (especially those exposing Graylog via reverse proxies) need to be updated as upstream removed/replaced some settings. See <link xlink:href="http://docs.graylog.org/en/3.0/pages/upgrade/graylog-3.0.html#simplified-http-interface-configuration">Upgrading Graylog</link> for details.
+     <literal>graylog</literal> has been upgraded from version 2.* to 3.*. Some
+     setups making use of extraConfig (especially those exposing Graylog via
+     reverse proxies) need to be updated as upstream removed/replaced some
+     settings. See
+     <link xlink:href="http://docs.graylog.org/en/3.0/pages/upgrade/graylog-3.0.html#simplified-http-interface-configuration">Upgrading
+     Graylog</link> for details.
     </para>
    </listitem>
   </itemizedlist>
@@ -500,163 +530,174 @@
    <listitem>
     <para>
      The <option>services.matomo</option> module gained the option
-     <option>services.matomo.package</option> which determines the used
+     <option>services.matomo.package</option> which determines the used Matomo
-     Matomo version.
+     version.
     </para>
     <para>
-     The Matomo module now also comes with the systemd service <literal>matomo-archive-processing.service</literal>
+     The Matomo module now also comes with the systemd service
-     and a timer that automatically triggers archive processing every hour.
+     <literal>matomo-archive-processing.service</literal> and a timer that
-     This means that you can safely
+     automatically triggers archive processing every hour. This means that you
+     can safely
      <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour">
-      disable browser triggers for Matomo archiving
+     disable browser triggers for Matomo archiving </link> at
-     </link> at <literal>Administration > System > General Settings</literal>.
+     <literal>Administration > System > General Settings</literal>.
     </para>
     <para>
      Additionally, you can enable to
      <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs">
-      delete old visitor logs
+     delete old visitor logs </link> at <literal>Administration > System >
-     </link> at <literal>Administration > System > Privacy</literal>,
+     Privacy</literal>, but make sure that you run <literal>systemctl start
-     but make sure that you run <literal>systemctl start matomo-archive-processing.service</literal>
+     matomo-archive-processing.service</literal> at least once without errors
-     at least once without errors if you have already collected data before,
+     if you have already collected data before, so that the reports get
-     so that the reports get archived before the source data gets deleted.
+     archived before the source data gets deleted.
     </para>
    </listitem>
    <listitem>
     <para>
-     <literal>composableDerivation</literal> along with supporting library functions
+     <literal>composableDerivation</literal> along with supporting library
-     has been removed.
+     functions has been removed.
     </para>
    </listitem>
    <listitem>
     <para>
-     The deprecated <literal>truecrypt</literal> package has been removed
+     The deprecated <literal>truecrypt</literal> package has been removed and
-     and <literal>truecrypt</literal> attribute is now an alias for
+     <literal>truecrypt</literal> attribute is now an alias for
      <literal>veracrypt</literal>. VeraCrypt is backward-compatible with
-     TrueCrypt volumes. Note that <literal>cryptsetup</literal> also
+     TrueCrypt volumes. Note that <literal>cryptsetup</literal> also supports
-     supports loading TrueCrypt volumes.
+     loading TrueCrypt volumes.
     </para>
    </listitem>
    <listitem>
     <para>
-      The Kubernetes DNS addons, kube-dns, has been replaced with CoreDNS.
+     The Kubernetes DNS addons, kube-dns, has been replaced with CoreDNS. This
-      This change is made in accordance with Kubernetes making CoreDNS the official default
+     change is made in accordance with Kubernetes making CoreDNS the official
-      starting from
+     default starting from
-      <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#sig-cluster-lifecycle">Kubernetes v1.11</link>.
+     <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#sig-cluster-lifecycle">Kubernetes
-      Please beware that upgrading DNS-addon on existing clusters might induce
+     v1.11</link>. Please beware that upgrading DNS-addon on existing clusters
-      minor downtime while the DNS-addon terminates and re-initializes.
+     might induce minor downtime while the DNS-addon terminates and
-      Also note that the DNS-service now runs with 2 pod replicas by default.
+     re-initializes. Also note that the DNS-service now runs with 2 pod
-      The desired number of replicas can be configured using:
+     replicas by default. The desired number of replicas can be configured
-      <option>services.kubernetes.addons.dns.replicas</option>.
+     using: <option>services.kubernetes.addons.dns.replicas</option>.
     </para>
    </listitem>
    <listitem>
     <para>
-       The quassel-webserver package and module was removed from nixpkgs due to the lack
+     The quassel-webserver package and module was removed from nixpkgs due to
-       of maintainers.
+     the lack of maintainers.
     </para>
    </listitem>
    <listitem>
     <para>
-     The manual gained a
+     The manual gained a <link linkend="module-services-matrix"> new chapter on
-     <link linkend="module-services-matrix">
+     self-hosting <literal>matrix-synapse</literal> and
-      new chapter on self-hosting <literal>matrix-synapse</literal> and <literal>riot-web</literal>
+     <literal>riot-web</literal> </link>, the most prevalent server and client
-     </link>, the most prevalent server and client implementations for the
+     implementations for the
-     <link xlink:href="https://matrix.org/">Matrix</link> federated communication network.
+     <link xlink:href="https://matrix.org/">Matrix</link> federated
+     communication network.
     </para>
    </listitem>
    <listitem>
     <para>
-       The astah-community package was removed from nixpkgs due to it being discontinued and the downloads not being available anymore.
+     The astah-community package was removed from nixpkgs due to it being
+     discontinued and the downloads not being available anymore.
     </para>
    </listitem>
    <listitem>
     <para>
-       The httpd service now saves log files with a .log file extension by default for
+     The httpd service now saves log files with a .log file extension by
-       easier integration with the logrotate service.
+     default for easier integration with the logrotate service.
     </para>
    </listitem>
    <listitem>
     <para>
-       The owncloud server packages and httpd subservice module were removed
+     The owncloud server packages and httpd subservice module were removed from
-       from nixpkgs due to the lack of maintainers.
+     nixpkgs due to the lack of maintainers.
     </para>
    </listitem>
    <listitem>
     <para>
-       It is possible now to uze ZRAM devices as general purpose ephemeral block devices,
+     It is possible now to uze ZRAM devices as general purpose ephemeral block
-       not only as swap. Using more than 1 device as ZRAM swap is no longer recommended,
+     devices, not only as swap. Using more than 1 device as ZRAM swap is no
-       but is still possible by setting <literal>zramSwap.swapDevices</literal> explicitly.
+     longer recommended, but is still possible by setting
+     <literal>zramSwap.swapDevices</literal> explicitly.
     </para>
     <para>
      ZRAM algorithm can be changed now.
     </para>
     <para>
-      Changes to ZRAM algorithm are applied during <literal>nixos-rebuild switch</literal>,
+     Changes to ZRAM algorithm are applied during <literal>nixos-rebuild
-      so make sure you have enough swap space on disk to survive ZRAM device rebuild. Alternatively,
+     switch</literal>, so make sure you have enough swap space on disk to
-      use <literal>nixos-rebuild boot; reboot</literal>.
+     survive ZRAM device rebuild. Alternatively, use <literal>nixos-rebuild
+     boot; reboot</literal>.
     </para>
    </listitem>
    <listitem>
     <para>
-      Flat volumes are now disabled by default in <literal>hardware.pulseaudio</literal>.
+     Flat volumes are now disabled by default in
-      This has been done to prevent applications, which are unaware of this feature, setting
+     <literal>hardware.pulseaudio</literal>. This has been done to prevent
-      their volumes to 100% on startup causing harm to your audio hardware and potentially your ears.
+     applications, which are unaware of this feature, setting their volumes to
+     100% on startup causing harm to your audio hardware and potentially your
+     ears.
     </para>
     <note>
      <para>
-      With this change application specific volumes are relative to the master volume which can be
+      With this change application specific volumes are relative to the master
-      adjusted independently, whereas before they were absolute; meaning that in effect, it scaled the
+      volume which can be adjusted independently, whereas before they were
-      device-volume with the volume of the loudest application.
+      absolute; meaning that in effect, it scaled the device-volume with the
+      volume of the loudest application.
      </para>
     </note>
    </listitem>
    <listitem>
     <para>
-     The <link xlink:href="https://github.com/DanielAdolfsson/ndppd"><literal>ndppd</literal></link> module
+     The
-     now supports <link linkend="opt-services.ndppd.enable">all config options</link> provided by the current
+     <link xlink:href="https://github.com/DanielAdolfsson/ndppd"><literal>ndppd</literal></link>
-     upstream version as service options. Additionally the <literal>ndppd</literal> package doesn't contain
+     module now supports <link linkend="opt-services.ndppd.enable">all config
-     the systemd unit configuration from upstream anymore, the unit is completely configured by the NixOS module now.
+     options</link> provided by the current upstream version as service
+     options. Additionally the <literal>ndppd</literal> package doesn't contain
+     the systemd unit configuration from upstream anymore, the unit is
+     completely configured by the NixOS module now.
     </para>
    </listitem>
    <listitem>
     <para>
-     New installs of NixOS will default to the Redmine 4.x series unless otherwise specified in
+     New installs of NixOS will default to the Redmine 4.x series unless
-     <literal>services.redmine.package</literal> while existing installs of NixOS will default to
+     otherwise specified in <literal>services.redmine.package</literal> while
-     the Redmine 3.x series.
+     existing installs of NixOS will default to the Redmine 3.x series.
     </para>
    </listitem>
    <listitem>
     <para>
-     The <link linkend="opt-services.grafana.enable">Grafana module</link> now supports declarative
+     The <link linkend="opt-services.grafana.enable">Grafana module</link> now
-     <link xlink:href="http://docs.grafana.org/administration/provisioning/">datasource and dashboard</link>
+     supports declarative
-     provisioning.
+     <link xlink:href="http://docs.grafana.org/administration/provisioning/">datasource
+     and dashboard</link> provisioning.
     </para>
    </listitem>
    <listitem>
     <para>
-       The use of insecure ports on kubernetes has been deprecated.
+     The use of insecure ports on kubernetes has been deprecated. Thus options:
-       Thus options:
      <varname>services.kubernetes.apiserver.port</varname> and
-       <varname>services.kubernetes.controllerManager.port</varname>
+     <varname>services.kubernetes.controllerManager.port</varname> has been
-       has been renamed to <varname>.insecurePort</varname>,
+     renamed to <varname>.insecurePort</varname>, and default of both options
-       and default of both options has changed to 0 (disabled).
+     has changed to 0 (disabled).
     </para>
    </listitem>
    <listitem>
     <para>
      Note that the default value of
-        <varname>services.kubernetes.apiserver.bindAddress</varname>
+     <varname>services.kubernetes.apiserver.bindAddress</varname> has changed
-        has changed from 127.0.0.1 to 0.0.0.0, allowing the apiserver to be
+     from 127.0.0.1 to 0.0.0.0, allowing the apiserver to be accessible from
-        accessible from outside the master node itself.
+     outside the master node itself. If the apiserver insecurePort is enabled,
-        If the apiserver insecurePort is enabled,
      it is strongly recommended to only bind on the loopback interface. See:
      <varname>services.kubernetes.apiserver.insecurebindAddress</varname>.
     </para>
    </listitem>
    <listitem>
     <para>
-        The option <varname>services.kubernetes.apiserver.allowPrivileged</varname>
+     The option
-        and <varname>services.kubernetes.kubelet.allowPrivileged</varname> now
+     <varname>services.kubernetes.apiserver.allowPrivileged</varname> and
+     <varname>services.kubernetes.kubelet.allowPrivileged</varname> now
      defaults to false. Disallowing privileged containers on the cluster.
     </para>
    </listitem>
@@ -668,32 +709,34 @@
    </listitem>
    <listitem>
     <para>
-        The <literal>intel</literal> driver has been removed from the default list of
+     The <literal>intel</literal> driver has been removed from the default list
-        <link linkend="opt-services.xserver.videoDrivers">X.org video drivers</link>.
+     of <link linkend="opt-services.xserver.videoDrivers">X.org video
-        The <literal>modesetting</literal> driver should take over automatically,
+     drivers</link>. The <literal>modesetting</literal> driver should take over
-        it is better maintained upstream and has less problems with advanced X11 features.
+     automatically, it is better maintained upstream and has less problems with
-        This can lead to a change in the output names used by <literal>xrandr</literal>.
+     advanced X11 features. This can lead to a change in the output names used
-        Some performance regressions on some GPU models might happen.
+     by <literal>xrandr</literal>. Some performance regressions on some GPU
-        Some OpenCL and VA-API applications might also break
+     models might happen. Some OpenCL and VA-API applications might also break
      (Beignet seems to provide OpenCL support with
-        <literal>modesetting</literal> driver, too).
+     <literal>modesetting</literal> driver, too). Kernel mode setting API does
-        Kernel mode setting API does not support backlight control,
+     not support backlight control, so <literal>xbacklight</literal> tool will
-        so <literal>xbacklight</literal> tool will not work;
+     not work; backlight level can be controlled directly via
-        backlight level can be controlled directly via <literal>/sys/</literal>
+     <literal>/sys/</literal> or with <literal>brightnessctl</literal>. Users
-        or with <literal>brightnessctl</literal>.
+     who need this functionality more than multi-output XRandR are advised to
-        Users who need this functionality more than multi-output XRandR are advised
+     add `intel` to `videoDrivers` and report an issue (or provide additional
-        to add `intel` to `videoDrivers` and report an issue (or provide additional
      details in an existing one)
     </para>
    </listitem>
    <listitem>
     <para>
-       Openmpi has been updated to version 4.0.0, which removes some deprecated MPI-1 symbols.
+     Openmpi has been updated to version 4.0.0, which removes some deprecated
-       This may break some older applications that still rely on those symbols.
+     MPI-1 symbols. This may break some older applications that still rely on
-       An upgrade guide can be found <link xlink:href="https://www.open-mpi.org/faq/?category=mpi-removed">here</link>.
+     those symbols. An upgrade guide can be found
+     <link xlink:href="https://www.open-mpi.org/faq/?category=mpi-removed">here</link>.
     </para>
     <para>
-     The nginx package now relies on OpenSSL 1.1 and supports TLS 1.3 by default. You can set the protocols used by the nginx service using <xref linkend="opt-services.nginx.sslProtocols"/>.
+     The nginx package now relies on OpenSSL 1.1 and supports TLS 1.3 by
+     default. You can set the protocols used by the nginx service using
+     <xref linkend="opt-services.nginx.sslProtocols"/>.
     </para>
    </listitem>
    <listitem>

nixos/doc/manual/release-notes/rl-1909.xml

@@ -53,14 +53,17 @@
    <listitem>
     <para>
      The <option>documentation</option> module gained an option named
-     <option>documentation.nixos.includeAllModules</option> which makes the generated
+     <option>documentation.nixos.includeAllModules</option> which makes the
-     <citerefentry><refentrytitle>configuration.nix</refentrytitle>
+     generated <citerefentry>
-     <manvolnum>5</manvolnum></citerefentry> manual page include all options from all NixOS modules
+     <refentrytitle>configuration.nix</refentrytitle>
-     included in a given <literal>configuration.nix</literal> configuration file. Currently, it is
+     <manvolnum>5</manvolnum></citerefentry> manual page include all options
-     set to <literal>false</literal> by default as enabling it frequently prevents evaluation. But
+     from all NixOS modules included in a given
-     the plan is to eventually have it set to <literal>true</literal> by default. Please set it to
+     <literal>configuration.nix</literal> configuration file. Currently, it is
-     <literal>true</literal> now in your <literal>configuration.nix</literal> and fix all the bugs
+     set to <literal>false</literal> by default as enabling it frequently
-     it uncovers.
+     prevents evaluation. But the plan is to eventually have it set to
+     <literal>true</literal> by default. Please set it to
+     <literal>true</literal> now in your <literal>configuration.nix</literal>
+     and fix all the bugs it uncovers.
     </para>
    </listitem>
   </itemizedlist>

nixos/modules/programs/zsh/oh-my-zsh.xml

@@ -87,9 +87,9 @@
 
   <para>
    <emphasis>Please keep in mind that this is not compatible with
-   <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable store
+   <literal>programs.zsh.ohMyZsh.custom</literal> as it requires an immutable
-   path while <literal>custom</literal> shall remain mutable! An evaluation
+   store path while <literal>custom</literal> shall remain mutable! An
-   failure will be thrown if both <literal>custom</literal> and
+   evaluation failure will be thrown if both <literal>custom</literal> and
    <literal>customPkgs</literal> are set.</emphasis>
   </para>
  </section>

nixos/modules/services/web-apps/matomo-doc.xml

@@ -12,15 +12,15 @@
   An automatic setup is not suported by Matomo, so you need to configure Matomo
   itself in the browser-based Matomo setup.
  </para>
-
  <section xml:id="module-services-matomo-database-setup">
   <title>Database Setup</title>
+
   <para>
    You also need to configure a MariaDB or MySQL database and -user for Matomo
    yourself, and enter those credentials in your browser. You can use
    passwordless database authentication via the UNIX_SOCKET authentication
    plugin with the following SQL commands:
-   <programlisting>
+<programlisting>
         # For MariaDB
         INSTALL PLUGIN unix_socket SONAME 'auth_socket';
         CREATE DATABASE matomo;
@@ -46,30 +46,32 @@
    database is not on the same host.
   </para>
  </section>
-
  <section xml:id="module-services-matomo-archive-processing">
   <title>Archive Processing</title>
+
   <para>
-   This module comes with the systemd service <literal>matomo-archive-processing.service</literal>
+   This module comes with the systemd service
-   and a timer that automatically triggers archive processing every hour.
+   <literal>matomo-archive-processing.service</literal> and a timer that
-   This means that you can safely
+   automatically triggers archive processing every hour. This means that you
+   can safely
    <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour">
-    disable browser triggers for Matomo archiving
+   disable browser triggers for Matomo archiving </link> at
-   </link> at <literal>Administration > System > General Settings</literal>.
+   <literal>Administration > System > General Settings</literal>.
   </para>
+
   <para>
    With automatic archive processing, you can now also enable to
    <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs">
-    delete old visitor logs
+   delete old visitor logs </link> at <literal>Administration > System >
-   </link> at <literal>Administration > System > Privacy</literal>,
+   Privacy</literal>, but make sure that you run <literal>systemctl start
-   but make sure that you run <literal>systemctl start matomo-archive-processing.service</literal>
+   matomo-archive-processing.service</literal> at least once without errors if
-   at least once without errors if you have already collected data before,
+   you have already collected data before, so that the reports get archived
-   so that the reports get archived before the source data gets deleted.
+   before the source data gets deleted.
   </para>
  </section>
-
  <section xml:id="module-services-matomo-backups">
   <title>Backup</title>
+
   <para>
    You only need to take backups of your MySQL database and the
    <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user
@@ -78,9 +80,9 @@
    <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />.
   </para>
  </section>
-
  <section xml:id="module-services-matomo-issues">
   <title>Issues</title>
+
   <itemizedlist>
    <listitem>
     <para>
@@ -97,7 +99,6 @@
    </listitem>
   </itemizedlist>
  </section>
-
  <section xml:id="module-services-matomo-other-web-servers">
   <title>Using other Web Servers than nginx</title>
 

nixos/modules/services/web-apps/nextcloud.xml

@@ -4,22 +4,24 @@
          version="5.0"
          xml:id="module-services-nextcloud">
  <title>Nextcloud</title>
-
  <para>
-  <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source, self-hostable cloud
+  <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an open-source,
-  platform. The server setup can be automated using
+  self-hostable cloud platform. The server setup can be automated using
-  <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A desktop client is packaged
+  <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. A
-  at <literal>pkgs.nextcloud-client</literal>.
+  desktop client is packaged at <literal>pkgs.nextcloud-client</literal>.
  </para>
-
  <section xml:id="module-services-nextcloud-basic-usage">
   <title>Basic usage</title>
+
   <para>
    Nextcloud is a PHP-based application which requires an HTTP server
-   (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal> optionally supports
+   (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal>
-   <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>) and a database
+   optionally supports
-   (it's recommended to use <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).
+   <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>)
+   and a database (it's recommended to use
+   <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).
   </para>
+
   <para>
    A very basic configuration may look like this:
 <programlisting>{ pkgs, ... }:
@@ -55,13 +57,17 @@
   <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];
 }</programlisting>
   </para>
+
   <para>
-   The options <literal>hostName</literal> and <literal>nginx.enable</literal> are used internally to configure an
+   The options <literal>hostName</literal> and <literal>nginx.enable</literal>
-   HTTP server using <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal> and <literal>nginx</literal>.
+   are used internally to configure an HTTP server using
-   The <literal>config</literal> attribute set is used for the <literal>config.php</literal> which is used
+   <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal>
-   for the application's configuration.
+   and <literal>nginx</literal>. The <literal>config</literal> attribute set is
-   <emphasis>Beware: this isn't entirely pure since the config is modified by the application's runtime!</emphasis>
+   used for the <literal>config.php</literal> which is used for the
+   application's configuration. <emphasis>Beware: this isn't entirely pure
+   since the config is modified by the application's runtime!</emphasis>
   </para>
+
   <para>
    In case the application serves multiple hosts (those are checked with
    <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>)
@@ -69,31 +75,41 @@
    <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.
   </para>
  </section>
-
  <section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
   <title>Pitfalls</title>
+
   <para>
-   Unfortunately Nextcloud appears to be very stateful when it comes to managing its own configuration. The
+   Unfortunately Nextcloud appears to be very stateful when it comes to
-   config file lives in the home directory of the <literal>nextcloud</literal> user (by default
+   managing its own configuration. The config file lives in the home directory
-   <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to track several
+   of the <literal>nextcloud</literal> user (by default
-   states of the application (e.g. whether installed or not).
+   <literal>/var/lib/nextcloud/config/config.php</literal>) and is also used to
+   track several states of the application (e.g. whether installed or not).
   </para>
+
   <para>
-   Right now changes to the <literal>services.nextcloud.config</literal> attribute set won't take effect
+   Right now changes to the <literal>services.nextcloud.config</literal>
-   after the first install
+   attribute set won't take effect after the first install (except
-   (except <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>) since the actual configuration
+   <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>)
-   file is generated by the NextCloud installer which also sets up critical parts such as the database
+   since the actual configuration file is generated by the NextCloud installer
-   structure.
+   which also sets up critical parts such as the database structure.
   </para>
+
   <para>
-   <emphasis>Warning: don't delete <literal>config.php</literal>! This file tracks the application's state and a deletion can cause unwanted side-effects!</emphasis>
+   <emphasis>Warning: don't delete <literal>config.php</literal>! This file
+   tracks the application's state and a deletion can cause unwanted
+   side-effects!</emphasis>
   </para>
+
   <para>
-   <emphasis>Warning: don't rerun <literal>nextcloud-occ maintenance:install</literal>! This command tries to install the application and can cause unwanted side-effects!</emphasis>
+   <emphasis>Warning: don't rerun <literal>nextcloud-occ
+   maintenance:install</literal>! This command tries to install the application
+   and can cause unwanted side-effects!</emphasis>
   </para>
+
   <para>
-    The issues are known and reported in <link xlink:href="https://github.com/NixOS/nixpkgs/issues/49783">#49783</link>, for now it's unfortunately necessary to manually work around these issues.
+   The issues are known and reported in
+   <link xlink:href="https://github.com/NixOS/nixpkgs/issues/49783">#49783</link>,
+   for now it's unfortunately necessary to manually work around these issues.
   </para>
  </section>
-
 </chapter>

nixos/tests/common/webroot/news-rss.xml

@@ -1,7 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<rss xmlns:blogChannel="http://backend.userland.com/blogChannelModule" version="2.0"><channel><title>NixOS News</title><link>https://nixos.org</link><description>News for NixOS, the purely functional Linux distribution.</description><image><title>NixOS</title><url>https://nixos.org/logo/nixos-logo-only-hires.png</url><link>https://nixos.org/</link></image><item><title>
+<rss xmlns:blogChannel="http://backend.userland.com/blogChannelModule" version="2.0">
-      NixOS 18.09 released
+ <channel>
-    </title><link>https://nixos.org/news.html</link><description>
+  <title>NixOS News</title><link>https://nixos.org</link>
+  <description>News for NixOS, the purely functional Linux distribution.</description>
+  <image>
+   <title>NixOS</title>
+   <url>https://nixos.org/logo/nixos-logo-only-hires.png</url><link>https://nixos.org/</link>
+  </image>
+  <item>
+   <title>NixOS 18.09 released</title><link>https://nixos.org/news.html</link>
+   <description>
     <a href="https://github.com/NixOS/nixos-artwork/blob/master/releases/18.09-jellyfish/jellyfish.png">
      <img class="inline" src="logo/nixos-logo-18.09-jellyfish-lores.png" alt="18.09 Jellyfish logo" with="100" height="87"/>
     </a>
@@ -12,4 +20,8 @@
       For information on how to upgrade from older release branches
       to 18.09, check out the
       <a href="/nixos/manual/index.html#sec-upgrading">manual section on upgrading</a>.
-    </description><pubDate>Sat Oct 06 2018 00:00:00 GMT</pubDate></item></channel></rss>
+    </description>
+   <pubDate>Sat Oct 06 2018 00:00:00 GMT</pubDate>
+  </item>
+ </channel>
+</rss>