add user-contributed docs: using conky with i3bar (with JSON)

diff --git a/docs/index.html.mako b/docs/index.html.mako
index bf80d27fe157316b75296179f99162cae1863cfe..519005b639a0bc9248d0682796148b5e67d15d10 100644 (file)
--- a/docs/index.html.mako
+++ b/docs/index.html.mako
@@ -94,6 +94,12 @@ workspaces</strong></a> <span class="author">(2012-09, by Sagar)</span><br>
 Shows how Sagar uses i3’s IPC interface to swap workspaces between two outputs.
 </p>
 
+<p>
+<a href="/docs/user-contributed/conky-i3bar.html"><strong>Using conky with
+i3bar</strong></a> <span class="author">(2012-11, by Gianrico)</span><br>
+Shows how to configure conky to generate JSON input for i3bar (with colors)!
+</p>
+
 </div>
 
 </div>

diff --git a/docs/user-contributed/conky-i3bar.html.mako b/docs/user-contributed/conky-i3bar.html.mako
new file mode 100644 (file)
index 0000000..4638e3b
--- /dev/null
+++ b/docs/user-contributed/conky-i3bar.html.mako
@@ -0,0 +1,156 @@
+<%!
+       section = "docs"
+%>
+<%inherit file="_templates/i3.mako" />
+<div id="content" class="usergen">
+<h1>User-contributed article: Using conky with i3bar</h1>
+
+<p>
+As explained in the i3 documentation, it’s possible to <a
+href="http://i3wm.org/docs/userguide.html#_displaying_a_status_line">use an
+external program to build the status information displayed
+by i3bar</a>.
+One of those programs is <a href="http://conky.sourceforge.net/">conky, a free,
+light-weight system monitor</a>.
+</p>
+
+<p>
+Since conky does not support the i3bar protocol by default, we could use the
+plain text output format, but then we cannot have i3bar display colors. This
+article shows how to configure conky to have colors with i3bar.
+</p>
+
+<p>
+As explained in more detail in the <a
+href="http://i3wm.org/docs/i3bar-protocol.html">i3bar protocol description</a>,
+i3bar can receive input serialized as JSON, and this way has color support,
+among other things (urgency flag, shortening description if more space is needed).
+</p>
+
+<h2>Example of colored status with conky</h2>
+
+<p>
+First of all we have to understand how i3bar expects JSON input:
+We have to provide an "infinite array", each element on that array is a "status
+line" that is displayed at a certain moment by i3bar.
+</p>
+
+<p>
+Let's make a short example. 
+We want to build a very simple status that displays the amunt of free space in
+home folder and the percentage of used RAM.
+Here's a sample JSON text for achieving our goal:
+</p>
+
+<pre><tt>{ "version": 1 }
+[
+ [].
+
+ [ { "full_text":"Home 84.0G Free", "color":"#ffffff" },
+   { "full_text":"RAM 32%" , "color":"#ffffff" } ],
+
+ [ { "full_text":"Home 84.0G Free", "color":"#ffffff" },
+   { "full_text":"RAM 34%" , "color":"#ffffff" } ],
+
+ [....],
+ [....],
+ ...</tt></pre>
+
+<p>
+The first line tells i3bar that we are using JSON input.
+The second line is the opening of the "infinite array".
+Each line after second is one "instance status" to be displayed in i3bar, 
+</p>
+
+<h2>Wrapper script</h2>
+
+<p>
+To obtain this output with conky we have to use it in combination with a short script.
+The script will write down the "fixed" part of the output (first and second line), then it will call conky.
+It will be conky’s duty to write each of the "instances".
+</p>
+
+<p>
+The script is quite simple:
+</p>
+
+<pre><tt>#!/bin/sh
+
+# 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:
+exec conky -c $HOME/.conkyrc</tt></pre>
+
+<p>
+Let's save this script as <tt>conky-i3bar</tt> in <tt>$HOME/bin</tt>.
+In the i3 config file the <tt>bar</tt> config will be something like that
+</p>
+
+<pre><tt>bar {
+    status_command $HOME/bin/conky-i3bar
+}</tt></pre>
+
+<h2>conky configuration</h2>
+
+<p>
+Now we have to write a <tt>~/.conkyrc</tt> file in order to obtain the desired status:
+</p>
+
+<pre><tt>[{ "full_text":"Home 84.0G Free" , "color":"#ffffff" },
+ { "full_text":"RAM 32%" , "color":"#ffffff" }],</tt></pre>
+
+<p>
+Here's a sample conkyrc that updates every 2 seconds. Just to make things a litte bit more exciting 
+we put a condition in the script in order to write the occupied RAM in red if the amount is more than 90%:
+</p>
+
+<pre><tt>out_to_x no
+own_window no
+out_to_console yes
+background no
+max_text_width 0
+
+# Update interval in seconds
+update_interval 2.0
+
+# This is the number of times Conky will update before quitting.
+# Set to zero to run forever.
+total_run_times 0
+
+# Shortens units to a single character (kiB->k, GiB->G, etc.). Default is off.
+short_units yes
+
+# How strict should if_up be when testing an interface for being up?
+# The value is one of up, link or address, to check for the interface
+# being solely up, being up and having link or being up, having link
+# and an assigned IP address. 
+if_up_strictness address
+
+# Add spaces to keep things from moving about?  This only affects certain objects.
+# use_spacer should have an argument of left, right, or none
+use_spacer left
+
+# Force UTF8? note that UTF8 support required XFT
+override_utf8_locale no
+
+# number of cpu samples to average
+# set to 1 to disable averaging
+cpu_avg_samples 2
+
+# Stuff after 'TEXT' will be formatted on screen
+TEXT
+
+# JSON for i3bar
+<%text filter="h">
+ [{ "full_text" : "Home ${fs_free /home} Free" , "color" : "\#ffffff" } , 
+  { "full_text" : "RAM ${memperc}%" , "color" :
+    ${if_match ${memperc}<90}"\#ffffff"${else}"\#ff0000"${endif} } , 
+</%text>
+]</tt></pre>