Merge pull request #27669 from keszybz/man-fixes-254

Some simple man page fixes to reduce the list of issues tagged for v254

3 files changed, 45 insertions, 33 deletions

diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml
index f8f1694b57..bdc4c3c193 100644
--- a/man/systemd-sleep.conf.xml
+++ b/man/systemd-sleep.conf.xml
@@ -138,21 +138,24 @@
         <term><varname>HibernateMode=</varname></term>
         <term><varname>HybridSleepMode=</varname></term>
 
-        <listitem><para>The string to be written to
-        <filename>/sys/power/disk</filename> by,
-        respectively,
+        <listitem><para>The string to be written to <filename>/sys/power/disk</filename> by, respectively,
         <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-        <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or
+        <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        or
         <citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
-        More than one value can be specified by separating
-        multiple values with whitespace. They will be tried
-        in turn, until one is written without error. If
-        neither succeeds, the operation will be aborted.
-        </para>
-
-        <para><citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-        uses the value of <varname>SuspendMode=</varname> when suspending and the value of <varname>HibernateMode=</varname> when hibernating.
-        </para></listitem>
+        More than one value can be specified by separating multiple values with whitespace. They will be
+        tried in turn, until one is written without error. If none of the writes succeed, the operation will
+        be aborted.</para>
+
+        <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
+        <command>cat /sys/power/disk</command> to display). See <ulink
+        url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">the
+        kernel documentation</ulink> for more details.</para>
+
+        <para>
+        <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        uses the value of <varname>SuspendMode=</varname> when suspending and the value of
+        <varname>HibernateMode=</varname> when hibernating.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -160,21 +163,25 @@
         <term><varname>HibernateState=</varname></term>
         <term><varname>HybridSleepState=</varname></term>
 
-        <listitem><para>The string to be written to
-        <filename>/sys/power/state</filename> by,
-        respectively,
+        <listitem><para>The string to be written to <filename>/sys/power/state</filename> by, respectively,
         <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-        <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or
+        <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        or
         <citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
-        More than one value can be specified by separating
-        multiple values with whitespace. They will be tried
-        in turn, until one is written without error. If
-        neither succeeds, the operation will be aborted.
+        More than one value can be specified by separating multiple values with whitespace. They will be
+        tried in turn, until one is written without error. If none of the writes succeed, the operation will
+        be aborted.
         </para>
 
-        <para><citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-        uses the value of <varname>SuspendState=</varname> when suspending and the value of <varname>HibernateState=</varname> when hibernating.
-        </para></listitem>
+        <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
+        <command>cat /sys/power/state</command> to display). See <ulink
+        url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">the
+        kernel documentation</ulink> for more details.</para>
+
+        <para>
+        <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        uses the value of <varname>SuspendState=</varname> when suspending and the value of
+        <varname>HibernateState=</varname> when hibernating.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 45294154db..c1088a3013 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -1826,17 +1826,22 @@ BindReadOnlyPaths=/var/lib/systemd</programlisting>
       <varlistentry>
         <term><varname>ProtectClock=</varname></term>
 
-        <listitem><para>Takes a boolean argument. If set, writes to the hardware clock or system clock will be denied.
-        It is recommended to turn this on for most services that do not need modify the clock. Defaults to off. Enabling
-        this option removes <constant>CAP_SYS_TIME</constant> and <constant>CAP_WAKE_ALARM</constant> from the
-        capability bounding set for this unit, installs a system call filter to block calls that can set the
-        clock, and <varname>DeviceAllow=char-rtc r</varname> is implied. This ensures <filename>/dev/rtc0</filename>,
-        <filename>/dev/rtc1</filename>, etc. are made read-only to the service. See
+        <listitem><para>Takes a boolean argument. If set, writes to the hardware clock or system clock will
+        be denied. Defaults to off. Enabling this option removes <constant>CAP_SYS_TIME</constant> and
+        <constant>CAP_WAKE_ALARM</constant> from the capability bounding set for this unit, installs a system
+        call filter to block calls that can set the clock, and <varname>DeviceAllow=char-rtc r</varname> is
+        implied. Note that the system calls are blocked altogether, the filter does not take into account
+        that some of the calls can be used to read the clock state with some parameter combinations.
+        Effectively, <filename>/dev/rtc0</filename>, <filename>/dev/rtc1</filename>, etc. are made read-only
+        to the service. See
         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-        for the details about <varname>DeviceAllow=</varname>. If this setting is on, but the unit
-        doesn't have the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services for which
+        for the details about <varname>DeviceAllow=</varname>. If this setting is on, but the unit doesn't
+        have the <constant>CAP_SYS_ADMIN</constant> capability (e.g. services for which
         <varname>User=</varname> is set), <varname>NoNewPrivileges=yes</varname> is implied.</para>
 
+        <para>It is recommended to turn this on for most services that do not need modify the clock or check
+        its state.</para>
+
         <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem>
       </varlistentry>
 
diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index a105b8af39..f691eef25d 100644
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -647,7 +647,7 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
       <para>For example:<programlisting>
 # Files created and modified, and directories accessed more than
 # an hour ago in "/tmp/foo/bar", are subject to time-based cleanup.
-d /tmp/foo/bar - - - - bmA:1h -</programlisting></para>
+d /tmp/foo/bar - - - bmA:1h -</programlisting></para>
 
       <para>Note that while the aging algorithm is run an exclusive BSD file lock (see <citerefentry
       project='man-pages'><refentrytitle>flock</refentrytitle><manvolnum>2</manvolnum></citerefentry>) is