Add documentation for external workspace bars

docs/Makefile

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

docs/wsbar

@@ -0,0 +1,94 @@
+External workspace bars
+=======================
+Michael Stapelberg <michael+i3@stapelberg.de>
+May 2010
+
+This document describes why the internal workspace bar is minimal and how an
+external workspace bar can be used. It explains the concepts using +i3-wsbar+
+as the reference implementation.
+
+== Internal and external bars
+
+The internal workspace bar of i3 is meant to be a reasonable default so that
+you can use i3 without having too much hassle when setting it up. It is quite
+simple and intended to stay this way. So, there is no way to display your own
+information in this bar (unlike dwm, wmii, awesome, …).
+
+We chose not to implement such a mechanism because that would be duplicating
+already existing functionality of tools such as dzen2, xmobar and similar.
+Instead, you should disable the internal bar and use an external workspace bar
+(which communicates with i3 through its IPC interface).
+
+== dock mode
+
+You typically want to see the same workspace bar on every workspace on a
+specific screen. Also, you don’t want to place the workspace bar somewhere
+in your layout by hand. This is where dock mode comes in: When a program sets
+the appropriate hint (_NET_WM_WINDOW_TYPE_DOCK), it will be managed in dock
+mode by i3. That means it will be placed at the bottom of the screen (while
+other edges of the screen are possible in the NetWM standard, this is not yet
+implemented in i3), it will not overlap any other window and it will be on
+every workspace for the specific screen it was placed on initially.
+
+== The IPC interface
+
+In the context of using an external workspace bar, the IPC interface needs to
+provide the bar program with the current workspaces and output (as in VGA-1,
+LVDS-1, …) configuration. In the other direction, the program has to be able
+to switch to specific workspaces.
+
+By default, the IPC interface is enabled and places its UNIX socket in
++~/.i3/ipc.sock+.
+
+To learn more about the protocol which is used for IPC, see +docs/ipc+.
+
+== Output changes (on-the-fly)
+
+i3 implements the RandR API and can handle changing outputs quite well. So, an
+external workspace bar implementation needs to make sure that when you change
+the resolution of any of your screens (or enable/disable an output), the bars
+will be adjusted properly.
+
+== i3-wsbar, the reference implementation
+
+Please keep in mind that +i3-wsbar+ is just a reference implementation. It is
+shipped with i3 to have a reasonable default. Thus, +i3-wsbar+ is designed to
+work well with dzen2 and there are no plans to make it more generic.
+
+=== The big picture
+
+The most common reason to use an external workspace bar is to integrate system
+information such as what +i3status+ provides into the workspace bar (to save
+screen space). So, we have +i3status+ or a similar program, which only provides
+text output (formatted in some way). To display this text nicely on the screen,
+there are programs such as dzen2, xmobar and similar. We will stick to dzen2
+from here on. So, we have the output of i3status, which needs to go into dzen2
+somehow. But we also want to display the list of workspaces. +i3-wsbar+ takes
+input on stdin, combines it with a formatted workspace list and pipes it to
+dzen2.
+
+Please note that +i3-wsbar+ does not print its output to stdout. Instead, it
+launches the dzen2 instances on its own. This is necessary to handle changes
+in the available outputs (to place a new dzen2 on a new screen for example).
+
+image:wsbar.png["Overview",link="wsbar.png"]
+
+=== Running i3-wsbar
+
+The most simple usage of i3-wsbar looks like this:
+-------------------------------
+i3-wsbar -c "dzen2 -x %x -dock"
+-------------------------------
+
+The +%x+ in the command name will be replaced by the X position of the output
+for which this workspace bar is running. i3 will automatically place the
+workspace bar on the correct output when dzen2 is started in dock mode. The
+bar which you will see should look exactly like the internal bar of i3.
+
+To actually get a benefit, you want to give +i3-wsbar+ some input:
+------------------------------------------
+i3status | i3-wsbar -c "dzen2 -x %x -dock"
+------------------------------------------
+
+It is recommended to place the above command in your i3 configuration file
+to start it automatically with i3.