Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

9 files changed, 1242 insertions, 0 deletions

diff --git a/doc/karm/Makefile.am b/doc/karm/Makefile.am
new file mode 100644
index 000000000..085981d9b
--- /dev/null
+++ b/doc/karm/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/karm/clipboard-history.png b/doc/karm/clipboard-history.png
new file mode 100644
index 000000000..ee0b04d32
--- /dev/null
+++ b/doc/karm/clipboard-history.png
diff --git a/doc/karm/copy-this-task.png b/doc/karm/copy-this-task.png
new file mode 100644
index 000000000..f5c89bea2
--- /dev/null
+++ b/doc/karm/copy-this-task.png
diff --git a/doc/karm/csvexport.png b/doc/karm/csvexport.png
new file mode 100644
index 000000000..7dc5f8e54
--- /dev/null
+++ b/doc/karm/csvexport.png
diff --git a/doc/karm/daterange.png b/doc/karm/daterange.png
new file mode 100644
index 000000000..3ad3a70f7
--- /dev/null
+++ b/doc/karm/daterange.png
diff --git a/doc/karm/idle-detect.png b/doc/karm/idle-detect.png
new file mode 100644
index 000000000..43bf71811
--- /dev/null
+++ b/doc/karm/idle-detect.png
diff --git a/doc/karm/index.docbook b/doc/karm/index.docbook
new file mode 100644
index 000000000..be0faf1ee
--- /dev/null
+++ b/doc/karm/index.docbook
@@ -0,0 +1,1238 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&karm;">
+  <!ENTITY package "kdepim">
+  <!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>Mark</firstname>
+<surname>Bucciarelli</surname>
+<affiliation>
+<address><email>mark@hubcapconsulting.com</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>lauri@kde.org</email></address></affiliation>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2000-2004</year>
+<holder>Jonathan Singer</holder>
+</copyright>
+
+<copyright>
+<year>2004-2005</year>
+<holder>Mark Bucciarelli</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-02-02</date>
+<releaseinfo>1.5.0</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
+	billable hours and can report the hours logged by task and day.</para>
+
+<para>This time history can be exported to a comma-delimited text file for
+	import into other billing and/or project management tools.</para>
+
+<para>&karm; detects when your keyboard and mouse are idle and can associate
+	different tasks with different desktops, two tools that can help keep the
+	timer running on the correct task.</para>
+
+<para>&karm; was originally written by Sirtaj Singh Kang. The word
+<quote>karm</quote> means <quote>work</quote> or <quote>deeds</quote> in the
+author's native Punjabi and is the same word (but a better transliteration)
+as <quote>karma</quote>.</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>
+
+<para>&karm; provides an additional command option that allows you to enter
+the name of the iCalendar file that is used to store your labor history.
+You enter a remote iCalendar file by using http or ftp as part of the file
+name; for example, http://www.mysite.com/mydata/mylabor.ics.</para>
+
+</sect1>
+
+<sect1 id="general-use">
+<title>Tasks</title>
+
+<informalexample>
+<para><emphasis>Problem:</emphasis> You are a free software consultant with
+many clients.  Some clients have multiple projects.  During the course of a
+day, you switch back and forth between different projects.  You need to track
+your time to generate monthly invoices.</para>
+<para><emphasis>Solution:</emphasis> Create one top-level task for each client
+and a subtask for each client project.  For projects that require more
+detailed tracking, create a list of project subtasks.  Track time by
+double-clicking on task you are currently working on.</para>
+</informalexample>
+
+<para>&karm; provides great flexibility in tracking your time, allowing
+unlimited tasks and task depth.  Time may be logged to any task, and more than
+one task can be active at any given time.</para>
+
+<para>
+To create a top-level task, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>New</guimenuitem>
+</menuchoice>
+
+To create a subtask, pick the parent task and select
+
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>New Subtask</guimenuitem>
+</menuchoice>
+</para>
+
+<para>When &karm; exits, the task list is saved to the file specified in 
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure KArm</guimenuitem>
+</menuchoice>.
+When it next opens, it reloads the task list from the same file.</para>
+
+<para>&karm; can import and export tasks to minimize your work. See <link linkend="interfaces">Other Systems</link>.</para>
+
+</sect1>
+
+<sect1 id="timers"><title>Timers</title>
+
+<informalexample>
+<para><emphasis>Problem:</emphasis> To remain solvent, you must bill an
+average of five hours a day.  To stay on track, you watch your daily and
+weekly totals.</para>
+<para><emphasis>Solution:</emphasis> Reset the session timer at the
+beginning of each work day and reset all timers at the beginning of each
+week.</para> </informalexample>
+
+<para>&karm; makes tracking time simple.  To start logging time against a
+task, double-click on the task.  To stop logging time, double-click
+the task again.  Active tasks display a small clock in the <guilabel>Session
+Time</guilabel> column.</para>
+	
+<para>Another visual clue of logging activity is the &karm; system tray icon.
+When a task is active, the second hand in the icon moves.  If you rest the
+mouse pointer over this icon, the name of the active task will display in a
+tooltip.  If more than one task is active, the task names in the tooltip are 
+separated by commas.</para>
+
+<para>&karm; maintains two timers for each task: one for the session time
+and one for the total time.  In the default configuration, &karm; displays
+two columns for each timer, resulting in a total of four columns for each task:</para>
+
+<variablelist>
+<varlistentry> <term><guilabel>Session Time</guilabel></term>
+<listitem><para>The time spent on the task since the session
+began.</para></listitem> </varlistentry> 
+
+<varlistentry> <term><guilabel>Total Session Time</guilabel></term>
+<listitem><para>The time spent on the task and all it's subtasks since the
+session began.</para></listitem> </varlistentry> 
+<varlistentry> <term><guilabel>Time</guilabel></term> <listitem><para>The time
+spent on the task since all times were reset.</para></listitem>
+</varlistentry> 
+
+<varlistentry> <term><guilabel>Total Time</guilabel></term>
+<listitem><para>The time spent on the task and all it's subtasks since all
+times were reset.</para></listitem> </varlistentry> 
+</variablelist>
+
+<para>To start a new session, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Start New Session</guimenuitem>
+</menuchoice>
+</para>
+
+<para>To reset all times, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Reset All Times</guimenuitem>
+</menuchoice>
+</para>
+
+<sect2><title>Desktop Tracking</title>
+
+<informalexample>
+<para><emphasis>Problem:</emphasis> You have two main projects that you
+switch between each day.  To help organize your work, you keep your project
+1 files on Desktop 1 and your project 2 files on Desktop
+2.</para>
+
+<para><emphasis>Solution:</emphasis> Associate project 1 task with Desktop 1
+and the project 2 task with Desktop 2.  When you switch from Desktop 2 to
+Desktop 1 active, &karm; automatically stops the project 2 task and starts
+the project 1 task.</para>
+</informalexample>
+
+<para>To associate a task with a one or more desktops, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>Edit</guimenuitem>
+</menuchoice>.
+
+Turn on <guilabel>Auto tracking</guilabel> and select the desktop or desktops
+to associate with this task.  When any of the selected desktops becomes active,
+after a short delay &karm; will be automatically start logging time against
+that task.</para>
+
+</sect2>
+
+<sect2><title>Idle Detection</title>
+
+<informalexample> <para><emphasis>Problem:</emphasis> You leave work early on
+Friday to run an errand and forget to stop the timer.  When you return on
+Monday, the timer is still running.</para>
+<para><emphasis>Solution:</emphasis> Turn on idle detection.</para>
+</informalexample>
+
+<para>&karm; can be configured to detect when the mouse and keyboard become
+ idle.  If the mouse and keyboard are idle for longer than the specified
+ number of minutes, &karm; displays the following dialog:</para>
+
+<screenshot>
+ <screeninfo>&karm; Idle Detection</screeninfo>
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="idle-detect.png" format="PNG"/>
+          </imageobject>
+          <textobject>
+            <phrase>&karm; Idle Detection Dialog</phrase>
+          </textobject>
+        </mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry><term><guibutton>Revert &amp; Stop</guibutton></term>
+<listitem><para>Subtract the amount of idle time from all active timers and
+stop them.</para><para>You were not working on the task(s) while you
+computer was idle and you are still are
+not.</para></listitem></varlistentry> 
+
+<varlistentry> <term><guibutton>Revert &amp; Continue</guibutton></term>
+<listitem><para>Subtract the amount of idle time from all active timers but
+keep them running.</para><para>You were not working on the task(s) while
+your computer was idle but you are now.  </para></listitem></varlistentry> 
+
+<varlistentry> <term><guibutton>Continue Timing</guibutton></term>
+<listitem><para>Apply the idle time to all active timers and keep them
+running.</para><para>You were working on the task(s) while your computer
+was idle and still are.  </para></listitem></varlistentry> </variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="reporting"><title>Reporting</title>
+
+<para>&karm; provides three ways to report on time you have logged.  You can
+send the session and time totals to the printer, copy the time totals to the
+clipboard, or copy the time history to the clipboard.</para>
+
+<sect2><title>Print Totals</title>
+<para>To generate the totals report for the printer, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Print</guimenuitem>
+</menuchoice>.
+This generates a three-column report for the complete list of tasks.  The
+first column is the task name, the second column is the <guilabel>Total
+Session Time</guilabel> and the third column is the <guilabel>Total
+Time</guilabel>.</para>
+</sect2>
+
+<sect2><title>Clip Totals</title>
+<para>To generate the totals report to the clipboard, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy Totals to Clipboard</guimenuitem>
+</menuchoice>.
+</para>
+
+<para>This report is generated for the currently selected task and all it's
+subtasks.  If the current task is a top-level task, &karm; asks you if you
+want to generate the report for the current task and it's subtasks or for the
+entire task list.</para>
+
+<screenshot>
+<screeninfo>&karm; Copy This Task</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="copy-this-task.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>&karm; Copy This Task Dialog</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>Once the report is generated, open KEdit or some other text editor and
+paste the report data.</para>
+
+<literallayout>
+<computeroutput>
+Task Totals
+2004-07-10 02:26
+
+  Time    Task
+----------------------------------------------
+  9:14    kde
+   9:14    karm
+    1:08    bugs
+    0:00    checkin changes
+   0:00    promo
+   0:00    web stuff
+----------------------------------------------
+  9:14 Total
+</computeroutput>
+</literallayout>
+
+<para>The first column is the <guilabel>Total Time</guilabel> and is indented
+(like the task names) to indicate task/sub-task relationships.  The reported times
+include the sub-task times.</para> 
+
+</sect2>
+
+<sect2><title>Clip History</title>
+
+<para>To generate the totals report to the clipboard, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy History to Clipboard</guimenuitem>
+</menuchoice>.
+</para>
+
+<important><para>You must turn on the <guilabel>Log History</guilabel> option in
+<menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure
+KArm</guimenuitem> </menuchoice>.  Otherwise, &karm; only keeps track of
+totals and not the detailed task history.</para></important>
+
+<para>This report is generated for the currently selected task and all it's
+subtasks. You also have the choice to generate it for all tasks.</para>
+
+<para>When you select the history report, &karm; first prompts you to enter the
+date range for the report:</para>
+
+<screenshot>
+<screeninfo>&karm; Enter Date Range</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="daterange.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>&karm; Enter Date Range</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>After entering a date range, open KEdit or some other text editor and
+paste the report data.</para>
+
+<literallayout>
+<computeroutput>
+Task History
+From Thursday 01 July 2004 to Monday 12 July 2004
+Printed on: 2004-07-12 17:18
+
+                               Week of Monday 05 July 2004
+     5     6     7     8     9    10    11
+-------------------------------------------------------------------------
+                                             0:00 kde
+                                             0:00  dc
+              !:22  1:46  3:14  1:44         8:06  karm
+                                             0:00   3.2 feature plan
+              1:08                           1:08   bugs
+                                             0:00   checkin changes
+                                             0:00  promo
+                                             0:00  web stuff
+-------------------------------------------------------------------------
+              2:30  1:46  3:14  1:44         9:14 Total
+</computeroutput>
+</literallayout>
+
+<para>The task history is totaled for each day and task, grouped by week.  The
+first seven columns are Monday through Sunday.  The eighth column is the total
+for the week and the ninth column is the task name.  The task names are
+indented to indicate the task/sub-task relationships.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="interfaces">
+<title>Other Systems</title>
+<sect2 id="korganizer"><title>KOrganizer</title>
+
+<para>&karm;, like KOrganizer and Apple's iCal, uses the industry standard
+<ulink
+url="http://developer.kde.org/documentation/standards/index.html">iCalendar</ulink>
+format for its data.  &karm; can read and write the to do lists created by
+these two applications.</para>
+
+<warning><para>If both &karm; and KOrganizer have the same file open, if you
+edit the file with KOrganizer, you risk losing data.  To be safe,
+only edit the file with one application or the other.</para></warning>
+
+</sect2>
+
+<sect2 id="planner"><title>Planner</title>
+
+<para>As a typical usecase, you might want to plan a project with the project 
+management tool Imendio Planner 
+(from <ulink url="http://planner.imendio.org">planner.imendio.org</ulink>) 
+and import its tasks to &karm;, to have them in the industry 
+standard <ulink
+url="http://developer.kde.org/documentation/standards/index.html">iCalendar</ulink> 
+format. Having done so, you are able to schedule the tasks in KOrganizer, and account your time 
+to them in &karm;. That's one way to help ensure your project stays on time
+and under budget.</para>
+
+</sect2>
+
+<sect2 id="dcop"><title>&DCOP;</title>
+
+<para>&DCOP; is the mechanism KDE programs use to communicate with each
+other.  A KDE program provides a list of functions that other programs (a Bash
+script, for example) can use.</para>
+
+<example><title>Bash script that echo's &karm;'s version</title>
+<programlisting>
+	DCOPID=`dcop | grep karm`
+	if [ $DCOPID ]
+	then
+		VERS=`dcop $DCOPID KarmDCOPIface version`
+		echo "&karm; version is $VERS"
+	else
+		echo "&karm; not running"
+	fi
+</programlisting>
+</example>
+
+<para>&karm;'s current &DCOP; interface is currently used mainly for automated
+	testing, so it is very limited.  For the full interface definition, see
+	<link linkend="dcopappendix">&DCOP; Interface Appendix</link>.</para>
+
+<para>To see the full &DCOP; interface of the &karm; version installed on your
+	system, run the following Bash script:</para>
+
+<example><title>List &karm;'s &DCOP; interface to console</title>
+<programlisting>
+	DCOPID=`dcop | grep karm`
+	if [ $DCOPID ]
+	then
+		dcop $DCOPID KarmDCOPIface
+	else
+		echo "&karm; not running"
+	fi
+</programlisting>
+</example>
+</sect2>
+
+<sect2 id="csv-export"><title>Export Totals to CSV</title>
+
+<para>&karm; can export both totals and history to a comma-delimited file
+format.  To export totals, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export to CSV file...</guimenuitem>
+</menuchoice> and &karm; displays the following export dialog:</para>
+
+<screenshot>
+<screeninfo>&karm; CSV Export Dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="csvexport.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>&karm; CSV Export Dialog</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>Enter the file you would like to export the data to, and modify the
+other dialog defaults if necessary.  Note that the date range control is
+disabled since you are exporting time totals, not the history data.  Click
+<guibutton>Export</guibutton> and &karm; exports the totals for all tasks to
+the file you selected.</para>
+
+<para>Here is an example of the output format:</para>
+
+<literallayout>
+<computeroutput>
+"kde",,,,,0.00,0.00,6.88,9.83
+,"karm",,,,6.88,8.70,6.88,9.83
+,,"3.2 feature plan",,,0.00,0.00,0.00,0.00
+,,"bugs",,,0.00,1.13,0.00,1.13
+,,"checkin changes - translation strings",,,0.00,0.00,0.00,0.00
+,,"time card report",,,0.00,0.00,0.00,0.00
+,"kopete",,,,0.00,0.00,0.00,0.00
+,"promo",,,,0.00,0.00,0.00,0.00
+,"web stuff",,,,0.00,0.00,0.00,0.00
+</computeroutput>
+</literallayout>
+
+<para>Top-level tasks are output in the first column, sub-tasks in the second,
+and so on.  The time data is output after the maximum task depth (five in
+this example).  The first time column is <guilabel>Session Time</guilabel>,
+the second is <guilabel>Time</guilabel>, the third is <guilabel>Total Session
+Time</guilabel> and the fourth is the <guilabel>Total Time</guilabel>.
+</para>
+
+
+</sect2>
+
+<sect2 id="csv-export-history"><title>Export History to CSV</title>
+
+<para>To export task history, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export History to CSV file...</guimenuitem>
+</menuchoice> and &karm; displays the same export dialog as shown above.</para>
+
+<para>Enter the file you would like to export the data to, and select a date
+range that you want the task history.  Modify the other dialog defaults if
+necessary.  Click <guibutton>Export</guibutton> and &karm; exports the
+task history for all tasks to the file you selected.</para>
+
+<para>Here is an example of the output format:</para>
+
+<literallayout>
+<computeroutput>
+Task History
+From Tuesday 06 July 2004 to Tuesday 13 July 2004
+Printed on: 2004-07-13 18:10
+2004-07-06,2004-07-07,2004-07-08,2004-07-09,2004-07-10,2004-07-11,2004-07-12,2004-07-13,
+,,,,,,,,0.00,"kde"
+,,1.77,3.23,1.73,,1.37,0.82,8.95,,"karm"
+,,,,,,,,0.00,,,"3.2 feature plan"
+,1.13,,,,,,,1.13,,,"bugs"
+,,,,,,,,0.00,,,"checkin changes - translation strings"
+,,,,,,,,0.00,,,"time card report"
+,,,,,,,,0.00,,"kopete"
+,,,,,,,,0.00,,"promo"
+,,,,,,,,0.00,,"web stuff"
+</computeroutput>
+</literallayout>
+
+<para>The three lines identify when the report was generated and for which
+date range.  The fourth row is a comma-delimited list of the dates in the
+date range, in ISO 8601 format (YYYY-MM-DD).  All subsequent rows list the
+time logged against each task.   The last numeric column is the row total
+across all days.  The task name prints after the total column, and is indented
+to indicate the task/sub-task relationship.  Top level task names appear
+in the first column after the total.</para>
+
+</sect2>
+</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. Clicking the plus sign and 
+minus sign in front of the main task toggles the view of 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>File</guimenu>
+<guimenuitem>Save</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>File</guimenu>
+<guimenuitem>Print</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+<action>Prints</action> the &karm; window</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Start New Session</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Resets </action>all session times to zero</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Reset All Times</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Resets </action>all times to zero</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Import Legacy Flat File...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Import </action>old style &karm; save files (&karm; 
+now uses iCalendar-style save files.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Import Tasks from Planner...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Import </action>an imendio planner project (see <ulink
+url="http://planner.imendio.org">planner.imendio.org</ulink>). All tasks, subtasks and their "completed" flag will be imported from a .planner-file. You can import them as a subtask by creating a subtask, leaving it marked, and then importing. </para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export to CSV file...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Export </action>
+<guilabel>Total Session Time</guilabel>,
+<guilabel>Session Time</guilabel>, <guilabel>Time</guilabel>, and
+<guilabel>Total Time</guilabel> to a text file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export History to CSV file...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Export </action> task history to a text file.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy Totals to Clipboard</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Copies </action> the current total time for a 
+task or all tasks to the &kde; clipboard</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy History to Clipboard</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Copies </action> daily times for a 
+given period to the &kde; clipboard</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</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><keycap>S</keycap></shortcut>
+<guimenu>Clock</guimenu>
+<guimenuitem>Start</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Starts</action> timing the selected task</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Clock</guimenu>
+<guimenuitem>Stop</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Stops</action> timing the selected task</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycap>&Esc;</keycap></shortcut>
+<guimenu>Clock</guimenu>
+<guimenuitem>Stop All Timers</guimenuitem>
+</menuchoice>
+</term>
+<listitem><para><action>Stops</action> timing all tasks</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>New</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>Delete</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>Edit</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 times 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><para>The Auto tracking option allows 
+timing to start and stop automatically when you switch to or from a particular 
+&kde; desktop.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>The <guimenu>Settings</guimenu> menu</title>
+<variablelist>
+
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts</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>Settings</guimenu>
+<guimenuitem>Configure KArm</guimenuitem>
+</menuchoice>
+</term>
+<listitem><para><action>Opens</action> a dialog to allow the user to
+configure &karm;</para>
+
+<para>The dialog has three tabbed panes: <guilabel>Behavior </guilabel>, which 
+allows you to specify an alert for no activity and a warning message when you 
+delete a task set, <guilabel>Display </guilabel>, which configures the fields 
+shown in the main window and <guilabel>Storage</guilabel>,
+which configures the location of the save file, whether auto saving is
+enabled and the auto save interval.</para> </listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>The <guimenu>Help</guimenu> menu</title>
+
+&help.menu.documentation;
+
+</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: </para>
+
+<itemizedlist>
+
+<listitem><para>1997-2000 Sirtaj Singh Kang
+<email>taj@kde.org</email>.</para>  </listitem> 
+
+<listitem><para>2001-2002 Tomas Pospisek
+<email>tpo_deb@sourcepole.ch</email></para></listitem>
+
+<listitem><para>2003-2004 Mark
+Bucciarelli<email>mark@hubcapconsulting.com</email></para></listitem>
+
+</itemizedlist>
+
+<para>Contributors (in alphabetical order)</para>
+<itemizedlist>
+<listitem><para>Allen Winter <email>winterz@verizon.net</email></para></listitem>
+<listitem><para>David Faure <email>faure@kde.org</email></para></listitem>
+<listitem><para>Espen Sand <email>espen@kde.org</email></para></listitem>
+<listitem><para>Gioele Barabucci <email>gioele@gioelebarabucci.com</email></para></listitem>
+<listitem><para>Jan Schaumann <email>jschauma@netmeister.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>
+<listitem><para>Mark Bucciarelli <email>mark@hubcapconsulting.com</email></para></listitem>
+<listitem><para>Thorsten St&auml;rk <email>dev@staerk.de</email></para></listitem>
+<listitem><para>Tomas Pospisek <email>tpo_deb@sourcepole.ch</email></para></listitem>
+<listitem><para>Willi Richert <email>w.richert@cox.net</email></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-2004 Jonathan Singer
+<email>jsinger@leeta.net</email> and Sirtaj Singh Kang
+<email>taj@kde.org</email>.</para>
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<glossary id="glossary">
+
+<glossentry id="gloss-active-task">
+<glossterm>active task</glossterm>
+<glossdef><para>A task which has a timer running.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-dcop">
+<glossterm>&DCOP;</glossterm>
+<glossdef><para>The interprocess communication protocol used in KDE.  Short
+for Desktop COmmunication Protocol.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-desktop">
+<glossterm>desktop</glossterm>
+<glossdef><para>GNU/Linux, FreeBSD and other systems that run X-Windows have
+multiple desktops.  You typically have four different desktops installed by
+default.  Each desktop can display it's own set of programs and files.  When
+KDE first starts up, the desktop you see is Desktop 1.  If you press
+<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>, you will see
+Desktop 2.  Pressing <keycombo
+action="simul">&Alt;<keycap>F1</keycap></keycombo> will bring back Desktop
+1.  </para></glossdef> </glossentry>
+
+<glossentry id="gloss-history">
+<glossterm>history</glossterm>
+<glossdef><para>If &karm; is configured to log history, it will record ever
+start/stop timer event. This history is never cleared when times are reset
+cleared and remains on file until the task is deleted.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-session"> <glossterm>session</glossterm>
+<glossdef><para>A user-defined starting point for the session timers.  A new
+session begins when you select <menuchoice> <guimenu>File</guimenu>
+<guimenuitem>Start New Session</guimenuitem> </menuchoice>.
+Session data is not saved when you create a new session.
+</para></glossdef> </glossentry>
+
+<glossentry id="gloss-system-time"> <glossterm><guilabel>Session
+Time</guilabel></glossterm> <glossdef><para>The time spent on the task
+since the session began.</para></glossdef> </glossentry> 
+
+<glossentry id="gloss-system-tray"> <glossterm>system tray</glossterm>
+<glossdef><para>The system tray is in the bar that (by default) appears at
+the bottom of the screen.  In this system tray <inlinemediaobject>
+<imageobject> <imagedata fileref="systray.png"
+format="PNG"/></imageobject> </inlinemediaobject> the &karm; icon is on the far
+right.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-top-level-task">
+<glossterm>top level task</glossterm>
+<glossdef><para>A task with no parent tasks.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-total-session-time"> <glossterm><guilabel>Total Session
+Time</guilabel></glossterm> <glossdef><para>The time spent on the task and
+all it's subtasks since the session began.</para></glossdef> </glossentry>
+<glossentry> <glossterm><guilabel>Time</guilabel></glossterm>
+<glossdef><para>The time spent on the task since all times were
+reset.</para></glossdef> </glossentry> 
+
+<glossentry id="gloss-total-time"> <glossterm><guilabel>Total Time</guilabel></glossterm>
+<glossdef><para>The time spent on the task and all it's subtasks since all
+times were reset.</para></glossdef> </glossentry> 
+
+</glossary>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-karm">
+<title>How to obtain &karm;</title>
+
+&install.intro.documentation;
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+<appendix id="dcopappendix"><title>&DCOP; Interface</title>
+
+<refentry id="dcop-version">
+<refmeta>
+<refentrytitle>version</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>version</refname>
+<refpurpose>Return &karm;'s version.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString version()
+</synopsis>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+<para><function>version()</function> is a &DCOP; call that returns &karm;'s
+version number; for example 1.5.0.  The version number is returned as a string
+in the typical GNU format of major.minor.bugfix.</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop-quit">
+<refmeta>
+<refentrytitle>quit</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>quit</refname>
+<refpurpose>Return &karm;'s quit.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString quit()
+</synopsis>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+<para><function>quit()</function> is a &DCOP; call that provides a way that an
+external program can gracefully shutdown &karm;.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop-hastodo">
+<refmeta>
+<refentrytitle>hastodo</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>hastodo</refname>
+<refpurpose>Check if top-level todo exists.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString hastodo(QString taskname)
+</synopsis>
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>taskname</parameter></term>
+<listitem>
+	<para>The name of the todo to look for.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+<para><function>hastodo(QString taskname)</function> is a &DCOP; call that
+	looks for a of the given name.  If found, it returns the
+	iCalendar UID that identifies that todo.  If not found, it returns an empty
+	string.
+</para>
+<para>The iCalendar file that &karm; currently has opened is the file that is
+searched.  All todo trees are searched, not just top-level todo's.  If more
+than one todo has a matching name, the first one found is returned.</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop-addtodo">
+<refmeta>
+<refentrytitle>addtodo</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>addtodo</refname>
+<refpurpose>Add new todo.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString addtodo(QString todoname)
+</synopsis>
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>todoname</parameter></term>
+<listitem>
+	<para>The name of new todo.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para><function>addtodo(QString todoname)</function> is a &DCOP; call that
+	adds a new top-level todo to the current storage.  The UID of the new todo
+	is returned.
+</para>
+</refsect1>
+</refentry>
+
+</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=2:sw=2:tw=78:noet
+-->
diff --git a/doc/karm/karm.png b/doc/karm/karm.png
new file mode 100644
index 000000000..0c4a0a3cc
--- /dev/null
+++ b/doc/karm/karm.png
diff --git a/doc/karm/systray.png b/doc/karm/systray.png
new file mode 100644
index 000000000..2b5459d2f
--- /dev/null
+++ b/doc/karm/systray.png