Merge branch 'next' (3.β is stable now)

docs/Makefile

@@ -1,5 +1,5 @@
 
-all: hacking-howto.html debugging.html
+all: hacking-howto.html debugging.html userguide.html
 
 hacking-howto.html: hacking-howto
 	asciidoc -a toc -n $<
@@ -7,6 +7,8 @@ hacking-howto.html: hacking-howto
 debugging.html: debugging
 	asciidoc -n $<
 
+userguide.html: userguide
+	asciidoc -a toc -n $<
 
 clean:
 	rm -f */*.{aux,log,toc,bm,pdf,dvi}

docs/debugging

@@ -84,35 +84,9 @@ gdb $(which i3) core.i3.3849
 
 Then, generate a backtrace using:
 
----------
-backtrace
----------
-
-Also, getting an overview of the local variables might help:
------------
-info locals
------------
-
-If your backtrace looks like this:
----------------------------------------------------------------------------------------------------
-(gdb) backtrace
-#0  0x041b1a01 in vfprintf () from /lib/libc.so.6
-#1  0x041b2f80 in vprintf () from /lib/libc.so.6
-#2  0x080555de in slog (fmt=0x8059ba0 "%s:%s:%d - Name should change to \"%s\"\n") at src/util.c:60
-#3  0x0804fa73 in handle_windowname_change_legacy (data=0x0, conn=0x42da908,
-                  state=0 '\0', window=8389918, atom=39, prop=0x4303f90) at src/handlers.c:752
-#4  0x0406cace in ?? () from /usr/lib/libxcb-property.so.1
-#5  0x00000000 in ?? ()
----------------------------------------------------------------------------------------------------
-
-you need to find the first frame which actually belongs to i3 code. You can easily spot them, as
-their filename starts with src/ and has a line number. In this case, frame 2 would be the correct
-frame, so before getting the local variables, switch to frame 2:
-
------------
-frame 2
-info locals
------------
+--------------
+backtrace full
+--------------
 
 == Sending bugreports/debugging on IRC
 

docs/hacking-howto

@@ -107,23 +107,38 @@ Contains forward definitions for all public functions, aswell as doxygen-compati
 comments (so if you want to get a bit more of the big picture, either browse all
 header files or use doxygen if you prefer that).
 
+src/client.c::
+Contains all functions which are specific to a certain client (make it
+fullscreen, see if its class/name matches a pattern, kill it, …).
+
 src/commands.c::
-Parsing commands
+Parsing commands and actually execute them (focussing, moving, …).
 
 src/config.c::
-Parses the configuration file
+Parses the configuration file.
 
 src/debug.c::
-Contains debugging functions to print unhandled X events
+Contains debugging functions to print unhandled X events.
+
+src/floating.c::
+Contains functions for floating mode (mostly resizing/dragging).
 
 src/handlers.c::
-Contains all handlers for all kind of X events
+Contains all handlers for all kind of X events (new window title, new hints,
+unmapping, key presses, button presses, …).
 
 src/layout.c::
-Renders your layout (screens, workspaces, containers)
+Renders your layout (screens, workspaces, containers).
 
 src/mainx.c::
-Initializes the window manager
+Initializes the window manager.
+
+src/manage.c::
+Looks at existing or new windows and decides whether to manage them. If so, it
+reparents the window and inserts it into our data structures.
+
+src/resize.c::
+Contains the functions to resize columns/rows in the table.
 
 src/resize.c::
 Contains the functions to resize columns/rows in the table.
@@ -213,7 +228,7 @@ chosen for those:
  * ``conn'' is the xcb_connection_t
  * ``event'' is the event of the particular type
  * ``container'' names a container
- * ``client'' names a client, for example when using a `CIRCLEQ_FOREACH`
+ * ``client'' names a client, for example when using a +CIRCLEQ_FOREACH+
 
 == Startup (src/mainx.c, main())
 
@@ -361,9 +376,26 @@ when rendering.
 
 === Resizing containers
 
-By clicking and dragging the border of a container, you can resize it freely.
+By clicking and dragging the border of a container, you can resize the whole column
+(respectively row) which this container is in. This is necessary to keep the table
+layout working and consistent.
 
-TODO
+Currently, only vertical resizing is implemented.
+
+The resizing works similarly to the resizing of floating windows or movement of floating
+windows:
+
+* A new, invisible window with the size of the root window is created (+grabwin+)
+* Another window, 2px width and as high as your screen (or vice versa for horizontal
+  resizing) is created. Its background color is the border color and it is only
+  there to signalize the user how big the container will be (it creates the impression
+  of dragging the border out of the container).
+* The +drag_pointer+ function of +src/floating.c+ is called to grab the pointer and
+  enter an own event loop which will pass all events (expose events) but motion notify
+  events. This function then calls the specified callback (+resize_callback+) which
+  does some boundary checking and moves the helper window. As soon as the mouse
+  button is released, this loop will be terminated.
+* The new width_factor for each involved column (respectively row) will be calculated.
 
 == User commands / commandmode (src/commands.c)
 
@@ -396,7 +428,8 @@ direction to move a window respectively or snap.
 
 == Using git / sending patches
 
-For a short introduction into using git, see TODO.
+For a short introduction into using git, see http://www.spheredev.org/wiki/Git_for_the_lazy
+or, for more documentation, see http://git-scm.com/documentation
 
 When you want to send a patch because you fixed a bug or implemented a cool feature (please
 talk to us before working on features to see whether they are maybe already implemented, not

docs/userguide

@@ -0,0 +1,371 @@
+i3 User’s Guide
+===============
+Michael Stapelberg <michael+i3@stapelberg.de>
+June 2009
+
+This document contains all information you need to configuring and using the i3
+window manager. If it does not, please contact me on IRC, Jabber or E-Mail and
+I’ll help you out.
+
+For a complete listing of the default keybindings, please see the manpage.
+
+== Using i3
+
+=== Creating terminals and moving around
+
+A very basic operation is to create a new terminal. By default, the keybinding
+for that is Mod1+Enter, that is Alt+Enter in the default configuration. By
+pressing Mod1+Enter, a new terminal will be created and it will fill the whole
+space which is available on your screen.
+
+image:single_terminal.png[Single terminal]
+
+It is important to keep in mind that i3 uses a table to manage your windows. At
+the moment, you have exactly one column and one row which leaves you with one
+cell. In this cell, there is a container in which your newly opened terminal is.
+
+If you now open another terminal, you still have only one cell. However, the
+container has both of your terminals. So, a container is just a group of clients
+with a specific layout. You can resize containers as they directly resemble
+columns/rows of the layout table.
+
+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, +Mod1+J+ is left, +Mod1+K+ is down, +Mod1+L+
+is up and `Mod1+;` is right. So, to switch between the terminals, use +Mod1+K+ or
++Mod1+L+.
+
+To create a new row/column, you can simply move a terminal (or any other window)
+to the direction you want to expand your table. So, let’s expand the table to
+the right by pressing `Mod1+Shift+;`.
+
+image:two_columns.png[Two columns]
+
+=== Changing mode of containers
+
+A container can be in two modes at the moment (more to be implemented later):
++default+ or +stacking+. In default mode, clients are sized so that every client
+gets an equal amount of space of the container. In stacking mode, only one
+focused client of the container is displayed and you get a list of windows
+at the top of the container.
+
+To switch the mode, press +Mod1+h+ for stacking and +Mod1+e+ for default.
+
+=== Toggling fullscreen mode for a window
+
+To display a window fullscreen or to go out of fullscreen mode again, press
++Mod1+f+.
+
+=== Opening other applications
+
+Aside from opening applicatios from a terminal, you can also use the handy
++dmenu+ which is opened by pressing +Mod1+v+ by default. Just type the name
+(or a part of it) of the application which you want to open. It has to be in
+your +$PATH+ for that to work.
+
+Furthermore, if you have applications you open very frequently, you can also
+create a keybinding for it. See the section "Configuring i3" for details.
+
+=== Closing windows
+
+If an application does not provide a mechanism to close (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
+the WM_DELETE protocol, this will correctly close the application (saving
+any modifications or doing other cleanup). If the application doesn’t support
+it, your X server will kill the window and the behaviour depends on the
+application.
+
+=== Using workspaces
+
+Workspaces are an easy way to group a set of windows. By default, you are on
+the first workspace, as the bar on the bottom left indicates. To switch to
+another workspace, press +Mod1+num+ where +num+ is the number of the workspace
+you want to use. If the workspace does not exist yet, it will be created.
+
+A common paradigm is to put the web browser on one workspace, communication
+applications (+mutt+, +irssi+, ...) on another one and the ones with which you
+work on the third one. Of course, there is no need to follow this approach.
+
+If you have multiple screens, a workspace will be created on each screen. If
+you open a new workspace, it will be bound to the screen you created it on.
+When you switch to a workspace on another screen, i3 will set focus to this
+screen.
+
+=== Moving windows to workspaces
+
+To move a window to another workspace, simply press +Mod1+Shift+num+ where
++num+ is (like when switching workspaces) the number of the target workspace.
+Similarly to switching workspaces, the target workspace will be created if
+it does not yet exist.
+
+=== Resizing columns
+
+To resize columns just grab the border between the two columns and move it to
+the wanted size.
+
+A command for doing this via keyboard will be implemented soon.
+
+=== Restarting i3 inplace
+
+To restart i3 inplace (and thus get it into a clean state if it has a bug, to
+reload your configuration or even to upgrade to a newer version of i3) you
+can use +Mod1+Shift+r+. Be aware, though, that this kills your current layout
+and all the windows you have opened will be put in a default container in only
+one cell. Saving the layout will be implemented in a later version.
+
+=== Exiting i3
+
+To cleanly exit i3 without killing your X server, you can use +Mod1+Shift+e+.
+
+=== Snapping
+
+Snapping is a mechanism to increase/decrease the colspan/rowspan of a container.
+Colspan/rowspan is the amount of columns/rows a specific cell of the table
+consumes. This is easier explained by giving an example, so take the following
+layout:
+
+image:snapping.png[Snapping example]
+
+To use the full size of your screen, you can now snap container 3 downwards
+by pressing +Mod1+Control+k+ (or snap container 2 rightwards).
+
+=== Floating
+
+Floating is the opposite of tiling mode. The position and size of a window
+are then 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
+windows or toolbar windows (GIMP or similar).
+
+You can enable floating for a window by pressing +Mod1+Shift+Space+. By
+dragging the window’s titlebar with your mouse, you can move the window
+around. By grabbing the borders and moving them you can resize the window.
+
+Bindings for doing this with your keyboard will follow.
+
+Floating clients are always on top of tiling clients.
+
+== Configuring i3
+
+This is where the real fun begins ;-). Most things are very dependant on your
+ideal working environment, so we can’t make reasonable defaults for them.
+
+While not using a programming language for the configuration, i3 stays
+quite flexible regarding to the things you usually want your window manager
+to do.
+
+For example, you can configure bindings to jump to specific windows,
+you can set specific applications to start on a specific workspace, you can
+automatically start applications, you can change the colors of i3 or bind
+your keys to do useful stuff.
+
+terminal::
+	Specifies the terminal emulator program you prefer. It will be started
+	by default when you press Mod1+Enter, but you can overwrite this. Refer
+	to it as +$terminal+ to keep things modular.
+font::
+	Specifies the default font you want i3 to use. Use an X core font
+	descriptor here, like
+	+-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1+. You can
+	use +xfontsel(1)+ to pick one.
+
+=== Keyboard bindings
+
+You can use each command (see below) using keyboard bindings. At the moment,
+keyboard bindings require you to specify the keycode (38) of the key, not its key
+symbol ("a"). This has some advantages (keybindings make sense regardless of
+the layout you type) and some disadvantages (hard to remember, you have to look
+them up every time).
+
+*Syntax*:
+--------------------------------
+bind [Modifiers+]keycode command
+--------------------------------
+
+*Examples*:
+--------------------------------
+# Fullscreen
+bind Mod1+41 f
+
+# Restart
+bind Mod1+Shift+27 restart
+--------------------------------
+
+Available Modifiers:
+
+Mod1-Mod5, Shift, Control::
+Standard modifiers, see +xmodmap(1)+
+
+Mode_switch::
+Unlike other window managers, i3 can use Mode_switch as a modifier. This allows
+you to remap capslock (for example) to Mode_switch and use it for both: typing
+umlauts or special characters 'and' having some comfortably reachable key
+bindings. For example, when typing, capslock+1 or capslock+2 for switching
+workspaces is totally convenient. Try it :-).
+
+=== The floating modifier
+
+To move floating windows with your mouse, you can either grab their titlebar
+or configure the so called floating modifier which you can then press and
+click anywhere in the window itself. The most common setup is to configure
+it as the same one you use for managing windows (Mod1 for example). Afterwards,
+you can press Mod1, click into a window using your left mouse button and drag
+it to the position you want it at.
+
+*Syntax*:
+--------------------------------
+floating_modifier <Modifiers>
+--------------------------------
+
+*Examples*:
+--------------------------------
+floating_modifier Mod1
+--------------------------------
+
+
+=== Variables
+
+As you learned in the previous section about keyboard bindings, you will have
+to configure lots of bindings containing modifier keys. If you want to save
+yourself some typing and have the possibility to change the modifier you want
+to use later, variables can be handy.
+
+*Syntax*:
+--------------
+set name value
+--------------
+
+*Examples*:
+------------------------
+set $m Mod1
+bind $m+Shift+27 restart
+------------------------
+
+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, like when configuring
+wmii.
+
+=== Automatically putting clients on specific workspaces
+
+It is recommended that you match on window classes whereever possible because
+some applications first create their window and then care about setting the
+correct title. Firefox with Vimperator comes to mind, as the window starts up
+being named Firefox and only when Vimperator is loaded, the title changes. 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 use the special workspace +~+ to specify that matching clients should
+be put into floating mode.
+
+*Syntax*:
+----------------------------------------------------
+assign ["]window class[/window title]["] [→] workspace
+----------------------------------------------------
+
+*Examples*:
+----------------------
+assign urxvt 2
+assign urxvt → 2
+assign "urxvt" → 2
+assign "urxvt/VIM" → 3
+assign "gecko" → ~
+----------------------
+
+=== Automatically starting applications on startup
+
+By using the +exec+ keyword outside a keybinding, you can configure which
+commands will be performed by i3 on the first start (not when reloading inplace
+however). The commands will be run in order.
+
+*Syntax*:
+------------
+exec command
+------------
+
+*Examples*:
+--------------------------------
+exec sudo i3status | dzen2 -dock
+--------------------------------
+
+=== Jumping to specific windows
+
+Especially when in a multi-monitor environment, you want to quickly jump to a specific
+window, for example while currently working on workspace 3 you may want to jump to
+your mailclient to mail 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.
+
+*Syntax*:
+----------------------------------------------------
+jump ["]window class[/window title]["]
+jump workspace [ column row ]
+----------------------------------------------------
+
+You can either use the same matching algorithm as in the +assign+ command (see above)
+or you can specify the position of the client if you always use the same layout.
+
+*Examples*:
+--------------------------------------
+# Get me to the next open VIM instance
+bind Mod1+38 jump "urxvt/VIM"
+--------------------------------------
+
+=== 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 you focused before.
+
+*Syntax*:
+--------------
+focus [number] | floating | tilling | 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 colors
+
+You can change all colors which i3 uses to draw the window decorations and the
+bottom bar.
+
+*Syntax*:
+--------------------------------------------
+colorclass border background text
+--------------------------------------------
+
+Where colorclass can be one of:
+
+client.focused::
+	A client which currently has the focus.
+client.focused_inactive::
+	A client which is the focused one of its container, but it does not have
+	the focus at the moment.
+client.unfocused::
+	A client which is not the focused one of its container.
+bar.focused::
+	The current workspace in the bottom bar.
+bar.unfocused::
+	All other workspaces in the bottom bar.
+
+Colors are in HTML hex format, see below.
+
+*Examples*:
+--------------------------------------
+# class        border  backgr. text
+client.focused #2F343A #900000 #FFFFFF
+--------------------------------------