]> git.sur5r.net Git - i3/i3/blobdiff - docs/userguide
Merge branch 'master' into next
[i3/i3] / docs / userguide
index aea0e760a3a387df219d80be91449d48ae5cce88..05a0b1e8fb8ed33d07d7448dcec75d3d5baf7920 100644 (file)
@@ -1,49 +1,38 @@
 i3 User’s Guide
 ===============
 Michael Stapelberg <michael+i3@stapelberg.de>
-May 2011
-
-*********************************************************************************
-This document is not yet finished. The tree branch is still in development. The
-information provided here should be correct, just not complete yet.
-*********************************************************************************
+August 2011
 
 This document contains all the information you need to configure and use the i3
 window manager. If it does not, please contact us on IRC (preferred) or post your
 question(s) on the mailing list.
 
-//////////////////////////////////////////////////////////////////////////////
 == Default keybindings
 
 For the "too long; didn’t read" people, here is an overview of the default
 keybindings (click to see the full size image):
 
-*Keys to use with Mod1 (alt):*
-
-image:keyboard-layer1.png["Keys to use with Mod1 (alt)",width=600,link="keyboard-layer1.png"]
+*Keys to use with mod (alt):*
 
-*Keys to use with Shift+Mod1:*
+image:keyboard-layer1.png["Keys to use with mod (alt)",width=600,link="keyboard-layer1.png"]
 
-image:keyboard-layer2.png["Keys to use with Shift+Mod1",width=600,link="keyboard-layer2.png"]
+*Keys to use with Shift+mod:*
 
-As i3 uses keycodes in the default configuration, it does not matter which
-keyboard layout you actually use. The key positions are what matters (of course
-you can also use keysymbols, see <<keybindings>>).
+image:keyboard-layer2.png["Keys to use with Shift+mod",width=600,link="keyboard-layer2.png"]
 
 The red keys are the modifiers you need to press (by default), the blue keys
 are your homerow.
-//////////////////////////////////////////////////////////////////////////////
 
 == Using i3
 
 Throughout this guide, the keyword +mod+ will be used to refer to the
-configured modifier. This is the windows key (mod4) by default, with alt (mod1)
+configured modifier. This is the alt key (Mod1) by default, with windows (Mod4)
 being a popular alternative.
 
 === Opening terminals and moving around
 
 One very basic operation is opening a new terminal. By default, the keybinding
-for this is mod+Enter, that is Win+Enter in the default configuration. By
+for this is mod+Enter, that is Alt+Enter in the default configuration. By
 pressing mod+Enter, a new terminal will be opened.  It will fill the whole
 space available on your screen.
 
@@ -51,17 +40,17 @@ image:single_terminal.png[Single terminal]
 
 If you now open another terminal, i3 will place it next to the current one,
 splitting the screen size in half. Depending on your monitor, i3 will put the
-new window right to the old window (for widescreen) or below the old window
-(rotated displays).
+created window beside the existing window (on wide displays) or below the
+existing window (rotated displays).
 
 image:two_terminals.png[Two terminals]
 
-To move the focus between the two terminals, you use the direction keys which
-you may know from the editor +vi+. However, in i3, your homerow is used for
-these keys (in +vi+, the keys are shifted to the left by one for compatibility
-with most keyboard layouts). Therefore, +mod+J+ is left, +mod+K+ is down,
-+mod+L+ is up and `mod+;` is right. So, to switch between the terminals,
-use +mod+K+ or +mod+L+.
+To move the focus between the two terminals, you can use the direction keys
+which you may know from the editor +vi+. However, in i3, your homerow is used
+for these keys (in +vi+, the keys are shifted to the left by one for
+compatibility with most keyboard layouts). Therefore, +mod+J+ is left, +mod+K+
+is down, +mod+L+ is up and `mod+;` is right. So, to switch between the
+terminals, use +mod+K+ or +mod+L+. Of course, you can also use the arrow keys.
 
 At the moment, your workspace is split (it contains two terminals) in a
 specific direction (horizontal by default). Every window can be split
@@ -75,9 +64,9 @@ TODO: picture of the tree
 To split a window vertically, press +mod+v+. To split it horizontally, press
 +mod+h+.
 
-=== Changing container modes
+=== Changing the container layout
 
-A container can have the following modes:
+A split container can have one of the following layouts:
 
 default::
 Windows are sized so that every window gets an equal amount of space in the
@@ -89,39 +78,35 @@ tabbed::
 The same principle as +stacking+, but the list of windows at the top is only
 a single line which is vertically split.
 
-To switch modes, press +Mod1+e+ for default, +Mod1+h+ for stacking and
-+Mod1+w+ for tabbed.
+To switch modes, press +mod+e+ for default, +mod+s+ for stacking and
++mod+w+ for tabbed.
 
 image:modes.png[Container modes]
 
 === Toggling fullscreen mode for a window
 
-To display a window fullscreen or to go out of fullscreen mode again, press
-+mod+f+.
-
-/////////////////////////////////////////////////////////////////////////////
-TODO: not yet implemented
+To display a window in fullscreen mode or to go out of fullscreen mode again,
+press +mod+f+.
 
-There is also a global fullscreen mode in i3 in which the client will use all
-available outputs. To use it, or to get out of it again, press +mod+Shift+f+.
-/////////////////////////////////////////////////////////////////////////////
+There is also a global fullscreen mode in i3 in which the client will span all
+available outputs.
 
 === Opening other applications
 
 Aside from opening applications from a terminal, you can also use the handy
-+dmenu+ which is opened by pressing +mod+p+ by default. Just type the name
-(or a part of it) of the application which you want to open. The application
-typed has to be in your +$PATH+ for this to work.
++dmenu+ which is opened by pressing +mod+d+ by default. Just type the name
+(or a part of it) of the application which you want to open. The corresponding
+application has to be in your +$PATH+ for this to work.
 
 Additionally, if you have applications you open very frequently, you can
 create a keybinding for starting the application directly. See the section
-"Configuring i3" for details.
+<<configuring>> for details.
 
 === Closing windows
 
 If an application does not provide a mechanism for closing (most applications
 provide a menu, the escape key or a shortcut like +Control+W+ to close), you
-can press +Mod1+Shift+q+ to kill a window. For applications which support
+can press +mod+Shift+q+ to kill a window. For applications which support
 the WM_DELETE protocol, this will correctly close the application (saving
 any modifications or doing other cleanup). If the application doesn’t support
 the WM_DELETE protocol your X server will kill the window and the behaviour
@@ -186,13 +171,12 @@ Floating windows are always on top of tiling windows.
 
 == Tree
 
-The most important change and reason for the name is that i3 stores all
-information about the X11 outputs, workspaces and layout of the windows on them
-in a tree. The root node is the X11 root window, followed by the X11 outputs,
-then workspaces and finally the windows themselve. In previous versions of i3
-we had multiple lists (of outputs, workspaces) and a table for each workspace.
-That approach turned out to be complicated to use (snapping), understand and
-implement.
+i3 stores all information about the X11 outputs, workspaces and layout of the
+windows on them in a tree. The root node is the X11 root window, followed by
+the X11 outputs, then dock areas and a content container, then workspaces and
+finally the windows themselve. In previous versions of i3 we had multiple lists
+(of outputs, workspaces) and a table for each workspace. That approach turned
+out to be complicated to use (snapping), understand and implement.
 
 === The tree consists of Containers
 
@@ -215,7 +199,7 @@ layout when using a tree as data structure. In i3, every +Container+ has an
 orientation (horizontal, vertical or unspecified). So, in our example with the
 workspace, the default orientation of the workspace +Container+ is horizontal
 (most monitors are widescreen nowadays). If you change the orientation to
-vertical (+Alt+v+ in the default config) and *then* open two terminals, i3 will
+vertical (+mod+v+ in the default config) and *then* open two terminals, i3 will
 configure your windows like this:
 
 image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"]
@@ -225,8 +209,8 @@ Let’s assume you have two terminals on a workspace (with horizontal
 orientation), focus is on the right terminal. Now you want to open another
 terminal window below the current one. If you would just open a new terminal
 window, it would show up to the right due to the horizontal workspace
-orientation. Instead, press +Alt+v+ to create a +Vertical Split Container+ (to
-open a +Horizontal Split Container+, use +Alt+h+). Now you can open a new
+orientation. Instead, press +mod+v+ to create a +Vertical Split Container+ (to
+open a +Horizontal Split Container+, use +mod+h+). Now you can open a new
 terminal and it will open below the current one:
 
 image::tree-layout1.png["Layout",float="right"]
@@ -237,21 +221,21 @@ unfloat::[]
 You probably guessed it already: There is no limit on how deep your hierarchy
 of splits can be.
 
-=== Level up
+=== Focus parent
 
 Let’s stay with our example from above. We have a terminal on the left and two
 vertically split terminals on the right, focus is on the bottom right one. When
 you open a new terminal, it will open below the current one.
 
 So, how can you open a new terminal window to the *right* of the current one?
-The solution is to use +level up+, which will focus the +Parent Container+ of
+The solution is to use +focus parent+, which will focus the +Parent Container+ of
 the current +Container+. In this case, you would focus the +Vertical Split
 Container+ which is *inside* the horizontally oriented workspace. Thus, now new
 windows will be opened to the right of the +Vertical Split Container+:
 
-image::tree-shot3.png["shot3",title="Level Up, then open new terminal"]
-
+image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"]
 
+[[configuring]]
 == Configuring i3
 
 This is where the real fun begins ;-). Most things are very dependant on your
@@ -270,6 +254,14 @@ To change the configuration of i3, copy +/etc/i3/config+ to +\~/.i3/config+
 (or +~/.config/i3/config+ if you like the XDG directory scheme) and edit it
 with a text editor.
 
+On first start (and on all following starts, unless you have a configuration
+file), i3 will offer you to create a configuration file. You can tell the
+wizard to use either Alt (Mod1) or Windows (Mod4) as modifier in the config
+file. Also, the created config file will use the key symbols of your current
+keyboard layout. To start the wizard, use the command +i3-config-wizard+.
+Please note that you must not have +~/.i3/config+, otherwise the wizard will
+exit.
+
 === Comments
 
 It is possible and recommended to use comments in your configuration file to
@@ -283,10 +275,9 @@ a # and can only be used at the beginning of a line:
 
 === Fonts
 
-i3 uses X core fonts (not Xft) for rendering window titles and the internal
-workspace bar. You can use +xfontsel(1)+ to generate such a font description.
-To see special characters (Unicode), you need to use a font which supports
-the ISO-10646 encoding.
+i3 uses X core fonts (not Xft) for rendering window titles. You can use
++xfontsel(1)+ to generate such a font description. To see special characters
+(Unicode), you need to use a font which supports the ISO-10646 encoding.
 
 If i3 cannot open the configured font, it will output an error in the logfile
 and fall back to a working font.
@@ -314,9 +305,9 @@ also mix your bindings, though i3 will not protect you from overlapping ones).
   are the ones you use in Xmodmap to remap your keys. To get the current
   mapping of your keys, use +xmodmap -pke+.
 
-* Keycodes do not need to have a symbol assigned (handy for some hotkeys
-  on some notebooks) and they will not change their meaning as you switch to a
-  different keyboard layout (when using +xmodmap+).
+* Keycodes do not need to have a symbol assigned (handy for custom vendor
+  hotkeys on some notebooks) and they will not change their meaning as you
+  switch to a different keyboard layout (when using +xmodmap+).
 
 My recommendation is: If you often switch keyboard layouts but you want to keep
 your bindings in the same physical location on the keyboard, use keycodes.
@@ -332,10 +323,10 @@ bindcode [Modifiers+]keycode command
 *Examples*:
 --------------------------------
 # Fullscreen
-bindsym Mod1+f f
+bindsym mod+f f
 
 # Restart
-bindsym Mod1+Shift+r restart
+bindsym mod+Shift+r restart
 
 # Notebook-specific hotkeys
 bindcode 214 exec /home/michael/toggle_beamer.sh
@@ -373,31 +364,50 @@ you hold the shift button as well, the resize will be proportional.
 floating_modifier <Modifiers>
 --------------------------------
 
-*Examples*:
+*Example*:
 --------------------------------
 floating_modifier Mod1
 --------------------------------
 
-////////////////////////////////////////////////////////////////////////
-=== Layout mode for new containers
+=== Orientation for new workspaces
 
-TODO: this is workspace_layout. but workspace_layout only works for the first
-con, right?
+New workspaces get a reasonable default orientation: Wide-screen monitors
+(anything wider than high) get horizontal orientation, rotated monitors
+(anything higher than wide) get vertical orientation.
 
-This option determines in which mode new containers will start. See also
-<<stack-limit>>.
+With the +default_orientation+ configuration directive, you can override that
+behaviour.
+
+*Syntax*:
+----------------------------------------------
+default_orientation <horizontal|vertical|auto>
+----------------------------------------------
+
+*Example*:
+----------------------------
+default_orientation vertical
+----------------------------
+
+=== Layout mode for new containers
+
+This option determines in which mode new containers on workspace level will
+start.
+///////////////////////////////
+See also <<stack-limit>>.
+//////////////////////////////
 
 *Syntax*:
 ---------------------------------------------
-new_container <default|stacking|tabbed>
-new_container stack-limit <cols|rows> <value>
+workspace_layout <default|stacking|tabbed>
 ---------------------------------------------
+/////////////////////////////////////////////
+new_container stack-limit <cols|rows> <value>
+/////////////////////////////////////////////
 
-*Examples*:
+*Example*:
 ---------------------
-new_container tabbed
+workspace_layout tabbed
 ---------------------
-////////////////////////////////////////////////////////////////////////
 
 === Border style for new windows
 
@@ -408,11 +418,36 @@ This option determines which border style new windows will have.
 new_window <normal|1pixel|borderless>
 ---------------------------------------------
 
-*Examples*:
+*Example*:
 ---------------------
 new_window 1pixel
 ---------------------
 
+=== Arbitrary commands for specific windows (for_window)
+
+With the +for_window+ command, you can let i3 execute any command when it
+encounters a specific window. This can be used to set windows to floating or to
+change their border style, for example.
+
+*Syntax*:
+-----------------------------
+for_window [criteria] command
+-----------------------------
+
+*Examples*:
+------------------------------------------------
+# enable floating mode for all XTerm windows
+for_window [class="XTerm"] floating enable
+
+# Make all urxvts use a 1-pixel border:
+for_window [class="urxvt"] border 1pixel
+
+# A less useful, but rather funny example:
+# makes the window floating as soon as I change
+# directory to ~/work
+for_window [title="x200: ~/work"] floating enable
+------------------------------------------------
+
 === Variables
 
 As you learned in the section about keyboard bindings, you will have
@@ -422,10 +457,10 @@ variables can be handy.
 
 *Syntax*:
 --------------
-set name value
+set $name value
 --------------
 
-*Examples*:
+*Example*:
 ------------------------
 set $m Mod1
 bindsym $m+Shift+r restart
@@ -435,19 +470,20 @@ Variables are directly replaced in the file when parsing. There is no fancy
 handling and there are absolutely no plans to change this. If you need a more
 dynamic configuration you should create a little script which generates a
 configuration file and run it before starting i3 (for example in your
-+.xsession+ file).
++~/.xsession+ file).
 
 === Automatically putting clients on specific workspaces
 
 [[assign_workspace]]
 
-It is recommended that you match on window classes wherever possible because
-some applications first create their window, and then worry about setting the
-correct title. Firefox with Vimperator comes to mind. The window starts up
-being named Firefox, and only when Vimperator is loaded does the title change.
-As i3 will get the title as soon as the application maps the window (mapping
-means actually displaying it on the screen), you’d need to have to match on
-'Firefox' in this case.
+Specific windows can be matched by window class and/or window title. It is
+recommended that you match on window classes instead of window titles whenever
+possible because some applications first create their window, and then worry
+about setting the correct title. Firefox with Vimperator comes to mind. The
+window starts up being named Firefox, and only when Vimperator is loaded does
+the title change. As i3 will get the title as soon as the application maps the
+window (mapping means actually displaying it on the screen), you’d need to have
+to match on 'Firefox' in this case.
 
 You can prefix or suffix workspaces with a `~` to specify that matching clients
 should be put into floating mode. If you specify only a `~`, the client will
@@ -473,18 +509,22 @@ use it, it has to be a UTF-8 encoded arrow, not `->` or something like that.
 
 === Automatically starting applications on i3 startup
 
-By using the +exec+ keyword outside a keybinding, you can configure which
-commands will be performed by i3 on initial startup (not when restarting i3
-in-place however). These commands will be run in order.
+By using the +exec+ keyword outside a keybinding, you can configure
+which commands will be performed by i3 on initial startup. +exec+
+commands will not run when restarting i3, if you need a command to run
+also when restarting i3 you should use the +exec_always+
+keyword. These commands will be run in order.
 
 *Syntax*:
-------------
+-------------------
 exec command
-------------
+exec_always command
+-------------------
 
 *Examples*:
 --------------------------------
-exec i3status | dzen2 -dock
+exec i3status | i3bar -d
+exec_always ~/my_script.sh
 --------------------------------
 
 [[workspace_screen]]
@@ -514,8 +554,7 @@ workspace 5 output VGA1
 
 === Changing colors
 
-You can change all colors which i3 uses to draw the window decorations and the
-bottom bar.
+You can change all colors which i3 uses to draw the window decorations.
 
 *Syntax*:
 --------------------------------------------
@@ -533,12 +572,6 @@ client.unfocused::
        A client which is not the focused one of its container.
 client.urgent::
        A client which has its urgency hint activated.
-bar.focused::
-       The current workspace in the bottom bar.
-bar.unfocused::
-       All other workspaces in the bottom bar.
-bar.urgent::
-       A workspace which has at least one client with an activated urgency hint.
 
 You can also specify the color to be used to paint the background of the client
 windows. This color will be used to paint the window on top of which the client
@@ -557,11 +590,14 @@ area of the termianal and the i3 border.
 
 Colors are in HTML hex format (#rrggbb), see the following example:
 
-*Examples*:
---------------------------------------
-# class        border  backgr. text
-client.focused #2F343A #900000 #FFFFFF
---------------------------------------
+*Examples (default colors)*:
+-----------------------------------------------
+# class                 border  backgr. text
+client.focused          #4c7899 #285577 #ffffff
+client.focused_inactive #333333 #5f676a #ffffff
+client.unfocused        #333333 #222222 #888888
+client.urgent           #2f343a #900000 #ffffff
+-----------------------------------------------
 
 Note that for the window decorations, the color around the child window is the
 background color, and the border color is only the two thin lines at the top of
@@ -573,10 +609,13 @@ i3 uses unix sockets to provide an IPC interface. This allows third-party
 programs to get information from i3, such as the current workspaces
 (to display a workspace bar), and to control i3.
 
-To enable it, you have to configure a path where the unix socket will be
-stored. The default path is +/tmp/i3-ipc.sock+.
+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.
 
-You can override the default path through the environment-variable +I3SOCK+.
+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.
 
 *Examples*:
 ----------------------------
@@ -586,7 +625,7 @@ ipc-socket /tmp/i3-ipc.sock
 You can then use the +i3-msg+ application to perform any command listed in
 the next section.
 
-=== Disable focus follows mouse
+=== Focus follows mouse
 
 If you have a setup where your mouse usually is in your way (like a touchpad
 on your laptop which you do not want to disable completely), you might want
@@ -599,89 +638,203 @@ to click on links in your browser window).
 focus_follows_mouse <yes|no>
 ----------------------------
 
-*Examples*:
+*Example*:
 ----------------------
 focus_follows_mouse no
 ----------------------
 
+=== Popups during fullscreen mode
+
+When you are in fullscreen mode, some applications still open popup windows
+(take Xpdf for example). This is because these applications may not be aware
+that they are in fullscreen mode (they do not check the corresponding hint).
+There are two things which are possible to do in this situation:
+
+1. Just ignore the popup (don’t map it). This won’t interrupt you while you are
+   in fullscreen. However, some apps might react badly to this (deadlock until
+   you go out of fullscreen).
+2. Leave fullscreen mode. This is the default.
+
+*Syntax*:
+-------------------------------------------------
+popup_during_fullscreen <ignore|leave_fullscreen>
+-------------------------------------------------
+
+*Example*:
+------------------------------
+popup_during_fullscreen ignore
+------------------------------
+
+=== Focus wrapping
+
+When being in a tabbed or stacked container, the first container will be
+focused when you use +focus down+ on the last container -- the focus wraps. If
+however there is another stacked/tabbed container in that direction, focus will
+be set on that container. This is the default behaviour so you can navigate to
+all your windows without having to use +focus parent+.
+
+If you want the focus to *always* wrap and you are aware of using +focus
+parent+ to switch to different containers, you can use the
++force_focus_wrapping+ configuration directive. After enabling it, the focus
+will always wrap.
+
+*Syntax*:
+-----------------------------
+force_focus_wrapping <yes|no>
+-----------------------------
+
+*Example*:
+------------------------
+force_focus_wrapping yes
+------------------------
+
 == List of commands
 
+=== Splitting containers
+
+The split command makes the current window a split container. Split containers
+can contain multiple windows. Every split container has an orientation, it is
+either split horizontally (a new window gets placed to the right of the current
+one) or vertically (a new window gets placed below the current one).
+
+If you apply this command to a split container with the same orientation,
+nothing will happen. If you use a different orientation, the split container’s
+orientation will be changed (if it does not have more than one window).
+
+*Syntax*:
+---------------------------
+split <vertical|horizontal>
+---------------------------
+
+*Example*:
+------------------------------
+bindsym mod+v split vertical
+bindsym mod+h split horizontal
+------------------------------
+
 === Manipulating layout
 
-To change the layout of the current container to stacking, use +layout
-stacking+, for default use +layout default+ and for tabbed, use +layout
-tabbed+. To make the current client (!) fullscreen, use +fullscreen+, to make
-it floating (or tiling again) use +mode floating+ respectively +mode tiling+
-(or +mode toggle+):
+Use +layout default+, +layout stacking+ or +layout tabbed+ to change the
+current container layout to default, stacking or tabbed layout, respectively.
+
+To make the current window (!) fullscreen, use +fullscreen+, to make
+it floating (or tiling again) use +floating enable+ respectively +floating disable+
+(or +floating toggle+):
 
 *Examples*:
 --------------
-bindsym Mod1+s layout stacking
-bindsym Mod1+l layout default
-bindsym Mod1+w layout tabbed
+bindsym mod+s layout stacking
+bindsym mod+l layout default
+bindsym mod+w layout tabbed
 
 # Toggle fullscreen
-bindsym Mod1+f fullscreen
+bindsym mod+f fullscreen
 
 # Toggle floating/tiling
-bindsym Mod1+t mode toggle
+bindsym mod+t floating toggle
 --------------
 
 === Focusing/Moving containers
 
-To change the focus, use one of the +prev h+, +next v+, +prev v+ and +next h+
-commands, meaning left, down, up, right (respectively).
+To change the focus, use the focus command: +focus left+, +focus right+, +focus down+ and +focus up+.
+
+There are a few special parameters you can use for the focus command:
+
+parent::
+       Sets focus to the +Parent Container+ of the current +Container+.
+child::
+       The opposite of +focus parent+, sets the focus to the last focused
+       child container.
+floating::
+       Sets focus to the last focused floating container.
+tiling::
+       Sets focus to the last focused tiling container.
+mode_toggle::
+       Toggles between floating/tiling containers.
 
 For moving, use +move left+, +move right+, +move down+ and +move up+.
 
 *Examples*:
 ----------------------
 # Focus clients on the left, bottom, top, right:
-bindsym Mod1+j prev h
-bindsym Mod1+k next v
-bindsym Mod1+j prev v
-bindsym Mod1+semicolon next h
+bindsym mod+j focus left
+bindsym mod+k focus down
+bindsym mod+l focus up
+bindsym mod+semicolon focus right
+
+# Focus parent container
+bindsym mod+u focus parent
+
+# Focus last floating/tiling container
+bindsym mod+g focus mode_toggle
 
 # Move client to the left, bottom, top, right:
-bindsym Mod1+j move left
-bindsym Mod1+k move down
-bindsym Mod1+j move up
-bindsym Mod1+semicolon move right
+bindsym mod+j move left
+bindsym mod+k move down
+bindsym mod+l move up
+bindsym mod+semicolon move right
 ----------------------
 
-=== Changing workspaces/moving containers to workspaces
+=== Changing (named) workspaces/moving to workspaces
 
 To change to a specific workspace, use the +workspace+ command, followed by the
-number or name of the workspace. To move containers, use +move workspace+.
+number or name of the workspace. To move containers to specific workspaces, use
++move workspace+.
 
-//////////////////////////////////////////////////////////////////////////////
-TODO: not yet implemented
+You can also switch to the next and previous workspace with the commands
++workspace next+ and +workspace prev+, which is handy, for example, if you have
+workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
+combination.
 
-You can also switch to the next and previous workspace with the commands +nw+
-and +pw+, which is handy, for example, if you have workspace 1, 3, 4 and 9 and
-you want to cycle through them with a single key combination.
-//////////////////////////////////////////////////////////////////////////////
+To move a container to another xrandr output such as +LVDS1+ or +VGA1+, you can
+use the +move output+ command followed by the name of the target output. You
+may also use +left+, +right+, +up+, +down+ instead of the xrandr output name to
+move to the the next output in the specified direction.
 
 *Examples*:
 -------------------------
-bindsym Mod1+1 workspace 1
-bindsym Mod1+2 workspace 2
+bindsym mod+1 workspace 1
+bindsym mod+2 workspace 2
+...
+
+bindsym mod+Shift+1 move workspace 1
+bindsym mod+Shift+2 move workspace 2
+...
+-------------------------
+
+==== Named workspaces
+
+Workspaces are identified by their name. So, instead of using numbers in the
+workspace command, you can use an arbitrary name:
+
+*Example*:
+-------------------------
+bindsym mod+1 workspace mail
 ...
+-------------------------
+
+If you want the workspace to have a number *and* a name, just prefix the
+number, like this:
 
-bindsym Mod1+Shift+1 move workspace 1
-bindsym Mod1+Shift+2 move workspace 2
+*Example*:
+-------------------------
+bindsym mod+1 workspace 1: mail
+bindsym mod+2 workspace 2: www
 ...
 -------------------------
 
+Note that the workspace will really be named "1: mail". i3 treats workspace
+names beginning with a number in a slightly special way. Normally, named
+workspaces are ordered the way they appeared. When they start with a number, i3
+will order them numerically.
+
 [[resizingconfig]]
 
-=== Resizing columns/rows
+=== Resizing containers/windows
 
-If you want to resize columns/rows using your keyboard, you can use the
+If you want to resize containers/windows using your keyboard, you can use the
 +resize+ command, I recommend using it inside a so called +mode+:
 
-///////////////////////////////////////////////////////////////////////
-TODO: mode is not yet implemented
 .Example: Configuration file, defining a mode for resizing
 ----------------------------------------------------------------------
 mode "resize" {
@@ -694,11 +847,11 @@ mode "resize" {
         bindsym j resize shrink left
         bindsym Shift+j resize grow left
 
-        bindsym k resize grow bottom
-        bindsym Shift+k resize shrink bottom
+        bindsym k resize grow down
+        bindsym Shift+k resize shrink down
 
-        bindsym l resize shrink top
-        bindsym Shift+l resize grow top
+        bindsym l resize shrink up
+        bindsym Shift+l resize grow up
 
         bindsym semicolon resize grow right
         bindsym Shift+semicolon resize shrink right
@@ -707,11 +860,9 @@ mode "resize" {
 }
 
 # Enter resize mode
-bindsym Mod1+r mode resize
+bindsym mod+r mode "resize"
 ----------------------------------------------------------------------
 
-///////////////////////////////////////////////////////////////////////
-
 === Jumping to specific windows
 
 Often when in a multi-monitor environment, you want to quickly jump to a
@@ -719,7 +870,7 @@ specific window. For example, while working on workspace 3 you may want to
 jump to your mail client to email your boss that you’ve achieved some
 important goal. Instead of figuring out how to navigate to your mailclient,
 it would be more convenient to have a shortcut. You can use the +focus+ command
-for that.
+with criteria for that.
 
 *Syntax*:
 ----------------------------------------------------
@@ -730,7 +881,7 @@ for that.
 *Examples*:
 ------------------------------------------------
 # Get me to the next open VIM instance
-bindsym Mod1+a [class="urxvt" title="VIM"] focus
+bindsym mod+a [class="urxvt" title="VIM"] focus
 ------------------------------------------------
 
 === VIM-like marks (mark/goto)
@@ -751,67 +902,44 @@ can also prefix this command and display a custom prompt for the input dialog.
 
 *Syntax*:
 ------------------------------
-mark <identifier>
+mark identifier
 [con_mark="identifier"] focus
 ------------------------------
 
+*Example (in a terminal)*:
+------------------------------
+$ i3-msg mark irssi
+$ i3-msg '[con_mark="irssi"] focus'
+------------------------------
+
 ///////////////////////////////////////////////////////////////////
 TODO: make i3-input replace %s
 *Examples*:
 ---------------------------------------
 # Read 1 character and mark the current window with this character
-bindsym Mod1+m exec i3-input -p 'mark ' -l 1 -P 'Mark: '
+bindsym mod+m exec i3-input -p 'mark ' -l 1 -P 'Mark: '
 
 # Read 1 character and go to the window with the character
-bindsym Mod1+g exec i3-input -p 'goto ' -l 1 -P 'Goto: '
+bindsym mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: '
 ---------------------------------------
 
 Alternatively, if you do not want to mess with +i3-input+, you could create
 seperate bindings for a specific set of labels and then only use those labels.
 ///////////////////////////////////////////////////////////////////
 
-///////////////////////////////////////////////////////////////////////////////
-TODO: not yet implemented
-=== Traveling the focus stack
-
-This mechanism can be thought of as the opposite of the +jump+ command.
-It travels the focus stack and jumps to the window which had focus previously.
-
-*Syntax*:
---------------
-focus [number] | floating | tiling | ft
---------------
-
-Where +number+ by default is 1 meaning that the next client in the focus stack
-will be selected.
-
-The special values have the following meaning:
-
-floating::
-       The next floating window is selected.
-tiling::
-       The next tiling window is selected.
-ft::
-       If the current window is floating, the next tiling window will be
-       selected; and vice-versa.
-///////////////////////////////////////////////////////////////////////////////
-
 === Changing border style
 
 To change the border of the current client, you can use +border normal+ to use the normal
 border (including window title), +border 1pixel+ to use a 1-pixel border (no window title)
 and +border none+ to make the client borderless.
 
-////////////////////////////////////////////////////////////////////////////
-TODO: not yet implemented
 There is also +border toggle+ which will toggle the different border styles.
-////////////////////////////////////////////////////////////////////////////
 
 *Examples*:
 ----------------------------
-bindsym Mod1+t border normal
-bindsym Mod1+y border 1pixel
-bindsym Mod1+u border none
+bindsym mod+t border normal
+bindsym mod+y border 1pixel
+bindsym mod+u border none
 ----------------------------
 
 [[stack-limit]]
@@ -851,16 +979,14 @@ image:stacklimit.png[Container limited to two columns]
 You can make i3 reload its configuration file with +reload+. You can also
 restart i3 inplace with the +restart+ command to get it out of some weird state
 (if that should ever happen) or to perform an upgrade without having to restart
-your X session. However, your layout is not preserved at the moment, meaning
-that all open windows will end up in a single container in default layout
-after the restart. To exit i3 properly, you can use the +exit+ command,
+your X session. To exit i3 properly, you can use the +exit+ command,
 however you don’t need to (simply killing your X session is fine as well).
 
 *Examples*:
 ----------------------------
-bindsym Mod1+Shift+r restart
-bindsym Mod1+Shift+w reload
-bindsym Mod1+Shift+e exit
+bindsym mod+Shift+r restart
+bindsym mod+Shift+w reload
+bindsym mod+Shift+e exit
 ----------------------------
 
 [[multi_monitor]]
@@ -982,24 +1108,16 @@ approach you have in the task bar of a traditional desktop environment.
 If you don’t already have your favorite way of generating such a status line
 (self-written scripts, conky, …), then i3status is the recommended tool for
 this task. It was written in C with the goal of using as few syscalls as
-possible to reduce the time your CPU is woken up from sleep states.
-
-Regardless of which application you use to generate the status line, you
-want to make sure that the application does one of the following things:
-
-1. Register as a dock window using EWMH hints. This will make i3 position the
-   window above the workspace bar but below every other client. This is the
-   recommended way, but in case of dzen2, for example, you need to check out
-   the source of dzen2 from subversion, as the -dock option is not present
-   in the released versions.
-2. Overlay the internal workspace bar. This method will not waste any space
-   on the workspace bar, however, it is rather hackish. Just configure
-   the output window to be over the workspace bar (say -x 200 and -y 780 if
-   your screen is 800 px height).
-
-The planned solution for this problem is to make the workspace bar optional
-and switch to a third party application completely (dzen2 for example)
-which will then contain the workspace bar.
+possible to reduce the time your CPU is woken up from sleep states. Because
+i3status only spits out text, you need to combine it with some other tool, like
+i3bar. Use a pipe to connect them: +i3status | i3bar -d+.
+
+Regardless of which application you use to display the status line, you
+want to make sure that it registers as a dock window using EWMH hints. i3 will
+position the window either at the top or at the bottom of the screen, depending
+on which hint the application sets. With i3bar, you can use +-d+ or +-dbottom+
+for positioning it at the bottom and +-dtop+ to position it at the top of the
+screen.
 
 === Giving presentations (multi-monitor)