release v2.10

[i3/i3status] / man / i3status.man

diff --git a/man/i3status.man b/man/i3status.man
index 06dc4a64cc1842520375027e1dbd568ef2d1b512..836cac590ac99c8ad928f9e0253b775eb1e1482c 100644 (file)
--- a/man/i3status.man
+++ b/man/i3status.man
@@ -1,11 +1,11 @@
 i3status(1)
 ===========
 Michael Stapelberg <michael@i3wm.org>
 i3status(1)
 ===========
 Michael Stapelberg <michael@i3wm.org>

-v2.8, January 2014
+v2.10, January 2016

 
 == NAME
 
 
 == NAME
 

-i3status - Generates a status line for i3bar, dzen2 or xmobar
+i3status - Generates a status line for i3bar, dzen2, xmobar or lemonbar

 
 == SYNOPSIS
 
 
 == SYNOPSIS
 


@@ -25,7 +25,7 @@ configuration files in the following order:
 == DESCRIPTION
 
 i3status is a small program (about 1500 SLOC) for generating a status bar for
 == DESCRIPTION
 
 i3status is a small program (about 1500 SLOC) for generating a status bar for

-i3bar, dzen2, xmobar or similar programs. It is designed to be very
+i3bar, dzen2, xmobar, lemonbar or similar programs. It is designed to be very

 efficient by issuing a very small number of system calls, as one generally
 wants to update such a status line every second. This ensures that even under
 high load, your status bar is updated correctly. Also, it saves a bit of energy
 efficient by issuing a very small number of system calls, as one generally
 wants to update such a status line every second. This ensures that even under
 high load, your status bar is updated correctly. Also, it saves a bit of energy


@@ -74,7 +74,7 @@ ethernet eth0 {
 battery 0 {
         format = "%status %percentage %remaining %emptytime"
         format_down = "No battery"
 battery 0 {
         format = "%status %percentage %remaining %emptytime"
         format_down = "No battery"

-        status_chr = "⚇ CHR""
+        status_chr = "⚇ CHR"

         status_bat = "⚡ BAT"
         status_full = "☻ FULL"
         path = "/sys/class/power_supply/BAT%d/uevent"
         status_bat = "⚡ BAT"
         status_full = "☻ FULL"
         path = "/sys/class/power_supply/BAT%d/uevent"


@@ -157,6 +157,9 @@ managers like dwm, wmii and xmonad though it will work with any windowmanger
 xmobar::
 xmobar is a minimalistic, text based, status bar. It was designed to work
 with the xmonad Window Manager.
 xmobar::
 xmobar is a minimalistic, text based, status bar. It was designed to work
 with the xmonad Window Manager.

+lemonbar::
+lemonbar is a lightweight bar based entirely on XCB. It has full UTF-8 support
+and is EWMH compliant.

 term::
 Use ANSI Escape sequences to produce a terminal-output as close as possible to
 the graphical outputs. This makes debugging your config file a little bit
 term::
 Use ANSI Escape sequences to produce a terminal-output as close as possible to
 the graphical outputs. This makes debugging your config file a little bit


@@ -181,6 +184,13 @@ format as the separator is drawn by i3bar directly otherwise. For the other
 output formats, the provided non-empty string will be automatically enclosed
 with the necessary coloring bits if color support is enabled.
 
 output formats, the provided non-empty string will be automatically enclosed
 with the necessary coloring bits if color support is enabled.
 

+i3bar supports Pango markup, allowing your format strings to specify font
+color, size, etc. by setting the +markup+ directive to "pango". Note that the
+ampersand ("&"), less-than ("<"), greater-than (">"), single-quote ("'"), and
+double-quote (""") characters need to be replaced with "`&amp;`", "`&lt;`",
+"`&gt;`", "`&apos;`", and "`&quot;`" respectively. This is done automatically
+for generated content (e.g. wireless ESSID, time).
+

 *Example configuration*:
 -------------------------------------------------------------
 general {
 *Example configuration*:
 -------------------------------------------------------------
 general {


@@ -237,6 +247,11 @@ space is below 2 GiB, it will be colored bad. If not specified, threshold_type
 is assumed to be "percentage_avail" and low_threshold to be set to 0, which
 implies no coloring at all.
 
 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.
+

 *Example order*: +disk /mnt/usbstick+
 
 *Example format*: +%free (%avail)/ %total+
 *Example order*: +disk /mnt/usbstick+
 
 *Example format*: +%free (%avail)/ %total+


@@ -254,6 +269,8 @@ implies no coloring at all.
 Expands the given path to a pidfile and checks if the process ID found inside
 is valid (that is, if the process is running). You can use this to check if
 a specific application, such as a VPN client or your DHCP client is running.
 Expands the given path to a pidfile and checks if the process ID found inside
 is valid (that is, if the process is running). You can use this to check if
 a specific application, such as a VPN client or your DHCP client is running.

+There also is an option "format_down". You can hide the output with
++format_down=""+.

 
 *Example order*: +run_watch DHCP+
 
 
 *Example order*: +run_watch DHCP+
 


@@ -263,6 +280,8 @@ a specific application, such as a VPN client or your DHCP client is running.
 
 Checks if the given path exists in the filesystem. You can use this to check if
 something is active, like for example a VPN tunnel managed by NetworkManager.
 
 Checks if the given path exists in the filesystem. You can use this to check if
 something is active, like for example a VPN tunnel managed by NetworkManager.

+There also is an option "format_down". You can hide the output with
++format_down=""+.

 
 *Example order*: +path_exists VPN+
 
 
 *Example order*: +path_exists VPN+
 


@@ -274,6 +293,9 @@ Gets the link quality, frequency and ESSID of the given wireless network
 interface. You can specify different format strings for the network being
 connected or not connected.
 
 interface. You can specify different format strings for the network being
 connected or not connected.
 

+The special interface name `_first_` will be replaced by the first wireless
+network interface found on the system (excluding devices starting with "lo").
+

 *Example order*: +wireless wlan0+
 
 *Example format*: +W: (%quality at %essid, %bitrate / %frequency) %ip+
 *Example order*: +wireless wlan0+
 
 *Example format*: +W: (%quality at %essid, %bitrate / %frequency) %ip+


@@ -284,6 +306,9 @@ Gets the IP address and (if possible) the link speed of the given ethernet
 interface. Getting the link speed requires the cap_net_admin capability. Set
 it using +setcap cap_net_admin=ep $(which i3status)+.
 
 interface. Getting the link speed requires the cap_net_admin capability. Set
 it using +setcap cap_net_admin=ep $(which i3status)+.
 

+The special interface name `_first_` will be replaced by the first non-wireless
+network interface found on the system (excluding devices starting with "lo").
+

 *Example order*: +ethernet eth0+
 
 *Example format*: +E: %ip (%speed)+
 *Example order*: +ethernet eth0+
 
 *Example format*: +E: %ip (%speed)+


@@ -399,6 +424,18 @@ in the +tztime+ module.
 
 *Example timezone*: +Europe/Berlin+
 
 
 *Example timezone*: +Europe/Berlin+
 

+If you would like to use markup in this section, there is a separate
++format_time+ option that is automatically escaped. Its output then replaces
+%time in the format string.
+
+*Example configuration (markup)*:
+-------------------------------------------------------------
+tztime time {
+       format = "<span foreground='#ffffff'>time:</span> %time"
+       format_time = "%H:%M %Z"
+}
+-------------------------------------------------------------
+

 === DDate
 
 Outputs the current discordian date in user-specified format. See +ddate(1)+ for
 === DDate
 
 Outputs the current discordian date in user-specified format. See +ddate(1)+ for


@@ -411,17 +448,31 @@ details on the format string.
 
 === Volume
 
 
 === Volume
 

-Outputs the volume of the specified mixer on the specified device. Works only
-on Linux because it uses ALSA.
-A simplified configuration can be used on FreeBSD and OpenBSD due to
-the lack of ALSA,  the +device+ and +mixer+ options can be
-ignored on these systems. On these systems the OSS API is used instead to
-query +/dev/mixer+ directly if +mixer_dix+ is -1, otherwise
-+/dev/mixer++mixer_idx+.
+Outputs the volume of the specified mixer on the specified device.  PulseAudio
+and ALSA (Linux only) are supported.  If PulseAudio is absent, a simplified
+configuration can be used on FreeBSD and OpenBSD due to the lack of ALSA,  the
++device+ and +mixer+ options can be ignored on these systems. On these systems
+the OSS API is used instead to query +/dev/mixer+ directly if +mixer_idx+ is
+-1, otherwise +/dev/mixer++mixer_idx+.
+
+To get PulseAudio volume information, one must use the following format in the
+device line:
+
+ device = "pulse"
+
+or
+
+ device = "pulse:N"
+
+where N is the index of the PulseAudio sink. If no sink is specified the
+default is used. If the device string is missing or is set to "default",
+PulseAudio will be tried if detected and will fallback to ALSA (Linux)
+or OSS (FreeBSD/OpenBSD).

 
 *Example order*: +volume master+
 
 *Example format*: +♪: %volume+
 
 *Example order*: +volume master+
 
 *Example format*: +♪: %volume+

+

 *Example format_muted*: +♪: 0%%+
 
 *Example configuration*:
 *Example format_muted*: +♪: 0%%+
 
 *Example configuration*:


@@ -434,6 +485,14 @@ volume master {
        mixer_idx = 0
 }
 -------------------------------------------------------------
        mixer_idx = 0
 }
 -------------------------------------------------------------

+*Example configuration (PulseAudio)*:
+-------------------------------------------------------------
+volume master {
+       format = "♪: %volume"
+       format_muted = "♪: muted (%volume)"
+       device = "pulse:1"
+}
+-------------------------------------------------------------

 
 == Universal module options
 
 
 == Universal module options