From f94edd9fc3b5656ca197fb3f08a565b7894f4b52 Mon Sep 17 00:00:00 2001
From: Michael Stapelberg <michael@stapelberg.de>
Date: Sun, 12 Aug 2012 18:47:24 +0200
Subject: [PATCH] i3bar-protocol: add example (illustration-only!) shell
 script, clarify {"version":1} header

---
 contrib/trivial-bar-script.sh | 29 +++++++++++++++++++++++++++++
 docs/i3bar-protocol           |  9 ++++++++-
 2 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100755 contrib/trivial-bar-script.sh

diff --git a/contrib/trivial-bar-script.sh b/contrib/trivial-bar-script.sh
new file mode 100755
index 00000000..15bc7dee
--- /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 f66c7a9a..21ba9aa0 100644
--- a/docs/i3bar-protocol
+++ b/docs/i3bar-protocol
@@ -1,7 +1,7 @@
 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.
@@ -49,6 +49,9 @@ consists of a single JSON hash:
 { "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
@@ -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.
 
+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::
-- 
2.39.2