From 9ecf9e414a97e861db403e043696fed6033508f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Sun, 14 Aug 2016 16:27:59 -0400
Subject: [PATCH] man: explain that *KeyIgnoreInhibited only apply to a subset
 of locks

Follow-up for #3924.

(cherry picked from commit 05b2a8fd7a0533758d2f532df798cabc3c442683)
---
 man/logind.conf.xml            | 42 ++++++++++++++++++++++++++----------------
 man/systemd-inhibit.xml        |  2 +-
 man/systemd-logind.service.xml |  2 +-
 3 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/man/logind.conf.xml b/man/logind.conf.xml
index adba5a4131..5931832996 100644
--- a/man/logind.conf.xml
+++ b/man/logind.conf.xml
@@ -211,7 +211,7 @@
         <term><varname>HandleLidSwitch=</varname></term>
         <term><varname>HandleLidSwitchDocked=</varname></term>
 
-        <listitem><para>Controls whether logind shall handle the
+        <listitem><para>Controls how logind shall handle the
         system power and sleep keys and the lid switch to trigger
         actions such as system power-off or suspend. Can be one of
         <literal>ignore</literal>,
@@ -240,7 +240,16 @@
         docking station, or if more than one display is connected, the
         action specified by <varname>HandleLidSwitchDocked=</varname>
         occurs; otherwise the <varname>HandleLidSwitch=</varname>
-        action occurs.</para></listitem>
+        action occurs.</para>
+
+        <para>A different application may disable logind's handling of system power and
+        sleep keys and the lid switch by taking a low-level inhibitor lock
+        ("handle-power-key", "handle-suspend-key", "handle-hibernate-key",
+        "handle-lid-switch"). This is most commonly used by graphical desktop environments
+        to take over suspend and hibernation handling, and to use their own configuration
+        mechanisms. If a low-level inhibitor lock is taken, logind will not take any
+        action when that key or switch is triggered and the <varname>Handle*=</varname>
+        settings are irrelevant.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -249,21 +258,22 @@
         <term><varname>HibernateKeyIgnoreInhibited=</varname></term>
         <term><varname>LidSwitchIgnoreInhibited=</varname></term>
 
-        <listitem><para>Controls whether actions triggered by the
-        power and sleep keys and the lid switch are subject to
-        inhibitor locks. These settings take boolean arguments. If
-        <literal>no</literal>, the inhibitor locks taken by
-        applications in order to block the requested operation are
-        respected. If <literal>yes</literal>, the requested operation
-        is executed in any case.
+        <listitem><para>Controls whether actions that <command>systemd-logind</command>
+        takes when the power and sleep keys and the lid switch are triggered are subject
+        to high-level inhibitor locks ("shutdown", "sleep", "idle"). Low level inhibitor
+        locks ("handle-*-key"), are always honoured, irrespective of this setting.</para>
+
+        <para>These settings take boolean arguments. If <literal>no</literal>, the
+        inhibitor locks taken by applications are respected. If <literal>yes</literal>,
+        "shutdown", "sleep", and "idle" inhibitor locks are ignored.
         <varname>PowerKeyIgnoreInhibited=</varname>,
-        <varname>SuspendKeyIgnoreInhibited=</varname> and
-        <varname>HibernateKeyIgnoreInhibited=</varname> default to
-        <literal>no</literal>.
-        <varname>LidSwitchIgnoreInhibited=</varname> defaults to
-        <literal>yes</literal>. This means that the lid switch does
-        not respect suspend blockers by default, but the power and
-        sleep keys do. </para></listitem>
+        <varname>SuspendKeyIgnoreInhibited=</varname>, and
+        <varname>HibernateKeyIgnoreInhibited=</varname> default to <literal>no</literal>.
+        <varname>LidSwitchIgnoreInhibited=</varname> defaults to <literal>yes</literal>.
+        This means that when <command>systemd-logind</command> is handling events by
+        itself (no low level inhibitor locks are taken by another application), the lid
+        switch does not respect suspend blockers by default, but the power and sleep keys
+        do.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml
index 9d85908f97..ce169960d8 100644
--- a/man/systemd-inhibit.xml
+++ b/man/systemd-inhibit.xml
@@ -61,7 +61,7 @@
     <title>Description</title>
 
     <para><command>systemd-inhibit</command> may be used to execute a
-    program with a shutdown, sleep or idle inhibitor lock taken. The
+    program with a shutdown, sleep, or idle inhibitor lock taken. The
     lock will be acquired before the specified command line is
     executed and released afterwards.</para>
 
diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml
index 5733e42cd1..f0bdb1c756 100644
--- a/man/systemd-logind.service.xml
+++ b/man/systemd-logind.service.xml
@@ -84,7 +84,7 @@
       management</para></listitem>
     </itemizedlist>
 
-    <para>User sessions are registered in logind via the
+    <para>User sessions are registered with logind via the
     <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     PAM module.</para>