changes related to temperature and layout
[monky] / doc / docs.xml
index d77c2e5..878b698 100644 (file)
@@ -1,12 +1,12 @@
-<?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-12-07</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 the git repo.
+               <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 the git repo</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 &apos;${time %D %H:%M}&apos; -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 &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>
-               <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>