From: Michael Stapelberg Date: Mon, 12 Oct 2009 07:57:42 +0000 (+0200) Subject: Add manpage in asciidoc format X-Git-Tag: 2.0~23 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=1815ea410db7439b7d0c574cb49bd017776da0fd;p=i3%2Fi3status Add manpage in asciidoc format --- diff --git a/i3status.1 b/i3status.1 deleted file mode 100644 index facd043..0000000 --- a/i3status.1 +++ /dev/null @@ -1,158 +0,0 @@ -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. - -.TH i3status 1 "MAY 2009" Linux "User Manuals" - -.SH NAME -i3status \- Generates a status line for dzen2 or wmii -.SH SYNOPSIS -.B i3status -.RB [\|\-c -.IR configfile \|] - -.SH DESCRIPTION - -.B i3status -is a small program (around 500 SLOC) for filling dzen2 or wmii's status bar via -its 9P pseudo filesystem. It is designed to be very efficient by issuing a very -small number of systemcalls (as the bar should be updated every second or at -your specified interval). This ensures that even under high load, your status bar -is updated correctly and it saves a little bit of battery life by not spawning -new processes every second like shell scripts does. - -.SH CONFIGURATION -.TP -.B wlan -Specifies the name of your WLAN interface (e.g. wlan0 or ath0 or eth1). Don't -specify if you don't have a WLAN interface or if it should not be displayed. - -.TP -.B eth -Specifies the name of your ethernet interface (e.g. eth0). Don't specify if you -don't have an ethernet interface or if it should not be displayed. - -.TP -.B wmii_path -Specifies the path to the rbar-folder of your mounted wmii pseudo file system -(e.g. /mnt/wmii/rbar/). It has to be terminated by a slash. - -.TP -.B time_format -Format for the time/date to be displayed. See strftime(3) or date(1). Don't -specify it if you don't want the time to be shown. - -.TP -.B battery -The number of the battery you want to display. This option can be specified -multiple times to display multiple batteries. Don't specify it if you don't -have a battery. To get the number of the specific battery, see -/sys/class/power_supply/BAT* - -If you want i3status to use the last full capacity instead of the design capacity -of the battery, specify the f-flag, like this: - -.Vb 10 -# Use the last full capacity -battery 0,f -.Ve - -.TP -.B run_watch -You can specify this directive multiple times. Each line first has a name (one -word, separated by space) followed by a path (can contain wildcards, given to -glob(3)). The path is the path to a PID-file which contains just the process ID -of a process. i3status will then check if the process is still running and -displays "yes" or "no" depending on the status. This is useful for displaying -if your VPN is running, or dhclient for DHCP and so on... - -.TP -.B order -Followed by a comma separated list of the modules (run, wlan, eth, battery, -load, time) this directive specifies the order of the information which should -be displayed. An order is accomplished by prefixing the files in wmii's /rbar -directory with a number, that is 0VPN, 1DHCP, 2time and so on.. - -.TP -.B color -If specified, color mode is on. This affects WLAN which will be displayed red -if WLAN is down and the run_watch system which will display the status in -red/green. - -.TP -.B get_ethspeed -Get current speed of the ethernet interface using the same mechanism as -ethtool. You need to start i3status with root privileges to use this. - -.TP -.B get_cpu_temperature -Gets the temperature of the first thermal zone or the specified thermal zone -(if any). Use it to display your CPU temperature. - -.TP -.B normcolors -Specifies the colors for background/border in the same format (html colorcodes) -as wmii's configuration (just the last two values), that is #222222 #333333 for -example. Text color will be determined automatically (red/green/#888888), -depending on context. - -.TP -.B interval -Specifies the interval in which the status bar will be updated. If you got a -very slow system or feel you don't need so much information, you may want to -increase it. - -.SH FILES -.TP -.B /etc/i3status.conf -System-wide configuration file. - -.SH EXAMPLE CONFIGURATION -.PP -.Vb 10 -\&wlan wlan0 -\ð eth0 -\&wmii_path /mnt/wmii/rbar/ -\&time_format %d.%m.%Y %H:%M:%S -\&battery 0 -\&battery 1,f -\&run_watch DHCP /var/run/dhclient*.pid -\&run_watch VPN /var/run/vpnc*.pid -\&order run,wlan,eth,battery,load,time -\&normcolors #000000 #333333 -\&color -\&get_cpu_temperature -.Ve - -.SH MOUNTING WMII'S PSEUDO FILESYSTEM -As of now (February 2009, Linux 2.6.28) you can mount wmii's 9P pseudo filesystem using: -.PP -.Vb 3 -mount -t 9p -o rw,trans=unix,uname=michael,dfltuid=1000,dfltgid=50,name=michael,noauto,noextend /tmp/ns.michael.:0/wmii /mnt/wmii -# Perhaps you need to load module 9pnet_fd if that does not work -modprobe 9pnet_fd -.Ve - -.SH BUGS -Sometimes, i3status crashes when the wlan interface vanishes (killswitch). I -haven't yet found the bug, as it is not reproducible. If you can reproduce -this, please fix it and send me a patch. - -.SH SEE ALSO -.BR strftime (3), -.BR date (1), -.BR glob (3) - -.SH AUTHORS -Michael Stapelberg - -Thorsten Toepper - -.SH WEBSITE -See http://i3.zekjur.net/i3status for the newest release. diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 0000000..7b00eab --- /dev/null +++ b/man/Makefile @@ -0,0 +1,4 @@ +all: + a2x -f manpage --asciidoc-opts="-f asciidoc.conf" i3status.man +clean: + rm -f i3status.xml i3status.1 i3status.html diff --git a/man/asciidoc.conf b/man/asciidoc.conf new file mode 100644 index 0000000..b9f6023 --- /dev/null +++ b/man/asciidoc.conf @@ -0,0 +1,18 @@ +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +i3status +v2 +i3 Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/man/i3status.man b/man/i3status.man new file mode 100644 index 0000000..d73c6cc --- /dev/null +++ b/man/i3status.man @@ -0,0 +1,209 @@ +i3status(1) +=========== +Michael Stapelberg +v2, October 2009 + +== NAME + +i3status - Generates a status line for dzen2 or xmobar + +== SYNOPSIS + +i3status [-c configfile] + +== OPTIONS + +-c:: +Specifies an alternate configuration file path (default is /etc/i3status.conf +or ~/.i3status.conf). + +== DESCRIPTION + +i3status is a small program (less than 1000 SLOC) for generating a status bar +for dzen2, xmobar or similar programs. It is designed to be very efficient by +issuing a very small number of systemcalls, 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 by not hogging +your CPU as much as spawning the corresponding amount of shell commands would. + +== CONFIGURATION + +Since version 2, the configuration file for i3status will be parsed using +libconfuse. This makes configuration easier in the programmer’s point of +view and more flexible for the user at the same time. + +The basic idea of i3status is that you can specify which "modules" should +be used (the order directive). You can then configure each module with its +own section. For every module, you can specify the output format. See below +for a complete reference. + +.Sample configuration +------------------------------------------------------------- +general { + colors = true + interval = 5 +} + +order = "ipv6" +order += "disk /" +order += "run_watch DHCP" +order += "run_watch VPN" +order += "wireless wlan0" +order += "ethernet eth0" +order += "battery 0" +order += "cpu_temperature 0" +order += "load" +order += "time" + +wireless wlan0 { + format_up = "W: (%quality at %essid) %ip" + format_down = "W: down" +} + +ethernet eth0 { + # if you use %speed, i3status requires root privileges + format = "E: %ip (%speed)" +} + +battery 0 { + format = "%status %remaining" +} + +run_watch DHCP { + pidfile = "/var/run/dhclient*.pid" +} + +run_watch VPN { + pidfile = "/var/run/vpnc/pid" +} + +time { + format = "%Y-%m-%d %H:%M:%S" +} + +load { + format = "%5min" +} + +cpu_temperature 0 { + format = "T: %degrees °C" +} + +disk "/" { + format = "%free" +} +------------------------------------------------------------- + +=== General + +The colors directive will disable all colors if you set it to +false+. ++interval+ is the time in seconds which i3status will sleep until printing +the next status line. + +=== IPv6 + +This module gets the IPv6 address used for outgoing connections (that is, the +best available public IPv6 address on your computer). + +*Example format*: +%ip+ + +=== Disk + +Gets used, free and total amount of bytes on the given mounted filesystem. + +*Example order*: +disk /mnt/usbstick+ + +*Example format*: +%free / %total+ + +=== Run-watch + +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. + +*Example order*: +run_watch DHCP+ + +=== Wireless + +Gets the link quality and ESSID of the given wireless network interface. You +can specify different format strings for the network being connected or not +connected. + +*Example order*: +wireless wlan0+ + +*Example format*: +W: (%quality at %essid) %ip+ + +=== Ethernet + +Gets the IP address and (if possible) the link speed of the given ethernet +interface. Getting the link speed requires root privileges. + +*Example order*: +ethernet eth0+ + +*Example format*: +E: %ip (%speed)+ + +=== Battery + +Gets the status (charging, discharging, running), percentage and remaining +time of the given battery. + +*Example order*: +battery 0+ + +*Example format*: +%status %remaining+ + +=== CPU-Temperature + +Gets the temperature of the given thermal zone. + +*Example order*: +cpu_temperature 0+ + +*Example format*: +T: %degrees °C+ + +=== Load + +Gets the system load (number of processes waiting for CPU time in the last +5, 10 and 15 minutes). + +*Example order*: +load+ + +*Example format*: +%5min %10min %15min+ + +=== Time + +Formats the current system time. See +strftime(3)+ for the format. + +*Example order*: +time+ + +*Example format*: +%Y-%m-%d %H:%M:%S+ + +== Using i3status with dzen2 + +After installing dzen2, you can directly use it with i3status: + +*Example for usage of i3status with dzen2*: +-------------------------------------------------------------- +i3status | dzen2 -fg white -ta r -w 1280 \ +-fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1" +-------------------------------------------------------------- + +== Using i3status with xmobar + +To get xmobar to start, you might need to copy the default configuration +file to +~/.xmobarrc+. + +*Example for usage of i3status with xmobar*: +--------------------------------------------------------------------- +i3status-xmobar | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]" +--------------------------------------------------------------------- + +== SEE ALSO + ++strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+ + +== AUTHORS + +Michael Stapelberg and contributors + +Thorsten Toepper + +Baptiste Daroussin