Merge pull request #17195 from keszybz/man-cleanups

Man page cleanups

22 files changed, 186 insertions, 194 deletions

diff --git a/man/environment.d.xml b/man/environment.d.xml
index 0f53b0fef1..4db44616a7 100644
--- a/man/environment.d.xml
+++ b/man/environment.d.xml
@@ -76,7 +76,7 @@
         <title>Setup environment to allow access to a program installed in
         <filename index="false">/opt/foo</filename></title>
 
-        <para><filename>/etc/environment.d/60-foo.conf</filename>:
+        <para><filename index="false">/etc/environment.d/60-foo.conf</filename>:
         </para>
         <programlisting>
         FOO_DEBUG=force-software-gl,log-verbose
diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml
index d5899dc362..48114394c4 100644
--- a/man/file-hierarchy.xml
+++ b/man/file-hierarchy.xml
@@ -603,13 +603,12 @@
   <refsect1>
     <title>System Packages</title>
 
-    <para>Developers of system packages should follow strict rules
-    when placing their own files in the file system. The following
-    table lists recommended locations for specific types of files
-    supplied by the vendor.</para>
+    <para>Developers of system packages should follow strict rules when placing their files in the file
+    system. The following table lists recommended locations for specific types of files supplied by the
+    vendor.</para>
 
     <table>
-      <title>System Package Vendor Files Locations</title>
+      <title>System package vendor files locations</title>
       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
         <colspec colname="directory" />
         <colspec colname="purpose" />
@@ -648,11 +647,11 @@
     <filename>/usr/share/</filename> hierarchy to the locations
     defined by the various relevant specifications.</para>
 
-    <para>During runtime, and for local configuration and runtime state,
-    additional directories are defined:</para>
+    <para>The following directories shall be used by the package for local configuration and files created
+    during runtime:</para>
 
     <table>
-      <title>System Package Variable Files Locations</title>
+      <title>System package variable files locations</title>
       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
         <colspec colname="directory" />
         <colspec colname="purpose" />
@@ -699,16 +698,13 @@
   <refsect1>
     <title>User Packages</title>
 
-    <para>Programs running in user context should follow strict rules
-    when placing their own files in the user's home directory. The
-    following table lists recommended locations in the home directory
-    for specific types of files supplied by the vendor if the
-    application is installed in the home directory. (Note, however,
-    that user applications installed system-wide should follow the
-    rules outlined above regarding placing vendor files.)</para>
+    <para>Programs running in user context should follow strict rules when placing their own files in the
+    user's home directory. The following table lists recommended locations in the home directory for specific
+    types of files supplied by the vendor if the application is installed in the home directory. (User
+    applications installed system-wide are covered by the rules outlined above for vendor files.)</para>
 
     <table>
-      <title>User Package Vendor File Locations</title>
+      <title>Vendor package file locations under the home directory of the user</title>
       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
         <colspec colname="directory" />
         <colspec colname="purpose" />
@@ -725,7 +721,7 @@
           </row>
           <row>
       <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/</filename></entry>
-      <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
+      <entry>Public shared libraries of the package. As above, be careful with using overly generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
           </row>
           <row>
       <entry><filename>~/.local/lib/<replaceable>package</replaceable>/</filename></entry>
@@ -739,15 +735,15 @@
       </tgroup>
     </table>
 
-    <para>Additional static vendor files may be installed in the
-    <filename>~/.local/share/</filename> hierarchy to the locations
-    defined by the various relevant specifications.</para>
+    <para>Additional static vendor files may be installed in the <filename>~/.local/share/</filename>
+    hierarchy, mirroring the subdirectories specified in the section "Vendor-supplied operating system
+    resources" above.</para>
 
-    <para>During runtime, and for local configuration and state,
-    additional directories are defined:</para>
+    <para>The following directories shall be used by the package for per-user local configuration and files
+    created during runtime:</para>
 
     <table>
-      <title>User Package Variable File Locations</title>
+      <title>User package variable file locations</title>
       <tgroup cols='2' align='left' colsep='1' rowsep='1'>
         <colspec colname="directory" />
         <colspec colname="purpose" />
diff --git a/man/homectl.xml b/man/homectl.xml
index dd16e47beb..2ceb56e3f0 100644
--- a/man/homectl.xml
+++ b/man/homectl.xml
@@ -120,7 +120,7 @@
 
         <listitem><para>Read the user's JSON record from the specified file. If passed as
         <literal>-</literal> read the user record from standard input. The supplied JSON object must follow
-        the structure documented on <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink>.
+        the structure documented in <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink>.
         This option may be used in conjunction with the <command>create</command> and
         <command>update</command> commands (see below), where it allows configuring the user record in JSON
         as-is, instead of setting the individual user record properties (see below).</para></listitem>
@@ -299,11 +299,13 @@
       <varlistentry>
         <term><option>--timezone=</option><replaceable>TIMEZONE</replaceable></term>
 
-        <listitem><para>Takes a timezone specification as string that sets the timezone for the specified
-        user. Expects a `tzdata` location string. When the user logs in the <varname>$TZ</varname>
-        environment variable is initialized from this setting. Example:
-        <option>--timezone=Europe/Amsterdam</option> will result in the environment variable
-        <literal>TZ=:Europe/Amsterdam</literal>.</para></listitem>
+        <listitem><para>Takes a time zone location name that sets the timezone for the specified user. When
+        the user logs in the <varname>$TZ</varname> environment variable is initialized from this
+        setting. Example: <option>--timezone=Europe/Amsterdam</option> will result in the environment
+        variable <literal>TZ=:Europe/Amsterdam</literal>. (<literal>:</literal> is used intentionally as part
+        of the timezone specification, see
+        <citerefentry><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -419,7 +421,7 @@
 
         <listitem><para>Takes a password hint to store alongside the user record. This string is stored
         accessible only to privileged users and the user itself and may not be queried by other users.
-        Example: <option>--password-hint="My first pet's name"</option></para></listitem>
+        Example: <option>--password-hint="My first pet's name"</option>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml
index 70504510f9..d348795063 100644
--- a/man/sysctl.d.xml
+++ b/man/sysctl.d.xml
@@ -70,11 +70,11 @@ key.pattern.overridden.with.glob = custom
     followed by <literal>=</literal>, see SYNOPSIS.</para>
 
     <para>Any access permission errors and attempts to write variables not present on the local system are
-    logged at debug level and do not cause the service to fail. Moreover, if a variable assignment is
-    prefixed with a single <literal>-</literal> character, failure to set the variable for other reasons will
-    be logged at debug level and will not cause the service to fail. In other cases, errors when setting
-    variables are logged with higher priority and cause the service to return failure at the end (after
-    processing other variables).</para>
+    logged at debug level and do not cause the service to fail. Other types of errors when setting variables
+    are logged with higher priority and cause the service to return failure at the end (after processing
+    other variables). As an exception, if a variable assignment is prefixed with a single
+    <literal>-</literal> character, failure to set the variable for any reason will be logged at debug level
+    and will not cause the service to fail.</para>
 
     <para>The settings configured with <filename>sysctl.d</filename> files will be applied early on boot. The
     network interface-specific options will also be applied individually for each network interface as it
diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml
index 0976394b66..48d1c89a47 100644
--- a/man/systemd-firstboot.xml
+++ b/man/systemd-firstboot.xml
@@ -211,8 +211,8 @@
       <varlistentry>
         <term><option>--prompt</option></term>
 
-        <listitem><para>Query the user for locale, keymap, timezone, hostname
-        and root password. This is equivalent to specifying
+        <listitem><para>Query the user for locale, keymap, timezone, hostname,
+        root's password, and root's shell. This is equivalent to specifying
         <option>--prompt-locale</option>,
         <option>--prompt-keymap</option>,
         <option>--prompt-timezone</option>,
diff --git a/man/systemd-hibernate-resume-generator.xml b/man/systemd-hibernate-resume-generator.xml
index f532a19a48..60d66b201d 100644
--- a/man/systemd-hibernate-resume-generator.xml
+++ b/man/systemd-hibernate-resume-generator.xml
@@ -49,7 +49,7 @@
 
         <listitem><para>Takes a path to the resume device. Both
         persistent block device paths like
-        <filename>/dev/disk/by-foo/bar</filename> and
+        <filename index="false">/dev/disk/by-foo/bar</filename> and
         <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-style
         specifiers like <literal>FOO=bar</literal> are
         supported.</para></listitem>
diff --git a/man/systemd-homed.service.xml b/man/systemd-homed.service.xml
index ab8bcab8cb..d6a239bc96 100644
--- a/man/systemd-homed.service.xml
+++ b/man/systemd-homed.service.xml
@@ -86,9 +86,9 @@
     <para>In order to migrate a home directory from a host <literal>foobar</literal> to another host
     <literal>quux</literal> it is hence sufficient to copy
     <filename>/var/lib/systemd/home/local.public</filename> from the host <literal>foobar</literal> to
-    <literal>quux</literal>, maybe calling the file on the destination
-    <filename>/var/lib/systemd/home/foobar.public</filename>, reflecting the origin of the key. If the user
-    record should be modifiable on <literal>quux</literal> the pair
+    <literal>quux</literal>, maybe calling the file on the destination <filename
+    index="false">/var/lib/systemd/home/foobar.public</filename>, reflecting the origin of the key. If the
+    user record should be modifiable on <literal>quux</literal> the pair
     <filename>/var/lib/systemd/home/local.public</filename> and
     <filename>/var/lib/systemd/home/local.private</filename> need to be copied from <literal>foobar</literal>
     to <literal>quux</literal>, and placed under the identical paths there, as currently only a single
diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml
index a976c606bd..a6b1aa0f13 100644
--- a/man/systemd-machined.service.xml
+++ b/man/systemd-machined.service.xml
@@ -107,9 +107,9 @@
     For more information please consult
     <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     and
-    <citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    <citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     and
-    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>
 
     <para>A small companion daemon
diff --git a/man/systemd-mount.xml b/man/systemd-mount.xml
index f1089eed3b..3641c90248 100644
--- a/man/systemd-mount.xml
+++ b/man/systemd-mount.xml
@@ -131,8 +131,9 @@
         <term><option>--type=</option></term>
         <term><option>-t</option></term>
 
-        <listitem><para>Specifies the file system type to mount (e.g. <literal>vfat</literal>, <literal>ext4</literal>,
-        …). If omitted (or set to <literal>auto</literal>) the file system is determined automatically.</para></listitem>
+        <listitem><para>Specifies the file system type to mount (e.g. <literal>vfat</literal> or
+        <literal>ext4</literal>). If omitted or set to <literal>auto</literal>, the file system type is
+        determined automatically.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml
index 6d583003ba..f61bfd9980 100644
--- a/man/systemd-notify.xml
+++ b/man/systemd-notify.xml
@@ -136,11 +136,10 @@
       <varlistentry>
         <term><option>--no-block</option></term>
 
-        <listitem><para>Do not synchronously wait for the requested operation to finish.
-        Use of this option is only recommended when <command>systemd-notify</command>
-        is spawned by the service manager, or when the invoking process is directly spawned
-        by the service manager and has enough privileges to allow <command>systemd-notify
-        </command> to send the notification on its behalf. Sending notifications with
+        <listitem><para>Do not synchronously wait for the requested operation to finish.  Use of this option
+        is only recommended when <command>systemd-notify</command> is spawned by the service manager, or when
+        the invoking process is directly spawned by the service manager and has enough privileges to allow
+        <command>systemd-notify</command> to send the notification on its behalf. Sending notifications with
         this option set is prone to race conditions in all other cases.</para></listitem>
       </varlistentry>
 
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index 7c89bc4423..854559cb61 100644
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -348,16 +348,17 @@
         terminated. When the mode parameter is specified as <option>no</option> (the default), the whole OS tree is
         made available writable (unless <option>--read-only</option> is specified, see above).</para>
 
-        <para>Note that if one of the volatile modes is chosen, its effect is limited to the root file system (or
-        <filename>/var/</filename> in case of <option>state</option>), and any other mounts placed in the hierarchy are
-        unaffected — regardless if they are established automatically (e.g. the EFI system partition that might be
-        mounted to <filename>/efi/</filename> or <filename>/boot/</filename>) or explicitly (e.g. through an additional
-        command line option such as <option>--bind=</option>, see below). This means, even if
-        <option>--volatile=overlay</option> is used changes to <filename>/efi/</filename> or
-        <filename>/boot/</filename> are prohibited in case such a partition exists in the container image operated on,
-        and even if <option>--volatile=state</option> is used the hypothetical file <filename>/etc/foobar</filename> is
-        potentially writable if <option>--bind=/etc/foobar</option> if used to mount it from outside the read-only
-        container <filename>/etc</filename> directory.</para>
+        <para>Note that if one of the volatile modes is chosen, its effect is limited to the root file system
+        (or <filename>/var/</filename> in case of <option>state</option>), and any other mounts placed in the
+        hierarchy are unaffected — regardless if they are established automatically (e.g. the EFI system
+        partition that might be mounted to <filename>/efi/</filename> or <filename>/boot/</filename>) or
+        explicitly (e.g. through an additional command line option such as <option>--bind=</option>, see
+        below). This means, even if <option>--volatile=overlay</option> is used changes to
+        <filename>/efi/</filename> or <filename>/boot/</filename> are prohibited in case such a partition
+        exists in the container image operated on, and even if <option>--volatile=state</option> is used the
+        hypothetical file <filename index="false">/etc/foobar</filename> is potentially writable if
+        <option>--bind=/etc/foobar</option> if used to mount it from outside the read-only container
+        <filename>/etc</filename> directory.</para>
 
         <para>The <option>--ephemeral</option> option is closely related to this setting, and provides similar
         behaviour by making a temporary, ephemeral copy of the whole OS image and executing that. For further details,
@@ -404,24 +405,20 @@
         <literal>user.verity.usrhash</literal> extended file attribute or via a <filename>.usrhash</filename>
         file adjacent to the disk image, following the same format and logic as for the root hash for the
         root file system described here. Note that there's currently no switch to configure the root hash for
-        the <filename>/usr/</filename> from the command line.</para></listitem>
+        the <filename>/usr/</filename> from the command line.</para>
+
+        <para>Also see the <varname>RootHash=</varname> option in
+        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>--root-hash-sig=</option></term>
 
-        <listitem><para>Takes a PKCS7 formatted binary signature of the <option>--root-hash=</option> option as a path
-        to a DER encoded signature file or as an ASCII base64 string encoding of the DER encoded signature, prefixed
-        by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root hash hex
-        string is valid and done by a public key present in the kernel keyring. If this option is not specified, but a
-        file with the <filename>.roothash.p7s</filename> suffix is found next to the image file, bearing otherwise the
-        same name (except if the image has the <filename>.raw</filename> suffix, in which case the signature file must
-        not have it in its name), the signature is read from it and automatically used.</para>
-
-        <para>The root hash for the <filename>/usr/</filename> file system included in a disk image may be
-        configured via a <filename>.usrhash.p7s</filename> file adjacent to the disk image. There's currently
-        no switch to configure the signature of the root hash of the <filename>/usr/</filename> file system
-        from the command line.</para></listitem>
+        <listitem><para>Takes a PKCS7 signature of the <option>--root-hash=</option> option.
+        The semantics are the same as for the <varname>RootHashSignature=</varname> option, see
+        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml
index 914607e3f8..6137a6d836 100644
--- a/man/systemd-resolved.service.xml
+++ b/man/systemd-resolved.service.xml
@@ -212,9 +212,9 @@
     receives any DNS traffic not matching any of its configured search/route-only domains, set the "DNS
     default route" option for it to false.</para>
 
-    <para>See the <ulink url="https://www.freedesktop.org/wiki/Software/systemd/resolved">resolved D-Bus API
-    Documentation</ulink> for information about the APIs <filename>systemd-resolved</filename> provides.
-    </para>
+    <para>See
+    <citerefentry><refentrytitle>org.freedesktop.resolve1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for information about the D-Bus APIs <filename>systemd-resolved</filename> provides.</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index ed657831f6..e5e97bf8fe 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -231,13 +231,14 @@
       <varlistentry>
         <term><varname>RootHashSignature=</varname></term>
 
-        <listitem><para>Takes a PKCS7 formatted binary signature of the <varname>RootHash=</varname> option as a path
-        to a DER encoded signature file or as an ASCII base64 string encoding of the DER encoded signature, prefixed
-        by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root hash
-        signature is valid and created by a public key present in the kernel keyring. If this option is not specified,
-        but a file with the <filename>.roothash.p7s</filename> suffix is found next to the image file, bearing otherwise
-        the same name (except if the image has the <filename>.raw</filename> suffix, in which case the signature file
-        must not have it in its name), the signature is read from it and automatically used.</para>
+        <listitem><para>Takes a PKCS7 signature of the <varname>RootHash=</varname> option as a path to a
+        DER-encoded signature file, or as an ASCII base64 string encoding of a DER-encoded signature prefixed
+        by <literal>base64:</literal>. The dm-verity volume will only be opened if the signature of the root
+        hash is valid and signed by a public key present in the kernel keyring. If this option is not
+        specified, but a file with the <filename>.roothash.p7s</filename> suffix is found next to the image
+        file, bearing otherwise the same name (except if the image has the <filename>.raw</filename> suffix,
+        in which case the signature file must not have it in its name), the signature is read from it and
+        automatically used.</para>
 
         <para>If the disk image contains a separate <filename>/usr/</filename> partition it may also be
         Verity protected, in which case the signature for the root hash may configured via a
@@ -681,7 +682,7 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         <listitem><para>Takes a profile name as argument. The process executed by the unit will switch to
         this profile when started. Profiles must already be loaded in the kernel, or the unit will fail. If
         prefixed by <literal>-</literal>, all errors will be ignored. This setting has no effect if AppArmor
-        is not enabled. This setting not affect commands prefixed with <literal>+</literal>.</para>
+        is not enabled. This setting does not affect commands prefixed with <literal>+</literal>.</para>
         </listitem>
       </varlistentry>
 
@@ -1025,10 +1026,12 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
       <varlistentry>
         <term><varname>CPUSchedulingResetOnFork=</varname></term>
 
-        <listitem><para>Takes a boolean argument. If true, elevated CPU scheduling priorities and policies will be
-        reset when the executed processes fork, and can hence not leak into child processes. See
-        <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> for
-        details. Defaults to false.</para></listitem>
+        <listitem><para>Takes a boolean argument. If true, elevated CPU scheduling priorities and policies
+        will be reset when the executed processes call
+        <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+        and can hence not leak into child processes. See
+        <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+        for details. Defaults to false.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -1167,12 +1170,12 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
         <term><varname>LogsDirectory=</varname></term>
         <term><varname>ConfigurationDirectory=</varname></term>
 
-        <listitem><para>These options take a whitespace-separated list of directory names. The specified directory
-        names must be relative, and may not include <literal>..</literal>. If set, one or more
-        directories by the specified names will be created (including their parents) below the locations
-        defined in the following table, when the unit is started. Also, the corresponding environment variable
-        is defined with the full path of directories. If multiple directories are set, then in the environment variable
-        the paths are concatenated with colon (<literal>:</literal>).</para>
+        <listitem><para>These options take a whitespace-separated list of directory names. The specified
+        directory names must be relative, and may not include <literal>..</literal>. If set, when the unit is
+        started, one or more directories by the specified names will be created (including their parents)
+        below the locations defined in the following table. Also, the corresponding environment variable will
+        be defined with the full paths of the directories. If multiple directories are set, then in the
+        environment variable the paths are concatenated with colon (<literal>:</literal>).</para>
         <table>
           <title>Automatic directory creation and environment variables</title>
           <tgroup cols='4'>
@@ -1275,7 +1278,7 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
 
         <para>Example: if a system service unit has the following,
         <programlisting>RuntimeDirectory=foo/bar baz</programlisting>
-        the service manager creates <filename>/run/foo</filename> (if it does not exist),
+        the service manager creates <filename index='false'>/run/foo</filename> (if it does not exist),
 
         <filename index='false'>/run/foo/bar</filename>, and <filename index='false'>/run/baz</filename>. The
         directories <filename index='false'>/run/foo/bar</filename> and
@@ -1334,10 +1337,10 @@ StateDirectory=aaa/bbb ccc</programlisting>
         <term><varname>ReadOnlyPaths=</varname></term>
         <term><varname>InaccessiblePaths=</varname></term>
 
-        <listitem><para>Sets up a new file system namespace for executed processes. These options may be used to limit
-        access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths
-        relative to the host's root directory (i.e. the system running the service manager).  Note that if paths
-        contain symlinks, they are resolved relative to the root directory set with
+        <listitem><para>Sets up a new file system namespace for executed processes. These options may be used
+        to limit access a process has to the file system. Each setting takes a space-separated list of paths
+        relative to the host's root directory (i.e. the system running the service manager). Note that if
+        paths contain symlinks, they are resolved relative to the root directory set with
         <varname>RootDirectory=</varname>/<varname>RootImage=</varname>.</para>
 
         <para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace
@@ -2960,8 +2963,8 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
       <varlistentry>
         <term><varname>$LOG_NAMESPACE</varname></term>
 
-        <listitem><para>If the <varname>LogNamespace=</varname> service setting is used, contains name of the
-        selected logging namespace.</para></listitem>
+        <listitem><para>Contains the name of the selected logging namespace when the
+        <varname>LogNamespace=</varname> service setting is used.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -3623,7 +3626,8 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy
         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-        <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+        <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+        <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>
       </para>
   </refsect1>
 
diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml
index 31e3d8b210..a343e5697b 100644
--- a/man/systemd.journal-fields.xml
+++ b/man/systemd.journal-fields.xml
@@ -219,12 +219,10 @@
         <term><varname>_SYSTEMD_OWNER_UID=</varname></term>
 
         <listitem>
-          <para>The control group path in the systemd hierarchy, the
-          the systemd slice unit name, the systemd unit name, the
-          unit name in the systemd user manager (if any), the systemd
-          session ID (if any), and the owner UID of the systemd user
-          unit or systemd session (if any) of the process the journal
-          entry originates from.</para>
+          <para>The control group path in the systemd hierarchy, the systemd slice unit name, the systemd
+          unit name, the unit name in the systemd user manager (if any), the systemd session ID (if any), and
+          the owner UID of the systemd user unit or systemd session (if any) of the process the journal entry
+          originates from.</para>
         </listitem>
       </varlistentry>
 
@@ -398,15 +396,12 @@
       <varlistentry>
         <term><varname>_KERNEL_DEVICE=</varname></term>
         <listitem>
-          <para>The kernel device name. If the entry is associated to
-          a block device, the major and minor of the device node,
-          separated by <literal>:</literal> and prefixed by
-          <literal>b</literal>. Similar for character devices but
-          prefixed by <literal>c</literal>. For network devices, this
-          is the interface index prefixed by <literal>n</literal>. For
-          all other devices, this is the subsystem name prefixed by
-          <literal>+</literal>, followed by <literal>:</literal>,
-          followed by the kernel device name.</para>
+          <para>The kernel device name. If the entry is associated to a block device, contains the major and
+          minor numbers of the device node, separated by <literal>:</literal> and prefixed by
+          <literal>b</literal>. Similarly for character devices, but prefixed by <literal>c</literal>. For
+          network devices, this is the interface index prefixed by <literal>n</literal>. For all other
+          devices, this is the subsystem name prefixed by <literal>+</literal>, followed by
+          <literal>:</literal>, followed by the kernel device name.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml
index 2e716cca9c..863fa9108f 100644
--- a/man/systemd.netdev.xml
+++ b/man/systemd.netdev.xml
@@ -523,9 +523,8 @@
   <refsect1>
     <title>[MACVTAP] Section Options</title>
 
-    <para>The [MACVTAP] section applies for
-    netdevs of kind <literal>macvtap</literal> and accepts the
-    same key as [MACVLAN].</para>
+    <para>The [MACVTAP] section applies for netdevs of kind <literal>macvtap</literal> and accepts the same
+    keys as [MACVLAN].</para>
   </refsect1>
 
   <refsect1>
@@ -558,9 +557,8 @@
   <refsect1>
     <title>[IPVTAP] Section Options</title>
 
-    <para>The [IPVTAP] section only applies for
-    netdevs of kind <literal>ipvtap</literal> and accepts the
-    same key as [IPVLAN].</para>
+    <para>The [IPVTAP] section only applies for netdevs of kind <literal>ipvtap</literal> and accepts the
+    same keys as [IPVLAN].</para>
   </refsect1>
 
   <refsect1>
@@ -818,7 +816,7 @@
       <varlistentry>
         <term><varname>IPDoNotFragment=</varname></term>
         <listitem>
-          <para>Accepts the same key in [VXLAN] section.</para>
+          <para>Accepts the same key as in [VXLAN] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -876,8 +874,8 @@
         <term><varname>PeerTunnelId=</varname></term>
         <listitem>
           <para>Specifies the peer tunnel id. Takes a number in the range 1—4294967295. The value used must
-          match the <literal>PeerTunnelId=</literal> value being used at the peer. This setting is
-          compulsory.</para>
+          match the <literal>TunnelId=</literal> value being used at the peer. This setting is compulsory.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -1100,43 +1098,43 @@
       <varlistentry>
         <term><varname>Port=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecReceiveChannel] section.</para>
+          <para>Accepts the same key as in [MACsecReceiveChannel] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>MACAddress=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecReceiveChannel] section.</para>
+          <para>Accepts the same key as in [MACsecReceiveChannel] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>PacketNumber=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecTransmitAssociation] section.</para>
+          <para>Accepts the same key as in [MACsecTransmitAssociation] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>KeyId=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecTransmitAssociation] section.</para>
+          <para>Accepts the same key as in [MACsecTransmitAssociation] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>Key=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecTransmitAssociation] section.</para>
+          <para>Accepts the same key as in [MACsecTransmitAssociation] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>KeyFile=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecTransmitAssociation] section.</para>
+          <para>Accepts the same key as in [MACsecTransmitAssociation] section.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><varname>Activate=</varname></term>
         <listitem>
-          <para>Accepts the same key in [MACsecTransmitAssociation] section.</para>
+          <para>Accepts the same key as in [MACsecTransmitAssociation] section.</para>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -1379,7 +1377,7 @@
           <para>Specifies the encapsulation mechanism used to store networking packets of various protocols
           inside the UDP packets. Supports the following values:
 
-          <literal>FooOverUDP</literal> provides the simplest no frills model of UDP encapsulation, it simply
+          <literal>FooOverUDP</literal> provides the simplest no-frills model of UDP encapsulation, it simply
           encapsulates packets directly in the UDP payload. <literal>GenericUDPEncapsulation</literal> is a
           generic and extensible encapsulation, it allows encapsulation of packets for any IP protocol and
           optional data as part of the encapsulation. For more detailed information see <ulink
@@ -1391,10 +1389,9 @@
       <varlistentry>
         <term><varname>Port=</varname></term>
         <listitem>
-          <para>Specifies the port number, where the IP encapsulation packets will arrive. Please take note
-          that the packets will arrive with the encapsulation will be removed. Then they will be manually fed
-          back into the network stack, and sent ahead for delivery to the real destination. This option is
-          mandatory.</para>
+          <para>Specifies the port number where the encapsulated packets will arrive. Those packets will be
+          removed and manually fed back into the network stack with the encapsulation removed to be sent to
+          the real destination. This option is mandatory.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index 7cf9f2f6ed..1527208e45 100644
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -1549,11 +1549,16 @@ IPv6Token=prefixstable:2002:da8:1::</programlisting></para>
         <varlistentry>
           <term><varname>MUDURL=</varname></term>
           <listitem>
-            <para>When configured, the Manufacturer Usage Descriptions (MUD) URL will be sent to the
-            DHCPv4 server. Takes an URL of length up to 255 characters. A superficial verification that
-            the string is a valid URL will be performed. DHCPv4 clients are intended to have at most one
-            MUD URL associated with them. See
-            <ulink url="https://tools.ietf.org/html/rfc8520">RFC 8520</ulink>.</para>
+            <para>When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to the
+            DHCPv4 server. Takes a URL of length up to 255 characters. A superficial verification that the
+            string is a valid URL will be performed. DHCPv4 clients are intended to have at most one MUD URL
+            associated with them. See <ulink url="https://tools.ietf.org/html/rfc8520">RFC 8520</ulink>.
+            </para>
+
+            <para>MUD is an embedded software standard defined by the IETF that allows IoT device makers to
+            advertise device specifications, including the intended communication patterns for their device
+            when it connects to the network. The network can then use this to author a context-specific
+            access policy, so the device functions only within those parameters.</para>
           </listitem>
         </varlistentry>
 
@@ -1848,18 +1853,18 @@ IPv6Token=prefixstable:2002:da8:1::</programlisting></para>
         <varlistentry>
           <term><varname>MUDURL=</varname></term>
           <listitem>
-            <para>When configured, the Manufacturer Usage Descriptions (MUD) URL will be sent to the DHCPV6 server.
-            Takes an URL of length up to 255 characters. A superficial verification that the string is a valid URL
-            will be performed. DHCPv6 clients are intended to have at most one MUD URL associated with them. See
-            <ulink url="https://tools.ietf.org/html/rfc8520">RFC 8520</ulink>.</para>
+            <para>When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to
+            the DHCPV6 server. The syntax and semantics are the same as for <varname>MUDURL=</varname> in the
+            [DHCPv4] section described above.</para>
           </listitem>
         </varlistentry>
 
         <varlistentry>
           <term><varname>RequestOptions=</varname></term>
           <listitem>
-            <para>When configured, allows to set arbitrary request options in the DHCPv6 request options list and will
-            sent to the DHCPV6 server. A whitespace-separated list of integers in the range 1..254. Defaults to unset.</para>
+            <para>When configured, allows to set arbitrary request options in the DHCPv6 request options list
+            that will be sent to the DHCPV6 server. A whitespace-separated list of integers in the range
+            1..254. Defaults to unset.</para>
           </listitem>
         </varlistentry>
 
@@ -2050,8 +2055,8 @@ IPv6Token=prefixstable:2002:da8:1::</programlisting></para>
         <varlistentry>
           <term><varname>UseOnLinkPrefix=</varname></term>
           <listitem>
-            <para>When true (the default), the onlink prefix received in the Router Advertisement will be used and take
-            precedence over any statically configured ones.</para>
+            <para>When true (the default), the onlink prefix received in the Router Advertisement will be
+            used and takes precedence over any statically configured ones.</para>
           </listitem>
         </varlistentry>
 
@@ -2563,19 +2568,16 @@ IPv6Token=prefixstable:2002:da8:1::</programlisting></para>
   <refsect1>
     <title>[LLDP] Section Options</title>
       <para>The [LLDP] section manages the Link Layer Discovery Protocol (LLDP) and accepts the following
-      keys.</para>
+      keys:</para>
       <variablelist class='network-directives'>
         <varlistentry>
           <term><varname>MUDURL=</varname></term>
           <listitem>
-            <para>Controls support for Ethernet LLDP packet's Manufacturer Usage Description (MUD). MUD is an embedded software
-            standard defined by the IETF that allows IoT Device makers to advertise device specifications, including the intended
-            communication patterns for their device when it connects to the network. The network can then use this intent to author
-            a context-specific access policy, so the device functions only within those parameters. Takes an URL of length up to 255
-            characters. A superficial verification that the string is a valid URL
-            will be performed. See
-            <ulink url="https://tools.ietf.org/html/rfc8520">RFC 8520</ulink> for details. The MUD URL received
-            from the LLDP packets will be saved at the state files and can be read via
+            <para>When configured, the specified Manufacturer Usage Descriptions (MUD) URL will be sent in
+            LLDP packets. The syntax and semantics are the same as for <varname>MUDURL=</varname> in the
+            [DHCPv4] section described above.</para>
+
+            <para>The MUD URLs received via LLDP packets are saved and can be read using the
             <function>sd_lldp_neighbor_get_mud_url()</function> function.</para>
           </listitem>
         </varlistentry>
@@ -2893,11 +2895,11 @@ IPv6Token=prefixstable:2002:da8:1::</programlisting></para>
       <varlistentry>
         <term><varname>LimitBytes=</varname></term>
         <listitem>
-          <para>Specifies the hard limit on the FIFO size in bytes. The size limit (a buffer size) to prevent
-          it from overflowing in case it is unable to dequeue packets as quickly as it receives them. When
-          this limit is reached, incoming packets are dropped. When suffixed with K, M, or G, the specified
-          size is parsed as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults
-          to unset and kernel's default is used.</para>
+          <para>Specifies the hard limit in bytes on the FIFO buffer size. The size limit prevents overflow
+          in case the kernel is unable to dequeue packets as quickly as it receives them. When this limit is
+          reached, incoming packets are dropped. When suffixed with K, M, or G, the specified size is parsed
+          as Kilobytes, Megabytes, or Gigabytes, respectively, to the base of 1024. Defaults to unset and
+          kernel default is used.</para>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -3104,13 +3106,12 @@ IPv6Token=prefixstable:2002:da8:1::</programlisting></para>
       <varlistentry>
         <term><varname>PriorityMap=</varname></term>
         <listitem>
-          <para>The priority map maps the priority of a packet to a band. The argument is a white-space
-          separated list of numbers. The first number indicates which band the packets with priority
-          0 should be put to, the second is for priority 1, and so on. There can be up to 16 numbers in
-          the list. If there are fewer, the default band that traffic with one of the unmentioned
-          priorities goes to is the last one. Each band number must be 0..255. This setting can be
-          specified multiple times. If an empty string is assigned, then the all previous assignments
-          are cleared.</para>
+          <para>The priority map maps the priority of a packet to a band. The argument is a whitespace
+          separated list of numbers. The first number indicates which band the packets with priority 0 should
+          be put to, the second is for priority 1, and so on. There can be up to 16 numbers in the list. If
+          there are fewer, the default band that traffic with one of the unmentioned priorities goes to is
+          the last one. Each band number must be in the range 0..255. This setting can be specified multiple
+          times. If an empty string is assigned, then the all previous assignments are cleared.</para>
         </listitem>
       </varlistentry>
     </variablelist>
diff --git a/man/systemd.offline-updates.xml b/man/systemd.offline-updates.xml
index 81a37f6789..49d98d496a 100644
--- a/man/systemd.offline-updates.xml
+++ b/man/systemd.offline-updates.xml
@@ -126,8 +126,8 @@
         script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds
         you should trigger the reboot in your own code, for example by invoking logind's
         <command>Reboot()</command> call or calling <command>systemctl reboot</command>. See
-        <ulink url="https://www.freedesktop.org/wiki/Software/systemd/logind">logind dbus API</ulink>
-        for details.</para>
+        <citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for details about the logind D-Bus API.</para>
       </listitem>
 
       <listitem>
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index d11e37da84..aec3a764a8 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -1307,7 +1307,7 @@ ls</programlisting>
       <title>Simple service</title>
 
       <para>The following unit file creates a service that will
-      execute <filename>/usr/sbin/foo-daemon</filename>. Since no
+      execute <filename index="false">/usr/sbin/foo-daemon</filename>. Since no
       <varname>Type=</varname> is specified, the default
       <varname>Type=</varname><option>simple</option> will be assumed.
       systemd will assume the unit to be started immediately after the
diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml
index ba0ad1d36e..74e0007c88 100644
--- a/man/systemd.socket.xml
+++ b/man/systemd.socket.xml
@@ -299,7 +299,7 @@
         url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
         FunctionFS</ulink> endpoints location to listen on, for
         implementation of USB gadget functions. This expects an
-        absolute file system path of FunctionFS mount point as the argument.
+        absolute file system path of a FunctionFS mount point as the argument.
         Behavior otherwise is very similar to the <varname>ListenFIFO=</varname>
         directive above. Use this to open the FunctionFS endpoint
         <filename>ep0</filename>. When using this option, the
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index a948969a8f..d99a2183a2 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -862,8 +862,8 @@
           pulled in via a <option>Wants=</option> dependency of the storage daemon and thus generally not be
           part of any transaction unless a storage daemon is used. The instance name for instances of this
           template unit must be a properly escaped block device node path, e.g.
-          <filename>blockdev@dev-mapper-foobar.target</filename> for the storage device
-          <filename>/dev/mapper/foobar</filename>.</para></listitem>
+          <filename index="false">blockdev@dev-mapper-foobar.target</filename> for the storage device
+          <filename index="false">/dev/mapper/foobar</filename>.</para></listitem>
         </varlistentry>
         <varlistentry>
           <term><filename>cryptsetup-pre.target</filename></term>
@@ -1162,7 +1162,7 @@
             <citerefentry><refentrytitle>systemd-xdg-autostart-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
             for the XDG desktop files in autostart directories.
             Desktop Environments can opt-in to use this service by adding a <varname>Wants=</varname>
-            dependency on <literal>xdg-desktop-autostart.target</literal></para>.
+            dependency on <literal>xdg-desktop-autostart.target</literal>.</para>
           </listitem>
         </varlistentry>
       </variablelist>
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index cc6606022b..1ab6e2b0b9 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -279,7 +279,7 @@
     <para>When the input qualifies as absolute file system path, this algorithm is extended slightly: the path to the
     root directory <literal>/</literal> is encoded as single dash <literal>-</literal>. In addition, any leading,
     trailing or duplicate <literal>/</literal> characters are removed from the string before transformation. Example:
-    <filename>/foo//bar/baz/</filename> becomes <literal>foo-bar-baz</literal>.</para>
+    <filename index="false">/foo//bar/baz/</filename> becomes <literal>foo-bar-baz</literal>.</para>
 
     <para>This escaping is fully reversible, as long as it is known whether the escaped string was a path (the
     unescaping results are different for paths and non-path strings). The
@@ -1922,7 +1922,7 @@ ExecStart=/usr/sbin/foo-daemon
 
       <para>After running <command>systemctl enable</command>, a
       symlink
-      <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename>
+      <filename index="false">/etc/systemd/system/multi-user.target.wants/foo.service</filename>
       linking to the actual unit will be created. It tells systemd to
       pull in the unit when starting
       <filename>multi-user.target</filename>. The inverse
diff --git a/man/systemd.xml b/man/systemd.xml
index d53b52b6b7..0d6f853426 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -670,7 +670,7 @@
         <para>These variables may contain a list of paths, separated by colons
         (<literal>:</literal>). When set, if the list ends with an empty
         component (<literal>...:</literal>), this list is prepended to the
-        usual set of of paths. Otherwise, the specified list replaces the usual
+        usual set of paths. Otherwise, the specified list replaces the usual
         set of paths.
         </para></listitem>
       </varlistentry>
@@ -850,9 +850,9 @@
         <listitem><para>Controls log output, with the same effect as the
         <varname>$SYSTEMD_LOG_COLOR</varname>, <varname>$SYSTEMD_LOG_LEVEL</varname>,
         <varname>$SYSTEMD_LOG_LOCATION</varname>, <varname>$SYSTEMD_LOG_TARGET</varname>,
-        <varname>$SYSTEMD_LOG_TIME</varname>, <varname>$SYSTEMD_LOG_TID</varname> environment variables
-        described above.  <varname>systemd.log_color</varname>, <varname>systemd.log_location</varname>,
-        <varname>systemd.log_time</varname> and <varname>systemd.log_tid=</varname> can be specified without
+        <varname>$SYSTEMD_LOG_TIME</varname>, and <varname>$SYSTEMD_LOG_TID</varname> environment variables
+        described above. <varname>systemd.log_color</varname>, <varname>systemd.log_location</varname>,
+        <varname>systemd.log_time</varname>, and <varname>systemd.log_tid=</varname> can be specified without
         an argument, with the same effect as a positive boolean.</para></listitem>
       </varlistentry>
 
@@ -1084,18 +1084,18 @@
       <para>Those options correspond directly to options listed above in "Kernel Command Line". Both forms
       may be used equivalently for the system manager, but it is recommended to use the forms listed above in
       this context, because they are properly namespaced. When an option is specified both on the kernel
-      command line, and as a normal command line argument, the latter has higher precedence.</para>
+      command line and as a normal command line argument, the latter has higher precedence.</para>
 
       <para>When <command>systemd</command> is used as a user manager, the kernel command line is ignored and
-      the options described are understood. Nevertheless, <command>systemd</command> is usually started in
-      this mode through the
+      only the options described below are understood. Nevertheless, <command>systemd</command> is usually
+      started in this mode through the
       <citerefentry><refentrytitle>user@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
       service, which is shared between all users, and it may be more convenient to use configuration files to
-      modify settings, see
-      <citerefentry><refentrytitle>systemd-user.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-      or a drop-in that specifies one of the environment variables listed above in the Environment section,
-      see
-      <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+      modify settings (see
+      <citerefentry><refentrytitle>systemd-user.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
+      or a drop-in that specifies one of the environment variables listed above in the Environment section
+      (see the discussion of <varname>Environment=</varname> and <varname>EnvironmentFile=</varname> in
+      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>
 
       <variablelist>
         <varlistentry>