<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&karm;">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">

<bookinfo>
<title>The &karm; Handbook</title>

<authorgroup>
<author>
<firstname>Jonathan</firstname>
<surname>Singer</surname>
<affiliation>
<address><email>jsinger@leeta.net</email></address>
</affiliation>
</author>

<author>
<firstname>Sirtaj</firstname>
<othername>Singh</othername>
<surname>Kang</surname>
<affiliation><address><email>taj@kde.org</email></address></affiliation>
</author>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<contrib>Reviewer</contrib>
<affiliation><address><email>vampyr@atconnex.net</email></address></affiliation>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2000</year>
<holder>Jonathan Singer</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2001-07-05</date>
<releaseinfo>1.00.00</releaseinfo>

<abstract><para>&karm; tracks time spent on various tasks.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>karm</keyword>
<keyword>kdeutils</keyword>
<keyword>time</keyword>
<keyword>tracker</keyword>
<keyword>project</keyword>
</keywordset>

</bookinfo>

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

<para>&karm; tracks time spent on various tasks. It is useful for
tracking hours to be billed to different clients or just to find out
what percentage of your day is spent playing Doom or reading
Slashdot.</para>

<para>&karm; was written by Sirtaj Singh Kang. The word
<quote>karm</quote> means <quote>work</quote> in the author's native
Punjabi.</para>

</chapter>


<chapter id="using-Karm">
<title>Using &karm;</title>

<sect1 id="starting">
<title>Starting &karm;</title>

<para>Type <command>karm</command> at a command prompt or select
<guimenuitem>Personal Time Tracker</guimenuitem> from the
<guisubmenu>Utilities</guisubmenu> group in the <guimenu>KDE start
menu</guimenu>. The standard &Qt; and &kde; command options are
available, and can be listed by entering
<userinput><command>karm</command> <option>--help</option></userinput>
at the command line.</para>

</sect1>

<sect1 id="general-use">
<title>General usage</title>

<para>Enter the various tasks you wish to track.</para>

<para>To start timing a task, select it and double-click on it, choose
<guimenuitem>Start</guimenuitem> from the <guimenu>Clock</guimenu> menu
or press the <guiicon>Start</guiicon> button in the toolbar. To stop
timing it, double-click it, choose <guimenuitem>Stop</guimenuitem> from
the <guimenu>Clock</guimenu> menu or press the <guiicon>Stop</guiicon>
button in the toolbar.</para>

<para>Multiple tasks can now be timed simultaneously.</para>

<para>Tasks can be saved and are restored at the next use.</para>

</sect1>

</chapter>

<chapter id="interface">
<title>The &karm; interface</title>

<para>The main &karm; window has the following components: menubar, toolbar,
task/time window and status bar.</para>

<screenshot>
<screeninfo>&karm; Screen</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="karm.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>&karm; Screen</phrase>
          </textobject>
        </mediaobject>
</screenshot>

<sect1 id="main-window">
<title>The Task/Time window</title>

<para>The various tasks are displayed in this window, along with the
time accumulated for each in the current session and in total. Tasks
being timed have a small clock icon next to the session time.</para>

<para>Subtasks can be created for each task. Double-clicking on a task
displays or collapses its associated subtasks. The total time accrued
for a task includes the times for its subtasks, as well as its own
accumulated time.</para>

</sect1>

<sect1 id="menus">
<title>The &karm; menubar</title>
<sect2>
<title>The <guimenu>File</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice><shortcut>
<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>S</accel>ave</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Saves the current tasks and subtasks with their accumulated
times</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>P</accel>rint</guimenuitem>
</menuchoice></term>
<listitem><para>
<action>Prints</action> the &karm; window</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>R</accel>eset Session Time</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Resets the total elapsed time for the current session to
zero</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>Q</accel>uit</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Closes</action> &karm;</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Clock</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>S</keycap></keycombo>
</shortcut>
<guimenu>Clock</guimenu>
<guimenuitem><accel>S</accel>tart</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>Starts</action> timing the selected task</para></listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Esc;</keycombo>
</shortcut>
<guimenu>Clock</guimenu>
<guimenuitem>S<accel>t</accel>op</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Stops</action> timing the selected task</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Task</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>Task</guimenu>
<guimenuitem><accel>N</accel>ew</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Add</action> a new task</para></listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>Task</guimenu>
<guimenuitem>New Subtask</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>Add</action> a new subtask to the selected task</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>Del</keycap>
</shortcut>
<guimenu>Task</guimenu>
<guimenuitem><accel>D</accel>elete</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>Delete</action> the selected task or subtask</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
</shortcut>
<guimenu>Task</guimenu>
<guimenuitem><accel>E</accel>dit</guimenuitem>
</menuchoice>
</term>
<listitem>
<para><action>Change the name or accumulated time</action> for the
current task</para><para>There are two options for changing the time: Edit
Absolute, in which the session and total names can be changed separately,
and Edit Relative, in which a certain change is added to or subtracted from
both the session and total times.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> menu</title>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Configure <accel>K</accel>ey Bindings...</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Opens</action> a dialog to allow the user to customize
the keyboard shortcuts</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>C</accel>onfigure KArm</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Opens</action> a dialog to allow the user to
configure &karm;</para>

<para>The dialog has two tabbed panes: <guilabel>Saving</guilabel>,
which configures the location of the save file, whether autosaving is
enabled and the autosave interval, and <guilabel>Idle
Detection</guilabel> which, when set, pops up an alert when no activity
has been detected for a specified amount of time.</para> </listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2>
<title>The <guimenu>Help</guimenu> menu</title>
<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut><keycap>F1</keycap></shortcut>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>C</accel>ontents</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Opens this document</action></para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F1</keycap></keycombo></shortcut>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>What's <accel>T</accel>his?...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Select this and click on items to learn more about
them</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>R</accel>eport Bug...</guimenuitem>
</menuchoice>
</term>
<listitem><para>A convenient dialog for reporting bugs in
&karm;</para></listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>A</accel>bout KArm</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Provides information</action> about
&karm;</para></listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>About <accel>K</accel>DE</guimenuitem>
</menuchoice>
</term>
<listitem><para><action>Provides information about the KDE
project</action></para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

</sect1>

<sect1 id="tool-bar">
<title>The Toolbar</title>
<para>The toolbar contains icons for the following commands:</para>

<note><para>(All behave identically to the menu command.)</para></note>

<itemizedlist>
<listitem><para><guiicon>Start</guiicon></para></listitem>
<listitem><para><guiicon>Stop</guiicon></para></listitem>
<listitem><para><guiicon>New</guiicon></para></listitem>
<listitem><para><guiicon>New Subtask</guiicon></para></listitem>
<listitem><para><guiicon>Delete</guiicon></para></listitem>
<listitem><para><guiicon>Edit</guiicon></para></listitem>
</itemizedlist>

</sect1>

<sect1 id="status-bar">
<title>The Statusbar</title>

<para>Reports the total elapsed time for the session.</para>
</sect1>

</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&karm;
</para>

<para>
Program copyright 1997-2000 Sirtaj Singh Kang <email>taj@kde.org</email>.</para>

<para>Contributors</para>
<itemizedlist>
<listitem><para>Espen Sand <email>espen@kde.org</email></para></listitem>
<listitem><para>Jesper Pedersen <email>blackie@ifad.dk</email></para></listitem>
<listitem><para>Kalle Dalheimer <email>kalle@kde.org</email></para></listitem>
<listitem><para>Klar&auml;lvdalens Datakonsult AB</para></listitem>
</itemizedlist>

<para>&karm; was inspired by Harald Tveit Alvestrand's very useful
utility called <application>titrax</application>, the only failing of
which is that it is based on the Xt toolkit.</para>

<para>Documentation copyright 2000 Jonathan Singer
<email>jsinger@leeta.net</email> and Sirtaj Singh Kang
<email>taj@kde.org</email>.</para>

&underFDL;
&underGPL;

</chapter>

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

<sect1 id="getting-kapp">
<title>How to obtain &karm;</title>

<para>&karm; is part of the kdeutils package and should be compiled and
installed as indicated in the package's main directory. New versions of
kdeutils can be obtained at <ulink
url="ftp://ftp.kde.org/pub/kde">ftp://ftp.kde.org/pub/kde/</ulink>.</para>

<para>To build &karm;:</para>

<screen><userinput><command>cd</command> <filename class="directory">kdeutils/karm</filename></userinput>
<userinput><command>./configure</command></userinput>
<userinput><command>make</command></userinput>
<userinput><command>su</command></userinput>
<userinput><command>make install</command></userinput>
</screen>

</sect1>

</appendix>

&documentation.index; 
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

// vim:ts=0:sw=2:tw=78:noet
-->
