i3bar-protocol: add example (illustration-only!) shell script, clarify {"version...

diff --git a/contrib/trivial-bar-script.sh b/contrib/trivial-bar-script.sh
new file mode 100755 (executable)
index 0000000..15bc7de
--- /dev/null
+++ b/contrib/trivial-bar-script.sh
@@ -0,0 +1,29 @@
+#!/bin/sh
+# vim:ts=4:sw=4:expandtab
+# © 2012 Michael Stapelberg, Public Domain
+
+# This script is a trivial shell script to send your own output to i3bar while
+# using the JSON protocol.
+#
+# It is ugly and that is inherent to using JSON with shell scripts. You
+# _really_ should not do that. See i3status or i3status’s contrib/ directory
+# for examples of how to handle the output in higher-level languages.
+#
+# This example is purely for illustration of the protocol. DO NOT USE IT IN THE
+# REAL WORLD.
+
+# Send the header so that i3bar knows we want to use JSON:
+echo '{ "version": 1 }'
+
+# Begin the endless array.
+echo '['
+
+# We send an empty first array of blocks to make the loop simpler:
+echo '[]'
+
+# Now send blocks with information forever:
+while :;
+do
+       echo ",[{\"name\":\"time\",\"full_text\":\"$(date)\"}]"
+       sleep 1
+done

diff --git a/docs/i3bar-protocol b/docs/i3bar-protocol
index f66c7a9a6129a8c90b9175aa4a963bbe9ed8c7a2..21ba9aa0f8e350252e1fdbc8f7a8f76b9d125056 100644 (file)
--- a/docs/i3bar-protocol
+++ b/docs/i3bar-protocol
@@ -1,7 +1,7 @@
 i3bar input protocol
 ====================
 Michael Stapelberg <michael@i3wm.org>
 i3bar input protocol
 ====================
 Michael Stapelberg <michael@i3wm.org>

-February 2012
+August 2012

 
 This document explains the protocol in which i3bar expects its input. It
 provides support for colors, urgency, shortening and easy manipulation.
 
 This document explains the protocol in which i3bar expects its input. It
 provides support for colors, urgency, shortening and easy manipulation.


@@ -49,6 +49,9 @@ consists of a single JSON hash:
 { "version": 1 }
 ----------------
 
 { "version": 1 }
 ----------------
 

+(Note that before i3 v4.3 the precise format had to be +{"version":1}+,
+byte-for-byte.)
+

 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
 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


@@ -86,6 +89,10 @@ Please note that this example was pretty printed for human consumption.
 i3status and others will output single statuslines in one line, separated by
 \n.
 
 i3status and others will output single statuslines in one line, separated by
 \n.
 

+You can find an example of a shell script which can be used as your
++status_command+ in the bar configuration at
+http://code.stapelberg.de/git/i3/tree/contrib/trivial-bar-script.sh?h=next
+

 === Blocks in detail
 
 full_text::
 === Blocks in detail
 
 full_text::