git.maemo.org Git - monky/blob - doc/docs.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   4 <!ENTITY testtable SYSTEM "test.xml">
   5 <!ENTITY command_options SYSTEM "command_options.xml">
   6 <!ENTITY config_settings SYSTEM "config_settings.xml">
   7 <!ENTITY variables SYSTEM "variables.xml">
   8 ]>
   9
  10 <refentry>
  11         <refentryinfo>
  12                 <address>
  13                         <email>brenden1@users.sourceforge.net</email>
  14                 </address>
  15                 <author>
  16                         <firstname>Brenden</firstname>
  17                         <surname>Matthews</surname>
  18                 </author>
  19                 <date>2009-06-06</date>
  20         </refentryinfo>
  21
  22         <refmeta>
  23                 <refentrytitle>conky</refentrytitle>
  24                 <manvolnum>1</manvolnum>
  25         </refmeta>
  26
  27         <refnamediv>
  28                 <refname>conky</refname>
  29                 <refpurpose>A system monitor for X originally based on the torsmo code, but more kickass.  It just keeps on given'er. Yeah.</refpurpose>
  30         </refnamediv>
  31
  32         <refsynopsisdiv>
  33                 <cmdsynopsis>
  34                         <command>conky</command>
  35                         <arg><replaceable>options</replaceable></arg>
  36                 </cmdsynopsis>
  37         </refsynopsisdiv>
  38
  39         <refsect1>
  40                 <title>Description</title>
  41                 <para>
  42                         Conky is a system monitor for X originally based on torsmo.
  43                         Since its inception, Conky has changed significantly from its predecessor, while maintaining
  44                         simplicity and configurability.  Conky can display just about anything, either
  45                         on your root desktop or in its own window.  Not only does Conky have many
  46                         built-in objects, it can also display just about any piece of information by
  47                         using scripts and other external programs.
  48                 </para>
  49                 <para>
  50                         Conky has more than 250 built in objects, including support for
  51                         a plethora of OS stats (uname, uptime, CPU usage, mem usage, disk
  52                         usage, "top" like process stats, and network monitoring, just to name a few),
  53                         built in IMAP and POP3 support, built in support for many popular
  54                         music players (MPD, XMMS2, BMPx, Audacious), and much much more.
  55                         Conky can display this info either as text,     or using simple progress
  56                         bars and graph widgets, with different fonts and colours.
  57                 </para>
  58                 <para>
  59                         We are always looking for help, whether its reporting bugs, writing patches, or writing docs.
  60                         Please use the facilities at SourceForge to make bug reports, feature requests, and submit patches,
  61                         or stop by #conky on irc.freenode.net if you have questions or want to contribute.
  62                 </para>
  63                 <para>
  64                         Thanks for your interest in Conky.
  65                 </para>
  66         </refsect1>
  67
  68         <refsect1>
  69                 <title>Compiling</title>
  70                 <para>
  71                         For users compiling from source on a binary distro, make sure you have the X development
  72                         libraries installed (Unless you provide configure with "--disable-x11").  This should be a
  73                         package along the lines of "libx11-dev" or "xorg-x11-dev" for X11 libs, and similar "-dev"
  74                         format for the other libs required (depending on your configure options). You should be able
  75                         to see which extra packages you need to install by reading errors that you get from
  76                         './configure'.
  77                 </para>
  78                 <para>
  79                         Conky has (for some time) been available in the repositories of most popular distributions.
  80                         Here are some installation instructions for a few:
  81                 </para>
  82                 <para>
  83                         Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-admin/conky" for installation.
  84                 </para>
  85                 <para>
  86                         Debian, etc. users -- Conky should be in your repositories, and can be installed by doing
  87                         "aptitude install conky".
  88                 </para>
  89                 <para>
  90                         Example to compile and run Conky with all optional components (note that some configure options may differ for your system):
  91                 </para>
  92                 <variablelist>
  93                         <varlistentry>
  94                                 <term>
  95                                         <command><option>sh autogen.sh</option></command> <option># Only required if building from the git repo</option>
  96                                 </term>
  97                         </varlistentry>
  98                         <varlistentry>
  99                                 <term>
 100                                         <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>
 101                                 </term>
 102                         </varlistentry>
 103                         <varlistentry>
 104                                 <term>
 105                                         <command><option>make</option></command>
 106                                 </term>
 107                         </varlistentry>
 108                         <varlistentry>
 109                                 <term>
 110                                         <command><option>make install</option></command> <option># Optional</option>
 111                                 </term>
 112                         </varlistentry>
 113                         <varlistentry>
 114                                 <term>
 115                                         <command><option>src/conky</option></command>
 116                                 </term>
 117                         </varlistentry>
 118                 </variablelist>
 119                 <para>
 120                         Conky has been tested to be compatible with C99 C, however it has not been tested
 121                         with anything other than gcc, and is not guaranteed to work with other compilers.
 122                 </para>
 123                 <para>
 124
 125                 </para>
 126         </refsect1>
 127
 128
 129
 130         <refsect1>
 131                 <title>You Should Know</title>
 132                 <para>
 133                         Conky is generally very good on resources.  That said, the more you try to make Conky
 134                         do, the more resources it is going to consume.
 135                 </para>
 136                 <para>
 137                         An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1 conky".
 138                         Saves you the trouble of having to kill and then restart.  You can now also do the same with SIGHUP.
 139                 </para>
 140         </refsect1>
 141
 142         <refsect1>
 143                 <title>Options</title>
 144
 145                 <para>Command line options override configurations defined in configuration file.</para>
 146
 147                 &command_options;
 148
 149         </refsect1>
 150
 151         <refsect1>
 152                 <title>Configuration Settings</title>
 153
 154                 <para>
 155                         Default configuration file location is $HOME/.conkyrc or
 156                         ${sysconfdir}/conky/conky.conf.  On most systems, sysconfdir is /etc,
 157                         and you can find the sample config file there (/etc/conky/conky.conf).
 158                 </para>
 159                 <para>
 160                         You might want to copy it to $HOME/.conkyrc and then start modifying it.
 161                         Other configs can be found at http://conky.sf.net/
 162                 </para>
 163
 164                 &config_settings;
 165         </refsect1>
 166
 167         <refsect1>
 168                 <title>Variables</title>
 169
 170                 <para>
 171                         Colors are parsed using XParsecolor(), there might be a list of them:
 172                         /usr/share/X11/rgb.txt. Also, <ulink url="http://sedition.com/perl/rgb.html">
 173                                 http://sedition.com/perl/rgb.html</ulink>.
 174                         Color can be also in #rrggbb format (hex).
 175                 </para>
 176
 177                 &variables;
 178         </refsect1>
 179
 180         <refsect1>
 181                 <title>Examples</title>
 182                 <variablelist>
 183
 184                         <varlistentry>
 185                                 <term><varname>conky </varname><option>-t &apos;${time %D %H:%M}&apos; -o -u 30</option></term>
 186                                 <listitem>Start Conky in its own window with date and clock as text and 30 sec update interval.</listitem>
 187                         </varlistentry>
 188
 189                         <varlistentry>
 190                                 <term><varname>conky </varname><option>-a top_left -x 5 -y 500 -d</option></term>
 191                                 <listitem>Start Conky to background at coordinates (5, 500).</listitem>
 192                         </varlistentry>
 193
 194                         <varlistentry>
 195                                 <term><varname>conky </varname><option>-C > ~/.conkyrc</option></term>
 196                                 <listitem>Do not start Conky, but have it output the builtin default config file to ~/.conkyrc for later customising.</listitem>
 197                         </varlistentry>
 198
 199                 </variablelist>
 200         </refsect1>
 201
 202         <refsect1>
 203                 <title>Files</title>
 204                 <variablelist>
 205                         <varlistentry>
 206                                 <term><filename>${sysconfdir}/conky/conky.conf</filename></term>
 207                                 <listitem>Default system-wide configuration file. The value of ${sysconfdir} depends on the compile-time options (most likely /etc).</listitem>
 208                         </varlistentry>
 209                         <varlistentry>
 210                                 <term><filename>~/.conkyrc</filename></term>
 211                                 <listitem>Default personal configuration file.</listitem>
 212                         </varlistentry>
 213                 </variablelist>
 214         </refsect1>
 215
 216         <refsect1>
 217                 <title>Bugs</title>
 218                 <para>
 219                         Drawing to root or some other desktop window directly doesn't work with
 220                         all window managers. Especially doesn't work well with Gnome and it has
 221                         been reported that it doesn't work with KDE either. Nautilus can be
 222                         disabled from drawing to desktop with program gconf-editor. Uncheck
 223                         show_desktop in /apps/nautilus/preferences/. There is -w switch in Conky
 224                         to set some specific window id. You might find xwininfo -tree useful to
 225                         find the window to draw to. You can also use -o argument which makes
 226                         Conky to create its own window.  If you do try running Conky in its own
 227                         window, be sure to read up on the own_window_type settings and experiment.
 228                 </para>
 229         </refsect1>
 230
 231         <refsect1>
 232                 <title>See Also</title>
 233                 <para><ulink url="http://conky.sourceforge.net/">
 234                                 http://conky.sourceforge.net/</ulink></para>
 235                 <para><ulink url="http://www.sourceforge.net/projects/conky">
 236                                 http://www.sourceforge.net/projects/conky</ulink></para>
 237                 <para><ulink url="http://wiki.conky.be">
 238                                 http://wiki.conky.be</ulink></para>
 239                 <para>
 240                         #conky on irc.freenode.net
 241                 </para>
 242         </refsect1>
 243
 244         <refsect1>
 245                 <title>Copying</title>
 246                 <para>
 247                         Copyright (c) 2005-2009 Brenden Matthews, Philip Kovacs, et. al.
 248                         Any original torsmo code is licensed under the BSD license (see LICENSE.BSD for a copy).
 249                         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).
 250                 </para>
 251         </refsect1>
 252         <refsect1>
 253                 <title>Authors</title>
 254                 <para>
 255                         The Conky dev team (see AUTHORS for a full list of contributors).
 256                 </para>
 257         </refsect1>
 258 </refentry>