From 2f76f1cfaee2f775df8b367cb77aed751af45956 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Wed, 17 May 2023 11:12:32 +0200
Subject: [PATCH] man: explain allowed values for /sys/power/{disk,state}

Also fix the grammar: "neither" can only be used with two values, and
here we have an inderminate number >= 1.

Fixes #26460.
---
 man/systemd-sleep.conf.xml | 53 +++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 23 deletions(-)

diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml
index f8f1694b57d..bdc4c3c1932 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>
+        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>SuspendMode=</varname> when suspending and the value of <varname>HibernateMode=</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/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>