timer: Add a "real world" example

This was asked on IRC. While many user configs have such patterns,
the documentation had none.

It isn't using the test framework because of the delay.

lib/gears/timer.lua

@@ -1,6 +1,48 @@
 ---------------------------------------------------------------------------
 --- Timer objects and functions.
 --
+-- @usage
+--    -- Create a widget and update its content using the output of a shell
+--    -- command every 10 seconds:
+--    local mybatterybar = wibox.widget {
+--        {
+--            min_value    = 0,
+--            max_value    = 100,
+--            value        = 0,
+--            paddings     = 1,
+--            border_width = 1,
+--            forced_width = 50,
+--            border_color = "#0000ff",
+--            id           = "mypb",
+--            widget       = wibox.widget.progressbar,
+--        },
+--        {
+--            id           = "mytb",
+--            text         = "100%",
+--            widget       = wibox.widget.textbox,
+--        },
+--        layout      = wibox.layout.stack,
+--        set_battery = function(self, val)
+--            self.mytb.text  = tonumber(val).."%"
+--            self.mypb.value = tonumber(val)
+--        end,
+--    }
+--
+--    gears.timer {
+--        timeout   = 10,
+--        autostart = true,
+--        callback  = function()
+--            -- You should read it from `/sys/class/power_supply/` (on Linux)
+--            -- instead of spawning a shell. This is only an example.
+--            awful.spawn.easy_async(
+--                {"sh", "-c", "acpi | sed -n 's/^.*, \([0-9]*\)%/\1/p'"},
+--                function(out)
+--                    mybatterybar.battery = out
+--                end
+--            )
+--        end
+--    }
+--
 -- @author Uli Schlachter
 -- @copyright 2014 Uli Schlachter
 -- @classmod gears.timer