-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
- <!ENTITY testtable SYSTEM "test.xml">
- <!ENTITY command_options SYSTEM "command_options.xml">
- <!ENTITY config_settings SYSTEM "config_settings.xml">
- <!ENTITY variables SYSTEM "variables.xml">
- ]>
-
+<?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 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>
- <email>brenden1@users.sourceforge.net</email>
- </address>
- <author>
- <firstname>Brenden</firstname>
- <surname>Matthews</surname>
- </author>
- <date>2005-08-24</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.</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>conky</command>
- <arg><replaceable>options</replaceable></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
- <para>
- Conky is a system monitor for X originally based on the torsmo code.
- Since it's original conception, Conky has changed a fair bit from it's predecessor.
- Conky can display just about anything, either on your root desktop or in it's own window.
- Conky has many built-in objects, as well as the ability to execute programs and scripts,
- then display the output from stdout.
+ <refentryinfo>
+ <address>
+ <email>brenden1@users.sourceforge.net</email>
+ </address>
+ <author>
+ <firstname>Brenden</firstname>
+ <surname>Matthews</surname>
+ </author>
+ <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>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>conky</command>
+ <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
+ using scripts and other external programs.
</para>
- <para>
- We are always looking for help, and anyone interested in becoming a developer is welcome.
- Please use the facilities at SourceForge to make bug reports, feature requests, and submit patches.
+ <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>
- </refsect1>
-
+ <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>
- First, make sure you have the X development libraries installed, this should be a package along the lines
- of "libx11-dev or xorg-x11-dev". Gentoo users, Conky is in Gentoo's Portage. Simply use "emerge conky" for installation.
- There is also usually an up-to-date ebuild within Conky's package or in CVS.
+ <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>
- To compile and run Conky with all optional components:
+ <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.
+ </para>
+ <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>
<variablelist>
<varlistentry>
<term>
- <command><option>sh autogen.sh</option></command> <option># Only required if building from CVS</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
---enable-double-buffer --enable-own-window --enable-proc-uptime
---enable-mpd --enable-xft --enable-seti</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>./conky</option></command>
+ <command>
+ <option>src/conky</option>
+ </command>
</term>
</varlistentry>
</variablelist>
- <para>
- Conky doesn't probably compile with other compilers than gcc and icc.
- It doesn't compile with C89 compiler and not even with pure C99.
- It uses few things that might not exist: strdup(), strcasecmp(), strncasecmp(),
- optarg variable with getopt() and long long (not in C89). Crashes in file system
- statistics stuff when compiled with icc, I don't know exactly why.
+ <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>
- You can disable 'drawing to own window' feature in case you don't need it by passing
- --disable-own-window to configure -script.
+ <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>
- <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>
</refsect1>
-
-
-
- <refsect1>
- <title>You Should Know</title>
- <para>
- Conky is generally very good on resources. However, certain objects in
- Conky are harder on resources then others. In particular, the $tail,
- $top, $font, and $graph objects are quite costly in comparison to the rest of Conky.
+ <refsect1>
+ <title>Options</title>
+ <para>Command line options override configurations defined in
+ configuration file.
</para>
- <para>
- If you do use them, please do not complain about memory or CPU usage,
- unless you think something is going seriously wrong (mem leak, et cetera).
- </para>
- </refsect1>
-
- <refsect1>
- <title>Options</title>
-
- <para>Command line options override configurations defined in configuration file.</para>
-
&command_options;
-
- </refsect1>
-
+ </refsect1>
<refsect1>
<title>Configuration Settings</title>
-
- <para>
- Default configuration file is $HOME/.conkyrc (can be changed from
- conky.c among other things). See conkyrc.sample. You might want to copy
- it to $HOME/.conkyrc and then start modifying it.
+ <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>
-
&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/X11R6/lib/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).
-
- Note that when displaying bytes, power is 1024 and not 1000 so 1M really
- means 1024*1024 bytes and not 1000*1000.
- </para>
-
+ 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>
</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>-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.
- </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>
+ <refsect1>
+ <title>See Also</title>
<para>
- #conky on irc.freenode.net
+ <ulink url="http://conky.sourceforge.net/">
+ http://conky.sourceforge.net/</ulink>
</para>
- </refsect1>
-
- <refsect1>
- <title>Authors</title>
<para>
- The Conky dev team. What's up now??!
+ <ulink url="http://www.sourceforge.net/projects/conky">
+ http://www.sourceforge.net/projects/conky</ulink>
</para>
- </refsect1>
-
+ <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-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>
+ </refsect1>
</refentry>
projects / monky / blobdiff