Implement scratchpad functionality (see userguide)

[i3/i3] / docs / userguide

diff --git a/docs/userguide b/docs/userguide
index 26c12b77ce62434e753e9b921241f833c2facdd7..5785eca9f4ce0dbc3d6e8076fc1156dbe69c1eda 100644 (file)
--- a/docs/userguide
+++ b/docs/userguide
@@ -643,16 +643,19 @@ programs to get information from i3, such as the current workspaces
 (to display a workspace bar), and to control i3.
 
 The IPC socket is enabled by default and will be created in
-+/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the PID
-of i3.
++/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
+the PID of i3 and XXXXXX is a string of random characters from the portable
+filename character set (see mkdtemp(3)).
 
 You can override the default path through the environment-variable +I3SOCK+ or
 by specifying the +ipc-socket+ directive. This is discouraged, though, since i3
-does the right thing by default.
+does the right thing by default. If you decide to change it, it is strongly
+recommended to set this to a location in your home directory so that no other
+user can create that directory.
 
 *Examples*:
 ----------------------------
-ipc-socket /tmp/i3-ipc.sock
+ipc-socket ~/.i3/i3-ipc.sock
 ----------------------------
 
 You can then use the +i3-msg+ application to perform any command listed in
@@ -1453,6 +1456,40 @@ bindsym mod+Shift+w reload
 bindsym mod+Shift+e exit
 ----------------------------
 
+=== Scratchpad
+
+There are two commands to use any existing window as scratchpad window. +move
+scratchpad+ will move a window to the scratchpad workspace. This will make it
+invisible until you show it again. There is no way to open that workspace.
+Instead, when using +scratchpad show+, the window will be shown again, as a
+floating window, centered on your current workspace (using +scratchpad show+ on
+a visible scratchpad window will make it hidden again, so you can have a
+keybinding to toggle).
+
+As the name indicates, this is useful for having a window with your favorite
+editor always at hand. However, you can also use this for other permanently
+running applications which you don’t want to see all the time: Your music
+player, alsamixer, maybe even your mail client…?
+
+*Syntax*:
+---------------
+move scratchpad
+
+scratchpad show
+---------------
+
+*Examples*:
+------------------------------------------------
+# Make the currently focused window a scratchpad
+bindsym mod+Shift+minus move scratchpad
+
+# Show the first scratchpad window
+bindsym mod+minus scratchpad show
+
+# Show the sup-mail scratchpad window, if any.
+bindsym mod4+s [title="^Sup ::"] scratchpad show
+------------------------------------------------
+
 [[multi_monitor]]
 
 == Multiple monitors