<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
  <!ENTITY kappname "&karm;" -- this only *seems* redundant -->
  <!ENTITY % English "INCLUDE">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  %ents;
]>

<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>

</authorgroup>

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

<legalnotice>&FDLNotice;</legalnotice>

<date>14/12/2000</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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><keycap>P</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>P</accel>rints</guimenuitem>
</menuchoice></term>
<listitem><para><action>Prints</action> the &karm; window</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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>Ctrl</keycap><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"><keycap>Ctrl</keycap><keycap>T</keycap></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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><keycap>Alt</keycap><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"><keycap>Ctrl</keycap><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>P</accel>references...</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>


<![ %addindex; [ &kdedocindex; ]]>
</book>
