-<?xml version="1.0" encoding="UTF-8" ?>
+<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-<!ENTITY testtable SYSTEM "test.xml">
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+[
<!ENTITY command_options SYSTEM "command_options.xml">
<!ENTITY config_settings SYSTEM "config_settings.xml">
<!ENTITY variables SYSTEM "variables.xml">
+<!ENTITY lua SYSTEM "lua.xml">
]>
-
<refentry>
<refentryinfo>
<address>
<firstname>Brenden</firstname>
<surname>Matthews</surname>
</author>
- <date>2008-09-11</date>
+ <date>2010-10-05</date>
</refentryinfo>
-
<refmeta>
<refentrytitle>conky</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
-
<refnamediv>
<refname>conky</refname>
- <refpurpose>A system monitor for X originally based on the torsmo code, but more kickass. It just keeps on given'er. Yeah.</refpurpose>
+ <refpurpose>A system monitor for X originally based on the
+ torsmo code, but more kickass. It just keeps on given'er.
+ Yeah.</refpurpose>
</refnamediv>
-
<refsynopsisdiv>
<cmdsynopsis>
<command>conky</command>
- <arg><replaceable>options</replaceable></arg>
+ <arg>
+ <replaceable>options</replaceable>
+ </arg>
</cmdsynopsis>
</refsynopsisdiv>
-
<refsect1>
<title>Description</title>
- <para>
- Conky is a system monitor for X originally based on torsmo.
- Since its inception, Conky has changed significantly from its predecessor, while maintaining
- simplicity and configurability. Conky can display just about anything, either
- on your root desktop or in its own window. Not only does Conky have many
- built-in objects, it can also display just about any piece of information by
+ <para>Conky is a system monitor for X originally based on
+ torsmo. Since its inception, Conky has changed
+ significantly from its predecessor, while maintaining
+ simplicity and configurability. Conky can display just
+ about anything, either on your root desktop or in its own
+ window. Not only does Conky have many built-in objects, it
+ can also display just about any piece of information by
using scripts and other external programs.
</para>
- <para>
- Conky has more than 250 built in objects, including support for
- a plethora of OS stats (uname, uptime, CPU usage, mem usage, disk
- usage, "top" like process stats, and network monitoring, just to name a few),
- built in IMAP and POP3 support, built in support for many popular
- music players (MPD, XMMS2, BMPx, Audacious), and much much more.
- Conky can display this info either as text, or using simple progress
- bars and graph widgets, with different fonts and colours.
- </para>
- <para>
- We are always looking for help, whether its reporting bugs, writing patches, or writing docs.
- Please use the facilities at SourceForge to make bug reports, feature requests, and submit patches,
- or stop by #conky on irc.freenode.net if you have questions or want to contribute.
+ <para>Conky has more than 250 built in objects, including
+ support for a plethora of OS stats (uname, uptime, CPU
+ usage, mem usage, disk usage, "top" like process stats, and
+ network monitoring, just to name a few), built in IMAP and
+ POP3 support, built in support for many popular music
+ players (MPD, XMMS2, BMPx, Audacious), and much much more.
+ Conky can display this info either as text, or using simple
+ progress bars and graph widgets, with different fonts and
+ colours.
</para>
- <para>
- Thanks for your interest in Conky.
+ <para>We are always looking for help, whether its reporting
+ bugs, writing patches, or writing docs. Please use the
+ facilities at SourceForge to make bug reports, feature
+ requests, and submit patches, or stop by #conky on
+ irc.freenode.net if you have questions or want to
+ contribute.</para>
+ <para>Thanks for your interest in Conky.
</para>
</refsect1>
-
<refsect1>
<title>Compiling</title>
- <para>
- For users compiling from source on a binary distro, make sure you have the X development
- libraries installed. This should be a package along the lines of "libx11-dev" or
- "xorg-x11-dev" for X11 libs, and similar "-dev" format for the other libs required (depending
- on your configure options).
+ <para>For users compiling from source on a binary distro,
+ make sure you have the X development libraries installed
+ (Unless you provide configure with "--disable-x11"). This
+ should be a package along the lines of "libx11-dev" or
+ "xorg-x11-dev" for X11 libs, and similar "-dev" format for
+ the other libs required (depending on your configure
+ options). You should be able to see which extra packages
+ you need to install by reading errors that you get from
+ './configure'. You can enable/disable stuff by giving
+ options to configure, but be careful with disabling. For
+ example: with --disable-math you won't get errors but
+ logarithmic graphs will be normal graphs and gauges
+ will miss their line.
</para>
- <para>
- Conky has (for some time) been available in the repositories of most popular distributions.
- Here are some installation instructions for a few:
+ <para>Conky has (for some time) been available in the
+ repositories of most popular distributions. Here are some
+ installation instructions for a few:
</para>
- <para>
- Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-admin/conky" for installation.
- There is also usually an up-to-date ebuild within Conky's package or in SVN.
+ <para>Gentoo users -- Conky is in Gentoo's Portage...
+ simply use "emerge app-admin/conky" for
+ installation.
</para>
- <para>
- Debian, etc. users -- Conky should be in your repositories, and can be installed by doing
- "aptitude install conky".
+ <para>Debian, etc. users -- Conky should be in your
+ repositories, and can be installed by doing "aptitude
+ install conky".
</para>
- <para>
- Example to compile and run Conky with all optional components (note that some configure options may differ for your system):
+ <para>Example to compile and run Conky with all optional
+ components (note that some configure options may differ for
+ your system):
</para>
<variablelist>
<varlistentry>
<term>
- <command><option>sh autogen.sh</option></command> <option># Only required if building from SVN</option>
+ <command>
+ <option>sh autogen.sh</option>
+ </command>
+ <option># Only required if building from the
+ git repo</option>
</term>
</varlistentry>
<varlistentry>
<term>
- <command><option>./configure </option></command><option>--prefix=/usr --mandir=/usr/share/man --infodir=/usr/share/info --datadir=/usr/share --sysconfdir=/etc --localstatedir=/var/lib --disable-own-window --enable-audacious[=yes|no|legacy] --enable-bmpx --disable-hddtemp --disable-mpd --enable-xmms2 --disable-portmon --disable-network --enable-debug --disable-x11 --disable-double-buffer --disable-xdamage --disable-xft</option>
+ <command>
+ <option>./configure</option>
+ </command>
+ <option>--prefix=/usr --mandir=/usr/share/man
+ --infodir=/usr/share/info --datadir=/usr/share
+ --sysconfdir=/etc --localstatedir=/var/lib
+ --disable-own-window
+ --enable-audacious[=yes|no|legacy]
+ --enable-bmpx --disable-hddtemp --disable-mpd
+ --enable-xmms2 --disable-portmon
+ --disable-network --enable-debug --disable-x11
+ --disable-double-buffer --disable-xdamage
+ --disable-xft</option>
</term>
</varlistentry>
<varlistentry>
<term>
- <command><option>make</option></command>
+ <command>
+ <option>make</option>
+ </command>
</term>
</varlistentry>
<varlistentry>
<term>
- <command><option>make install</option></command> <option># Optional</option>
+ <command>
+ <option>make install</option>
+ </command>
+ <option># Optional</option>
</term>
</varlistentry>
<varlistentry>
<term>
- <command><option>src/conky</option></command>
+ <command>
+ <option>src/conky</option>
+ </command>
</term>
</varlistentry>
</variablelist>
- <para>
- Conky has been tested to be compatible with C99 C, however it has not been tested
- with anything other than gcc, and is not guaranteed to work with other compilers.
- </para>
- <para>
-
+ <para>Conky has been tested to be compatible with C99 C,
+ however it has not been tested with anything other than
+ gcc, and is not guaranteed to work with other
+ compilers.
</para>
+ <para></para>
</refsect1>
-
-
-
<refsect1>
<title>You Should Know</title>
- <para>
- Conky is generally very good on resources. That said, the more you try to make Conky
- do, the more resources it is going to consume.
+ <para>Conky is generally very good on resources. That said,
+ the more you try to make Conky do, the more resources it is
+ going to consume.
</para>
- <para>
- An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1 conky".
- Saves you the trouble of having to kill and then restart. You can now also do the same with SIGHUP.
+ <para>An easy way to force Conky to reload your ~/.conkyrc:
+ "killall -SIGUSR1 conky". Saves you the trouble of having
+ to kill and then restart. You can now also do the same with
+ SIGHUP.
</para>
</refsect1>
-
<refsect1>
<title>Options</title>
-
- <para>Command line options override configurations defined in configuration file.</para>
-
+ <para>Command line options override configurations defined in
+ configuration file.
+ </para>
&command_options;
-
</refsect1>
-
<refsect1>
<title>Configuration Settings</title>
-
- <para>
- Default configuration file location is $HOME/.conkyrc or
- ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is /etc,
- and you can find the sample config file there (/etc/conky/conky.conf).
+ <para>Default configuration file location is $HOME/.conkyrc or
+ ${sysconfdir}/conky/conky.conf. On most systems, sysconfdir is
+ /etc, and you can find the sample config file there
+ (/etc/conky/conky.conf).
</para>
- <para>
- You might want to copy it to $HOME/.conkyrc and then start modifying it.
- Other configs can be found at http://conky.sf.net/
+ <para>You might want to copy it to $HOME/.conkyrc and then
+ start modifying it. Other configs can be found at
+ http://conky.sf.net/
</para>
-
&config_settings;
</refsect1>
-
<refsect1>
- <title>Variables</title>
-
+ <title>Objects/Variables</title>
+ <para>Colours are parsed using XParsecolor(), there might be a
+ list of them: /usr/share/X11/rgb.txt.
+ Colour can be also in
+ #rrggbb format (hex).
+ </para>
<para>
- Colors are parsed using XParsecolor(), there might be a list of them:
- /usr/share/X11/rgb.txt. Also, <ulink url="http://sedition.com/perl/rgb.html">
- http://sedition.com/perl/rgb.html</ulink>.
- Color can be also in #rrggbb format (hex).
+ Some objects may create threads, and sometimes these threads will
+ not be destroyed until Conky terminates. There is no way to
+ destroy or clean up threads while Conky is running. For example,
+ if you use an MPD variable, the MPD thread will keep running until
+ Conky dies. Some threaded objects will use one of the parameters
+ as a 'key', so that you only have 1 relevant thread running (for
+ example, the $curl, $rss and $weather objects launch one thread per
+ URI).
</para>
-
&variables;
</refsect1>
-
+ <refsect1>
+ <title>Lua API</title>
+ <para>Conky features a Lua Programming API, and also ships with Lua
+ bindings for some useful libraries. Conky defines certain global
+ functions and variables which can be accessed from Lua code running
+ in Conky.
+ </para>
+ <para>To use Lua Conky, you first need to make sure you have a version of Conky
+ with Lua support enabled (``conky -v'' will report this). Scripts
+ must first be loaded using the lua_load configuration option. You
+ then call functions in Lua via Conky's $lua, $lua_read, and Lua
+ hooks.
+ </para>
+ <para>
+ Be careful when creating threaded objects through the Lua API. You
+ could wind up with a whole bunch of threads running if a thread is
+ created with each iteration.
+ </para>
+ <para>
+ At this time, the Lua API should not be considered stable and may
+ change drastically from one release to another as it matures.
+ </para>
+ <para>
+ NOTE: In order to accommodate certain features in the cairo
+ library's API, Conky will export a few additional functions for the
+ creation of certain structures. These are documented below.
+ </para>
+ &lua;
+ </refsect1>
<refsect1>
<title>Examples</title>
<variablelist>
-
<varlistentry>
- <term><varname>conky </varname><option>-t '${time %D %H:%M}' -o -u 30</option></term>
- <listitem>Start Conky in its own window with date and clock as text and 30 sec update interval.</listitem>
+ <term>
+ <varname>conky</varname>
+ <option>-t '${time %D %H:%M}' -o -u 30</option>
+ </term>
+ <listitem>Start Conky in its own window with date
+ and clock as text and 30 sec update
+ interval.</listitem>
</varlistentry>
-
<varlistentry>
- <term><varname>conky </varname><option>-a top_left -x 5 -y 500 -d</option></term>
- <listitem>Start Conky to background at coordinates (5, 500).</listitem>
+ <term>
+ <varname>conky</varname>
+ <option>-a top_left -x 5 -y 500 -d</option>
+ </term>
+ <listitem>Start Conky to background at coordinates
+ (5, 500).</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <varname>conky</varname>
+ <option>-C > ~/.conkyrc</option>
+ </term>
+ <listitem>Do not start Conky, but have it output
+ the builtin default config file to ~/.conkyrc for
+ later customising.</listitem>
</varlistentry>
-
</variablelist>
</refsect1>
-
<refsect1>
<title>Files</title>
- <filename>~/.conkyrc</filename> default configuration file
+ <variablelist>
+ <varlistentry>
+ <term>
+ <filename>
+ ${sysconfdir}/conky/conky.conf</filename>
+ </term>
+ <listitem>Default system-wide configuration file.
+ The value of ${sysconfdir} depends on the
+ compile-time options (most likely /etc).</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>~/.conkyrc</filename>
+ </term>
+ <listitem>Default personal configuration
+ file.</listitem>
+ </varlistentry>
+ </variablelist>
</refsect1>
-
<refsect1>
<title>Bugs</title>
- <para>
- Drawing to root or some other desktop window directly doesn't work with
- all window managers. Especially doesn't work well with Gnome and it has
- been reported that it doesn't work with KDE either. Nautilus can be
- disabled from drawing to desktop with program gconf-editor. Uncheck
- show_desktop in /apps/nautilus/preferences/. There is -w switch in Conky
- to set some specific window id. You might find xwininfo -tree useful to
- find the window to draw to. You can also use -o argument which makes
- Conky to create its own window. If you do try running Conky in its own
- window, be sure to read up on the own_window_type settings and experiment.
- </para>
+ <para>Drawing to root or some other desktop window directly
+ doesn't work with all window managers. Especially doesn't
+ work well with Gnome and it has been reported that it
+ doesn't work with KDE either. Nautilus can be disabled from
+ drawing to desktop with program gconf-editor. Uncheck
+ show_desktop in /apps/nautilus/preferences/. There is -w
+ switch in Conky to set some specific window id. You might
+ find xwininfo -tree useful to find the window to draw to.
+ You can also use -o argument which makes Conky to create
+ its own window. If you do try running Conky in its own
+ window, be sure to read up on the own_window_type settings
+ and experiment.</para>
</refsect1>
-
<refsect1>
<title>See Also</title>
- <para><ulink url="http://conky.sourceforge.net/">
- http://conky.sourceforge.net/</ulink></para>
- <para><ulink url="http://www.sourceforge.net/projects/conky">
- http://www.sourceforge.net/projects/conky</ulink></para>
<para>
- #conky on irc.freenode.net
+ <ulink url="http://conky.sourceforge.net/">
+ http://conky.sourceforge.net/</ulink>
+ </para>
+ <para>
+ <ulink url="http://www.sourceforge.net/projects/conky">
+ http://www.sourceforge.net/projects/conky</ulink>
+ </para>
+ <para>
+ <ulink url="http://wiki.conky.be">
+ http://wiki.conky.be</ulink>
</para>
+ <para>#conky on irc.freenode.net</para>
</refsect1>
-
<refsect1>
<title>Copying</title>
- <para>
- Copyright (c) 2005-2008 Brenden Matthews, Philip Kovacs, et. al.
- Any original torsmo code is licensed under the BSD license (see LICENSE.BSD for a copy).
- All code written since the fork of torsmo is licensed under the GPL (see LICENSE.GPL for a copy), except where noted differently (such as in portmon code, timed thread code, and audacious code which are LGPL, and prss which is an MIT-style license).
- </para>
+ <para>Copyright (c) 2005-2010 Brenden Matthews, Philip
+ Kovacs, et. al. Any original torsmo code is licensed under
+ the BSD license (see LICENSE.BSD for a copy). All code
+ written since the fork of torsmo is licensed under the GPL
+ (see LICENSE.GPL for a copy), except where noted
+ differently (such as in portmon code, timed thread code,
+ and audacious code which are LGPL, and prss which is an
+ MIT-style license).</para>
</refsect1>
<refsect1>
<title>Authors</title>
- <para>
- The Conky dev team (see AUTHORS for a full list of contributors).
- </para>
+ <para>The Conky dev team (see AUTHORS for a full list of
+ contributors).</para>
</refsect1>
</refentry>