diff options
Diffstat (limited to 'doc/kicker-applets/ktimemon.docbook')
| -rw-r--r-- | doc/kicker-applets/ktimemon.docbook | 429 |
1 files changed, 429 insertions, 0 deletions
diff --git a/doc/kicker-applets/ktimemon.docbook b/doc/kicker-applets/ktimemon.docbook new file mode 100644 index 0000000..b7ce2d5 --- /dev/null +++ b/doc/kicker-applets/ktimemon.docbook @@ -0,0 +1,429 @@ +<chapter id="ktimemon"> +<chapterinfo> + +<title>&ktimemon;</title> + +<authorgroup> +<author> +<firstname>Martin</firstname> +<surname>Maierhofer</surname> +<affiliation> +<address><email>m.maierhofer@tees.ac.uk</email></address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +<date>2001-11-29</date> +<releaseinfo>0.03.01</releaseinfo> +<abstract> +<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> +</chapterinfo> + +<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 +<acronym>CPU</acronym>, 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>, +&ie; it can display information in the system panel tray.</para> + +<note> +<para>Currently, &ktimemon; only supports a limited number of systems: +&Linux; based installations with the <filename>/proc</filename> file +system, &Solaris; based installations with the +<filename>kstat</filename> library, and Digital &UNIX; (formerly +DEC/OSF1) based installations with the +<command>table</command>(2) system call. Help with +porting it to other platforms is most welcome. +</para> +</note> + +<para> +&ktimemon; can be started from the command line or from the &kde; +<guimenu>start</guimenu> menu (in the <guisubmenu>Utilities</guisubmenu> +submenu). If you choose to start from the command line, &ktimemon; +honors the usual &X-Window; program flags such as +<option>-geometry</option>. &ktimemon; is +<emphasis>session-aware</emphasis>, &ie; it keeps track of the current +state (colors, &etc;) and restores it in the user's next session. +</para> + +<sect1 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> (&ie; 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> + +<sect2 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, &ie; by clicking the +&LMB; mouse button anywhere in the &ktimemon; window, the displayed +information switches from <guilabel>Normal Mode</guilabel> (the default) +to <guilabel>Extended Mode</guilabel>, and vice versa. +</para> + +<sect3 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><acronym>CPU</acronym> usage.</term> +<listitem> +<para>&ktimemon; shows the bar in three different colors, representing +<acronym>CPU</acronym> 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 <acronym>CPU</acronym> idle time.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Memory usage.</term> +<listitem> +<para>Similar to the <acronym>CPU</acronym> 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 <quote>inactive</quote> memory (&ie; 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 <quote>mode switch</quote> in +the &ktimemon; window switches to <quote>Extended Mode</quote>.</para> + +</sect3> + +<sect3 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:</para> + +<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 analog +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>Since there is no <quote>natural</quote> way of scaling the +information shown in <quote>Extended Mode</quote>, 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 colors, &ie; +the colors setup for <quote>Normal Mode</quote> is also used for +displaying information in <quote>Extended Mode</quote> (see also <link +linkend="config">Configuration</link> on how to change the color +scheme).</para> +</sect3> +</sect2> + </sect1> + +<sect1 id="menu"> +<title>Menu Structure</title> + +<para> +By default, the &RMB; mouse button is bound to the <quote>menu +pop-up</quote> action, &ie; clicking the right mouse button anywhere in +the &ktimemon; window brings up a menu, which is discussed in the +following sections. +</para> + +<sect2 id="config-menu"> +<title><guimenuitem>Settings...</guimenuitem></title> + +<para>The <guimenuitem>Settings...</guimenuitem> menu item is used to +pop up the configuration dialog. Configuration options are discussed in +section <link linkend="config">Configuration</link>. +</para> +</sect2> + +<sect2 id="docked-in-panel"> +<title><guimenuitem>Docked In Panel</guimenuitem></title> + +<para> +By selecting the <guimenuitem>Docked In Panel</guimenuitem> menu item, +&ktimemon; switches between its standard display (&ie; a normal window) +and the panelized state, where the &ktimemon; window disappears and a +smaller version is displayed in the system panel. Apart from the +reduction in size, the <quote>panelized</quote> &ktimemon; behaves +exactly like its big brother. +</para> +</sect2> + +<sect2 id="help"> +<title><guimenu>Help</guimenu></title> + +&help.menu.documentation; + +</sect2> + +<sect2 id="horizontal-bars"> +<title><guimenuitem>Horizontal Bars</guimenuitem></title> + +<para>By selecting the <guimenuitem>Horizontal Bars</guimenuitem> 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><guimenuitem>Quit</guimenuitem></title> + +<para> +The <guimenuitem>Quit</guimenuitem> menu item - surprise, surprise +-- is used to terminate &ktimemon;. It will save the current state +(⪚ the color 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 +<filename>$<envar>HOME</envar>/.kde/share/config/ktimemonrc</filename>, +where <filename class="directory">$<envar>HOME</envar></filename> refers +to the user's home folder. If this file is deleted, &ktimemon; will +start in its default state in the next invocation. +</para> +</sect2> +</sect1> + +<sect1 id="config"> +<title>Configuration</title> + +<para> +&ktimemon; can be configured via a straight-forward dialog (see also the +discussion of the <link linkend="config-menu">Configuration +Menu</link>). On the <guilabel>General</guilabel> 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 +<guilabel>Autoscaling</guilabel> 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 <guilabel>Colors</guilabel> page can be used to tailor the colors of +the bar graph to individual preferences. A small sample bar graph gives +immediate feedback. +</para> + +<para> +In the <guilabel>Interaction</guilabel> 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, &ie; shell commands, environment variables, redirection &etc; can +be used.</para> + +<para>The <guilabel>Interaction</guilabel> 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> +</sect1> + +<sect1 id="faq"> +<title>Common Questions and Answers </title> + +<qandaset> +<qandaentry> +<question> +<para>Which operating systems does &ktimemon; support?</para> +</question> +<answer> +<para> +&ktimemon; supports &Linux; based systems with the <filename +class="devicefile">/proc</filename> file system, &Solaris; based +systems with the <filename>kstat</filename> library, and Digital +&UNIX; (formerly DEC/OSF1) systems with the +<command>table</command>(2) 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 +<email>m.maierhofer@tees.ac.uk</email> if you intend to port &ktimemon; +to other flavors of &UNIX;. +</para> +</answer> + +</qandaentry> + +<qandaentry id="autoscaling"> +<question> +<para> +How does autoscaling work? +</para> +</question> +<answer> +<para> +Glad you asked. Since there is no sensible predetermined scaling factor +for paging/swapping operations and context switches (unlike ⪚ memory +utilization, where you can take the total memory size as baseline), +&ktimemon; uses a semi-intelligent (well, ...) autoscaling +mechanism. Autoscaling works as follows: +</para> + +<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 (&ie; 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> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Why does a message box with <errorname>diagnostic output from child +command</errorname> pop up? +</para> +</question> +<answer> +<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, so shell commands, environment variables and +more can be used. To allow some feedback to the user, &ktimemon; +monitors the <systemitem>stderr</systemitem> output of 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 <systemitem>stderr</systemitem>. A simple and elegant +solution to this problem is to add <userinput>2>/dev/null</userinput> +at the end of the command specification. This redirects diagnostic +messages to message nirvana, and stops the message box popping up. +</para> +</answer> +</qandaentry> + +</qandaset> +</sect1> + +<sect1 id="ktimemon-thanks-and-acknowledgements"> +<title>Thanks and Acknowledgments</title> + +<para>&ktimemon; is based on an Xt version by my brother.</para> + +<para>Thanks to Tobe Toben, +<email>ttoben@artis.uni-oldenburg.de</email>, Cristian Tibirna +<email>ctibirna@gch.ulaval.ca</email>, Dirk A. Mueller +<email>dmuell@rhrk.uni-kl.de</email>, Mark Krischer +<email>krischem@amp.com</email>, and Lubos Lunak +<email>l.lunak@sh.cvut.cz</email> for bug reports, patches, comments, +suggestions. +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underGPL; + +</sect1> +</chapter> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + |