recommend using xss-lock to start i3lock

related to i3#207
related to i3#311
fixes i3#310

Author: stapelberg

README.md

@@ -56,8 +56,16 @@ Requirements
 
 Running i3lock
 -------------
-Simply invoke the 'i3lock' command. To get out of it, enter your password and
-press enter.
+
+To test i3lock, you can directly run the `i3lock` command. To get out of it,
+enter your password and press enter.
+
+For a more permanent setup, we strongly recommend using `xss-lock` so that the
+screen is locked *before* your laptop suspends:
+
+```
+xss-lock --transfer-sleep-lock -- i3lock --nofork
+```
 
 On OpenBSD the `i3lock` binary needs to be setgid `auth` to call the
 authentication helpers, e.g. `/usr/libexec/auth/login_passwd`.

i3lock.1

@@ -31,6 +31,20 @@ i3lock \- improved screen locker
 .RB [\|\-u\|]
 .RB [\|\-e\|]
 
+.SH RECOMMENDED USAGE
+.RB xss-lock
+.RB --transfer-sleep-lock
+.RB --
+.RB i3lock
+.RB --nofork
+
+Using
+.B xss-lock
+ensures that your screen is locked before your laptop suspends.
+
+Notably, using a systemd service file is not adequate, as it will not delay
+suspend until your screen is locked.
+
 .SH DESCRIPTION
 .B i3lock
 is a simple screen locker like slock. After starting it, you will see a white
@@ -156,8 +170,8 @@ use a wrapper script around i3lock like the following:
 The \-I (-\-inactivity-timeout=seconds) was removed because it only makes sense with DPMS.
 
 .SH SEE ALSO
-.IR xautolock(1)
-\- use i3lock as your screen saver
+.IR xss-lock(1)
+\- hooks up i3lock to the systemd login manager
 
 .IR convert(1)
 \- feed a wide variety of image formats to i3lock