<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY ktimemon "<application>ktimemon</application>">
]>

<book lang="en">
<bookinfo>
<title>KTimemon Manual</title>
<authorgroup>
<author>
<firstname>Martin</firstname>
<surname>Maierhofer</surname>
<affiliation>
<address><email>m.maierhofer@tees.ac.uk</email></address>
</affiliation>
</author>
</authorgroup>
<date>16/04/1999</date>
<releaseinfo>0.03.01</releaseinfo>
<abstract>
<para>Online help / Introduction to KTimemon. Covers version 0.3a.</para>
<para>&ktimemon; is a system monitor for the K Desktop Environment</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>ktimemon</keyword>
<keyword>system monitor</keyword>
<keyword>timemon</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>KTimemon is a small program to keep track of your computer's system
usage. It can display bar graphs containing information about CPU,
memory, and swap usage as well as disk usage and context switch
activity. In keeping with the spirit of <ulink url="http://www.kde.org/">KDE</ulink>, it supports configuration via a graphical user
interface. It also supports <emphasis>docking</emphasis>, i.e. it can display
information in the system panel tray.</para>

<para><emphasis remap="bf">Note:</emphasis> Currently, KTimemon only supports a limited number of
systems: Linux based installations with the <literal remap="tt">/proc</literal>
file system, Solaris based installations with the <emphasis>kstat</emphasis> library,
and Digital Unix (formerly DEC/OSF1) based installations with the
<emphasis>table(2)</emphasis> system call. Help with porting it to other platforms is 
most welcome.</para>

<para>KTimemon can be started from the command line or from the KDE
start menu (in the <emphasis>Utilities</emphasis> submenu). If you choose to start 
from the command line, KTimemon honours the usual X Windows program 
flags such as <literal remap="tt">-geometry</literal>. KTimemon is <emphasis>session-aware</emphasis>, i.e. it
keeps track of the current state (colours, etc) and restores it in the
user's next session.</para>
</chapter>

<chapter id="installation">
<title>Installation</title>

<para>You can obtain KTimemon from the <ulink url="ftp://ftp.kde.org/pub/kde/unstable/apps/utils/ktimemon-0.3a.tgz">KDE ftp server</ulink>  (and its mirror sites). Download the package
to a directory of your choice and type the following commands:</para>

<para><screen>$ cd &lt;the_directory_where_you_put_ktimemon-0.3a.tgz&gt;
$ gzip -cd ktimemon-0.3a.tgz | tar xfv -
$ cd ktimemon-0.3a
$ ./configure
$ make install
</screen>
</para>

<para>Hopefully, KTimemon will be compiled and installed without any further
intervention (if you have any problems installing KTimemon, please
drop me a note at <ulink url="mailto:m.maierhofer@tees.ac.uk">m.maierhofer@tees.ac.uk</ulink>). KTimemon should end up in the KDE
directory hierarchy, and you will be able to invoke it from the
<emphasis>Utilities</emphasis> menu after you restart the panel.</para>
</chapter>

<chapter id="fund">
<title>Onscreen Fundamentals</title>

<para>After starting KTimemon a small window will appear displaying
information gathered from the operating system. If you move the mouse 
pointer over the KTimemon window and let it rest for a small amount of 
time, a <emphasis>tool-tip</emphasis> (i.e. a small transient window) will appear. The 
tool-tip contains numeric information about the system parameters displayed 
by the bar graphs. Tool-tips can be disabled (refer to <link linkend="config">Configuration</link>).</para>

<sect1 id="modes">
<title>Display Modes</title>

<para>KTimemon can display two different sets of system information. As
explained in the <link linkend="config">Configuration</link> chapter, mouse 
buttons can be bound to various actions. Per default, the left mouse
button is bound to the mode switch action, i.e. by clicking the left
mouse button anywhere in the KTimemon window, the displayed
information switches from "Normal Mode" (the default) to "Extended
Mode", and vice versa.</para>

<sect2 id="normalmode">
<title>Normal Mode</title>

<para>After starting KTimemon for the first time, it will show
information about the current CPU activity, as well as memory and swap
usage. Three bar graphs are used to show this information; they are
updated regularly (the default sample interval is 0.5s, but it can be
changed, see <link linkend="config">Configuration</link>). The three bar
graphs represent (from left to right):
<variablelist>
<varlistentry>
<term>CPU usage.</term>
<listitem>
<para>KTimemon shows the bar in three different colours,
representing CPU time spent in various modes. From bottom to top 
they are: kernel mode, user mode, and user mode with lowered 
priority (<emphasis>nice</emphasis>) - since Solaris does not seem to support
statistics for nice mode, the topmost part of the bar represents
time spent in the <emphasis>wait</emphasis> state on such systems. The gap from the 
top of the bar to the top of the window represents the percentage
the CPU idle time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Memory usage.</term>
<listitem>
<para>Similar to the CPU usage bar, this bar is composed
of three sub fields, representing (from bottom to top): memory
allocated by processes, memory used for I/O buffering, and memory used
for file caching. For Digital Unix based systems, the middle section 
represents "inactive" memory (i.e. memory allocated and not used for
a certain amount of time), and for Solaris based systems, the middle 
section of the bar is not used, and the topmost section represents
the amount of memory used by the kernel. Again, the gap from the top
of the bar to the top of the window represents free memory.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swap usage.</term>
<listitem>
<para>This bar consists of a single field representing
the current swap usage relative to the system's total amount of swap
space. </para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Clicking the mouse button bound to "mode switch" in the KTimemon
window switches to "Extended Mode".</para>
</sect2>

<sect2 id="xtndmode">
<title>Extended Mode </title>

<para>In this mode, the three bar graphs are used to display a different
set of system information. Again from left to right, they show:
<variablelist>
<varlistentry>
<term>Paging activity.</term>
<listitem>
<para>This bar consists of two parts, the lower half
of which shows the number of memory pages written to secondary
storage in the last sample interval. Similarly, the upper half
indicates the number of pages read from secondary storage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Swapping activity.</term>
<listitem>
<para>The second bar displays the analogue
information for swap activity.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Context switches.</term>
<listitem>
<para>Again, this bar graph consists of a single
field which indicates the number of context switches in the last
sample interval.</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Since there is no "natural" way of scaling the information shown in
"Extended Mode", by default KTimemon uses <emphasis>autoscaling</emphasis> (explained
in the <link linkend="autoscaling">Common Questions Section</link>). There
is, however, the possibility of specifying the scaling information,
see the <link linkend="config">Configuration</link> section.</para>

<para>Note that the two sets of bar graphs share the same colours, i.e. the
colours setup for "Normal Mode" is also used for displaying
information in "Extended Mode" (see also <link linkend="config">Configuration</link> on how to change the colour scheme).</para>
</sect2>
</sect1>

<sect1 id="menu">
<title>Menu Structure</title>

<para>By default, the right mouse button is bound to the "menu pop-up"
action, i.e. clicking the right mouse button anywhere in the KTimemon
window brings up a menu, which is discussed in the following sections.</para>

<sect2 id="help">
<title>Help</title>

<para>The <emphasis>Help</emphasis> Menu is fairly conventional. Chances are good you
already discovered this functionality.</para>
</sect2>

<sect2 id="configmenu">
<title>Settings...</title>

<para>The <emphasis>Settings...</emphasis> Menu is used to pop up the configuration
dialog. Configuration options are discussed in section <link linkend="config">Configuration</link>.</para>
</sect2>

<sect2 id="dockedinpanel">
<title>Docked In Panel</title>

<para>By selecting the <emphasis>Docked In Panel</emphasis> menu, KTimemon switches
between its standard display (i.e. a normal window) and the panelised
state, where the KTimemon window disappears and a smaller version is
displayed in the system panel. Apart from the reduction in size, the
"panelised" KTimemon behaves exactly like its big brother.</para>
</sect2>

<sect2 id="horizontalbars">
<title>Horizontal Bars</title>

<para>By selecting the <emphasis>Horizontal Bars</emphasis> menu entry, KTimemon switches 
from vertical bars to horizontal bars and vice versa. Not very useful, 
but it was easy to implement ;-)</para>
</sect2>

<sect2 id="quit">
<title>Quit</title>

<para>The <emphasis>Quit</emphasis> menu - surprise, surprise -- is used to terminate
KTimemon. It will save the current state (e.g. the colour scheme,
window size, whether it is displayed in the panel) and restore the
state in the next invocation.</para>

<para>The configuration information is saved in the file
<literal remap="tt">$(HOME)/.kde/share/config/ktimemonrc</literal>, where <literal remap="tt">$(HOME)</literal>
refers to the user's home directory. If this file is deleted, KTimemon
will start in its default state in the next invocation.</para>
</sect2>
</sect1>
</chapter>

<chapter id="config">
<title>Configuration</title>

<para>KTimemon can be configured via a straight-forward dialog (see also
the discussion of the <link linkend="configmenu">Configuration Menu</link>).
On the <emphasis remap="bf">General</emphasis> page, the sample interval can be specified as well
as scaling information (see also the discussion of the <link linkend="xtndmode">extended mode</link>). If the <emphasis>Autoscaling</emphasis> check
box is ticked (autoscaling is explained in the <link linkend="autoscaling">FAQ</link> section), the scaling factors cannot be edited, since
KTimemon determines them automatically.</para>

<para>The <emphasis remap="bf">Colours</emphasis> page can be used to tailor the colours of the bar graph
to individual preferences. A small sample bar graph gives immediate
feedback.</para>

<para>In the <emphasis remap="bf">Interaction</emphasis> page, mouse bindings can be adapted. Clicking
a mouse button on the KTimemon window can be ignored, trigger a mode
switch (see also <link linkend="modes">Modes</link>), invoke the context
menu (see also <link linkend="menu">Menu</link>), or invoke an external
process. The command line specified for external processes is
interpreted by the standard shell, i.e. shell commands, environment
variables, redirection etc. can be used.</para>

<para>The Interaction page also contains a check box which can be used
to disable to automatic appearance of tool-tips with numeric
information about the bar graphs (compare <link linkend="fund">Onscreen Fundamentals</link>).</para>
</chapter>

<chapter id="autoscaling">
<title>Common Questions and Answers </title>

<para><variablelist>
<varlistentry>
<term>Which operating systems does KTimemon support?</term>
<listitem>
<para>KTimemon supports Linux based systems with the <literal remap="tt">/proc</literal> file
system, Solaris based systems with the <emphasis>kstat</emphasis> library, and Digital 
Unix (formerly DEC/OSF1) systems with the <emphasis>table(2)</emphasis> system call
interface. Only the Linux version has been thoroughly tested, if you
experience any problems with the Solaris/Digital Unix port, please do
not hesitate to contact me.</para>
<para>Also, contributions to KTimemon to adapt it to other platforms are
most welcome. Please contact me at <ulink url="mailto:m.maierhofer@tees.ac.uk">m.maierhofer@tees.ac.uk</ulink> if
you intend to port KTimemon to other flavours of Unix.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>How does autoscaling work?</term>
<listitem>
<para>Glad you asked. Since there is no
sensible predetermined scaling factor for paging/swapping operations
and context switches (unlike e.g. memory utilisation, where you can
take the total memory size as baseline), KTimemon uses a
semi-intelligent (well, ...) autoscaling mechanism. Autoscaling
works as follows:
<itemizedlist>
<listitem>
<para> Each of the three bar graphs as described in the <link linkend="xtndmode">extended mode section</link> has an
associated scaling factor. The initial values of these
factors are set to some predetermined value.</para>
</listitem>
<listitem>
<para> Each time a new sample is displayed, the respective value is
tentatively scaled with the corresponding factor. If the
value can be displayed in the scale chosen by the factor, no
change occurs (i.e. small changes in the activity are
reflected by a changing height of the bar).</para>
</listitem>
<listitem>
<para> If the scaled value would be either too large or too small to
be displayed with the current scaling factor, the scaling is
adjusted so that the new value displayed is roughly halfway
up the bar graph. Thus, subsequent changes should have a good
chance of getting displayed relative to the current value,
without having to change the scale again.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Why does a message box with "diagnostic output from child
command" pop up?</term>
<listitem>
<para>If you bind a mouse button to an external command
(as described in the <link linkend="config">Configuration</link> chapter),
KTimemon does not check for a valid command name. Instead, a command
shell is invoked to execute the statement, i.e. shell commands,
environment variables, etc. can be used. To allow some feedback to the 
user, KTimemon monitors the <emphasis>stderr</emphasis> outputof the command shell,
and reports it in this message box.</para>
<para>While this scheme can be helpful in case a command is not found, it 
can be quite annoying if the invoked command prints harmless diagnostic
information on <emphasis>stderr</emphasis>. A simple and elegant solution to this
problem is to add <literal remap="tt">2&gt;/dev/null</literal>, at the end of the command
specification. This redirects diagnostic messages to Nirvana and stops 
the message box to come along.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</chapter>

<chapter id="revisionhistory">
<title>Revision History</title>

<para><variablelist>
<varlistentry>
<term>Version 0.1.</term>
<listitem>
<para>(29 July 1998) Initial release.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Version 0.2.</term>
<listitem>
<para>(20 August 1998) 
<itemizedlist>
<listitem>
<para>Added support for <link linkend="xtndmode">extended mode</link>.</para>
</listitem>
<listitem>
<para>Changed the configuration dialog to use layouts instead of 
fixed geometry.</para>
</listitem>
<listitem>
<para>Changed details in the configuration dialog (e.g. the location
of the <literal remap="tt">/proc</literal> mount point are now detected
automatically.</para>
</listitem>
<listitem>
<para>Added support for internationalisation.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Version 0.2a.</term>
<listitem>
<para>(29 August 1998) 
<itemizedlist>
<listitem>
<para>Fixed small bug in auto detection of the <literal remap="tt">/proc</literal> file system
from <literal remap="tt">/etc/mtab</literal>.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Version 0.2b.</term>
<listitem>
<para>(3 December 1998)
<itemizedlist>
<listitem>
<para>Fixed tiny compatibility problem with the default colour allocation
(has anyone changed QColor "recently"?).</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Version 0.3.</term>
<listitem>
<para>(11 February 1999)
<itemizedlist>
<listitem>
<para>Fixed bug in handling the configuration courtesy of Cristian Tibirna.
You may want to remove the <literal remap="tt">ktimemonrc</literal> file from
<literal remap="tt">$(HOME)/.kde/share/config</literal> to start with a "clean"
configuration.</para>
</listitem>
<listitem>
<para>The configuration dialog is now only allocated on demand. This
reduces the memory footprint of KTimemon a bit.</para>
</listitem>
<listitem>
<para>Initial port to Digital Unix (DEC/OSF1) and Solaris.</para>
</listitem>
<listitem>
<para>Configurable vertical and horizontal bars.</para>
</listitem>
<listitem>
<para>The layout of the memory usage information has been slightly 
rearranged.</para>
</listitem>
<listitem>
<para>Configurable mouse binding.</para>
</listitem>
<listitem>
<para>Some preliminary support for SMP. Don't hold your breath though.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Version 0.3a.</term>
<listitem>
<para>(16 April 1999)
<itemizedlist>
<listitem>
<para>Added tooltips to timemon widget (suggested by Mark Krischer).</para>
</listitem>
<listitem>
<para>Added missing internationalisation in the configuration panel
and cleaned up translation (thanks to Lubos Lunak for the
report).</para>
</listitem>
<listitem>
<para>Minor code cleanup in the sample class.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</chapter>

<chapter id="thanksandacknowledgements">
<title>Thanks and Acknowledgements</title>

<para>KTimemon is based on an Xt version by my brother.</para>

<para>Thanks to 
<ulink url="mailto:ttoben@artis.uni-oldenburg.de">Tobe Toben</ulink>,
<ulink url="mailto:ctibirna@gch.ulaval.ca">Cristian Tibirna</ulink>, 
<ulink url="mailto:dmuell@rhrk.uni-kl.de">Dirk A. Mueller</ulink>,
<ulink url="mailto:krischem@amp.com">Mark Krischer</ulink>
and <ulink url="mailto:l.lunak@sh.cvut.cz">Lubos Lunak</ulink>
for bug reports, patches, comments, suggestions.</para>
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
