release i3 v4.4

[i3/i3.github.io] / docs / userguide.html

diff --git a/docs/userguide.html b/docs/userguide.html
index 3f96d9e86e73ee5e136b9136a53f94c17c25cc7c..0f294dfb58732aa52910ea48210a2662948d40b3 100644 (file)
--- a/docs/userguide.html
+++ b/docs/userguide.html
@@ -49,16 +49,16 @@ contact us on IRC (preferred) or post your question(s) on the mailing list.</p><
 <div class="sectionbody">\r
 <div class="paragraph"><p>For the "too long; didn’t read" people, here is an overview of the default\r
 keybindings (click to see the full size image):</p></div>\r
-<div class="paragraph"><p><strong>Keys to use with mod (alt):</strong></p></div>\r
+<div class="paragraph"><p><strong>Keys to use with $mod (Alt):</strong></p></div>\r
 <div class="paragraph"><p><span class="image">\r
 <a class="image" href="keyboard-layer1.png">\r
-<img src="keyboard-layer1.png" alt="Keys to use with mod (alt)" width="600" />\r
+<img src="keyboard-layer1.png" alt="Keys to use with $mod (Alt)" width="600" />\r
 </a>\r
 </span></p></div>\r
-<div class="paragraph"><p><strong>Keys to use with Shift+mod:</strong></p></div>\r
+<div class="paragraph"><p><strong>Keys to use with Shift+$mod:</strong></p></div>\r
 <div class="paragraph"><p><span class="image">\r
 <a class="image" href="keyboard-layer2.png">\r
-<img src="keyboard-layer2.png" alt="Keys to use with Shift+mod" width="600" />\r
+<img src="keyboard-layer2.png" alt="Keys to use with Shift+$mod" width="600" />\r
 </a>\r
 </span></p></div>\r
 <div class="paragraph"><p>The red keys are the modifiers you need to press (by default), the blue keys\r
@@ -68,14 +68,14 @@ are your homerow.</p></div>
 <div class="sect1">\r
 <h2 id="_using_i3">2. Using i3</h2>\r
 <div class="sectionbody">\r
-<div class="paragraph"><p>Throughout this guide, the keyword <tt>mod</tt> will be used to refer to the\r
-configured modifier. This is the alt key (Mod1) by default, with windows (Mod4)\r
+<div class="paragraph"><p>Throughout this guide, the keyword <tt>$mod</tt> will be used to refer to the\r
+configured modifier. This is the Alt key (Mod1) by default, with windows (Mod4)\r
 being a popular alternative.</p></div>\r
 <div class="sect2">\r
 <h3 id="_opening_terminals_and_moving_around">2.1. Opening terminals and moving around</h3>\r
 <div class="paragraph"><p>One very basic operation is opening a new terminal. By default, the keybinding\r
-for this is mod+Enter, that is Alt+Enter in the default configuration. By\r
-pressing mod+Enter, a new terminal will be opened.  It will fill the whole\r
+for this is $mod+Enter, that is Alt+Enter in the default configuration. By\r
+pressing $mod+Enter, a new terminal will be opened.  It will fill the whole\r
 space available on your screen.</p></div>\r
 <div class="paragraph"><p><span class="image">\r
 <img src="single_terminal.png" alt="Single terminal" />\r
@@ -90,9 +90,9 @@ existing window (rotated displays).</p></div>
 <div class="paragraph"><p>To move the focus between the two terminals, you can use the direction keys\r
 which you may know from the editor <tt>vi</tt>. However, in i3, your homerow is used\r
 for these keys (in <tt>vi</tt>, the keys are shifted to the left by one for\r
-compatibility with most keyboard layouts). Therefore, <tt>mod+J</tt> is left, <tt>mod+K</tt>\r
-is down, <tt>mod+L</tt> is up and <tt>mod+;</tt> is right. So, to switch between the\r
-terminals, use <tt>mod+K</tt> or <tt>mod+L</tt>. Of course, you can also use the arrow keys.</p></div>\r
+compatibility with most keyboard layouts). Therefore, <tt>$mod+J</tt> is left, <tt>$mod+K</tt>\r
+is down, <tt>$mod+L</tt> is up and <tt>$mod+;</tt> is right. So, to switch between the\r
+terminals, use <tt>$mod+K</tt> or <tt>$mod+L</tt>. Of course, you can also use the arrow keys.</p></div>\r
 <div class="paragraph"><p>At the moment, your workspace is split (it contains two terminals) in a\r
 specific direction (horizontal by default). Every window can be split\r
 horizontally or vertically again, just like the workspace. The terminology is\r
@@ -100,8 +100,8 @@ horizontally or vertically again, just like the workspace. The terminology is
 or browser) and "split container" for containers that consist of one or more\r
 windows.</p></div>\r
 <div class="paragraph"><p>TODO: picture of the tree</p></div>\r
-<div class="paragraph"><p>To split a window vertically, press <tt>mod+v</tt> before you create the new window.\r
-To split it horizontally, press <tt>mod+h</tt>.</p></div>\r
+<div class="paragraph"><p>To split a window vertically, press <tt>$mod+v</tt> before you create the new window.\r
+To split it horizontally, press <tt>$mod+h</tt>.</p></div>\r
 </div>\r
 <div class="sect2">\r
 <h3 id="_changing_the_container_layout">2.2. Changing the container layout</h3>\r
@@ -137,8 +137,8 @@ a single line which is vertically split.
 </p>\r
 </dd>\r
 </dl></div>\r
-<div class="paragraph"><p>To switch modes, press <tt>mod+e</tt> for splith/splitv (it toggles), <tt>mod+s</tt> for\r
-stacking and <tt>mod+w</tt> for tabbed.</p></div>\r
+<div class="paragraph"><p>To switch modes, press <tt>$mod+e</tt> for splith/splitv (it toggles), <tt>$mod+s</tt> for\r
+stacking and <tt>$mod+w</tt> for tabbed.</p></div>\r
 <div class="paragraph"><p><span class="image">\r
 <img src="modes.png" alt="Container modes" />\r
 </span></p></div>\r
@@ -146,14 +146,14 @@ stacking and <tt>mod+w</tt> for tabbed.</p></div>
 <div class="sect2">\r
 <h3 id="_toggling_fullscreen_mode_for_a_window">2.3. Toggling fullscreen mode for a window</h3>\r
 <div class="paragraph"><p>To display a window in fullscreen mode or to go out of fullscreen mode again,\r
-press <tt>mod+f</tt>.</p></div>\r
+press <tt>$mod+f</tt>.</p></div>\r
 <div class="paragraph"><p>There is also a global fullscreen mode in i3 in which the client will span all\r
 available outputs (the command is <tt>fullscreen global</tt>).</p></div>\r
 </div>\r
 <div class="sect2">\r
 <h3 id="_opening_other_applications">2.4. Opening other applications</h3>\r
 <div class="paragraph"><p>Aside from opening applications from a terminal, you can also use the handy\r
-<tt>dmenu</tt> which is opened by pressing <tt>mod+d</tt> by default. Just type the name\r
+<tt>dmenu</tt> which is opened by pressing <tt>$mod+d</tt> by default. Just type the name\r
 (or a part of it) of the application which you want to open. The corresponding\r
 application has to be in your <tt>$PATH</tt> for this to work.</p></div>\r
 <div class="paragraph"><p>Additionally, if you have applications you open very frequently, you can\r
@@ -164,7 +164,7 @@ create a keybinding for starting the application directly. See the section
 <h3 id="_closing_windows">2.5. Closing windows</h3>\r
 <div class="paragraph"><p>If an application does not provide a mechanism for closing (most applications\r
 provide a menu, the escape key or a shortcut like <tt>Control+W</tt> to close), you\r
-can press <tt>mod+Shift+q</tt> to kill a window. For applications which support\r
+can press <tt>$mod+Shift+q</tt> to kill a window. For applications which support\r
 the WM_DELETE protocol, this will correctly close the application (saving\r
 any modifications or doing other cleanup). If the application doesn’t support\r
 the WM_DELETE protocol your X server will kill the window and the behaviour\r
@@ -174,7 +174,7 @@ depends on the application.</p></div>
 <h3 id="_using_workspaces">2.6. Using workspaces</h3>\r
 <div class="paragraph"><p>Workspaces are an easy way to group a set of windows. By default, you are on\r
 the first workspace, as the bar on the bottom left indicates. To switch to\r
-another workspace, press <tt>mod+num</tt> where <tt>num</tt> is the number of the workspace\r
+another workspace, press <tt>$mod+num</tt> where <tt>num</tt> is the number of the workspace\r
 you want to use. If the workspace does not exist yet, it will be created.</p></div>\r
 <div class="paragraph"><p>A common paradigm is to put the web browser on one workspace, communication\r
 applications (<tt>mutt</tt>, <tt>irssi</tt>, &#8230;) on another one, and the ones with which you\r
@@ -186,7 +186,7 @@ focus to that screen.</p></div>
 </div>\r
 <div class="sect2">\r
 <h3 id="_moving_windows_to_workspaces">2.7. Moving windows to workspaces</h3>\r
-<div class="paragraph"><p>To move a window to another workspace, simply press <tt>mod+Shift+num</tt> where\r
+<div class="paragraph"><p>To move a window to another workspace, simply press <tt>$mod+Shift+num</tt> where\r
 <tt>num</tt> is (like when switching workspaces) the number of the target workspace.\r
 Similarly to switching workspaces, the target workspace will be created if\r
 it does not yet exist.</p></div>\r
@@ -201,11 +201,11 @@ columns/rows with your keyboard.</p></div>
 <div class="sect2">\r
 <h3 id="_restarting_i3_inplace">2.9. Restarting i3 inplace</h3>\r
 <div class="paragraph"><p>To restart i3 inplace (and thus get into a clean state if there is a bug, or\r
-to upgrade to a newer version of i3) you can use <tt>mod+Shift+r</tt>.</p></div>\r
+to upgrade to a newer version of i3) you can use <tt>$mod+Shift+r</tt>.</p></div>\r
 </div>\r
 <div class="sect2">\r
 <h3 id="_exiting_i3">2.10. Exiting i3</h3>\r
-<div class="paragraph"><p>To cleanly exit i3 without killing your X server, you can use <tt>mod+Shift+e</tt>.</p></div>\r
+<div class="paragraph"><p>To cleanly exit i3 without killing your X server, you can use <tt>$mod+Shift+e</tt>.</p></div>\r
 </div>\r
 <div class="sect2">\r
 <h3 id="_floating">2.11. Floating</h3>\r
@@ -214,7 +214,7 @@ are not managed by i3, but by you. Using this mode violates the tiling
 paradigm but can be useful for some corner cases like "Save as" dialog\r
 windows, or toolbar windows (GIMP or similar). Those windows usually set the\r
 appropriate hint and are opened in floating mode by default.</p></div>\r
-<div class="paragraph"><p>You can toggle floating mode for a window by pressing <tt>mod+Shift+Space</tt>. By\r
+<div class="paragraph"><p>You can toggle floating mode for a window by pressing <tt>$mod+Shift+Space</tt>. By\r
 dragging the window’s titlebar with your mouse you can move the window\r
 around. By grabbing the borders and moving them you can resize the window. You\r
 can also do that by using the <a href="#floating_modifier">[floating_modifier]</a>.</p></div>\r
@@ -260,7 +260,7 @@ orientation (horizontal, vertical or unspecified) and the orientation depends
 on the layout the container is in (vertical for splitv and stacking, horizontal\r
 for splith and tabbed). So, in our example with the workspace, the default\r
 layout of the workspace <tt>Container</tt> is splith (most monitors are widescreen\r
-nowadays). If you change the layout to splitv (<tt>mod+l</tt> in the default config)\r
+nowadays). If you change the layout to splitv (<tt>$mod+l</tt> in the default config)\r
 and <strong>then</strong> open two terminals, i3 will configure your windows like this:</p></div>\r
 <div class="imageblock">\r
 <div class="content">\r
@@ -273,8 +273,8 @@ Let’s assume you have two terminals on a workspace (with splith layout, that i
 horizontal orientation), focus is on the right terminal. Now you want to open\r
 another terminal window below the current one. If you would just open a new\r
 terminal window, it would show up to the right due to the splith layout.\r
-Instead, press <tt>mod+v</tt> to split the container with the splitv layout (to\r
-open a <tt>Horizontal Split Container</tt>, use <tt>mod+h</tt>). Now you can open a new\r
+Instead, press <tt>$mod+v</tt> to split the container with the splitv layout (to\r
+open a <tt>Horizontal Split Container</tt>, use <tt>$mod+h</tt>). Now you can open a new\r
 terminal and it will open below the current one:</p></div>\r
 <div class="imageblock" style="float:right;">\r
 <div class="content">\r
@@ -316,7 +316,7 @@ command.</p></div>
 single workspace on which you open three terminal windows. All these terminal\r
 windows are directly attached to one node inside i3’s layout tree, the\r
 workspace node. By default, the workspace node’s orientation is <tt>horizontal</tt>.</p></div>\r
-<div class="paragraph"><p>Now you move one of these terminals down (<tt>mod+k</tt> by default). The workspace\r
+<div class="paragraph"><p>Now you move one of these terminals down (<tt>$mod+k</tt> by default). The workspace\r
 node’s orientation will be changed to <tt>vertical</tt>. The terminal window you moved\r
 down is directly attached to the workspace and appears on the bottom of the\r
 screen. A new (horizontal) container was created to accomodate the other two\r
@@ -376,13 +376,15 @@ and fall back to a working font.</p></div>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt>font &lt;X core font description&gt;\r
-font xft:&lt;a FreeType font description&gt;</tt></pre>\r
+font pango:[family list] [style options] [size]</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt>font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1\r
-font xft:DejaVu Sans Mono 10</tt></pre>\r
+font pango:DejaVu Sans Mono 10\r
+font pango:DejaVu Sans Mono, Terminus Bold Semi-Condensed 11\r
+font pango:Terminus 11x</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
@@ -426,10 +428,10 @@ bindcode [--release] [Modifiers+]keycode command</tt></pre>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt># Fullscreen\r
-bindsym mod+f fullscreen\r
+bindsym $mod+f fullscreen\r
 \r
 # Restart\r
-bindsym mod+Shift+r restart\r
+bindsym $mod+Shift+r restart\r
 \r
 # Notebook-specific hotkeys\r
 bindcode 214 exec --no-startup-id /home/michael/toggle_beamer.sh\r
@@ -544,17 +546,30 @@ start.</p></div>
 <div class="sect2">\r
 <h3 id="_border_style_for_new_windows">4.8. Border style for new windows</h3>\r
 <div class="paragraph"><p>This option determines which border style new windows will have. The default is\r
-"normal".</p></div>\r
+"normal". Note that new_float applies only to windows which are starting out as\r
+floating windows, e.g. dialog windows.</p></div>\r
 <div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>new_window &lt;normal|1pixel|none&gt;</tt></pre>\r
+<pre><tt>new_window &lt;normal|1pixel|none|pixel&gt;\r
+new_float &lt;normal|1pixel|none|pixel&gt;</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt>new_window 1pixel</tt></pre>\r
 </div></div>\r
+<div class="paragraph"><p>The "normal" and "pixel" border styles support an optional border width in\r
+pixels:</p></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt># The same as new_window none\r
+new_window pixel 0\r
+\r
+# A 3 px border\r
+new_window pixel 3</tt></pre>\r
+</div></div>\r
 </div>\r
 <div class="sect2">\r
 <h3 id="_hiding_vertical_borders">4.9. Hiding vertical borders</h3>\r
@@ -857,10 +872,16 @@ links in your browser window).</p></div>
 <div class="paragraph"><p>When you are in fullscreen mode, some applications still open popup windows\r
 (take Xpdf for example). This is because these applications may not be aware\r
 that they are in fullscreen mode (they do not check the corresponding hint).\r
-There are two things which are possible to do in this situation:</p></div>\r
+There are three things which are possible to do in this situation:</p></div>\r
 <div class="olist arabic"><ol class="arabic">\r
 <li>\r
 <p>\r
+Display the popup if it belongs to the fullscreen application only. This is\r
+   the default and should be reasonable behavior for most users.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
 Just ignore the popup (don’t map it). This won’t interrupt you while you are\r
    in fullscreen. However, some apps might react badly to this (deadlock until\r
    you go out of fullscreen).\r
@@ -868,19 +889,19 @@ Just ignore the popup (don’t map it). This won’t interrupt you while you are
 </li>\r
 <li>\r
 <p>\r
-Leave fullscreen mode. This is the default.\r
+Leave fullscreen mode.\r
 </p>\r
 </li>\r
 </ol></div>\r
 <div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>popup_during_fullscreen &lt;ignore|leave_fullscreen&gt;</tt></pre>\r
+<pre><tt>popup_during_fullscreen &lt;smart|ignore|leave_fullscreen&gt;</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>popup_during_fullscreen ignore</tt></pre>\r
+<pre><tt>popup_during_fullscreen smart</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
@@ -934,7 +955,7 @@ Xinerama, instead they are counted up, starting at 0: <tt>xinerama-0</tt>, <tt>x
 <a href="#back_and_forth">[back_and_forth]</a>) when switching to the workspace that is currently focused.</p></div>\r
 <div class="paragraph"><p>For instance: Assume you are on workspace "1: www" and switch to "2: IM" using\r
 mod+2 because somebody sent you a message. You don’t need to remember where you\r
-came from now, you can just press mod+2 again to switch back to "1: www".</p></div>\r
+came from now, you can just press $mod+2 again to switch back to "1: www".</p></div>\r
 <div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
@@ -946,6 +967,28 @@ came from now, you can just press mod+2 again to switch back to "1: www".</p></d
 <pre><tt>workspace_auto_back_and_forth yes</tt></pre>\r
 </div></div>\r
 </div>\r
+<div class="sect2">\r
+<h3 id="_delaying_urgency_hint_reset_on_workspace_change">4.22. Delaying urgency hint reset on workspace change</h3>\r
+<div class="paragraph"><p>If an application on another workspace sets an urgency hint, switching to this\r
+workspace may lead to immediate focus of the application, which also means the\r
+window decoration color would be immediately resetted to <tt>client.focused</tt>. This\r
+may make it unnecessarily hard to tell which window originally raised the\r
+event.</p></div>\r
+<div class="paragraph"><p>In order to prevent this, you can tell i3 to delay resetting the urgency state\r
+by a certain time using the <tt>force_display_urgency_hint</tt> directive. Setting the\r
+value to 0 disables this feature.</p></div>\r
+<div class="paragraph"><p>The default is 500ms.</p></div>\r
+<div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>force_display_urgency_hint &lt;timeout&gt; ms</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p><strong>Example</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>force_display_urgency_hint 500 ms</tt></pre>\r
+</div></div>\r
+</div>\r
 </div>\r
 </div>\r
 <div class="sect1">\r
@@ -1154,7 +1197,7 @@ bar {
 <div class="content">\r
 <pre><tt>bar {\r
     font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1\r
-    font xft:DejaVu Sans Mono 10\r
+    font pango:DejaVu Sans Mono 10\r
 }</tt></pre>\r
 </div></div>\r
 </div>\r
@@ -1283,7 +1326,7 @@ the following keybinding:</p></div>
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+x move container to workspace 3; workspace 3</tt></pre>\r
+<pre><tt>bindsym $mod+x move container to workspace 3; workspace 3</tt></pre>\r
 </div></div>\r
 <div class="paragraph" id="command_criteria"><p>Furthermore, you can change the scope of a command, that is, which containers\r
 should be affected by that command, by using various criteria. These are\r
@@ -1292,10 +1335,10 @@ which have the class Firefox, use:</p></div>
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+x [class="Firefox"] kill\r
+<pre><tt>bindsym $mod+x [class="Firefox"] kill\r
 \r
 # same thing, but case-insensitive\r
-bindsym mod+x [class="(?i)firefox"] kill</tt></pre>\r
+bindsym $mod+x [class="(?i)firefox"] kill</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p>The criteria which are currently implemented are:</p></div>\r
 <div class="dlist"><dl>\r
@@ -1385,10 +1428,10 @@ searched in your $PATH.</p></div>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt># Start the GIMP\r
-bindsym mod+g exec gimp\r
+bindsym $mod+g exec gimp\r
 \r
 # Start the terminal emulator urxvt which is not yet startup-notification-aware\r
-bindsym mod+Return exec --no-startup-id urxvt</tt></pre>\r
+bindsym $mod+Return exec --no-startup-id urxvt</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p>The <tt>--no-startup-id</tt> parameter disables startup-notification support for this\r
 particular exec command. With startup-notification, i3 can make sure that a\r
@@ -1417,8 +1460,8 @@ to splith or vice-versa.</p></div>
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+v split vertical\r
-bindsym mod+h split horizontal</tt></pre>\r
+<pre><tt>bindsym $mod+v split vertical\r
+bindsym $mod+h split horizontal</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
@@ -1438,21 +1481,21 @@ layout toggle [split|all]</tt></pre>
 <div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+s layout stacking\r
-bindsym mod+l layout toggle split\r
-bindsym mod+w layout tabbed\r
+<pre><tt>bindsym $mod+s layout stacking\r
+bindsym $mod+l layout toggle split\r
+bindsym $mod+w layout tabbed\r
 \r
 # Toggle between stacking/tabbed/split:\r
-bindsym mod+x layout toggle\r
+bindsym $mod+x layout toggle\r
 \r
 # Toggle between stacking/tabbed/splith/splitv:\r
-bindsym mod+x layout toggle all\r
+bindsym $mod+x layout toggle all\r
 \r
 # Toggle fullscreen\r
-bindsym mod+f fullscreen\r
+bindsym $mod+f fullscreen\r
 \r
 # Toggle floating/tiling\r
-bindsym mod+t floating toggle</tt></pre>\r
+bindsym $mod+t floating toggle</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
@@ -1528,36 +1571,36 @@ relevant for floating containers. The default amount is 10 pixels.</p></div>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt># Focus container on the left, bottom, top, right:\r
-bindsym mod+j focus left\r
-bindsym mod+k focus down\r
-bindsym mod+l focus up\r
-bindsym mod+semicolon focus right\r
+bindsym $mod+j focus left\r
+bindsym $mod+k focus down\r
+bindsym $mod+l focus up\r
+bindsym $mod+semicolon focus right\r
 \r
 # Focus parent container\r
-bindsym mod+u focus parent\r
+bindsym $mod+u focus parent\r
 \r
 # Focus last floating/tiling container\r
-bindsym mod+g focus mode_toggle\r
+bindsym $mod+g focus mode_toggle\r
 \r
 # Focus the output right to the current one\r
-bindsym mod+x focus output right\r
+bindsym $mod+x focus output right\r
 \r
 # Focus the big output\r
-bindsym mod+x focus output HDMI-2\r
+bindsym $mod+x focus output HDMI-2\r
 \r
 # Move container to the left, bottom, top, right:\r
-bindsym mod+j move left\r
-bindsym mod+k move down\r
-bindsym mod+l move up\r
-bindsym mod+semicolon move right\r
+bindsym $mod+j move left\r
+bindsym $mod+k move down\r
+bindsym $mod+l move up\r
+bindsym $mod+semicolon move right\r
 \r
 # Move container, but make floating containers\r
 # move more than the default\r
-bindsym mod+j move left 20 px\r
+bindsym $mod+j move left 20 px\r
 \r
 # Move floating container to the center\r
 # of all outputs\r
-bindsym mod+c move absolute position center</tt></pre>\r
+bindsym $mod+c move absolute position center</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
@@ -1576,38 +1619,40 @@ container to the next/previous workspace and <tt>move container to workspace cur
 <div class="paragraph"><p>See <a href="#move_to_outputs">[move_to_outputs]</a> for how to move a container/workspace to a different\r
 RandR output.</p></div>\r
 <div class="paragraph" id="back_and_forth"><p>To switch back to the previously focused workspace, use <tt>workspace\r
-back_and_forth</tt>.</p></div>\r
+back_and_forth</tt>; likewise, you can move containers to the previously focused\r
+workspace using <tt>move container to workspace back_and_forth</tt>.</p></div>\r
 <div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt>workspace &lt;next|prev|next_on_output|prev_on_output&gt;\r
 workspace back_and_forth\r
 workspace &lt;name&gt;\r
-workspace number &lt;number&gt;\r
+workspace number &lt;name&gt;\r
 \r
 move [window|container] [to] workspace &lt;name&gt;\r
-move [window|container] [to] workspace number &lt;number&gt;\r
+move [window|container] [to] workspace number &lt;name&gt;\r
 move [window|container] [to] workspace &lt;prev|next|current&gt;</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+1 workspace 1\r
-bindsym mod+2 workspace 2\r
+<pre><tt>bindsym $mod+1 workspace 1\r
+bindsym $mod+2 workspace 2\r
 ...\r
 \r
-bindsym mod+Shift+1 move container to workspace 1\r
-bindsym mod+Shift+2 move container to workspace 2\r
+bindsym $mod+Shift+1 move container to workspace 1\r
+bindsym $mod+Shift+2 move container to workspace 2\r
 ...\r
 \r
 # switch between the current and the previously focused one\r
-bindsym mod+b workspace back_and_forth\r
+bindsym $mod+b workspace back_and_forth\r
+bindsym $mod+Shift+b move container to workspace back_and_forth\r
 \r
 # move the whole workspace to the next output\r
-bindsym mod+x move workspace to output right\r
+bindsym $mod+x move workspace to output right\r
 \r
 # move firefox to current workspace\r
-bindsym mod+F1 [class="Firefox"] move workspace current</tt></pre>\r
+bindsym $mod+F1 [class="Firefox"] move workspace current</tt></pre>\r
 </div></div>\r
 <div class="sect3">\r
 <h4 id="_named_workspaces">6.5.1. Named workspaces</h4>\r
@@ -1616,7 +1661,7 @@ workspace command, you can use an arbitrary name:</p></div>
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+1 workspace mail\r
+<pre><tt>bindsym $mod+1 workspace mail\r
 ...</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p>If you want the workspace to have a number <strong>and</strong> a name, just prefix the\r
@@ -1624,8 +1669,8 @@ number, like this:</p></div>
 <div class="paragraph"><p><strong>Example</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+1 workspace 1: mail\r
-bindsym mod+2 workspace 2: www\r
+<pre><tt>bindsym $mod+1 workspace 1: mail\r
+bindsym $mod+2 workspace 2: www\r
 ...</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p>Note that the workspace will really be named "1: mail". i3 treats workspace\r
@@ -1634,29 +1679,40 @@ workspaces are ordered the way they appeared. When they start with a number, i3
 will order them numerically. Also, you will be able to use <tt>workspace number 1</tt>\r
 to switch to the workspace which begins with number 1, regardless of which name\r
 it has. This is useful in case you are changing the workspace’s name\r
-dynamically.</p></div>\r
+dynamically. To combine both commands you can use <tt>workspace number 1: mail</tt> to\r
+specify a default name if there&#8217;s currently no workspace starting with a "1".</p></div>\r
 </div>\r
 <div class="sect3">\r
 <h4 id="_renaming_workspaces">6.5.2. Renaming workspaces</h4>\r
 <div class="paragraph"><p>You can rename workspaces. This might be useful to start with the default\r
 numbered workspaces, do your work, and rename the workspaces afterwards to\r
-reflect what’s actually on them.</p></div>\r
+reflect what’s actually on them. You can also omit the old name to rename\r
+the currently focused workspace. This is handy if you wan&#8217;t to use the\r
+rename command with <tt>i3-input</tt>.</p></div>\r
 <div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>rename workspace &lt;old_name&gt; to &lt;new_name&gt;</tt></pre>\r
+<pre><tt>rename workspace &lt;old_name&gt; to &lt;new_name&gt;\r
+rename workspace to &lt;new_name&gt;</tt></pre>\r
 </div></div>\r
 <div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt>i3-msg 'rename workspace 5 to 6'\r
 i3-msg 'rename workspace 1 to "1: www"'\r
-i3-msg 'rename workspace "1: www" to "10: www"'</tt></pre>\r
+i3-msg 'rename workspace "1: www" to "10: www"'\r
+i3-msg 'rename workspace to "2: mail"\r
+bindsym $mod+r exec i3-input -F 'rename workspace to %s' -P 'New name: '</tt></pre>\r
 </div></div>\r
 </div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="_moving_containers_workspaces_to_randr_outputs">6.6. Moving containers/workspaces to RandR outputs</h3>\r
+<h3 id="_moving_workspaces_to_a_different_screen">6.6. Moving workspaces to a different screen</h3>\r
+<div class="paragraph"><p>See <a href="#move_to_outputs">[move_to_outputs]</a> for how to move a container/workspace to a different\r
+RandR output.</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_moving_containers_workspaces_to_randr_outputs">6.7. Moving containers/workspaces to RandR outputs</h3>\r
 <div class="paragraph" id="move_to_outputs"><p>To move a container to another RandR output (addressed by names like <tt>LVDS1</tt> or\r
 <tt>VGA1</tt>) or to a RandR output identified by a specific direction (like <tt>left</tt>,\r
 <tt>right</tt>, <tt>up</tt> or <tt>down</tt>), there are two commands:</p></div>\r
@@ -1671,14 +1727,14 @@ move workspace to output &lt;&lt;left|right|down|up&gt;|&lt;output&gt;&gt;</tt><
 <div class="content">\r
 <pre><tt># Move the current workspace to the next output\r
 # (effectively toggles when you only have two outputs)\r
-bindsym mod+x move workspace to output right\r
+bindsym $mod+x move workspace to output right\r
 \r
 # Put this window on the presentation output.\r
-bindsym mod+x move container to output VGA1</tt></pre>\r
+bindsym $mod+x move container to output VGA1</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="resizingconfig">6.7. Resizing containers/windows</h3>\r
+<h3 id="resizingconfig">6.8. Resizing containers/windows</h3>\r
 <div class="paragraph"><p>If you want to resize containers/windows using your keyboard, you can use the\r
 <tt>resize</tt> command:</p></div>\r
 <div class="paragraph"><p><strong>Syntax</strong>:</p></div>\r
@@ -1721,11 +1777,11 @@ default is 10 percentage points).</p></div>
 }\r
 \r
 # Enter resize mode\r
-bindsym mod+r mode "resize"</tt></pre>\r
+bindsym $mod+r mode "resize"</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="_jumping_to_specific_windows">6.8. Jumping to specific windows</h3>\r
+<h3 id="_jumping_to_specific_windows">6.9. Jumping to specific windows</h3>\r
 <div class="paragraph"><p>Often when in a multi-monitor environment, you want to quickly jump to a\r
 specific window. For example, while working on workspace 3 you may want to\r
 jump to your mail client to email your boss that you’ve achieved some\r
@@ -1742,11 +1798,11 @@ with criteria for that.</p></div>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt># Get me to the next open VIM instance\r
-bindsym mod+a [class="urxvt" title="VIM"] focus</tt></pre>\r
+bindsym $mod+a [class="urxvt" title="VIM"] focus</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="_vim_like_marks_mark_goto">6.9. VIM-like marks (mark/goto)</h3>\r
+<h3 id="_vim_like_marks_mark_goto">6.10. VIM-like marks (mark/goto)</h3>\r
 <div class="paragraph" id="vim_like_marks"><p>This feature is like the jump feature: It allows you to directly jump to a\r
 specific window (this means switching to the appropriate workspace and setting\r
 focus to the windows). However, you can directly mark a specific window with\r
@@ -1771,7 +1827,7 @@ $ i3-msg '[con_mark="irssi"] focus'</tt></pre>
 </div></div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="_changing_border_style">6.10. Changing border style</h3>\r
+<h3 id="_changing_border_style">6.11. Changing border style</h3>\r
 <div class="paragraph"><p>To change the border of the current client, you can use <tt>border normal</tt> to use the normal\r
 border (including window title), <tt>border 1pixel</tt> to use a 1-pixel border (no window title)\r
 and <tt>border none</tt> to make the client borderless.</p></div>\r
@@ -1779,13 +1835,13 @@ and <tt>border none</tt> to make the client borderless.</p></div>
 <div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+t border normal\r
-bindsym mod+y border 1pixel\r
-bindsym mod+u border none</tt></pre>\r
+<pre><tt>bindsym $mod+t border normal\r
+bindsym $mod+y border 1pixel\r
+bindsym $mod+u border none</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="stack-limit">6.11. Reloading/Restarting/Exiting</h3>\r
+<h3 id="stack-limit">6.12. Reloading/Restarting/Exiting</h3>\r
 <div class="paragraph"><p>You can make i3 reload its configuration file with <tt>reload</tt>. You can also\r
 restart i3 inplace with the <tt>restart</tt> command to get it out of some weird state\r
 (if that should ever happen) or to perform an upgrade without having to restart\r
@@ -1794,20 +1850,22 @@ however you don’t need to (simply killing your X session is fine as well).</p>
 <div class="paragraph"><p><strong>Examples</strong>:</p></div>\r
 <div class="listingblock">\r
 <div class="content">\r
-<pre><tt>bindsym mod+Shift+r restart\r
-bindsym mod+Shift+w reload\r
-bindsym mod+Shift+e exit</tt></pre>\r
+<pre><tt>bindsym $mod+Shift+r restart\r
+bindsym $mod+Shift+w reload\r
+bindsym $mod+Shift+e exit</tt></pre>\r
 </div></div>\r
 </div>\r
 <div class="sect2">\r
-<h3 id="_scratchpad">6.12. Scratchpad</h3>\r
+<h3 id="_scratchpad">6.13. Scratchpad</h3>\r
 <div class="paragraph"><p>There are two commands to use any existing window as scratchpad window. <tt>move\r
 scratchpad</tt> will move a window to the scratchpad workspace. This will make it\r
 invisible until you show it again. There is no way to open that workspace.\r
 Instead, when using <tt>scratchpad show</tt>, the window will be shown again, as a\r
 floating window, centered on your current workspace (using <tt>scratchpad show</tt> on\r
 a visible scratchpad window will make it hidden again, so you can have a\r
-keybinding to toggle).</p></div>\r
+keybinding to toggle). Note that this is just a normal floating window, so if\r
+you want to "remove it from scratchpad", you can simple make it tiling again\r
+(<tt>floating toggle</tt>).</p></div>\r
 <div class="paragraph"><p>As the name indicates, this is useful for having a window with your favorite\r
 editor always at hand. However, you can also use this for other permanently\r
 running applications which you don’t want to see all the time: Your music\r
@@ -1823,10 +1881,10 @@ scratchpad show</tt></pre>
 <div class="listingblock">\r
 <div class="content">\r
 <pre><tt># Make the currently focused window a scratchpad\r
-bindsym mod+Shift+minus move scratchpad\r
+bindsym $mod+Shift+minus move scratchpad\r
 \r
 # Show the first scratchpad window\r
-bindsym mod+minus scratchpad show\r
+bindsym $mod+minus scratchpad show\r
 \r
 # Show the sup-mail scratchpad window, if any.\r
 bindsym mod4+s [title="^Sup ::"] scratchpad show</tt></pre>\r
@@ -1947,6 +2005,12 @@ If you have many workspaces on many monitors, it might get hard to keep
    quickly switch between windows. See <a href="#vim_like_marks">[vim_like_marks]</a>.\r
 </p>\r
 </li>\r
+<li>\r
+<p>\r
+For information on how to move existing workspaces between monitors,\r
+   see <a href="#_moving_containers_workspaces_to_randr_outputs">[_moving_containers_workspaces_to_randr_outputs]</a>.\r
+</p>\r
+</li>\r
 </ol></div>\r
 </div>\r
 </div>\r