docs/userguide: properly document command chaining and criteria

diff --git a/docs/userguide b/docs/userguide
index dbb6efa30ee40ad069a76e3e1453259731601d6d..50c8b2617d893d03c9e803a3771ddb35c6572e63 100644 (file)
--- a/docs/userguide
+++ b/docs/userguide
@@ -690,6 +690,54 @@ force_focus_wrapping yes
 
 == List of commands
 
+Commands are what you bind to specific keypresses. You can also issue commands
+at runtime without pressing a key by using the IPC interface. An easy way to
+do this is to use the +i3-msg+ utility:
+
+*Example*:
+--------------------------
+# execute this on your shell to make the current container borderless
+i3-msg border none
+--------------------------
+
+Commands can be chained by using +;+ (a semicolon). So, to move a window to a
+specific workspace and immediately switch to that workspace, you can configure
+the following keybinding:
+
+*Example*:
+-------------------------------------------
+bindsym mod+x move workspace 3; workspace 3
+-------------------------------------------
+
+Furthermore, you can change the scope of a command, that is, which containers
+should be affected by that command, by using various criteria. These are
+prefixed in square brackets to every command. If you want to kill all windows
+which have the class Firefox, use:
+
+*Example*:
+------------------------------------
+bindsym mod+x [class="Firefox"] kill
+------------------------------------
+
+The criteria which are currently implemented are:
+
+class::
+       Compares the window class (the second part of WM_CLASS)
+instance::
+       Compares the window instance (the first part of WM_CLASS)
+id::
+       Compares the X11 window ID, which you can get via +xwininfo+ for example.
+title::
+       Compares the X11 window title (_NET_WM_NAME or WM_NAME as fallback).
+mark::
+       Compares the mark set for this container, see <<vim_like_marks>>.
+con_id::
+       Compares the i3-internal container ID, which you can get via the IPC
+       interface. Handy for scripting.
+
+Note that currently all criteria are compared case-insensitive and do not
+support regular expressions. This is planned to change in the future.
+
 === Splitting containers
 
 The split command makes the current window a split container. Split containers