Merge branch 'master' into next

[i3/i3] / docs / userguide

diff --git a/docs/userguide b/docs/userguide
index e75f1ca10e7e2acb470402b10ec760b2031b2540..7145442d2d2659610574ea3a6013abde681ab482 100644 (file)
--- a/docs/userguide
+++ b/docs/userguide
@@ -799,6 +799,28 @@ bar {
 }
 ---------------------------
 
+=== i3bar command
+
+By default i3 will just pass +i3bar+ and let your shell handle the execution,
+searching your +$PATH+ for a correct version.
+If you have a different +i3bar+ somewhere or the binary is not in your +$PATH+ you can
+tell i3 what to execute.
+
+The specified command will be passed to +sh -c+, so you can use globbing and
+have to have correct quoting etc.
+
+*Syntax*:
+----------------------
+i3bar_command command
+----------------------
+
+*Example*:
+-------------------------------------------------
+bar {
+    i3bar_command /home/user/bin/i3bar
+}
+-------------------------------------------------
+
 === Statusline command
 
 i3bar can run a program and display every line of its +stdout+ output on the
@@ -815,7 +837,9 @@ status_command command
 
 *Example*:
 -------------------------------------------------
-status_command i3status --config ~/.i3status.conf
+bar {
+    status_command i3status --config ~/.i3status.conf
+}
 -------------------------------------------------
 
 === Display mode
@@ -837,7 +861,9 @@ mode <dock|hide>
 
 *Example*:
 ----------------
-mode hide
+bar {
+    mode hide
+}
 ----------------
 
 === Position
@@ -853,7 +879,9 @@ position <top|bottom>
 
 *Example*:
 ---------------------
-position top
+bar {
+    position top
+}
 ---------------------
 
 === Output(s)
@@ -862,6 +890,9 @@ You can restrict i3bar to one or more outputs (monitors). The default is to
 handle all outputs. Restricting the outputs is useful for using different
 options for different outputs by using multiple 'bar' blocks.
 
+To make a particular i3bar instance handle multiple outputs, specify the output
+directive multiple times.
+
 *Syntax*:
 ---------------
 output <output>
@@ -871,18 +902,20 @@ output <output>
 -------------------------------
 # big monitor: everything
 bar {
-       output HDMI2
-       status_command i3status
+    # The display is connected either via HDMI or via DisplayPort
+    output HDMI2
+    output DP2
+    status_command i3status
 }
 
 # laptop monitor: bright colors and i3status with less modules.
 bar {
-       output LVDS1
-       status_command i3status --config ~/.i3status-small.conf
-       colors {
-               background #000000
-               statusline #ffffff
-       }
+    output LVDS1
+    status_command i3status --config ~/.i3status-small.conf
+    colors {
+        background #000000
+        statusline #ffffff
+    }
 }
 -------------------------------
 
@@ -902,10 +935,14 @@ tray_output <none|output>
 *Example*:
 -------------------------
 # disable system tray
-tray_output none
+bar {
+    tray_output none
+}
 
 # show tray icons on the big monitor
-tray_output HDMI2
+bar {
+    tray_output HDMI2
+}
 -------------------------
 
 === Font
@@ -920,7 +957,9 @@ font <font>
 
 *Example*:
 --------------------------------------------------------------
-font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+bar {
+    font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+}
 --------------------------------------------------------------
 
 === Workspace buttons
@@ -937,7 +976,9 @@ workspace_buttons <yes|no>
 
 *Example*:
 --------------------
-workspace_buttons no
+bar {
+    workspace_buttons no
+}
 --------------------
 
 === Colors
@@ -977,14 +1018,16 @@ colors {
 
 *Example*:
 --------------------------------------
-colors {
-    background #000000
-    statusline #ffffff
-
-    focused_workspace  #ffffff #285577
-    active_workspace   #ffffff #333333
-    inactive_workspace #888888 #222222
-    urgent_workspace   #ffffff #900000
+bar {
+    colors {
+        background #000000
+        statusline #ffffff
+
+        focused_workspace  #ffffff #285577
+        active_workspace   #ffffff #333333
+        inactive_workspace #888888 #222222
+        urgent_workspace   #ffffff #900000
+    }
 }
 --------------------------------------
 
@@ -1066,7 +1109,7 @@ exec [--no-startup-id] command
 bindsym mod+g exec gimp
 
 # Start the terminal emulator urxvt which is not yet startup-notification-aware
-bindsym mod+enter exec --no-startup-id urxvt
+bindsym mod+Return exec --no-startup-id urxvt
 ------------------------------
 
 The +--no-startup-id+ parameter disables startup-notification support for this
@@ -1413,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