Implement aggregates for batteries.

[i3/i3status] / man / i3status.man

diff --git a/man/i3status.man b/man/i3status.man
index f71ce9821bb22f62f7126e6ad8b344edd540ab4e..cdde2aa3906dcb63fdbe315f03033a23104db63e 100644 (file)
--- a/man/i3status.man
+++ b/man/i3status.man
@@ -17,10 +17,10 @@ i3status [-c configfile] [-h] [-v]
 Specifies an alternate configuration file path. By default, i3status looks for
 configuration files in the following order:
 
-1. ~/.i3status.conf
-2. ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set)
-3. /etc/i3status.conf
-4. /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set)
+1. ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set)
+2. /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set)
+3. ~/.i3status.conf
+4. /etc/i3status.conf
 
 == DESCRIPTION
 
@@ -76,6 +76,7 @@ battery 0 {
         format_down = "No battery"
         status_chr = "⚡ CHR"
         status_bat = "🔋 BAT"
+        status_unk = "? UNK"
         status_full = "☻ FULL"
         path = "/sys/class/power_supply/BAT%d/uevent"
         low_threshold = 10
@@ -248,9 +249,7 @@ is assumed to be "percentage_avail" and low_threshold to be set to 0, which
 implies no coloring at all.
 
 You can define a different format with the option "format_not_mounted"
-which is used if the path does not exist or is not a mount point. So you can just empty
-the output for the given path with adding +format_not_mounted=""+
-to the config section.
+which is used if the path does not exist or is not a mount point. Defaults to "".
 
 *Example order*: +disk /mnt/usbstick+
 
@@ -315,7 +314,7 @@ network interface found on the system (excluding devices starting with "lo").
 
 === Battery
 
-Gets the status (charging, discharging, running), percentage, remaining
+Gets the status (charging, discharging, unknown, full), percentage, remaining
 time and power consumption (in Watts) of the given battery and when it's
 estimated to be empty. If you want to use the last full capacity instead of the
 design capacity (when using the design capacity, it may happen that your
@@ -337,14 +336,20 @@ colored red. The low_threshold type can be of threshold_type "time" or
 "percentage". So, if you configure low_threshold to 10 and threshold_type to
 "time", and your battery lasts another 9 minutes, it will be colored red.
 
+To show an aggregate of all batteries in the system, use "all" as the number. In
+this case (for Linux), the /sys path must contain the "%d" sequence. Otherwise,
+the number indicates the battery index as reported in /sys.
+
 Optionally custom strings including any UTF-8 symbols can be used for different
 battery states. This makes it possible to display individual symbols
-for each state (charging, discharging, full)
+for each state (charging, discharging, unknown, full)
 Of course it will also work with special iconic fonts, such as FontAwesome.
-If any of this special status strings is omitted, the default (CHR, BAT, FULL)
-is used.
+If any of these special status strings are omitted, the default (CHR, BAT, UNK,
+FULL) is used.
+
+*Example order (for the first battery)*: +battery 0+
 
-*Example order*: +battery 0+
+*Example order (aggregate of all batteries)*: +battery all+
 
 *Example format*: +%status %remaining (%emptytime %consumption)+
 
@@ -354,13 +359,17 @@ is used.
 
 *Example status_bat*: +🔋 BAT+
 
+*Example status_unk*: +? UNK+
+
 *Example status_full*: +☻ FULL+
 
 *Example low_threshold*: +30+
 
 *Example threshold_type*: +time+
 
-*Example path*: +/sys/class/power_supply/CMB1/uevent+
+*Example path (%d replaced by title number)*: +/sys/class/power_supply/CMB%d/uevent+
+
+*Example path (ignoring the number)*: +/sys/class/power_supply/CMB1/uevent+
 
 === CPU-Temperature
 
@@ -378,12 +387,25 @@ specified thermal zone is getting too hot. Defaults to 75 degrees C.
 
 === CPU Usage
 
-Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+ (FreeBSD/OpenBSD).
+Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+
+(FreeBSD/OpenBSD).
+
+It is possible to define a max_threshold that will color the load
+value red in case the CPU average over the last interval is getting
+higher than the configured threshold. Defaults to 95.
+
+It is possible to define a degraded_threshold that will color the load
+value yellow in case the CPU average over the last interval is getting
+higher than the configured threshold.  Defaults to 90.
 
 *Example order*: +cpu_usage+
 
 *Example format*: +%usage+
 
+*Example max_threshold*: +75+
+
+*Example degraded_threshold*: +25+
+
 === Load
 
 Gets the system load (number of processes waiting for CPU time in the last
@@ -430,9 +452,10 @@ If you would like to use markup in this section, there is a separate
 
 *Example configuration (markup)*:
 -------------------------------------------------------------
-tztime time {
+tztime berlin {
        format = "<span foreground='#ffffff'>time:</span> %time"
        format_time = "%H:%M %Z"
+       timezone = "Europe/Berlin"
 }
 -------------------------------------------------------------
 
@@ -613,7 +636,7 @@ Put that in some script, say +.bin/my_i3status.sh+ and execute that instead of i
 
 Note that if you want to use the JSON output format (with colors in i3bar), you
 need to use a slightly more complex wrapper script. There are examples in the
-contrib/ folder, see http://code.i3wm.org/i3status/tree/contrib
+contrib/ folder, see http://code.i3wm.org/i3status/tree/master/contrib
 
 == SIGNALS