add docs/i3bar-protocol

docs/Makefile

@@ -1,11 +1,14 @@
 # To pass additional parameters for asciidoc
 ASCIIDOC=asciidoc
 
-all: hacking-howto.html debugging.html debugging-release-version.html userguide.html ipc.html multi-monitor.html wsbar.html refcard.pdf testsuite.html
+all: hacking-howto.html debugging.html debugging-release-version.html userguide.html ipc.html multi-monitor.html wsbar.html refcard.pdf testsuite.html i3bar-protocol.html
 
 hacking-howto.html: hacking-howto
 	$(ASCIIDOC) -a toc -n $<
 
+i3bar-protocol.html: i3bar-protocol
+	$(ASCIIDOC) -a toc -n $<
+
 debugging.html: debugging
 	$(ASCIIDOC) -n $<
 

docs/i3bar-protocol

@@ -0,0 +1,148 @@
+i3bar input protocol
+====================
+Michael Stapelberg <michael@i3wm.org>
+February 2012
+
+This document explains the protocol in which i3bar expects its input. It
+provides support for colors, urgency, shortening and easy manipulation.
+
+== Rationale for chosing JSON
+
+Before describing the protocol, let’s cover why JSON is a building block of
+this protocol.
+
+1. Other bar display programs such as dzen2 or xmobar are using in-band
+   signaling: they recognize certain sequences (like ^fg(#330000) in your input
+   text). We would like to avoid that and separate information from
+   meta-information. By information, we mean the actual output, like the IP
+   address of your ethernet adapter and by meta-information, we mean in which
+   color it should be displayed right now.
+2. It is easy to write a simple script which manipulates part(s) of the input.
+   Each block of information (like a block for the disk space indicator, a block
+   for the current IP address, etc.) can be identified specifically and modified
+   in whichever way you like.
+3. It remains easy to write a simple script which just suffixes (or prefixes) a
+   status line input, because tools like i3status will output their JSON in
+   such a way that each line array will be terminated by a newline. Therefore,
+   you are not required to use a streaming JSON parser, but you can use any
+   JSON parser and write your script in any programming language. In fact, you
+   can decide to not bother with the JSON parsing at all and just inject your
+   output at a specific position (beginning or end).
+4. Relying on JSON does not introduce any new dependencies. In fact, the IPC
+   interface of i3 also uses JSON, therefore i3bar already depends on JSON.
+
+The only point against using JSON is computational complexity. If that really
+bothers you, just use the plain text input format (which i3bar will continue to
+support).
+
+== The protocol
+
+The first message of the protocol is a header block, which contains (at least)
+the version of the protocol to be used. In case there are significant changes
+(not only additions), the version will be incremented. i3bar will still
+understand the old protocol version, but in order to use the new one, you need
+to provide the correct version. The header block is terminated by a newline and
+consists of a single JSON hash:
+
+*Example*:
+----------------
+{ "version": 1 }
+----------------
+
+What follows is an infinite array (so it should be parsed by a streaming JSON
+parser, but as described above you can go for a simpler solution), whose
+elements are one array per status line. A status line is one unit of
+information which should be displayed at a time. i3bar will not display any
+input until the status line is complete. In each status line, every block will
+be represented by a JSON hash:
+
+*Example*:
+------
+[
+
+ [
+  {
+   "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
+   "color": "#00ff00"
+  },
+  {
+   "full_text": "2012-01-05 20:00:01"
+  }
+ ],
+
+ [
+  {
+   "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
+   "color": "#00ff00"
+  },
+  {
+   "full_text": "2012-01-05 20:00:02"
+  }
+ ],
+ …
+------
+
+Please note that this example was pretty printed for human consumption.
+i3status and others will output single statuslines in one line, separated by
+\n.
+
+=== Blocks in detail
+
+full_text::
+	The most simple block you can think of is one which just includes the
+	only required key, the +full_text+ key. i3bar will display the string
+	value and that’s it.
+short_text::
+	Where appropriate, the +short_text+ (string) entry should also be
+	provided. It will be used in case the status line needs to be shortened
+	because it uses more space than your screen provides. For example, when
+	displaying an IPv6 address, the prefix is usually (!) more relevant
+	than the suffix, because the latter stays constant when using autoconf,
+	while the prefix changes. When displaying the date, the time is more
+	important than the date (it is more likely that you know which day it
+	is than what time it is).
+color::
+	To make the current state of the information easy to spot, colors can
+	be used. For example, the wireless block could be displayed in red
+	(using the +color+ (string) entry) if the card is not associated with
+	any network and in green or yellow (depending on the signal strength)
+	when it is associated.
+	Colors are specified in hex (like in HTML), starting with a leading
+	hash sign. For example, +#ff0000+ means red.
+name and instance::
+	Every block should have a unique +name+ (string) entry so that it can
+	be easily identified in scripts which process the output. i3bar
+	completely ignores the name and instance fields. Make sure to also
+	specify an +instance+ (string) entry where appropriate. For example,
+	the user can have multiple disk space blocks for multiple mount points.
+urgent::
+	A boolean which specifies whether the current value is urgent. Examples
+	are battery charge values below 1 percent or no more available disk
+	space (for non-root users). The presentation of urgency is up to i3bar.
+
+If you want to put in your own entries into a block, prefix the key with an
+underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing
+them with an underscore makes it clear in every script that they are not part
+of the i3bar protocol.
+
+*Example*:
+------------------------------------------
+{
+ "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
+ "_ethernet_vendor": "Intel"
+}
+------------------------------------------
+
+An example of a block which uses all possible entries follows:
+
+*Example*:
+------------------------------------------
+{
+ "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
+ "short_text": "10.0.0.1",
+ "color": "#00ff00",
+ "urgent": false,
+ "name": "ethernet",
+ "instance": "eth0"
+}
+------------------------------------------