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.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/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>2006-05-09</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 the torsmo code.
  43     Since it's original conception, Conky has changed a fair bit from it's predecessor.
  44     Conky can display just about anything, either on your root desktop or in it's own window.
  45     Conky has many built-in objects, as well as the ability to execute programs and scripts,
  46     then display the output from stdout.
  47                 </para>
  48                 <para>
  49                 We are always looking for help, and anyone interested in becoming a developer is welcome.
  50                 Please use the facilities at SourceForge to make bug reports, feature requests, and submit patches.
  51                 </para>
  52                 <para>
  53                 Thanks for your interest in Conky.
  54                 </para>
  55   </refsect1>
  56
  57         <refsect1>
  58                 <title>Compiling</title>
  59                 <para>
  60                 For users compiling from source, make sure you have the X development libraries installed.
  61                 This should be a package along the lines of "libx11-dev or xorg-x11-dev".
  62                 </para>
  63                 <para>
  64                 Gentoo users -- Conky is in Gentoo's Portage... simply use "emerge app-admin/conky" for installation.
  65                 There is also usually an up-to-date ebuild within Conky's package or in Svn.
  66                 </para>
  67                 <para>
  68                 Debian,etc. users -- Conky will be in Debian's repositories soon (by mid-September, hopefully), and then
  69                 Ubuntu shortly thereafter. Until then, "dpkg -i" the .deb package to install.
  70                 </para>
  71                 <para>
  72                 Example to compile and run Conky with all optional components (note that some configure options may differ for your system):
  73                 </para>
  74                 <variablelist>
  75                         <varlistentry>
  76                                 <term>
  77                                         <command><option>sh autogen.sh</option></command> <option># Only required if building from Svn</option>
  78                                 </term>
  79                         </varlistentry>
  80                         <varlistentry>
  81                                 <term>
  82                                         <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-xft --enable-seti --enable-double-buffer --enable-own-window --enable-proc-uptime --enable-mpd --enable-mldonkey --enable-x11 --enable-portmon --enable-xmms --enable-bmp --enable-audacious --enable-infopipe --enable-bmpx </option>
  83                                 </term>
  84                         </varlistentry>
  85                         <varlistentry>
  86                                 <term>
  87                                         <command><option>make</option></command>
  88                                 </term>
  89                         </varlistentry>
  90                         <varlistentry>
  91                                 <term>
  92                                         <command><option>make install</option></command> <option># Optional</option>
  93                                 </term>
  94                         </varlistentry>
  95                         <varlistentry>
  96                                 <term>
  97                                         <command><option>src/conky</option></command>
  98                                 </term>
  99                         </varlistentry>
 100                 </variablelist>
 101                 <para>
 102                         Conky probably doesn't compile with compilers other than gcc and icc.
 103                         It doesn't compile with C89 compiler and not even with pure C99.
 104                         It uses a few   things that might not exist: strdup(), strcasecmp(), strncasecmp(),
 105                         optarg variable with getopt() and long long (not in C89). Crashes in file system
 106                         statistics stuff when compiled with icc, I don't know exactly why.
 107                 </para>
 108                 <para>
 109                         You can disable 'drawing to own window' feature in case you don't need it       by passing
 110                         --disable-own-window to configure -script.
 111                 </para>
 112                 <para>
 113
 114                 </para>
 115         </refsect1>
 116
 117
 118
 119   <refsect1>
 120     <title>You Should Know</title>
 121     <para>
 122                 Conky is generally very good on resources.  However, certain objects in
 123                 Conky are harder on resources then others.  In particular, the $tail,
 124                 $top, $font, and $graph objects are quite costly in comparison to the rest of Conky.
 125                 </para>
 126                 <para>
 127                 If you do use them, please do not complain about memory or CPU usage,
 128                 unless you think something's seriously wrong (mem leak, etc.).
 129                 </para>
 130                 <para>
 131                 An easy way to force Conky to reload your ~/.conkyrc: "killall -SIGUSR1 conky".
 132                 Saves you the trouble of having to kill and then restart.
 133                 </para>
 134                 <para>
 135                 IMPORTANT: For previous Conky users, Conky 1.3 no longer supports the metar stuff.
 136                 mdsplib was causing way too many problems. Hopefully there'll be a better solution in Conky 2.x...
 137                 </para>
 138   </refsect1>
 139
 140   <refsect1>
 141     <title>Options</title>
 142
 143     <para>Command line options override configurations defined in configuration file.</para>
 144
 145                 &command_options;
 146
 147   </refsect1>
 148
 149         <refsect1>
 150                 <title>Configuration Settings</title>
 151
 152                 <para>
 153                 Default configuration file is $HOME/.conkyrc (can be changed from
 154                 conky.c among other things). See conkyrc.sample. If installing from Debian package,
 155                 this should be in /usr/share/doc/conky/examples ("gunzip conkyrc.sample.gz" to get conkyrc.sample).
 156                 </para>
 157                 <para>
 158                 You might want to copy it to $HOME/.conkyrc and then start modifying it.
 159                 Other configs can be found at http://conky.sf.net
 160                 </para>
 161
 162                 &config_settings;
 163         </refsect1>
 164
 165         <refsect1>
 166                 <title>Variables</title>
 167
 168                 <para>
 169                 Colors are parsed using XParsecolor(), there might be a list of them:
 170                 /usr/X11R6/lib/X11/rgb.txt. Also, <ulink url="http://sedition.com/perl/rgb.html">
 171                                                                                                                                                          http://sedition.com/perl/rgb.html</ulink>.
 172                 Color can be also in #rrggbb format (hex).
 173
 174                 Note that when displaying bytes, power is 1024 and not 1000 so 1M really
 175                 means 1024*1024 bytes and not 1000*1000.
 176                 </para>
 177
 178                 &variables;
 179         </refsect1>
 180
 181         <refsect1>
 182                 <title>Examples</title>
 183                 <variablelist>
 184
 185                         <varlistentry>
 186                                 <term><varname>conky </varname><option>-t &apos;${time %D %H:%m}&apos; -o -u 30</option></term>
 187                                 <listitem>Start Conky in its own window with date and clock as text and 30 sec update interval.</listitem>
 188                         </varlistentry>
 189
 190                         <varlistentry>
 191                                 <term><varname>conky </varname><option>-a top_left -x 5 -y 500 -d</option></term>
 192                                 <listitem>Start Conky to background at coordinates (5, 500).</listitem>
 193                         </varlistentry>
 194
 195                 </variablelist>
 196         </refsect1>
 197
 198         <refsect1>
 199                 <title>Files</title>
 200                 <filename>~/.conkyrc</filename> default configuration file
 201         </refsect1>
 202
 203         <refsect1>
 204                 <title>Bugs</title>
 205                 <para>
 206                 Drawing to root or some other desktop window directly doesn't work with
 207                 all window managers. Especially doesn't work well with Gnome and it has
 208                 been reported that it doesn't work with KDE either. Nautilus can be
 209                 disabled from drawing to desktop with program gconf-editor. Uncheck
 210                 show_desktop in /apps/nautilus/preferences/. There is -w switch in Conky
 211                 to set some specific window id. You might find xwininfo -tree useful to
 212                 find the window to draw to. You can also use -o argument which makes
 213                 Conky to create its own window.
 214                 </para>
 215         </refsect1>
 216
 217   <refsect1>
 218     <title>See Also</title>
 219     <para><ulink url="http://conky.sourceforge.net">
 220     http://conky.sourceforge.net</ulink></para>
 221     <para><ulink url="http://www.sourceforge.net/projects/conky">
 222     http://www.sourceforge.net/projects/conky</ulink></para>
 223                 <para>
 224                         #conky on irc.freenode.net
 225                 </para>
 226   </refsect1>
 227
 228         <refsect1>
 229                 <title>Authors</title>
 230                 <para>
 231                         The Conky dev team. What's up now!
 232                 </para>
 233         </refsect1>
 234
 235 </refentry>