Llewellyn/conky
1
0
Fork 0
mirror of https://github.com/Llewellynvdm/conky.git synced 2024-11-15 17:47:09 +00:00
Code Issues Releases Activity
906dbb5b89
conky/doc/docs.xml
Brenden Matthews 0b3fbed045 Bump for release.
2010-10-05 15:26:24 -07:00

338 lines
11 KiB
XML
Raw Blame History

<?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>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>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>
<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
(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>
<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 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>
</term>
</varlistentry>
<varlistentry>
<term>
<command>
<option>make</option>
</command>
</term>
</varlistentry>
<varlistentry>
<term>
<command>
<option>make install</option>
</command>
<option># Optional</option>
</term>
</varlistentry>
<varlistentry>
<term>
<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>
</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>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>
&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>
<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>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>
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>
</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>-C &gt; ~/.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>
<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>
</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>
<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>
View Git Blame Copy Permalink