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

6 files changed, 4172 insertions, 0 deletions

diff --git a/doc/kalarm/Makefile.am b/doc/kalarm/Makefile.am
new file mode 100644
index 000000000..171f575ce
--- /dev/null
+++ b/doc/kalarm/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
diff --git a/doc/kalarm/alarmmessage.png b/doc/kalarm/alarmmessage.png
new file mode 100644
index 000000000..da0fa1aeb
--- /dev/null
+++ b/doc/kalarm/alarmmessage.png
diff --git a/doc/kalarm/editwindow.png b/doc/kalarm/editwindow.png
new file mode 100644
index 000000000..cfb60992e
--- /dev/null
+++ b/doc/kalarm/editwindow.png
diff --git a/doc/kalarm/index.docbook b/doc/kalarm/index.docbook
new file mode 100644
index 000000000..28f44e788
--- /dev/null
+++ b/doc/kalarm/index.docbook
@@ -0,0 +1,4170 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kalarm;">
+  <!ENTITY package "kdepim">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<!-- The language must NOT be changed here. -->
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kalarm; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>David</firstname>
+<surname>Jarvie</surname>
+<affiliation>
+<address><email>&David.Jarvie.mail;</email></address>
+</affiliation>
+</author>
+
+<othercredit role="developer">
+<firstname>David</firstname>
+<surname>Jarvie</surname>
+<affiliation><address><email>&David.Jarvie.mail;</email></address></affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year>
+<holder>David Jarvie</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<!-- Don't change format of date and version of the documentation -->
+
+<date>2008-01-23</date>
+<releaseinfo>1.05.00</releaseinfo>
+
+<abstract>
+<para>&kalarm; is a personal alarm message, command and email scheduler for &kde;.</para>
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdepim</keyword>
+<keyword>kalarm</keyword>
+<keyword>alarm</keyword>
+<keyword>reminder</keyword>
+</keywordset>
+
+</bookinfo>
+
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kalarm; lets you schedule the display of personal alarm
+messages, the playing of sound files, the execution of commands and
+the sending of emails.</para>
+
+<para>In its default graphical mode, &kalarm; displays the list of
+pending alarms, showing their times and details.  You can create new
+alarms, or you can select existing alarms for modification or
+deletion. You can also optionally view expired alarms.</para>
+
+<para>When configuring an alarm, you may either type in the alarm
+message text, specify a text or image file to display, specify a
+command to execute, or enter an email to send. You can also choose
+the color of the alarm message, whether to play a sound or speak the
+message, whether it should repeat, and whether the alarm should be
+canceled if it cannot be triggered at its scheduled time.</para>
+
+<para>Alarms may also be scheduled from the command line, or via &DCOP;
+calls from programs.</para>
+
+<para>When an alarm message is due, it is displayed on each &kde;
+desktop to ensure that you don't miss it. The message window shows the
+time for which the alarm was scheduled. It usually has a defer option
+to ask for the alarm to be displayed again later. An example of an
+alarm message:</para>
+
+<screenshot>
+<screeninfo>Screenshot of the &kalarm; message window</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="alarmmessage.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Alarm message</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>When the alarm specifies a command to execute or an email to
+send, &kalarm; displays nothing.</para>
+
+<para>&kalarm; can run in either of two modes:
+<quote>continuous</quote> (the default) where it runs from the
+system tray, or <quote>on-demand</quote> where it runs as and when
+required (with the option of displaying an independent system tray
+icon).</para>
+
+<para>This document makes various references to the <application>alarm
+daemon</application>.  This is an application which runs in the
+background, checking pending alarms and telling &kalarm; to display
+them when they become due.</para>
+
+</chapter>
+
+<chapter id="using-kalarm">
+<title>Using &kalarm;</title>
+
+<para>When it is run with no command line parameters, &kalarm; starts
+in graphical mode, and displays the current list of outstanding
+alarms.</para>
+
+<para>When &kalarm; starts in graphical mode, it checks whether the
+<application>alarm daemon</application> is running. If it is not
+already running, &kalarm; starts it.</para>
+
+<tip><para>All spin boxes in &kalarm; have an acceleration facility.
+To make the value change by larger steps, hold down the
+<keycap>Shift</keycap> key while you click on the spin arrow
+buttons.</para>
+
+<mediaobject>
+<imageobject>
+<imagedata fileref="spinbox.png" format="PNG"/>
+</imageobject>
+</mediaobject>
+</tip>
+
+<sect1 id="alarm-list">
+<title>Alarm list</title>
+
+<para>The main &kalarm; window displays the current list of pending
+alarms, showing their times, repetition intervals, colors, and
+message texts, names of files to display, commands to execute or email
+subjects. (For a recurring alarm, the time shown is its next scheduled
+trigger time. For an alarm with a reminder, the time shown is the time
+of the alarm proper, not the reminder time.) An icon at the left of
+each alarm text/file/command/email subject indicates the type of
+alarm.</para>
+
+<screenshot>
+<screeninfo>Screenshot of the &kalarm; main window</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="mainwindow.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Main window</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>For a repeated alarm, the list shows its next scheduled trigger
+time and its basic repetition interval (&eg; <quote>1 Day</quote> for
+a daily recurrence, <quote>3 Weeks</quote> for a recurrence which
+triggers on Monday and Wednesday every third week,
+<quote>Login</quote> for a repeat-at-login alarm).</para>
+
+<para>The alarms may be ordered by date/time, repeat interval, color,
+type or text by clicking on the titlebar for the appropriate column.
+To reverse the sort order, click the column titlebar again.</para>
+
+<para>You can optionally show the remaining time until each alarm is
+due, together with, or instead of, the alarm's scheduled time.
+To show or hide the alarm time column, select
+<menuchoice><guimenu>View</guimenu><guimenuitem>Show Alarm
+Times</guimenuitem></menuchoice>.
+To show or hide the time-to-alarm column, select
+<menuchoice><guimenu>View</guimenu><guimenuitem>Show Time To
+Alarms</guimenuitem></menuchoice>. At least one of these columns is
+always shown. You can use the
+<link linkend="preferences-view">Preferences dialog</link> to change
+the default columns to display.</para>
+
+<sect2 id="expired">
+<title>Expired alarms</title>
+
+<para>By default, &kalarm; stores alarms for a limited period once
+they have expired or been deleted. (But note that alarms which you
+delete are stored only if they have already triggered at least once.)
+You can control whether &kalarm; stores expired alarms, and for how
+long, in the
+<link linkend="preferences-general">Preferences dialog</link>.</para>
+
+<para>Expired alarms may be shown in the alarm list by selecting
+<menuchoice><guimenu>View</guimenu><guimenuitem>Show Expired
+Alarms</guimenuitem></menuchoice>. To hide them again, repeat the
+action. You can use the
+<link linkend="preferences-view">Preferences dialog</link> to show
+expired alarms by default.</para>
+
+</sect2>
+
+<sect2 id="search">
+<title>Searching the alarm list</title>
+
+<para>You can search through the alarm list to find alarms containing
+a search text. To invoke this, select <menuchoice>
+<guimenu>Edit</guimenu><guimenuitem>Find</guimenuitem></menuchoice>.
+In the search dialog, select the alarm types which you wish to search.
+To continue searching for more alarms which match, use <menuchoice>
+<guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice>
+or <menuchoice>
+<guimenu>Edit</guimenu><guimenuitem>Find Previous</guimenuitem>
+</menuchoice>.</para>
+
+<para>Searching is performed as follows:</para>
+
+<itemizedlist>
+<listitem>
+<para>Text alarms: the message text is searched.</para>
+</listitem>
+
+<listitem>
+<para>File alarms: the file path/URL is searched.</para>
+</listitem>
+
+<listitem>
+<para>Command alarms: the command line or command script is
+searched.</para>
+</listitem>
+
+<listitem>
+<para>Email alarms: in addition to the subject and body of the email,
+the recipients and the URLs of attachments are searched.</para>
+</listitem>
+</itemizedlist>
+
+<note><para>Only alarms currently shown in the alarm list can be
+selected for searching. So if you want to search expired alarms, you
+must first display them as described in the section above.</para></note>
+</sect2>
+</sect1>
+
+<sect1 id="create-edit">
+<title>Creating and manipulating alarms</title>
+
+<sect2>
+<title>Creating a new alarm</title>
+
+<para>To create a new alarm, do one of the following. This displays
+the <link linkend="alarm-edit-dlg">alarm edit dialog</link> through
+which you configure the alarm.</para>
+
+<itemizedlist>
+<listitem>
+<para>Select <menuchoice><guimenu>Actions</guimenu>
+<guimenuitem>New</guimenuitem></menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the system tray icon
+and choose
+<menuchoice><guimenuitem>New</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+
+<listitem>
+<para>Click the <mousebutton>Middle</mousebutton> mouse button on the
+system tray icon.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click in the alarm list and
+choose <menuchoice><guimenuitem>New</guimenuitem></menuchoice> from
+the context menu.</para>
+</listitem>
+
+<listitem>
+<para>Double click on empty space below the last entry in the alarm
+list.</para>
+</listitem>
+</itemizedlist>
+
+<para>Alternatively, you can create new alarms preconfigured from
+various sources:</para>
+
+<itemizedlist>
+<listitem>
+<para>To base your new alarm on an alarm template, follow the
+instructions in the <link linkend="templates">Alarm templates</link>
+section.</para>
+</listitem>
+
+<listitem>
+<para>To base your new alarm on an existing one, highlight the existing
+alarm in the list and select <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Copy</guimenuitem></menuchoice>.
+This opens the <link linkend="alarm-edit-dlg">alarm edit dialog</link>
+already filled in with a copy of the selected alarm's details.</para>
+</listitem>
+
+<listitem>
+<para>To create a new alarm which displays an existing email message,
+drag the email from &kmail; onto &kalarm;'s main window or system tray
+icon. This opens the <link linkend="alarm-edit-dlg">alarm edit
+dialog</link> with the entire email message (including sender,
+recipient, etc.) as the alarm text.</para>
+</listitem>
+
+<listitem>
+<para>To create a new email alarm to send a copy of an existing email
+message, drag the email from &kmail; onto &kalarm;'s main window or
+system tray icon. Then select the <guilabel>Email</guilabel> option.
+The <link linkend="alarm-edit-dlg">alarm edit dialog</link> is preset
+with the entire email message except sender.</para>
+</listitem>
+
+<listitem>
+<para>Dragging any piece of text onto &kalarm;'s main window or system
+tray icon opens the <link linkend="alarm-edit-dlg">alarm edit
+dialog</link> and sets the alarm text.</para>
+</listitem>
+
+<listitem>
+<para>To create a file display alarm, drag a file URL onto &kalarm;'s
+main window or system tray icon. This opens the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link> and sets the
+file name.</para>
+</listitem>
+
+<listitem>
+<para>You can automatically create birthday alarms for people in
+&kaddressbook; as described in <link linkend="birthdays">Importing
+birthdays from &kaddressbook;</link>.</para>
+</listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="edit-alarm">
+<title>Modifying an existing alarm</title>
+
+<para>To modify an existing pending alarm (expired alarms cannot be
+amended), do one of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Double click on its entry in the alarm list.</para>
+</listitem>
+
+<listitem>
+<para>Select it by clicking on its entry in the alarm list. Then
+choose <menuchoice><guimenu>Actions</guimenu>
+<guimenuitem>Edit</guimenuitem></menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on its entry in the alarm
+list and choose
+<menuchoice><guimenuitem>Edit</guimenuitem></menuchoice> from the
+context menu.</para>
+</listitem>
+</itemizedlist>
+
+<para>This displays the <link linkend="alarm-edit-dlg">alarm edit
+dialog</link>.</para>
+
+</sect2>
+
+<sect2>
+<title>Deleting/reactivating an alarm</title>
+
+<para>To delete existing alarms, do one of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select one or more alarms by clicking on their entries in the
+alarm list. Then choose <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Delete</guimenuitem>
+</menuchoice>.</para>
+</listitem>
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the desired entries in
+the alarm list and choose
+<menuchoice><guimenuitem>Delete</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+<para>When you delete an active alarm, it is stored as an expired
+alarm, provided that it has triggered at least once before being
+deleted, and provided that expired alarms are stored at all. (Use the
+<link linkend="preferences-general">Preferences dialog</link> to
+control whether and for how long expired alarms are stored.) When you
+delete an expired alarm, or an active alarm which has not yet
+triggered, it is removed permanently.</para>
+
+<para>You can reactivate a deleted alarm from the expired alarms list,
+provided that it has not yet expired. To do this, first display
+expired alarms, as described in
+<link linkend="expired">Expired alarms</link>. Then:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select one or more appropriate expired alarms by clicking on
+their entries in the alarm list. Then choose <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Reactivate</guimenuitem>
+</menuchoice>.</para>
+</listitem>
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the desired entries in
+the expired alarm list and choose
+<menuchoice><guimenuitem>Reactivate</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Enabling/disabling an alarm</title>
+
+<para>See <link linkend="enable-disable">Enabling and disabling alarms</link>
+for how to enable and disable alarms, either individually or as a whole.</para>
+
+</sect2>
+
+<sect2>
+<title>Viewing an alarm</title>
+
+<para>To view an existing alarm without the ability to modify it, do
+one of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select it by clicking on its entry in the alarm list. Then choose
+<menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>View</guimenuitem>
+</menuchoice>.</para>
+</listitem>
+<listitem>
+<para><mousebutton>Right</mousebutton> click on its entry in the alarm
+list and choose
+<menuchoice><guimenuitem>View</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+<para>This displays the <link linkend="alarm-edit-dlg">alarm edit
+dialog</link> in read-only mode.</para>
+
+</sect2>
+
+<sect2>
+<title>Acknowledging an alarm</title>
+
+<para>See <link linkend="message-window">Alarm message window</link>
+for how to acknowledge alarms.</para>
+
+</sect2>
+
+<sect2 id="templates">
+<title>Alarm templates</title>
+
+<para>If you frequently want to set up similar alarms, you can create
+an alarm template to avoid having to enter all the details from
+scratch each time. A template can contain all the details which an
+alarm can contain, apart from the start date.</para>
+
+<para>As an example, you may regularly want to set an
+alarm to remind you about a television program whose time varies
+from week to week. The template would contain all the alarm details
+(message text, whether to play a sound, etc.) except for the time and
+date. Now, to create the alarm, all you need to do is open the alarm
+edit dialog with that template and then enter the time and
+date.</para>
+
+<para>To create an alarm based on a template, open the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link> preset with
+the template details:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select the <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>New From Template</guimenuitem>
+</menuchoice> menu item, and then select the desired template.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the system tray icon
+and choose
+<menuchoice><guimenuitem>New Alarm From Template</guimenuitem></menuchoice>
+from the context menu. Then select the desired template.</para>
+</listitem>
+
+<listitem>
+<para>Open the <link linkend="alarm-edit-dlg">alarm edit dialog</link>
+in the usual way, and click the
+<guibutton>Load Template...</guibutton> button to select a template to
+preset the dialog with.</para>
+</listitem>
+</itemizedlist>
+
+<sect3>
+<title>Configuring templates</title>
+
+<para>You can create, modify or delete templates using the Alarm
+Templates dialog, or you can create a new alarm template based on an
+existing alarm.</para>
+
+<para>To create a new alarm template, do one of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Display the Alarm Templates dialog by selecting the <menuchoice>
+<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem>
+</menuchoice> menu item, and click <guibutton>New</guibutton>. This
+displays a blank template edit dialog.</para>
+</listitem>
+
+<listitem>
+<para>Display the Alarm Templates dialog by selecting the <menuchoice>
+<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem>
+</menuchoice> menu item, select an existing template from the list and
+click <guibutton>Copy</guibutton>. This opens the template edit dialog
+already filled in with a copy of the existing template's
+details.</para>
+</listitem>
+
+<listitem>
+<para>Highlight an alarm in the alarm list and select <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Create template</guimenuitem>
+</menuchoice>. This opens the template edit dialog already filled in
+with a copy of the selected alarm's details.</para>
+</listitem>
+</itemizedlist>
+
+<para>To modify an existing template, display the Alarm Templates
+dialog by selecting the <menuchoice>
+<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem>
+</menuchoice> menu item and click <guibutton>Edit</guibutton>. This
+displays the template edit dialog which is described below.</para>
+
+<para>To delete existing templates, display the Alarm Templates
+dialog by selecting the <menuchoice>
+<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem>
+</menuchoice> menu item, select one or more templates and click
+<guibutton>Delete</guibutton>. A confirmation prompt is issued to
+prevent accidental deletions.</para>
+
+</sect3>
+
+<sect3>
+<title>Template edit dialog</title>
+
+<para>The template edit dialog is similar to the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link>. The
+following controls are different:</para>
+
+<itemizedlist>
+<listitem>
+<para>Enter the template's name in <guilabel>Template name</guilabel>.
+It is the template's name which is displayed in template selection
+lists, so it is best to choose a name which will remind you of its
+function. Each template's name must be unique.</para>
+</listitem>
+
+<listitem>
+<para>In the <guilabel>Time</guilabel> group box, select one of:</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>Default time</guilabel> if you do not wish to specify
+any trigger time. Alarms based on this template will initially
+use the normal default trigger time for new alarms.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Time</guilabel> to enter a time when the alarm is to
+be triggered.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Any time</guilabel> to specify that the alarm should
+only have a date, not a time.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Time from now</guilabel> to enter how long (in hours
+and minutes) after the alarm is created, that it should be
+triggered.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para>In the <guilabel>Recurrence Rule</guilabel> group box in the
+<guilabel>Recurrence</guilabel> tab, no day or month need be selected
+for weekly or yearly recurrences, respectively.</para>
+</listitem>
+</itemizedlist>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="import">
+<title>Importing alarms from external calendars</title>
+
+<para>You can import alarms from other calendar files into &kalarm;,
+by <menuchoice><guimenu>File</guimenu>
+<guimenuitem>Import Alarms...</guimenuitem></menuchoice>. The
+import function scans the selected calendar file for events containing
+alarms, and copies them (with new unique IDs) into &kalarm;'s calendar.
+Events without alarms, and calendar entries other than events, are
+ignored.</para>
+
+<warning><para>If you import alarms from calendar files which were
+created by applications other than &kalarm;, the alarms may be changed
+by the import process &ndash; even alarm times may change. This depends on
+the data storage conventions used by the other application, and is
+unavoidable if those conventions differ from what &kalarm; expects.
+Always check imported alarms for unexpected changes, and adjust them
+as necessary.</para></warning>
+
+</sect2>
+
+<sect2 id="birthdays">
+<title>Importing birthdays from &kaddressbook;</title>
+
+<para>You can set up display alarms for birthdays stored in
+&kaddressbook;, by <menuchoice><guimenu>File</guimenu>
+<guimenuitem>Import Birthdays...</guimenuitem></menuchoice>. This
+displays a dialog which allows you to select which birthdays to create
+alarms for.</para>
+
+<itemizedlist>
+<listitem>
+<para>In the <guilabel>Alarm Text</guilabel> group box, you can set up
+the text to be displayed in the birthday alarm messages. The message
+text is created by combining the <guilabel>Prefix</guilabel> text
+followed by the person's name followed by the
+<guilabel>Suffix</guilabel> text. No spaces are added, so remember to
+include any necessary trailing space in <guilabel>Prefix</guilabel>
+and leading space in <guilabel>Suffix</guilabel>.</para>
+
+<note><para>If you change the alarm text, the birthday selection list
+will be re-evaluated.</para></note>
+</listitem>
+
+<listitem>
+<para>In the <guilabel>Select Birthdays</guilabel> list, select the
+birthdays which you want to create alarms for. Note that the list
+shows only those entries in &kaddressbook; which contain a birthday
+and which do not already have a birthday alarm in the format currently
+defined in the <guilabel>Alarm Text</guilabel> group box.</para>
+</listitem>
+
+<listitem>
+<para>The remaining controls are the same as for
+<guilabel>Text</guilabel> alarms in the
+<link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="undo">
+<title>Undo / redo</title>
+
+<para>You can undo and redo the most recent changes which you have
+made during the current session of &kalarm;. Most actions can be
+undone, including creation, edit and deletion of alarms and alarm
+templates, and reactivation of alarms. To prevent excessive resources
+being used by the undo history, the number of changes stored is
+limited to the last 12.</para>
+
+<para>To undo the last change, select <menuchoice>
+<guimenu>Edit</guimenu><guimenuitem>Undo</guimenuitem></menuchoice>.
+To redo the last change which was undone, select <menuchoice>
+<guimenu>Edit</guimenu><guimenuitem>Redo</guimenuitem>
+</menuchoice>.</para>
+
+<para>To undo a change other than the last one, click on the
+<guibutton>Undo</guibutton> button in the toolbar and hold the mouse
+button down. A list of actions will be displayed from which you can
+choose the one to undo. If you don't see the action which you are
+looking for, remember that you may need to undo more recent changes
+first, which the desired change depends on. For example, if you edited
+an alarm and then deleted it, you cannot undo the edit until you have
+first undone the deletion.</para>
+
+<para>Redoing a change other than the last one can be done in a
+similar manner, using the <guibutton>Redo</guibutton> toolbar
+button.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="alarm-edit-dlg">
+<title>The alarm edit dialog</title>
+
+<para>The alarm edit dialog enables you to view and edit an
+alarm.</para>
+
+<screenshot>
+<screeninfo>Screenshot of the alarm edit dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="editwindow.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Alarm edit dialog</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<sect2>
+<title>Alarm action</title>
+
+<para>In the <guilabel>Action</guilabel> group box, select the type
+of alarm:</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>Text</guilabel> in order to enter an alarm message text
+(which may include newlines) in the edit box. Set the following
+options:</para>
+
+<itemizedlist>
+<listitem>
+<para>The <guilabel>Sound</guilabel> option allows you to select
+whether an audible alarm should sound when the alarm message is
+displayed. Choose:</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>None</guilabel> to display the alarm silently.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Beep</guilabel> to sound a beep.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Speak</guilabel> to have the alarm message spoken as
+well as being displayed. This option is only available if you have
+<application>KTTSD</application> (from the kdeaccessibility package)
+installed and configured, together with a compatible speech
+synthesizer, &eg; <application>Festival</application>.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Sound file</guilabel> to play an audio file. Use the
+button on the right to display the Sound File dialog which lets you
+select a file to play and set volume and repetition options. If you
+hover the mouse over the selector, a tooltip will display the audio file
+currently selected.</para>
+
+<note><para>&kalarm; uses the &arts; sound server for repetition and
+volume control. If &kalarm; has been built without &arts; support,
+repetition and volume options will not be available and a simple sound
+file selector will appear in place of the full Sound File
+dialog.</para></note>
+
+<para>In the Sound File dialog:</para>
+
+<itemizedlist>
+<listitem>
+<para>Enter the sound file path, or use the button beside the
+edit box to display a file selection dialog. You can listen to the
+selected file by clicking the play button to the left of the edit
+field. That button then changes function to allow you to stop playing
+when you have heard enough.</para>
+</listitem>
+
+<listitem>
+<para>Check <guilabel>Repeat</guilabel> to continually repeat the
+audio file for as long as the alarm is displayed. (The alarm message
+window contains a button to stop playing the sound should you need
+silence but still want to display the alarm.)</para>
+</listitem>
+
+<listitem>
+<para>Check <guilabel>Volume</guilabel> and adjust the slider
+control if you want to adjust the volume at which the audio file is
+played.</para>
+</listitem>
+
+<listitem>
+<para>If you wish, you can fade the volume. Fading means to start
+playing the audio file at one volume and gradually change to the final
+volume, over a specified time interval. The final volume is that
+entered in <guilabel>Volume</guilabel> above. To enable fade, check
+<guilabel>Fade</guilabel>, and then enter the fade period in seconds
+in the <guilabel>Fade time</guilabel> field, and adjust the
+<guilabel>Initial volume</guilabel> slider.</para>
+</listitem>
+</itemizedlist>
+
+<note><para>When possible, &kmix; is used to set volumes. This
+ensures that the volume at which the alarm is played is unaffected by
+any changes in the computer's sound level. If &kmix; is not installed
+(or is older than &kde; 3.1), the volume is set relative to the sound
+level current at the time the alarm triggers. So in this case, the
+volume at which the alarm is played will vary depending on any changes
+in the computer's sound level.</para></note>
+
+<tip><para>You can use the <guibutton>Try</guibutton> button to test out
+the selected sound levels.</para></tip>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para>Use the <guibutton>Font &amp; Color...</guibutton> button to
+select a font, and foreground and background colors, for the alarm
+message. In the <guilabel>Choose Alarm Font &amp; Color</guilabel>
+dialog, check <guilabel>Use default font</guilabel> to display the
+message in whatever font is configured as the default at the time
+the message is displayed. To choose a specific font for the message,
+uncheck <guilabel>Use default font</guilabel>. (The default font, and
+the colors shown in the color selection lists, can be set in the
+<link linkend="preferences-fontcolour">Preferences dialog</link>.)</para>
+
+<para>The selected font and colors are shown in a sample text
+alongside the button. You can edit this text to show special
+characters.</para>
+</listitem>
+
+<listitem>
+<para>Use the <guibutton>Special Actions...</guibutton> button to
+specify shell commands to execute before or after displaying the
+alarm. In the <guilabel>Special Alarm Actions</guilabel>
+dialog:</para>
+
+<itemizedlist>
+<listitem>
+<para>In the <guilabel>Pre-alarm action</guilabel> field, enter a
+shell command to execute before the alarm is displayed.  Note that
+&kalarm; will wait for the command to complete before displaying the
+alarm.</para>
+
+<para>A pre-alarm action is only executed once when the alarm message
+is initially displayed, including when a reminder message is replaced
+by the actual alarm message. It is <emphasis>not</emphasis> executed
+in any of the following circumstances:</para>
+
+<itemizedlist>
+<listitem><para>When a reminder message is displayed.</para></listitem>
+<listitem><para>When the message is redisplayed after deferring the
+alarm.</para></listitem>
+<listitem><para>When the message was displaying at the time you logged
+off and is then restored when you log back in.</para></listitem>
+<listitem><para>When a recurring alarm triggers but the alarm message
+(or a deferred alarm message) from a previous occurrence of the alarm
+is still visible; in other words, when the previous occurrence of the
+alarm has not yet been acknowledged.</para></listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para>In the <guilabel>Post-alarm action</guilabel> field, enter a
+shell command to execute when the alarm is acknowledged (whether by
+clicking <guibutton>Close</guibutton> or by using the close button
+in the window's titlebar). It is <emphasis>not</emphasis>
+executed in any of the following circumstances:</para>
+
+<itemizedlist>
+<listitem><para>When a reminder message is closed.</para></listitem>
+<listitem><para>When you defer the alarm, except when the deferred
+alarm is finally acknowledged.</para></listitem>
+<listitem><para>When the alarm message is closed due to logging
+out.</para></listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+
+<para>See the description of Command alarms below for details of how
+shell commands are executed.</para>
+
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para><guilabel>File</guilabel> to enter the path or &URL; of a text
+or image file whose contents are to be displayed in the alarm message.
+Use the button beside the edit box to display a file selection dialog.
+Set options as for text alarms above, but note that the
+<guilabel>Speak</guilabel> option is not available.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Command</guilabel> to enter a command to
+execute.</para>
+
+<note><para>This option is not available if &kde; is running in kiosk
+mode.</para></note>
+
+<itemizedlist>
+<listitem>
+<para>The <guilabel>Enter a script</guilabel> checkbox lets you choose
+whether to enter a shell command line or a script.</para>
+
+<para>If this option is unchecked, you can enter a shell command line
+to execute. The command is passed straight to the default shell (defined
+by the <envar>SHELL</envar> environment variable), and may include
+whatever options, parameters, piped commands, etc. are permitted by
+the shell in a single line command.</para>
+
+<para>If this option is checked, you can enter the text of a script to
+execute. Remember to include a first line such as
+<literal>#!/bin/bash</literal> to ensure that the correct command
+interpreter is invoked.</para>
+</listitem>
+
+<listitem>
+<para>Use the <guilabel>Command Output</guilabel> group box to specify
+what you want to be done with any terminal output which the command
+produces when it executes.</para>
+
+<itemizedlist>
+<listitem>
+<para>Check <guilabel>Execute in terminal window</guilabel> to cause
+the command to be executed in a terminal window. You can choose
+which type of terminal window should be used in the
+<link linkend="preferences-general">Preferences dialog</link>.</para>
+</listitem>
+
+<listitem>
+<para>Check <guilabel>Log to file</guilabel> to save the command's
+output in a file. The output, prefixed by a heading showing the time
+at which the command was scheduled to run, will be appended to any
+existing contents of the file. Enter the file name in the edit box, or
+use the button beside the edit box to display a file selection
+dialog.</para>
+</listitem>
+
+<listitem>
+<para>Check <guilabel>Discard</guilabel> to throw away the command's
+output.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para><guilabel>Email</guilabel> to enter an email message to send.
+Fill in the recipients' addresses, the email subject line and the
+message body in the three edit fields. Use the button beside the
+addressee edit box to display your &kde; address book from which you
+can select email recipients. Attachments may be added using the
+<guibutton>Add...</guibutton> button. Note that attached files must
+still exist when the alarm is triggered; no copy is stored at the time
+the alarm is configured. To remove an attachment, highlight it in the
+drop-down list and click the <guibutton>Remove</guibutton>
+button.</para>
+
+<para>Set the following options:</para>
+
+<itemizedlist>
+<listitem>
+<para>The <guilabel>From</guilabel> combo box allows you to select
+which &kmail; identity to use as your email address for sending the
+email. This option only appears if your <guilabel>From</guilabel>
+email address in the
+<link linkend="preferences-email">Preferences dialog</link> is set to
+<guilabel>Use &kmail; identities</guilabel>. Otherwise your email
+address is preset in the
+<link linkend="preferences-email">Preferences dialog</link>, rendering
+this option inapplicable.</para>
+</listitem>
+
+<listitem>
+<para>Check <guilabel>Copy email to self</guilabel> to send a blind
+copy of the email to yourself when the alarm is triggered. The email
+address to which the copy will be sent may be set in the
+<link linkend="preferences-email">Preferences dialog</link>, the
+default being your email address set in the &kde; Control
+Center.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Deferral</title>
+
+<para>If the alarm is a recurring alarm and it was deferred after it
+was last displayed, the <guilabel>Deferred Alarm</guilabel> group box
+shows the time the alarm was deferred to.
+<guibutton>Change...</guibutton> displays a dialog which allows you to
+change the deferred time or to cancel the deferral.</para>
+
+</sect2>
+
+<sect2>
+<title>Time</title>
+
+<para>In the <guilabel>Time</guilabel> group box, select either</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>At date/time</guilabel> to enter the date and time
+when the alarm is to be triggered. Check <guilabel>Any time</guilabel>
+if you want to specify only a date for the alarm: in this case the
+alarm will be displayed at the first opportunity on or after the
+configured start-of-day time, on the specified date.
+(<link linkend="preferences-general">Configuring &kalarm;</link>
+describes how to set the start-of-day time.)</para>
+
+<para>For a non-recurring alarm, the date/time which you enter must be
+in the future, or if you enter only a date it must be today or later.
+For a recurring alarm, there are no such restrictions since the start
+date/time will be automatically adjusted to the first recurrence due
+after the current time.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Time from now</guilabel> to enter how long after now
+(in hours and minutes) the alarm should be triggered.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Reminder</title>
+
+<para>For a display alarm, check <guilabel>Reminder</guilabel> if you
+want to display a reminder in advance of the main alarm and of each of
+its recurrences (if any). Enter how long in advance using the edit
+controls beside the checkbox.</para>
+
+<note><para>Reminders are not displayed for sub-repetitions within a
+recurrence. Reminders are only shown before each main
+recurrence of the alarm.</para></note>
+
+<para>If the alarm recurs, check <guilabel>Reminder for first
+recurrence only</guilabel> if you only want a reminder before the
+alarm's first recurrence. If this is not checked, the reminder period
+is limited to being less than the recurrence interval.</para>
+
+</sect2>
+
+<sect2>
+<title>Cancelation</title>
+
+<para>The late-cancelation options determine how an alarm is treated
+after its scheduled time:</para>
+
+<itemizedlist>
+<listitem>
+<para>The <guilabel>Cancel if late</guilabel> checkbox determines what
+happens if the alarm cannot be triggered at its scheduled time.</para>
+
+<para>Check this box to cancel the alarm if it cannot be triggered
+within a specified time period after the right time. The time period
+is selected using controls which appear when you check the box. For
+example, if you enter a time period of 1 hour, the alarm will be
+triggered at the first opportunity up to an hour after it is due, but
+if it cannot be triggered within an hour its activation will be
+canceled.</para>
+
+<note><para>The lateness of date-only alarms, &ie; ones for which the
+<guilabel>Any time</guilabel> option is selected, is calculated from
+the start-of-day time on the alarm's scheduled date.</para></note>
+
+<para>Leave the box unchecked to trigger the alarm at the first
+opportunity starting at the scheduled time, regardless of how late it
+is.</para>
+
+<note><para>An alarm can only be triggered while you are logged in,
+and while both X and the <application>alarm daemon</application> are
+running.</para></note>
+</listitem>
+
+<listitem>
+<para>Check <guilabel>Auto-close window after this time</guilabel> if
+you want the alarm window to be automatically closed if it is still
+showing at the expiry of the late-cancelation time.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Recurrence</title>
+
+<para>Specify whether or how the alarm should be repeated using the
+<guilabel>Recurrence</guilabel> tab.</para>
+
+<note><para>The alarm's basic repetition characteristics are displayed
+for convenience in the title of the <guilabel>Recurrence</guilabel>
+tab. The recurrence interval is shown first, followed by any
+sub-repetition interval set up using the
+<guibutton>Sub-Repetition</guibutton> button.</para></note>
+
+<para>In the <guilabel>Recurrence Rule</guilabel> group box, set the
+recurrence type or time period as follows:</para>
+
+<itemizedlist>
+<listitem><para>To trigger the alarm once only, select <guilabel>No
+recurrence</guilabel>.</para></listitem>
+
+<listitem><para>Select <guilabel>At login</guilabel> to trigger the
+alarm whenever you log in, until its scheduled end time. Then, at its
+scheduled end time it will finally be triggered one last time. (Note
+that an alarm repeated at login will also be triggered any time you
+enable alarms, or restart or reset the <application>alarm
+daemon</application>.)</para></listitem>
+
+<listitem>
+<para>To make the alarm recur at regular intervals, select one of the
+time period types and then enter in the
+<guilabel>Recur every</guilabel> box how many time periods should
+elapse between recurrences. For example, to repeat
+every fortnight, you could select <guilabel>Daily</guilabel> and enter
+a value of 14, or select <guilabel>Weekly</guilabel> and enter a value
+of 2. Depending on the time period type selected, you may have further
+options:</para>
+
+<itemizedlist>
+<listitem>
+<para>For a weekly recurrence, check each day in the week on which you
+wish to trigger the alarm.</para>
+</listitem>
+
+<listitem>
+<para>For a monthly recurrence, you may select either a fixed date, or
+a position (&eg; the second Tuesday).</para>
+</listitem>
+
+<listitem>
+<para>For a yearly recurrence, you may select either a fixed day in
+the month, or a position in a month (&eg; the last Saturday in
+May). Check each month of the year in which you wish to trigger the
+alarm.</para>
+</listitem>
+</itemizedlist>
+
+<tip><para>To set a daily alarm to occur only on weekdays, use a
+weekly recurrence and check each weekday.</para></tip>
+
+</listitem>
+</itemizedlist>
+
+<para>In the <guilabel>Recurrence End</guilabel> group box, set the
+overall recurrence time span as follows:</para>
+
+<itemizedlist>
+<listitem><para>Select <guilabel>No end</guilabel> to continue the
+repetitions indefinitely.</para></listitem>
+
+<listitem><para>Select <guilabel>End after</guilabel> to specify the
+total number of occurrences of the alarm.</para></listitem>
+
+<listitem><para>Select <guilabel>End by</guilabel> to specify the
+date/time until which the alarm will be repeated.</para></listitem>
+</itemizedlist>
+
+<para>If you wish to exclude certain date/times from the recurrence
+which you have set up, specify them in the
+<guilabel>Exceptions</guilabel> group box. The list of exceptions
+(&ie; excluded date/times) is shown on the left. To add a new
+exception, enter a date on the right and press
+<guibutton>Add</guibutton>. To change an exception, highlight it in
+the list, enter the new date on the right and press
+<guibutton>Change</guibutton>. To delete an exception, highlight it
+in the list and press <guibutton>Delete</guibutton>.</para>
+
+<sect3>
+<title>Sub-Repetition</title>
+
+<para>You can use the <guibutton>Sub-Repetition</guibutton> button to
+set up a repetition within a repetition. In this case, each time the
+alarm is due as specified in the main recurrence, instead of being
+triggered just once it is triggered repeatedly in accordance with your
+sub-repetition specification. For example, to set up an alarm which
+repeats every hour from noon to 6 pm each Thursday, you would set up a
+weekly recurrence on Thursday at 12:00, and use the Sub-Repetition
+dialog to specify an interval of 1 hour and either a count of 6 or a
+duration of 6 hours.</para>
+
+<para>In the Sub-Repetition dialog which is displayed when you click
+the <guibutton>Sub-Repetition</guibutton> button, check
+<guilabel>Repeat every</guilabel> to set up a repetition, or uncheck
+it to remove the repetition. If <guilabel>Repeat every</guilabel> is
+checked, set up the repetition as follows:</para>
+
+<itemizedlist>
+<listitem><para>Enter the time interval between repetitions in the
+controls beside <guilabel>Repeat every</guilabel>. Select the desired
+time units (&eg; <guilabel>days</guilabel>) and then enter the number
+of units.</para>
+</listitem>
+
+<listitem><para>Specify either the repetition count or its
+duration:</para>
+
+<itemizedlist>
+<listitem><para>Select <guilabel>Number of times</guilabel> to enter
+how many times the alarm should be triggered after the main
+recurrence. So, for example, to make the alarm occur 4 times at each
+main recurrence, &ie; 3 additional times, you should enter 3
+here.</para>
+</listitem>
+
+<listitem><para>Select <guilabel>Duration</guilabel> to enter the
+total time period during which the alarm should be repeated. This need
+not be an exact multiple of the repetition interval; it will
+automatically be rounded down when you click
+<guibutton>OK</guibutton>.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+
+<note><para>To prevent overlapping sub-repetitions for the same alarm,
+a sub-repetition's duration is restricted to be less than the longest
+interval between main recurrences. Each time the alarm recurs as
+specified in the main recurrence, any still active sub-repetition
+which started at the previous recurrence is automatically
+cancelled.</para></note>
+
+</sect3>
+</sect2>
+
+<sect2>
+<title>Other controls</title>
+
+<para>For display alarms, the
+<guilabel>Confirm acknowledgment</guilabel> checkbox lets you specify
+whether you will be prompted for confirmation when you close the alarm
+message window. This may be used as a safeguard against accidental
+acknowledgment of alarms.</para>
+
+<para>Select <guilabel>Show in &korganizer;</guilabel> to add the
+alarm to &korganizer;'s active calendar, where it will appear as an
+event without an alarm. This option allows you to track alarms in
+&korganizer; while still making use of &kalarm;'s functions.</para>
+
+<note><para>If you later modify or delete the alarm in &kalarm;, the
+&korganizer; event will be modified or deleted correspondingly. But
+if you change the event in &korganizer;, the alarm in &kalarm; will
+not be affected.</para></note>
+
+<para>Press the <guibutton>Load Template</guibutton> button to select
+a template to preset the dialog with, as described in <link
+linkend="create-edit">Creating and manipulating alarms</link>. </para>
+
+<para>Press the <guibutton>Try</guibutton> button to test the alarm
+and check whether it works correctly. The alarm is executed just as
+if it had been scheduled in the normal way.</para>
+
+<para>Press the <guibutton>OK</guibutton> button
+when all details are correct, to add the alarm to the scheduled
+list.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="message-window">
+<title>Alarm message window</title>
+
+<para>When an alarm message is due, it is displayed on each &kde;
+desktop and cannot be covered by ordinary windows, to ensure that
+you see it. The message window shows the time for which the alarm was
+scheduled, so that you can see when it popped up if you were away from
+the computer at the time. (For reminder messages, however, the
+date/time shown is that for the main alarm or its recurrence, not the
+reminder message time, and the window title is
+<quote>Reminder</quote>).</para>
+
+<para>Alarm message windows remain visible until you acknowledge them,
+unless <guilabel>Auto-close window after late-cancelation
+time</guilabel> was checked in the <link
+linkend="alarm-edit-dlg">Alarm Edit dialog</link>. In the case of a
+recurring alarm, if an unacknowledged message window remains from a
+previous occurrence of the alarm, the existing window is simply popped
+up when the alarm recurs. This avoids having to acknowledge multiple
+copies of the same message should you not wish, or be unable, to
+acknowledge a message at the time it appears.</para>
+
+<para>The alarm message window provides whichever of the following
+options are applicable to the displayed alarm:</para>
+
+<itemizedlist>
+<listitem>
+<para>Acknowledge the alarm by clicking the
+<guibutton>Close</guibutton> button. This closes the window (after a
+prompt for confirmation, if you selected
+<guilabel>Confirm acknowledgment</guilabel>).</para>
+</listitem>
+
+<listitem>
+<para>Edit the alarm by clicking the <guibutton>Edit...</guibutton>
+button. This displays the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link>.</para>
+</listitem>
+
+<listitem>
+<para>Display options to defer the alarm until later by clicking the
+<guibutton>Defer...</guibutton> button. Then select
+<guilabel>Defer to date/time</guilabel> to enter the date and time
+when the message is to be redisplayed, or select <guilabel>Defer for
+time interval</guilabel> to enter how long after now (in hours and
+minutes) the message should be redisplayed. Then click
+<guibutton>Defer</guibutton> to defer the alarm message and close its
+window.</para>
+
+<note><para>The time the alarm is deferred to must be earlier than its
+next scheduled occurrence or next reminder. For this reason, the
+<guibutton>Defer...</guibutton> button in the alarm message window and
+the <guibutton>OK</guibutton> button in the deferral dialog are
+disabled one minute before the next occurrence or
+reminder.</para></note>
+
+<note><para>The <guibutton>Defer...</guibutton> button is not
+available for alarms which are displayed at login due to the
+<guilabel>Repeat at login</guilabel> option having been
+selected.</para></note>
+</listitem>
+
+<listitem>
+<para>Stop playing the alarm's sound file by clicking the button
+showing the <quote>stop playing</quote> symbol.</para>
+</listitem>
+
+<listitem>
+<para>If the alarm message was created by dragging an email from
+&kmail;, you can directly access the email in &kmail; by clicking the
+button showing the &kmail; icon. This will select and highlight the
+email in &kmail;'s folder list.</para>
+
+<warning><para>If &kmail;'s indexes are regenerated, the link to the
+email in &kmail; will be lost.</para></warning>
+</listitem>
+
+<listitem>
+<para>The button showing the <guiicon>&kalarm;</guiicon> icon provides
+a convenient way to activate &kalarm;.</para>
+</listitem>
+</itemizedlist>
+
+<para>The alarm message window may be displayed in two different
+modes, depending on your preferences. You can choose the mode in the
+<link linkend="preferences-view">Preferences dialog</link>.</para>
+
+<itemizedlist>
+<listitem>
+<para>As a normal window. In this mode, the keyboard focus is taken
+by the alarm message window when it appears, so if you are typing at
+the time your keystrokes will be diverted to it rather than your
+original application.</para>
+</listitem>
+
+<listitem>
+<para>As a non-modal window. In this mode, the keyboard focus is
+unaffected when the alarm message window appears, so it will not
+interfere with your typing. However in this mode the window has no
+titlebar or frame, so you cannot move it or resize it.</para>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="system-tray">
+<title>System tray operation</title>
+
+<para>&kalarm; may be run as an icon in the system tray. This
+icon allows one-click activation of &kalarm;, and provides both
+control and status indication of alarm monitoring. A normal &kalarm;
+icon indicates that alarms are being monitored, while a gray icon
+indicates that alarms are not being monitored.</para>
+
+<para>If you hover the mouse cursor over the system tray icon, a
+summary of the first few message alarms due in the next 24 hours are
+displayed as a tooltip. You can switch this feature off, or configure
+the number of alarms to display and their format, in the
+<link linkend="preferences-view">Preferences dialog</link>.</para>
+
+<para><mousebutton>Left</mousebutton> click on the system tray icon to
+toggle between displaying and hiding the &kalarm; main window.</para>
+
+<para><mousebutton>Right</mousebutton> click on the system tray icon to
+display its context menu:</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice></term>
+<listitem><para><action>Enables monitoring of alarms. This option
+only appears if alarms are currently disabled.</action></para>
+<para>See
+<link linkend="enable-disable">Enabling and disabling alarms</link>
+for details.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>Disable Alarms</guimenuitem></menuchoice></term>
+<listitem><para><action>Disables monitoring of alarms. This option
+only appears if alarms are currently enabled.</action></para>
+<para>See
+<link linkend="enable-disable">Enabling and disabling alarms</link>
+for details.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>New Alarm...</guimenuitem></menuchoice></term>
+<listitem><para><action>Opens the alarm edit dialog to create a new
+alarm.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>New Alarm From Template</guimenuitem></menuchoice></term>
+<listitem><para><action>Displays the list of alarm templates in a
+menu. When you select one, the alarm edit dialog is opened, preset
+with that template's details.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>Configure &kalarm;...</guimenuitem></menuchoice></term>
+<listitem><para><action>Displays the &kalarm; preferences dialog.</action></para>
+<para>The preferences dialog is described in
+<link linkend="preferences">Configuring &kalarm;</link>. It
+includes options relating to the &kalarm; system tray icon.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>Restore / Minimize</guimenuitem></menuchoice></term>
+<listitem><para><action>Restores or minimizes the main &kalarm; window.</action></para>
+<para>This option is only available if the run mode is
+<quote>continuous</quote>. (See
+<link linkend="preferences-general">Configuring &kalarm;</link> for a
+description of run modes.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>Quit</guimenuitem></menuchoice></term>
+<listitem><para><action>Closes the &kalarm; system tray
+icon.</action></para>
+<para>In <quote>continuous</quote> run mode
+only, it also closes all &kalarm; main windows. It has no effect on
+the monitoring of alarms by the <application>alarm
+daemon</application>, if you have deselected <guilabel>Disable alarms
+while not running</guilabel> in the Preferences dialog.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<sect2>
+<title>Displaying &kalarm; in the system tray</title>
+
+<para>You must be running the &kde; desktop or another suitable window
+manager in order to display &kalarm; in the system tray. If &kalarm;
+is running in <quote>continuous</quote> mode, the system tray icon is
+always displayed. These instructions apply only to
+<quote>on-demand</quote> mode. (See
+<link linkend="preferences-general">Configuring &kalarm;</link> for a
+description of run modes.)</para>
+
+<para>To display &kalarm; in the system tray, select <menuchoice>
+<guimenu>View</guimenu><guimenuitem>Show in System Tray</guimenuitem>
+</menuchoice>.</para>
+
+<para>To remove &kalarm; from the system tray, do one of the
+following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select <menuchoice><guimenu>View</guimenu>
+<guimenuitem>Hide from System Tray</guimenuitem></menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the system tray icon
+and choose <menuchoice><guimenuitem>Quit</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+</sect1>
+
+<sect1 id="refreshing">
+<title>Refreshing alarms</title>
+
+<para>If in the unlikely event that any alarm was not triggered when
+it should have been, you can refresh the alarm list and trigger any
+missed alarms by selecting
+<menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Refresh Alarms</guimenuitem>
+</menuchoice>.</para>
+
+<para>&kalarm; retriggers missed alarms by resetting the
+<application>alarm daemon</application>, which is discussed in the
+<link linkend="daemon-reset">Alarm daemon</link> section.</para>
+
+</sect1>
+
+<sect1 id="enable-disable">
+<title>Enabling and disabling alarms</title>
+
+<para>Alarms may be enabled and disabled either as a whole or
+individually:</para>
+
+<itemizedlist>
+<listitem>
+<para><quote>Alarm monitoring</quote> applies to alarms as a whole.
+When alarm monitoring is disabled, the <application>alarm
+daemon</application> ceases to check alarms and therefore no alarms
+will trigger at all. When alarm monitoring is enabled (the normal
+situation), all alarms which are not individually disabled will
+trigger at the appropriate times.</para>
+</listitem>
+
+<listitem>
+<para>Alarms may be individually enabled and disabled, independently
+of the alarm monitoring status. So the enabled/disabled status of
+individual alarms will be unchanged by disabling and then re-enabling
+alarm monitoring. Unlike alarm monitoring which could potentially be
+disabled due to &kalarm; not running or the
+<application>alarm daemon</application> not functioning, individual
+alarms can only be disabled if you use menu commands to do so.</para>
+
+<para>An alarm's individual enabled/disabled status is indicated by
+its color in the alarm list (the color being configurable in the
+<link linkend="preferences-fontcolour">Font &amp; Color</link> tab of
+the Preferences dialog).</para>
+</listitem>
+</itemizedlist>
+
+<para>For an alarm to trigger, it must be individually enabled as well
+as alarm monitoring being enabled.</para>
+
+<sect2>
+<title>Enabling alarm monitoring</title>
+
+<para>If &kalarm;'s run mode is <quote>continuous</quote> and you
+have selected <guilabel>Disable alarms while not running</guilabel>
+in the Preferences dialog, you must first ensure that &kalarm; is
+running in order for alarm monitoring to take place.</para>
+
+<para>Then if alarm monitoring is currently disabled, do one of the
+following to enable alarms:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select <menuchoice><guimenu>Actions</guimenu>
+<guimenuitem>Enable Alarms</guimenuitem></menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the system tray icon
+and choose
+<menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+<para>The <application>alarm daemon</application> is started if
+necessary and alarms will be monitored for when they become
+due.</para>
+
+</sect2>
+
+<sect2>
+<title>Disabling alarm monitoring</title>
+
+<para>There are several ways to disable alarm monitoring, which
+prevents &kalarm; from displaying any further alarms either until you
+re-enable alarms, or &ndash; assuming that the <application>alarm
+daemon</application> is configured to start at login &ndash; until the
+next time you log in.</para>
+
+<para>To disable alarms without stopping the <application>alarm
+daemon</application>, do one of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select <menuchoice><guimenu>Actions</guimenu>
+<guimenuitem>Disable Alarms</guimenuitem></menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the system tray icon
+and choose
+<menuchoice><guimenuitem>Disable Alarms</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+
+<listitem>
+<para>If &kalarm;'s run mode is <quote>continuous</quote> and you have
+selected <guilabel>Disable alarms while not running</guilabel> in the
+Preferences dialog, quit &kalarm;.</para>
+</listitem>
+</itemizedlist>
+
+<para>To disable alarms by stopping the <application>alarm
+daemon</application>:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Control Alarm Daemon...</guimenuitem></menuchoice>. This
+displays the Service Manager dialog which enables you to stop the
+<application>alarm daemon</application>.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Enabling and disabling individual alarms</title>
+
+<para>To enable individual alarms which are currently disabled, do
+one of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select one or more alarms by clicking on their entries in the
+alarm list. Then choose <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Enable</guimenuitem>
+</menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the desired entries in
+the alarm list and choose
+<menuchoice><guimenuitem>Enable</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+<para>To disable individual alarms which are currently enabled, do one
+of the following:</para>
+
+<itemizedlist>
+<listitem>
+<para>Select one or more alarms by clicking on their entries in the
+alarm list. Then choose <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Disable</guimenuitem>
+</menuchoice>.</para>
+</listitem>
+
+<listitem>
+<para><mousebutton>Right</mousebutton> click on the desired entries in
+the alarm list and choose
+<menuchoice><guimenuitem>Disable</guimenuitem></menuchoice>
+from the context menu.</para>
+</listitem>
+</itemizedlist>
+
+</sect2>
+</sect1>
+
+<sect1 id="quitting">
+<title>Quitting the program</title>
+
+<para>Quit &kalarm; by closing all its windows and the system tray
+icon, or if it is running in <quote>continuous</quote> mode, by
+closing any message windows and selecting <menuchoice>
+<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>,
+or <menuchoice><guimenuitem>Quit</guimenuitem></menuchoice> in the
+system tray icon context menu.</para>
+
+<para>The effect of <menuchoice><guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem></menuchoice> or of the system tray
+icon context menu item
+<menuchoice><guimenuitem>Quit</guimenuitem></menuchoice> depends on
+the run mode: in <quote>on-demand</quote> mode it hides the system
+tray icon, while in <quote>continuous</quote> mode it
+quits the program.</para>
+
+<tip><para>If you have deselected <guilabel>Disable alarms while not
+running</guilabel> in the Preferences dialog, quitting &kalarm; has no
+effect on the <application>alarm daemon</application> which if
+already active will continue to monitor scheduled alarms and request
+their display when they become due.</para></tip>
+
+</sect1>
+</chapter>
+
+<chapter id="preferences">
+<title>Configuring &kalarm;</title>
+
+<para>To configure &kalarm;'s operation to suit your system and your
+personal preferences, select <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kalarm;...</guimenuitem></menuchoice>.
+This displays the configuration dialog.</para>
+
+<sect1 id="preferences-general">
+<title>General</title>
+
+<para>The <guilabel>General</guilabel> section lets you control
+&kalarm;'s overall behavior:</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Run Mode</guilabel> group box: These options
+control &kalarm;'s system tray icon, and also allow some control over
+&kalarm;'s use of system resources by specifying whether or not to run
+it continuously. If system performance is of concern, running it on
+demand without displaying the system tray icon may be desirable;
+running it continuously in the system tray uses more system resources
+but gives the benefits of displaying an alarm-enabled indication and
+making the application more accessible. Running &kalarm; on demand
+does not affect the execution of alarms, since it is the
+<application>alarm daemon</application> and not &kalarm; which
+monitors the alarm list and triggers alarms.</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Run only on demand</guilabel>: &kalarm;
+is run only when an alarm is triggered, if you run it manually, or
+while its system tray icon is displayed. In this mode the system tray
+icon can still be displayed, but closing the system tray icon has no
+effect on any &kalarm; windows.</para>
+</listitem>
+
+<listitem><para><guilabel>Run continuously in system tray</guilabel>:
+&kalarm; runs continuously and the system tray icon is always
+displayed while it is running. In this mode, closing the system tray
+icon closes all &kalarm; main windows, and if no message windows are
+visible, quits the application. The options available in this mode
+are:</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Disable alarms while not running</guilabel>:
+Selecting this option has the effect that alarms will be disabled
+whenever &kalarm;'s system tray icon is not visible.</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Warn before quitting</guilabel>: When alarms
+are disabled while &kalarm; is not running, selecting this option
+prompts you for confirmation if you attempt to terminate &kalarm; using
+the system tray icon's <menuchoice><guimenu>Quit</guimenu></menuchoice>
+option. This prevents accidental disabling of alarms. For safety, this
+option is automatically re-enabled by default whenever you change run
+mode.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+
+<!--
+<para>In this mode, if no system tray exists, &kalarm; runs
+continuously in the background and alarms are always enabled.</para>
+-->
+</listitem>
+
+<listitem><para><guilabel>Autostart at login</guilabel>: In continuous
+mode, this starts &kalarm; at &kde; session login, ensuring that
+&kalarm; runs at all times unless you manually quit.</para>
+</listitem>
+
+<listitem><para><guilabel>Autostart system tray icon at
+login</guilabel>: In on-demand mode, this displays &kalarm;'s system
+tray icon at login. &kalarm; will run until the system tray icon is
+closed.</para>
+</listitem>
+
+<listitem><para><guilabel>Start alarm monitoring at login</guilabel>:
+This starts alarm monitoring at KDE session login, by starting the
+<application>alarm daemon</application>. Note that in order for alarms
+to be activated, you also need to select appropriate options in the
+<guilabel>Run Mode</guilabel> group box.</para>
+
+<warning><para>This option should always be checked unless you intend
+to discontinue use of &kalarm;.</para></warning>
+
+<note><para>This option is automatically reselected whenever &kalarm;
+is run. So if you have unchecked this option and want to continue to
+prevent the <application>alarm daemon</application> from running at
+login, you need to uncheck this option again each time you run
+&kalarm;.</para></note>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para><guilabel>Start of day for date-only
+alarms</guilabel>: Set the start-of-day time for the purposes of
+triggering date-only alarms, &ie; ones for which the <guilabel>Any
+time</guilabel> option was selected. On the date when they are due,
+such alarms will be output at the earliest opportunity during the
+24 hours starting from the start-of-day time.</para>
+</listitem>
+
+<listitem><para>If you set up yearly recurrences for February 29th,
+specify how these are to be handled in non-leap years by selecting one
+of the following options:</para>
+
+<itemizedlist>
+<listitem><para><guilabel>February 28th</guilabel>: the alarm will
+occur on February 29th in leap years, and on February 28th in
+non-leap years.</para>
+</listitem>
+
+<listitem><para><guilabel>March 1st</guilabel>: the alarm will
+occur on February 29th in leap years, and on March 1st in
+non-leap years.</para>
+</listitem>
+
+<listitem><para><guilabel>Do not repeat</guilabel>: the alarm will
+occur on February 29th in leap years, but will be suppressed in
+non-leap years.</para>
+</listitem>
+</itemizedlist>
+
+<note><para>Changing this option will not cause the next scheduled
+recurrence of any existing alarms to be re-evaluated. It will only
+affect new alarms, or existing alarms after they are next
+triggered.</para></note>
+</listitem>
+
+<listitem><para><guilabel>Confirm alarm deletions</guilabel>: Specify
+whether you should be prompted for confirmation each time you delete
+an alarm.</para>
+</listitem>
+
+<listitem><para><guilabel>Expired Alarms</guilabel> group box: These
+options control the storage of expired alarms.</para>
+<itemizedlist>
+<listitem><para><guilabel>Keep alarms after expiry</guilabel>:
+Select this option to store expired and deleted alarms. Deselect it
+to keep no record of alarms once they cease to be active. Note that
+deleted alarms are only stored if they have previously been
+triggered. If you delete an alarm before it ever triggers, it is
+discarded.</para>
+</listitem>
+
+<listitem><para><guilabel>Discard expired alarms after</guilabel>:
+Set the number of days to store expired and deleted alarms, after which
+they are permanently deleted.</para>
+</listitem>
+
+<listitem><para><guibutton>Clear expired alarms</guibutton>: This
+button discards all currently stored expired alarms. This has no
+effect on alarms which subsequently expire; they will continue to be
+stored according to the selected options.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para><guilabel>Terminal for Command Alarms</guilabel>:
+Here, you can select which type of terminal window should be used for
+command alarms which are executed in a terminal window. Some of the
+most common terminal window applications are preconfigured, &eg;
+<application>xterm</application>, &konsole;, although only those
+which are installed on your system will be shown here. You can view
+the actual command options used for each application by displaying the
+context help for its radio button.</para>
+
+<para>If you want to use another application, or want to use one of
+those listed but with different command options, select
+<guilabel>Other</guilabel> and enter the command to invoke the
+terminal window. By default, the alarm's command string will be
+appended to what you specify. Alternatively, you may specify where the
+alarm's command string should be inserted, by use of the following
+codes:</para>
+
+<variablelist>
+<varlistentry>
+<term>%c</term>
+<listitem>
+<para>The alarm's command string will be substituted.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>%w</term>
+<listitem>
+<para>The alarm's command string will be substituted, with a <literal>sleep</literal> appended.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>%C</term>
+<listitem>
+<para>A temporary command file containing the alarm's command string will be created, and the command to execute the file will be substituted.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>%W</term>
+<listitem>
+<para>A temporary command file containing the alarm's command string will be created with a <literal>sleep</literal> appended, and the command to execute the file will be substituted.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>When the command alarm is triggered, its command string will be
+quoted before being inserted into the terminal window command.</para>
+</listitem>
+
+</itemizedlist>
+</sect1>
+
+<sect1 id="preferences-email">
+<title>Email</title>
+
+<para>The <guilabel>Email</guilabel> section lets you choose options
+for sending and addressing email alarms:</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>Email client</guilabel>: Specify the email
+client to be used to send email alarms:</para>
+
+<itemizedlist>
+<listitem><para><guilabel>KMail</guilabel>: When an email alarm is
+triggered, the email is sent using &kmail; (which is started first if
+necessary) as follows:</para>
+
+<itemizedlist>
+<listitem><para>If &kmail; is version 1.7 or later, the email is sent
+automatically.</para>
+</listitem>
+
+<listitem><para>If &kmail; is an older version, the email is added to
+&kmail;'s <filename>outbox</filename> folder for later
+transmission.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para><guilabel>Sendmail</guilabel>: When an email alarm is
+triggered, the email is sent automatically using
+<application>sendmail</application>. This option will only work if
+your system is configured to use <application>sendmail</application>,
+or a <application>sendmail</application> compatible mail transport
+agent such as <application>postfix</application> or
+<application>qmail</application>.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para><guilabel>Copy sent emails into &kmail;'s sent-items folder</guilabel>:
+Select this option if, every time an email alarm is triggered, you
+want a copy of the transmitted email to be stored in &kmail;'s
+<filename>sent-items</filename> folder.</para>
+
+<note><para>This option is not available when &kmail; is selected as
+the email client, since &kmail; automatically does this.</para></note>
+</listitem>
+
+<listitem>
+<para>Select your email address to be used as the sender's address in
+email alarms:</para>
+
+<itemizedlist>
+<listitem><para>Select <guilabel>From</guilabel> to enter an email
+address.</para>
+</listitem>
+
+<listitem><para>Select <guilabel>Use address from Control
+Center</guilabel> to use the email address which is configured in the
+&kde; Control Center.</para>
+</listitem>
+
+<listitem><para>Select <guilabel>Use &kmail; identities</guilabel> to
+be able to choose at the time you configure an email alarm which of
+&kmail;'s email identities to use. &kmail;'s default identity will be
+used for alarms which were already configured before you selected this
+option.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para>Select your email address to be used for sending blind copies of
+email alarms to yourself when the
+<guilabel>Copy email to self</guilabel> option is selected:</para>
+
+<itemizedlist>
+<listitem><para>Select <guilabel>Bcc</guilabel> to enter an email
+address. If blind copies are to be sent to your account on the
+computer which &kalarm; runs on, you could simply enter your user
+login name here.</para>
+</listitem>
+
+<listitem><para>Select <guilabel>Use address from Control
+Center</guilabel> to use the email address which is configured in the
+&kde; Control Center.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem>
+<para><guilabel>Notify when remote emails are queued</guilabel>:
+Select this option to display a notification whenever an email alarm
+queues an email for sending to a remote system. This may be useful
+if, for example, you have a dial-up connection, or email is queued in
+&kmail;'s <filename>outbox</filename> folder, so that you can
+ensure that you do whatever is needed to actually transmit
+the email.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="preferences-view">
+<title>View</title>
+
+<para>The <guilabel>View</guilabel> section lets you control some
+aspects of &kalarm;'s appearance:</para>
+<itemizedlist>
+
+<listitem>
+<para><guilabel>System Tray Tooltip</guilabel> group box: These options
+control what information is shown in the tooltip which appears when the
+mouse cursor hovers over &kalarm;'s system tray icon.</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>Show next 24 hours' alarms</guilabel>: When selected,
+a summary of the first few alarms due in the next 24 hours is
+displayed.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Maximum number of alarms to show</guilabel>: Deselect
+this option to display all of the next 24 hours' alarms. Select it to
+set the maximum number of alarms which will be displayed.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Show alarm time</guilabel>: Select this option to show
+the time at which each alarm is scheduled.</para>
+</listitem>
+
+<listitem>
+<para><guilabel>Show time until alarm</guilabel>: Select this option to
+show the length of time remaining before each alarm's next scheduled
+occurrence. The length of time is shown in hours and minutes.</para>
+
+<itemizedlist>
+<listitem>
+<para><guilabel>Prefix</guilabel>: Specify a symbol or text to show in
+front of the length of time until the alarm, to distinguish it from the
+time at which the alarm is scheduled.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para><guilabel>Message windows have a title bar and take keyboard focus</guilabel>: This
+option controls whether alarm message windows are modal or not, &ie;
+whether they grab the keyboard focus when they appear. See the
+<link linkend="message-window">Alarm message window</link> section for
+details.</para>
+</listitem>
+
+<listitem><para><guilabel>System tray icon update interval</guilabel>: Set
+the frequency at which the &kalarm; system tray icon is updated to
+reflect whether alarms are currently being monitored. This involves
+checking whether the <application>alarm daemon</application> is
+running.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="preferences-fontcolour">
+<title>Font &amp; Color</title>
+
+<para>The <guilabel>Font &amp; Color</guilabel> section lets you set
+the default appearance of alarm messages, and the colors to be used
+in the alarm list:</para>
+<itemizedlist>
+
+<listitem><para>Select the default font and background color to use
+for alarm message display.</para>
+</listitem>
+
+<listitem><para>Edit the color selection list which is displayed when
+you click on the background color combo box:</para>
+<itemizedlist>
+
+<listitem><para><guilabel>Add color...</guilabel>: Displays a color
+selection dialog which lets you choose a color to add to the
+list.</para>
+</listitem>
+
+<listitem><para><guilabel>Remove color</guilabel>: Removes the color
+currently displayed in the <guilabel>Background color</guilabel>
+combo box from the list. The Custom color item cannot be removed from
+the list, and when it is displayed, this button is disabled.</para>
+</listitem>
+
+</itemizedlist>
+</listitem>
+
+<listitem><para>Select the color to be used in the alarm list to show
+disabled alarms.</para>
+</listitem>
+
+<listitem><para>Select the color to be used in the alarm list to show
+expired alarms.</para>
+</listitem>
+
+</itemizedlist>
+</sect1>
+
+<sect1 id="preferences-edit">
+<title>Edit</title>
+
+<para>The <guilabel>Edit</guilabel> section lets you choose
+default values for the options in the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link>:</para>
+
+<para>For display alarms:</para>
+
+<itemizedlist>
+<listitem><para>Set the default states for the <guilabel>Cancel if
+late</guilabel>, <guilabel>Auto-close window after this
+time</guilabel> and <guilabel>Confirm acknowledgment</guilabel>
+checkboxes.</para>
+</listitem>
+
+<listitem><para>Set the default reminder period units.</para>
+</listitem>
+
+<listitem><para>Set the default special display alarm actions.</para>
+</listitem>
+
+<listitem><para>Set the default sound options. Note that a default
+sound file may be specified even if the sound type is not set to
+<guilabel>Sound file</guilabel>.</para>
+</listitem>
+</itemizedlist>
+
+<para>For command alarms:</para>
+
+<itemizedlist>
+<listitem><para>Set the default states for the <guilabel>Enter a
+script</guilabel> and <guilabel>Execute in terminal window</guilabel>
+checkboxes.</para>
+</listitem>
+</itemizedlist>
+
+<para>For email alarms:</para>
+
+<itemizedlist>
+<listitem><para>Set the default state for the <guilabel>Copy email to
+self</guilabel> checkbox.</para>
+</listitem>
+</itemizedlist>
+
+<para>For all alarm types:</para>
+
+<itemizedlist>
+<listitem><para>Set the default recurrence type.</para>
+</listitem>
+</itemizedlist>
+</sect1>
+
+</chapter>
+
+<chapter id="cmdline-operation">
+<title>Command line operation</title>
+
+<para>When command line parameters are supplied, &kalarm; does not
+display the list of scheduled alarms as described in <link
+linkend="using-kalarm">Using &kalarm;</link> above. Command line
+options specific to &kalarm; may be used to perform the following
+operations:</para>
+
+<itemizedlist>
+<listitem><para>schedule a new alarm</para>
+</listitem>
+<listitem><para>control the <application>alarm daemon</application></para>
+</listitem>
+<listitem><para>control &kalarm;'s display mode</para>
+</listitem>
+<listitem><para>obtain help</para>
+</listitem>
+</itemizedlist>
+
+<para>Additional command line options are provided primarily to enable
+other programs to interface to &kalarm;. They are described in the
+chapter <link linkend="cmdline-interface">Developer's Guide to
+&kalarm;</link>.</para>
+
+<para>The command line must only contain options applicable to one
+&kalarm; operation. If you want to perform multiple operations, you
+must invoke &kalarm; multiple times with a single set of options each
+time.</para>
+
+<sect1 id="cmdline-schedule">
+<title>Schedule a new alarm</title>
+
+<para>The following options are used to schedule a new alarm:</para>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+  <entry>Option</entry>
+  <entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+  <entry><option>-a</option>, <option>--ack-confirm</option></entry>
+  <entry>Prompt for confirmation when the alarm message is
+  acknowledged.</entry>
+</row>
+<row>
+  <entry><option>-A</option>, <option>--attach <replaceable>URL</replaceable></option></entry>
+  <entry>Specify the path or &URL; of a file which is to be attached
+  to the email. This option may be repeated as necessary.
+  <option>--mail</option> must be specified with this option.</entry>
+</row>
+<row>
+  <entry><option>--auto-close</option></entry>
+  <entry>Automatically close the alarm window after the expiry of the
+  <option>--late-cancel</option> period.
+  <option>--late-cancel</option> must be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-b</option>, <option>--beep</option></entry>
+  <entry>Make an audible beep when the message is displayed.
+  <option>--speak</option>, <option>--play</option> and
+  <option>--play-repeat</option> cannot be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>--bcc</option></entry>
+  <entry>Blind copy the email to yourself.
+  <option>--mail</option> must be specified with this option.</entry>
+</row>
+<row>
+  <entry><option>-c</option>, <option>--color</option>, <option>--colour
+  <replaceable>color</replaceable></option></entry>
+  <entry>Set the message background color to the specified &Qt;
+  color name or hex code 0xRRGGBB.</entry>
+</row>
+<row>
+  <entry><option>-C</option>, <option>--colorfg</option>, <option>--colourfg
+  <replaceable>color</replaceable></option></entry>
+  <entry>Set the message foreground color to the specified &Qt;
+  color name or hex code 0xRRGGBB.</entry>
+</row>
+<row>
+  <entry><option>-d</option>, <option>--disable</option></entry>
+  <entry>Disable the alarm. It will not trigger until it has been
+  manually enabled.</entry>
+</row>
+<row>
+  <entry><option>-e</option>, <option>--exec <replaceable>commandline</replaceable></option></entry>
+  <entry>Specify a shell command to execute. If specified, this option
+  must be the last &kalarm; option in &kalarm;'s command line. All
+  subsequent command parameters and options  are interpreted as
+  forming the command line to execute. <option>--file</option> and
+  <option>--mail</option> cannot be specified with this option.
+  <option>--ack-confirm</option>, <option>--beep</option>,
+  <option>--color</option> and <option>--colorfg</option> are ignored
+  with this option.</entry>
+</row>
+<row>
+  <entry><option>-f</option>, <option>--file <replaceable>URL</replaceable></option></entry>
+  <entry>Specify the path or &URL; of a text or image file whose
+  contents are to form the alarm message. <option>--exec</option> and
+  <option>--mail</option> cannot be specified, and
+  <replaceable>message</replaceable> must not be present with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-F</option>, <option>--from-id
+  <replaceable>ID</replaceable></option></entry>
+  <entry>Use the specified &kmail; identity as the sender of the
+  email. <option>--mail</option> must be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-i</option>, <option>--interval
+  <replaceable>period</replaceable></option></entry>
+  <entry>Set the interval between repetitions of the alarm.
+  Hours/minutes are specified in the format
+  <replaceable>nHnM</replaceable>, where <replaceable>n</replaceable>
+  is a number, &eg; 3H30M. Other time periods are specified in the
+  format <replaceable>nX</replaceable>, where
+  <replaceable>n</replaceable> is a number and
+  <replaceable>X</replaceable> is one of the following letters: Y
+  (years), M (months), W (weeks), D (days). If
+  <option>--recurrence</option> is also specified, Y (years) and M
+  (months) are not allowed.
+  Mandatory if <option>--repeat</option> or <option>--until</option>
+  is specified.</entry>
+</row>
+<row>
+  <entry><option>-k</option>, <option>--korganizer</option></entry>
+  <entry>Show the alarm as an event in &korganizer;'s active
+  calendar.</entry>
+</row>
+<row>
+  <entry><option>-l</option>, <option>--late-cancel
+  <replaceable>period</replaceable></option></entry>
+  <entry>Cancel the alarm if it cannot be triggered within the
+  specified <replaceable>period</replaceable> after the correct
+  time. The <replaceable>period</replaceable> period is specified in
+  the same format as described for <option>--reminder</option>.
+  The default value of <replaceable>period</replaceable> is 1
+  minute.</entry>
+</row>
+<row>
+  <entry><option>-L</option>, <option>--login</option></entry>
+  <entry>Trigger the alarm every time you log in.
+  <option>--interval</option>, <option>--repeat</option> and
+  <option>--until</option> cannot be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-m</option>, <option>--mail
+  <replaceable>address</replaceable></option></entry>
+  <entry>Send an email to the specified address. This option may be
+  repeated as necessary.  <option>--exec</option> and
+  <option>--file</option> cannot be specified with this option.
+  <option>--ack-confirm</option>, <option>--beep</option>,
+  <option>--color</option> and <option>--colorfg</option> are ignored
+  with this option.</entry>
+</row>
+<row>
+  <entry><option>-p</option>, <option>--play <replaceable>URL</replaceable></option></entry>
+  <entry>Specify the path or &URL; of an audio file to be played once
+  when the alarm message is displayed. 
+  <option>--play-repeat</option>, <option>--beep</option> and
+  <option>--speak</option> cannot be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-P</option>, <option>--play-repeat <replaceable>URL</replaceable></option></entry>
+  <entry>Specify the path or &URL; of an audio file to be played
+  repeatedly for as long as the alarm message is displayed.
+  <option>--play</option>, <option>--beep</option> and
+  <option>--speak</option> cannot be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>--recurrence
+  <replaceable>spec</replaceable></option></entry>
+  <entry>Set the alarm to recur. Specify the recurrence using iCalendar
+  syntax (defined in
+  <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>),
+  &eg; <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>.
+  <option>--until</option> cannot be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-r</option>, <option>--repeat
+  <replaceable>count</replaceable></option></entry>
+  <entry>Set the number of times the alarm should be triggered, or if
+  a recurrence is specified with <option>--recurrence</option>, the
+  number of times the alarm should be triggered each time
+  <option>--recurrence</option> activates it (&ie; a repetition within
+  a recurrence). If <option>--recurrence</option> is not present,
+  specify -1 to repeat the alarm indefinitely.
+  <option>--interval</option> must be, and <option>--until</option>
+  cannot be, specified with this option.</entry>
+</row>
+<row>
+  <entry><option>-R</option>, <option>--reminder
+  <replaceable>period</replaceable></option></entry>
+  <entry>Output a reminder alarm the specified length of time before
+  the main alarm and each of its recurrences (if any). Hours/minutes are
+  specified in the format <replaceable>nHnM</replaceable>, where
+  <replaceable>n</replaceable> is a number, &eg; 3H30M. Other time
+  periods are specified in the format <replaceable>nX</replaceable>,
+  where <replaceable>n</replaceable> is a number and
+  <replaceable>X</replaceable> is one of the following letters: W
+  (weeks), D (days). This option cannot be specified with
+  <option>--exec</option>, <option>--mail</option> or
+  <option>--reminder-once</option>.</entry>
+</row>
+<row>
+  <entry><option>--reminder-once
+  <replaceable>period</replaceable></option></entry>
+  <entry>Output a reminder alarm once, the specified length of time
+  before the first recurrence of the alarm. No reminder will be 
+  displayed before subsequent recurrences (if any). This option cannot
+  be specified with <option>--exec</option>, <option>--mail</option>
+  or <option>--reminder</option>.</entry>
+</row>
+<row>
+  <entry><option>-s</option>, <option>--speak</option></entry>
+  <entry>Speak the message when it is displayed. This option requires
+  <application>KTTSD</application> to be installed and configured,
+  together with a compatible speech synthesizer.
+  <option>--beep</option>, <option>--play</option> and
+  <option>--play-repeat</option> cannot be specified with this
+  option.</entry>
+</row>
+<row>
+  <entry><option>-S</option>, <option>--subject
+  <replaceable>subject</replaceable></option></entry>
+  <entry>The subject line of the email. <option>--mail</option> must
+  be specified with this option.</entry>
+</row>
+<row>
+  <entry><option>-t</option>, <option>--time
+  <replaceable>date/time</replaceable></option></entry>
+  <entry>Trigger alarm on the date or at the date/time specified.
+  Specify a date without a time in the format
+  <replaceable>yyyy-mm-dd</replaceable>; specify a date and time by
+  <replaceable>[[[yyyy-]mm-]dd-]hh:mm</replaceable> (where omitted,
+  date fields default to the values for today).</entry>
+</row>
+<row>
+  <entry><option>-v</option>, <option>--volume
+  <replaceable>percentage</replaceable></option></entry>
+  <entry>Set the audio volume for playing the audio file. This option
+  can only be used when <option>--play</option> or
+  <option>--play-repeat</option> is specified.</entry>
+</row>
+<row>
+  <entry><option>-u</option>, <option>--until
+  <replaceable>date/time</replaceable></option></entry>
+  <entry>Repeat the alarm until the date or date/time specified.
+  Specify a date without a time in the same format as for
+  <option>--time</option>. <option>--interval</option> must be, and
+  <option>--repeat</option> and <option>--recurrence</option> cannot
+  be, specified with this option.</entry>
+</row>
+<row>
+  <entry><replaceable>message</replaceable></entry>
+  <entry>Message text to display or, if <option>--mail</option> is
+  specified, the body of the email message.</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>Either a message text, <option>--file</option> or
+<option>--exec</option> must be specified; except as noted above, all
+the options are optional.</para>
+
+<para>Two alternative examples which display a multi-line message with
+a red background at 10 p.m. on the 27th of this month are:</para>
+
+<informalexample><screen>
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>-c <replaceable>red</replaceable></option> <option>-t <replaceable>27-22:00</replaceable></option> <option><replaceable>"Remember to\nSTOP"</replaceable></option></userinput>
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>-c <replaceable>0xFF0000</replaceable></option> <option>-t <replaceable>27-22:00</replaceable></option> <option><replaceable>"Remember to\nSTOP"</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+</sect1>
+
+<sect1 id="cmdline-other">
+<title>Other options</title>
+
+<para>The following options are used to reset or halt the
+<application>alarm daemon</application>, to display the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link>, or to control
+&kalarm;'s display mode.</para>
+
+<para>See the <link linkend="daemon-reset">Alarm daemon</link> section
+for a discussion about resetting and stopping the <application>alarm
+daemon</application>.</para>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+  <entry>Option</entry>
+  <entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+  <entry><option>--edit <replaceable>eventID</replaceable></option></entry>
+  <entry>Display the alarm edit dialog to edit the alarm with the
+  specified event ID.</entry>
+</row>
+<row>
+  <entry><option>-n</option>, <option>--edit-new</option></entry>
+  <entry>Display the alarm edit dialog, in order to edit a new
+  alarm.</entry>
+</row>
+<row>
+  <entry><option>--edit-new-preset <replaceable>templateName</replaceable></option></entry>
+  <entry>Display the alarm edit dialog, preset with the alarm template
+  of the specified name, in order to edit a new alarm.</entry>
+</row>
+<row>
+  <entry><option>--reset</option></entry>
+  <entry>Reset the <application>alarm daemon</application>.</entry>
+</row>
+<row>
+  <entry><option>--stop</option></entry>
+  <entry>Stop the <application>alarm daemon</application>.</entry>
+</row>
+<row>
+  <entry><option>--tray</option></entry>
+  <entry>Display &kalarm; as an icon in the system tray.</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>For example, to reset the <application>alarm
+daemon</application>:</para>
+
+<informalexample><screen>
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>--reset</option></userinput>
+</screen>
+</informalexample>
+
+</sect1>
+
+<sect1 id="cmdline-help">
+<title>Help options</title>
+
+<para>The following help options are common to all
+&kde; programs:</para>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+  <entry>Option</entry>
+  <entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+  <entry><option>--help</option></entry>
+  <entry>Shows a brief options help text.</entry>
+</row>
+<row>
+  <entry><option>--help-qt</option></entry>
+  <entry>Shows numerous generic &Qt;-specific options.</entry>
+</row>
+<row>
+  <entry><option>--help-kde</option></entry>
+  <entry>Shows numerous generic &kde;-specific options.</entry>
+</row>
+<row>
+  <entry><option>--help-all</option></entry>
+  <entry>Shows all options.</entry>
+</row>
+<row>
+  <entry><option>--author</option></entry>
+  <entry>Shows the names and email addresses of &kalarm; authors.</entry>
+</row>
+<row>
+  <entry><option>-v</option>, <option>--version</option></entry>
+  <entry>Shows the running versions of the &Qt; library , &kde; and
+  &kalarm;.</entry>
+</row>
+<row>
+  <entry><option>--license</option></entry>
+  <entry>Show license information.</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+</sect1>
+</chapter>
+
+<chapter id="daemon">
+<title>Alarm daemon</title>
+
+<para>The <application>alarm daemon</application>, &kalarmd;, monitors
+&kalarm;'s calendar file for alarms becoming due. When it determines
+that an alarm is due, it tells &kalarm; to display or execute it, or
+to cancel it if it is late and late trigger was not selected for that
+alarm.</para>
+
+<para>The <application>alarm daemon</application> runs in the
+background, with no user interface. It may be controlled as described
+below.</para>
+
+<sect1 id="daemon-start">
+<title>Starting, resetting and stopping the <application>alarm daemon</application></title>
+
+<para>The <application>alarm daemon</application> is normally started
+at &kde; session login (unless you disable auto start in the
+<link linkend="preferences-general">Preferences dialog</link> and then
+cease to use &kalarm;), and runs continuously until logout. If for any
+reason it is not running, alarm monitoring will not occur and &kalarm;
+will not display or execute any alarms.</para>
+
+<sect2>
+<title>Starting the <application>alarm daemon</application></title>
+
+<para>To start the <application>alarm daemon</application>, you can
+either run &kalarm; in its default graphical mode (&ie; without any
+command line parameters other than <option>--tray</option>), enable
+alarms using &kalarm;'s system tray icon menu, reset the daemon as
+described <link linkend="daemon-reset">below</link>, or you can run
+the <application>alarm daemon</application> directly from the command
+line:</para>
+
+<screen width="40">
+<prompt>%</prompt> <userinput><command>kalarmd</command></userinput>
+</screen>
+
+</sect2>
+
+<sect2 id="daemon-reset">
+<title>Resetting the <application>alarm daemon</application></title>
+
+<para>It is also possible to reset the <application>alarm
+daemon</application> without stopping it. Resetting causes the
+<application>alarm daemon</application> to re-read the list of
+scheduled messages from the calendar file and re-initialize its
+&kalarm;-related data.</para>
+
+<para>Why might you want to reset the <application>alarm
+daemon</application>? It isn't a very likely occurrence, but if for
+any reason &kalarm; was not able to run when the <application>alarm
+daemon</application> told it to trigger an alarm, that alarm will
+never be displayed or executed until the <application>alarm
+daemon</application> is either reset or restarted.</para>
+
+<tip><para>Resetting starts the <application>alarm
+daemon</application> if it is not currently running.</para></tip>
+
+<para>To reset the <application>alarm daemon</application>, either use
+the menu command <menuchoice>
+<guimenu>Actions</guimenu><guimenuitem>Refresh Alarms</guimenuitem>
+</menuchoice> or type the following command:</para>
+
+<screen width="40">
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>--reset</option></userinput>
+</screen>
+
+</sect2>
+
+<sect2>
+<title>Stopping the <application>alarm daemon</application></title>
+
+<para>Stopping the <application>alarm daemon</application> will
+prevent any further monitoring of scheduled alarm messages until the
+daemon is restarted.</para>
+
+<para>To stop the <application>alarm daemon</application>, type the
+following command:</para>
+
+<screen width="40">
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>--stop</option></userinput>
+</screen>
+</sect2>
+
+</sect1>
+</chapter>
+
+<chapter id="developers">
+<title>Developer's Guide to &kalarm;</title>
+
+<para>&kalarm; provides an interface to allow other applications to
+request the following functions:</para>
+
+<itemizedlist>
+<listitem><para>schedule a new alarm</para></listitem>
+<listitem><para>trigger or cancel an already scheduled
+alarm</para></listitem>
+<listitem><para>cancel an already scheduled alarm</para></listitem>
+<listitem><para>trigger an already scheduled alarm</para></listitem>
+<listitem><para>display the alarm edit dialog</para></listitem>
+</itemizedlist>
+
+<para>Each of the above functions is implemented both by a &DCOP; call
+and by the command line. &DCOP; calls should be used in preference if
+&kalarm; is already running.</para>
+
+<sect1 id="dcop-interface">
+<title>&DCOP; interface</title>
+
+<para>The DCOP calls described in this document are all implemented in
+&kalarm;'s <constant>request</constant> DCOP object. The interface is
+defined in the file <filename>kalarmiface.h</filename>.</para>
+
+<note><para>In &kalarm; version 1.2, the DCOP interface was completely
+revised to allow easier calling of functions, and to conform better to
+the standard &kde; DCOP configuration. The old DCOP interface is
+currently still usable for compatibility purposes, but will be removed
+at some future date.</para></note>
+
+<refentry id="cancelEvent">
+<refmeta>
+<refentrytitle>cancelEvent</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>cancelEvent</refname>
+<refpurpose>cancel an already scheduled alarm.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+void cancelEvent(const QString&amp; <replaceable>calendarFile</replaceable>,
+                 const QString&amp; <replaceable>eventID</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>calendarFile</parameter></term>
+<listitem>
+<para>Specifies the &URL; (not path) of the calendar file containing
+the event to be canceled.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>eventID</parameter></term>
+<listitem>
+<para>Specifies the unique ID of the event to be canceled, as stored
+in <replaceable>calendarFile</replaceable>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+<para><function>cancelEvent()</function> is a &DCOP; call to cancel
+the specified alarm. &kalarm; deletes the alarm from the calendar file
+without displaying or executing it.</para>
+
+<note><para>The <replaceable>calendarFile</replaceable> parameter is
+only used for integrity checking: if the &URL; does not specify
+&kalarm;'s current default calendar file, the request will be
+ignored.</para></note>
+
+</refsect1>
+</refentry>
+
+<refentry id="triggerEvent">
+<refmeta>
+<refentrytitle>triggerEvent</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>triggerEvent</refname>
+<refpurpose>trigger an already scheduled alarm.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+void triggerEvent(const QString&amp; <replaceable>calendarFile</replaceable>,
+                  const QString&amp; <replaceable>eventID</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>calendarFile</parameter></term>
+<listitem>
+<para>Specifies the &URL; (not path) of the calendar file containing
+the event to be triggered.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>eventID</parameter></term>
+<listitem>
+<para>Specifies the unique ID of the event to be triggered, as stored
+in <replaceable>calendarFile</replaceable>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+<para><function>triggerEvent()</function> is a &DCOP; call to trigger
+the immediate display or execution of the specified alarm (regardless
+of what time it is scheduled for). &kalarm; retrieves the alarm from
+the calendar file and then displays or executes it.</para>
+
+<para>If the alarm is already due, &kalarm; then deletes all scheduled
+occurrences of the alarm up to the current time, and if no repetitions
+of the alarm still remain, the alarm is deleted from the calendar
+file. If the alarm is not due yet, its scheduled occurrences are left
+unchanged.</para>
+
+<note><para>The <replaceable>calendarFile</replaceable> parameter is
+only used for integrity checking: if the &URL; does not specify
+&kalarm;'s current default calendar file, the request will be
+ignored.</para></note>
+
+</refsect1>
+</refentry>
+
+<refentry id="handleEvent">
+<refmeta>
+<refentrytitle>handleEvent</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>handleEvent</refname>
+<refpurpose>trigger or cancel an already scheduled alarm.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+void handleEvent(const QString&amp; <replaceable>calendarFile</replaceable>,
+                 const QString&amp; <replaceable>eventID</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>calendarFile</parameter></term>
+<listitem>
+<para>Specifies the &URL; (not path) of the calendar file containing
+the event to be displayed/executed or canceled.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>eventID</parameter></term>
+<listitem>
+<para>Specifies the unique ID of the event to be displayed/executed or
+canceled, as stored in
+<replaceable>calendarFile</replaceable>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+<para><function>handleEvent()</function> is a &DCOP; call to
+display/execute or cancel the specified alarm. &kalarm; retrieves the
+alarm from the calendar file and then determines what action to take
+depending on when the alarm is due.</para>
+
+<itemizedlist>
+<listitem><para>If the alarm is not yet due, nothing happens.</para>
+</listitem>
+
+<listitem><para>If the alarm is due, it acts as follows. If a
+late-cancel value is set and the alarm is too late, &ie; the scheduled
+trigger time was longer than late-cancel minutes ago, &kalarm; does
+not display or execute the alarm; otherwise, &kalarm; displays or
+executes the alarm. If no repetitions of the alarm are still
+scheduled, &kalarm; then deletes the alarm from the calendar
+file.</para>
+</listitem>
+</itemizedlist>
+
+<note><para>The <replaceable>calendarFile</replaceable> parameter is
+only used for integrity checking: if the &URL; does not specify
+&kalarm;'s current default calendar file, the request will be
+ignored.</para></note>
+
+</refsect1>
+</refentry>
+
+<refentry id="scheduleMessage">
+<refmeta>
+<refentrytitle>scheduleMessage</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>scheduleMessage</refname>
+<refpurpose>schedule a new alarm message.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+bool scheduleMessage(const QString&amp; <replaceable>message</replaceable>,
+                     const QString&amp; <replaceable>dateTime</replaceable>,
+                     int <replaceable>lateCancel</replaceable>,
+                     int <replaceable>flags</replaceable>, 
+                     const QString&amp; <replaceable>bgColor</replaceable>, 
+                     const QString&amp; <replaceable>fgColor</replaceable>, 
+                     const QString&amp; <replaceable>font</replaceable>, 
+                     const KURL&amp; <replaceable>audioURL</replaceable>, 
+                     int <replaceable>reminder</replaceable>, 
+                     const QString&amp; <replaceable>recurrence</replaceable>,
+                     int <replaceable>subRepeatInterval</replaceable>, 
+                     int <replaceable>subRepeatCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleMessage(const QString&amp; <replaceable>message</replaceable>, 
+                     const QString&amp; <replaceable>dateTime</replaceable>, 
+                     int <replaceable>lateCancel</replaceable>, int <replaceable>flags</replaceable>, 
+                     const QString&amp; <replaceable>bgColor</replaceable>, 
+                     const QString&amp; <replaceable>fgColor</replaceable>, 
+                     const QString&amp; <replaceable>font</replaceable>, 
+                     const KURL&amp; <replaceable>audioURL</replaceable>, 
+                     int <replaceable>reminder</replaceable>, 
+                     int <replaceable>recurType</replaceable>, 
+                     int <replaceable>recurInterval</replaceable>, 
+                     int <replaceable>recurCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleMessage(const QString&amp; <replaceable>message</replaceable>, 
+                     const QString&amp; <replaceable>dateTime</replaceable>, 
+                     int <replaceable>lateCancel</replaceable>, 
+                     int <replaceable>flags</replaceable>, 
+                     const QString&amp; <replaceable>bgColor</replaceable>, 
+                     const QString&amp; <replaceable>fgColor</replaceable>, 
+                     const QString&amp; <replaceable>font</replaceable>, 
+                     const KURL&amp; <replaceable>audioURL</replaceable>, 
+                     int <replaceable>reminder</replaceable>, 
+                     int <replaceable>recurType</replaceable>, 
+                     int <replaceable>recurInterval</replaceable>, 
+                     const QString&amp; <replaceable>endDateTime</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>message</parameter></term>
+<listitem>
+<para>Specifies the text of the message to be scheduled.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>dateTime</parameter></term>
+<listitem>
+<para>Specifies the scheduled date, or date and time, at which the
+message should be displayed. For a date-only alarm, the string should
+be in the format <quote>YYYY-MM-DD</quote> (as returned by
+<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm
+with a date and time, the string should be in the format
+<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by
+<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or
+<quote>HH:MM[:SS]</quote> (as returned by
+<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is
+specified, today's date is used. Note that any seconds value is
+ignored.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>lateCancel</parameter></term>
+<listitem>
+<para>Causes the alarm to be canceled if it cannot be triggered within
+the specified number of minutes after the alarm's scheduled time. If
+the value is 0, the alarm will not be canceled no matter how late it
+is triggered.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>flags</parameter></term>
+<listitem>
+<para>Specifies the logical OR of the desired alarm flags. The flag
+bits are those defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Note that not all flag bits are
+applicable to message alarms.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>bgColor</parameter></term>
+<listitem>
+<para>Specifies the background color for displaying the message. The
+string may be in the format <quote>#RRGGBB</quote> (as returned by
+<methodname>QColor::name()</methodname>) where RR, GG and BB are
+two-digit hexadecimal values for red, green and blue. Alternatively
+the string may be in any of the other formats accepted by
+<methodname>QColor::setNamedColor()</methodname>, such as a name from
+the X color database (&eg; <quote>red</quote> or
+<quote>steelblue</quote>). Set the string to null to specify the
+current default background color.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>fgColor</parameter></term>
+<listitem>
+<para>Specifies the foreground color for displaying the message. The
+format of the string is the same as for
+<parameter>bgColor</parameter>, or alternatively set the string to
+null to specify the current default foreground color.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>font</parameter></term>
+<listitem>
+<para>Specifies the font for displaying the message. The format of the
+string is that output by <methodname>QFont::toString()</methodname>.
+Set the string to null to use the default message font current at the
+time the message is displayed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>audioURL</parameter></term>
+<listitem>
+<para>Specifies the audio file which is to be played when the message
+is displayed. Set the value to null if no audio file is to be
+played.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>reminder</parameter></term>
+<listitem>
+<para>Specifies the number of minutes in advance of the main alarm
+and of each of its recurrences (if any) at which a reminder alarm
+should be displayed. Specify 0 if no reminder is required.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurrence</parameter></term>
+<listitem>
+<para>Specifies a regular recurrence for the alarm, using iCalendar
+syntax as defined in
+<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>.
+For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>
+would specify 4 repetitions at 3-monthly intervals on the last Monday
+of the month. For a non-recurring alarm, specify an empty
+string.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurType</parameter></term>
+<listitem>
+<para>Specifies the recurrence type for the alarm. The permissible
+values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
+are defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Monthly recurrences are of the
+day of the month type, and yearly recurrences are of the date in
+the year type, with the date in both cases taken from the
+<parameter>dateTime</parameter> parameter.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurInterval</parameter></term>
+<listitem>
+<para>Specifies the number of periods
+(minutes/days/weeks/months/years as specified by
+<parameter>recurType</parameter>) between recurrences of the
+alarm.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurCount</parameter></term>
+<listitem>
+<para>Specifies the number of times that the alarm should be
+repeated. Specify -1 to repeat the alarm indefinitely.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>endDateTime</parameter></term>
+<listitem>
+<para>Specifies the end date, or date and time, for recurrences of the
+alarm. If <parameter>dateTime</parameter> includes a time, this
+parameter must also include a time; if <parameter>dateTime</parameter>
+contains only a date, this parameter must also contain only a
+date.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatInterval</parameter></term>
+<listitem>
+<para>Specifies the number of minutes between sub-repetitions of
+the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence
+is specified.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatCount</parameter></term>
+<listitem>
+<para>Specifies the number of sub-repetitions of the alarm,
+including the initial occurrence.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1 id="scheduleMessage-descrip">
+<title>Description</title>
+<para><function>scheduleMessage()</function> is a &DCOP; call to
+schedule the specified alarm message for display at the specified date
+and time. It has three forms. The most general form allows an
+arbitrary recurrence to be specified &ndash; use this also for
+non-repeating alarms. The other forms provide convenient access to a
+restricted set of alarm recurrence types, one specifying a repetition
+count and the other an end time.</para>
+
+<para>If the scheduled time (including any repetitions) has already
+passed, &kalarm; immediately displays the message (unless the
+<parameter>lateCancel</parameter> value indicates that it is now too
+late to display the alarm, in which case &kalarm; ignores the
+request). If the scheduled time (or a repetition) is in the future,
+&kalarm; adds the alarm message to the calendar file for later
+display.</para>
+</refsect1>
+</refentry>
+
+<refentry id="scheduleFile">
+<refmeta>
+<refentrytitle>scheduleFile</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>scheduleFile</refname>
+<refpurpose>schedule a new alarm which displays the contents of a
+text or image file.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+bool scheduleFile(const KURL&amp; <replaceable>URL</replaceable>,
+                  const QString&amp; <replaceable>dateTime</replaceable>,
+                  int <replaceable>lateCancel</replaceable>,
+                  int <replaceable>flags</replaceable>,
+                  const QString&amp; <replaceable>bgColor</replaceable>,
+                  const KURL&amp; <replaceable>audioURL</replaceable>,
+                  int <replaceable>reminder</replaceable>,
+                  const QString&amp; <replaceable>recurrence</replaceable>,
+                  int <replaceable>subRepeatInterval</replaceable>, 
+                  int <replaceable>subRepeatCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleFile(const KURL&amp; <replaceable>URL</replaceable>,
+                  const QString&amp; <replaceable>dateTime</replaceable>,
+                  int <replaceable>lateCancel</replaceable>,
+                  int <replaceable>flags</replaceable>,
+                  const QString&amp; <replaceable>bgColor</replaceable>,
+                  const KURL&amp; <replaceable>audioURL</replaceable>,
+                  int <replaceable>reminder</replaceable>,
+                  int <replaceable>recurType</replaceable>,
+                  int <replaceable>recurInterval</replaceable>,
+                  int <replaceable>recurCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleFile(const KURL&amp; <replaceable>URL</replaceable>,
+                  const QString&amp; <replaceable>dateTime</replaceable>,
+                  int <replaceable>lateCancel</replaceable>,
+                  int <replaceable>flags</replaceable>,
+                  const QString&amp; <replaceable>bgColor</replaceable>,
+                  const KURL&amp; <replaceable>audioURL</replaceable>,
+                  int <replaceable>reminder</replaceable>,
+                  int <replaceable>recurType</replaceable>,
+                  int <replaceable>recurInterval</replaceable>,
+                  const QString&amp; <replaceable>endDateTime</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>URL</parameter></term>
+<listitem>
+<para>Specifies the text or image file whose contents are to be
+displayed in the message to be scheduled.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>dateTime</parameter></term>
+<listitem>
+<para>Specifies the scheduled date, or date and time, at which the
+file should be displayed. For a date-only alarm, the string should
+be in the format <quote>YYYY-MM-DD</quote> (as returned by
+<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm
+with a date and time, the string should be in the format
+<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by
+<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or
+<quote>HH:MM[:SS]</quote> (as returned by
+<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is
+specified, today's date is used. Note that any seconds value is
+ignored.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>lateCancel</parameter></term>
+<listitem>
+<para>Causes the alarm to be canceled if it cannot be triggered within
+the specified number of minutes after the alarm's scheduled time. If
+the value is 0, the alarm will not be canceled no matter how late it
+is triggered.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>flags</parameter></term>
+<listitem>
+<para>Specifies the logical OR of the desired alarm flags. The flag
+bits are those defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Note that not all flag bits are
+applicable to file alarms.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>bgColor</parameter></term>
+<listitem>
+<para>Specifies the background color for displaying the file. The
+string may be in the format <quote>#RRGGBB</quote> (as returned by
+<methodname>QColor::name()</methodname>) where RR, GG and BB are
+two-digit hexadecimal values for red, green and blue. Alternatively
+the string may be in any of the other formats accepted by
+<methodname>QColor::setNamedColor()</methodname>, such as a name from
+the X color database (&eg; <quote>red</quote> or
+<quote>steelblue</quote>). Set the string to null to specify the
+current default background color.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>audioURL</parameter></term>
+<listitem>
+<para>Specifies the audio file which is to be played when the message
+is displayed. Set the value to null if no audio file is to be
+played.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>reminder</parameter></term>
+<listitem>
+<para>Specifies the number of minutes in advance of the main alarm
+and of each of its recurrences (if any) at which a reminder alarm
+should be displayed. Specify 0 if no reminder is required.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurrence</parameter></term>
+<listitem>
+<para>Specifies a regular recurrence for the alarm, using iCalendar
+syntax as defined in
+<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>.
+For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>
+would specify 4 repetitions at 3-monthly intervals on the last Monday
+of the month. For a non-recurring alarm, specify an empty
+string.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurType</parameter></term>
+<listitem>
+<para>Specifies the recurrence type for the alarm. The permissible
+values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
+are defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Monthly recurrences are of the
+day of the month type, and yearly recurrences are of the date in
+the year type, with the date in both cases taken from the
+<parameter>dateTime</parameter> parameter.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurInterval</parameter></term>
+<listitem>
+<para>Specifies the number of periods
+(minutes/days/weeks/months/years as specified by
+<parameter>recurType</parameter>) between recurrences of the
+alarm.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurCount</parameter></term>
+<listitem>
+<para>Specifies the number of times that the alarm should be
+repeated. Specify -1 to repeat the alarm indefinitely.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>endDateTime</parameter></term>
+<listitem>
+<para>Specifies the end date, or date and time, for recurrences of the
+alarm. If <parameter>dateTime</parameter> includes a time, this
+parameter must also include a time; if <parameter>dateTime</parameter>
+contains only a date, this parameter must also contain only a
+date.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatInterval</parameter></term>
+<listitem>
+<para>Specifies the number of minutes between sub-repetitions of
+the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence
+is specified.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatCount</parameter></term>
+<listitem>
+<para>Specifies the number of sub-repetitions of the alarm,
+including the initial occurrence.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para><function>scheduleFile()</function> is a &DCOP; call to schedule
+the specified text or image file for display at the specified date and
+time. Apart from specifying a file path or &URL; and omitting the
+foreground color and font, its usage is identical to
+<link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link>
+- see the description of that function for further details.</para>
+</refsect1>
+</refentry>
+
+
+<refentry id="scheduleCommand">
+<refmeta>
+<refentrytitle>scheduleCommand</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>scheduleCommand</refname>
+<refpurpose>schedule a new alarm which executes a shell
+command.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+bool scheduleCommand(const QString&amp; <replaceable>commandLine</replaceable>,
+                     const QString&amp; <replaceable>dateTime</replaceable>,
+                     int <replaceable>lateCancel</replaceable>,
+                     int <replaceable>flags</replaceable>,
+                     const QString&amp; <replaceable>recurrence</replaceable>,
+                     int <replaceable>subRepeatInterval</replaceable>, 
+                     int <replaceable>subRepeatCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleCommand(const QString&amp; <replaceable>commandLine</replaceable>,
+                     const QString&amp; <replaceable>dateTime</replaceable>,
+                     int <replaceable>lateCancel</replaceable>,
+                     int <replaceable>flags</replaceable>,
+                     int <replaceable>recurType</replaceable>,
+                     int <replaceable>recurInterval</replaceable>,
+                     int <replaceable>recurCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleCommand(const QString&amp; <replaceable>commandLine</replaceable>,
+                     const QString&amp; <replaceable>dateTime</replaceable>,
+                     int <replaceable>lateCancel</replaceable>,
+                     int <replaceable>flags</replaceable>,
+                     int <replaceable>recurType</replaceable>,
+                     int <replaceable>recurInterval</replaceable>,
+                     const QString&amp; <replaceable>endDateTime</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>commandLine</parameter></term>
+<listitem>
+<para>Specifies the command whose execution is to be scheduled. The
+<parameter>flags</parameter> parameter indicates whether this
+parameter contains a shell command line or a command script.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>dateTime</parameter></term>
+<listitem>
+<para>Specifies the scheduled date, or date and time, at which the
+command should be executed. For a date-only alarm, the string should
+be in the format <quote>YYYY-MM-DD</quote> (as returned by
+<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm
+with a date and time, the string should be in the format
+<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by
+<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or
+<quote>HH:MM[:SS]</quote> (as returned by
+<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is
+specified, today's date is used. Note that any seconds value is
+ignored.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>lateCancel</parameter></term>
+<listitem>
+<para>Causes the alarm to be canceled if it cannot be triggered within
+the specified number of minutes after the alarm's scheduled time. If
+the value is 0, the alarm will not be canceled no matter how late it
+is triggered.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>flags</parameter></term>
+<listitem>
+<para>Specifies the logical OR of the desired alarm flags. The flag
+bits are those defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Note that not all flag bits are
+applicable to command alarms.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurrence</parameter></term>
+<listitem>
+<para>Specifies a regular recurrence for the alarm, using iCalendar
+syntax as defined in
+<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>.
+For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>
+would specify 4 repetitions at 3-monthly intervals on the last Monday
+of the month. For a non-recurring alarm, specify an empty
+string.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurType</parameter></term>
+<listitem>
+<para>Specifies the recurrence type for the alarm. The permissible
+values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
+are defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Monthly recurrences are of the
+day of the month type, and yearly recurrences are of the date in
+the year type, with the date in both cases taken from the
+<parameter>dateTime</parameter> parameter.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurInterval</parameter></term>
+<listitem>
+<para>Specifies the number of periods
+(minutes/days/weeks/months/years as specified by
+<parameter>recurType</parameter>) between recurrences of the
+alarm.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurCount</parameter></term>
+<listitem>
+<para>Specifies the number of times that the alarm should be
+repeated. Specify -1 to repeat the alarm indefinitely.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>endDateTime</parameter></term>
+<listitem>
+<para>Specifies the end date, or date and time, for recurrences of the
+alarm. If <parameter>dateTime</parameter> includes a time, this
+parameter must also include a time; if <parameter>dateTime</parameter>
+contains only a date, this parameter must also contain only a
+date.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatInterval</parameter></term>
+<listitem>
+<para>Specifies the number of minutes between sub-repetitions of
+the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence
+is specified.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatCount</parameter></term>
+<listitem>
+<para>Specifies the number of sub-repetitions of the alarm,
+including the initial occurrence.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para><function>scheduleCommand()</function> is a &DCOP; call to
+schedule the specified shell command line, or command script, for
+execution at the specified date and time. Apart from specifying a
+command and omitting the message color, font and audio file
+parameters, its usage is identical to
+<link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link>
+- see the description of that function for further details.</para>
+</refsect1>
+</refentry>
+
+
+<refentry id="scheduleEmail">
+<refmeta>
+<refentrytitle>scheduleEmail</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>scheduleEmail</refname>
+<refpurpose>schedule a new alarm which sends an email.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+bool scheduleEmail(const QString&amp; <replaceable>fromID</replaceable>,
+                   const QString&amp; <replaceable>addresses</replaceable>,
+                   const QString&amp; <replaceable>subject</replaceable>,
+                   const QString&amp; <replaceable>message</replaceable>,
+                   const QString&amp; <replaceable>attachments</replaceable>,
+                   const QString&amp; <replaceable>dateTime</replaceable>,
+                   int <replaceable>lateCancel</replaceable>,
+                   int <replaceable>flags</replaceable>,
+                   const QString&amp; <replaceable>recurrence</replaceable>,
+                   int <replaceable>subRepeatInterval</replaceable>, 
+                   int <replaceable>subRepeatCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleEmail(const QString&amp; <replaceable>fromID</replaceable>,
+                   const QString&amp; <replaceable>addresses</replaceable>,
+                   const QString&amp; <replaceable>subject</replaceable>,
+                   const QString&amp; <replaceable>message</replaceable>,
+                   const QString&amp; <replaceable>attachments</replaceable>,
+                   const QString&amp; <replaceable>dateTime</replaceable>,
+                   int <replaceable>lateCancel</replaceable>,
+                   int <replaceable>flags</replaceable>,
+                   int <replaceable>recurType</replaceable>,
+                   int <replaceable>recurInterval</replaceable>,
+                   int <replaceable>recurCount</replaceable>)
+</synopsis>
+<synopsis>
+bool scheduleEmail(const QString&amp; <replaceable>fromID</replaceable>,
+                   const QString&amp; <replaceable>addresses</replaceable>,
+                   const QString&amp; <replaceable>subject</replaceable>,
+                   const QString&amp; <replaceable>message</replaceable>,
+                   const QString&amp; <replaceable>attachments</replaceable>,
+                   const QString&amp; <replaceable>dateTime</replaceable>,
+                   int <replaceable>lateCancel</replaceable>, 
+                   nt <replaceable>flags</replaceable>,
+                   int <replaceable>recurType</replaceable>,
+                   int <replaceable>recurInterval</replaceable>,
+                   const QString&amp; <replaceable>endTime</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>fromID</parameter></term>
+<listitem>
+<para>The &kmail; identity to use as the sender of the email. If
+empty, the sender's email address will be that configured in
+&kalarm;'s
+<link linkend="preferences-email">Email preferences</link>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>addresses</parameter></term>
+<listitem>
+<para>A comma separated list of recipients' email addresses.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subject</parameter></term>
+<listitem>
+<para>Specifies the subject line of the email.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>message</parameter></term>
+<listitem>
+<para>Specifies the email message body.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>attachments</parameter></term>
+<listitem>
+<para>A comma-separated list of paths or &URL;s of files to send as
+email attachments.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>dateTime</parameter></term>
+<listitem>
+<para>Specifies the scheduled date, or date and time, at which the
+email should be sent. For a date-only alarm, the string should
+be in the format <quote>YYYY-MM-DD</quote> (as returned by
+<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm
+with a date and time, the string should be in the format
+<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by
+<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or
+<quote>HH:MM[:SS]</quote> (as returned by
+<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is
+specified, today's date is used. Note that any seconds value is
+ignored.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>lateCancel</parameter></term>
+<listitem>
+<para>Causes the alarm to be canceled if it cannot be triggered within
+the specified number of minutes after the alarm's scheduled time. If
+the value is 0, the alarm will not be canceled no matter how late it
+is triggered.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>flags</parameter></term>
+<listitem>
+<para>Specifies the logical OR of the desired alarm flags. The flag
+bits are those defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Note that not all flag bits are
+applicable to email alarms.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurrence</parameter></term>
+<listitem>
+<para>Specifies a regular recurrence for the alarm, using iCalendar
+syntax as defined in
+<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>.
+For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>
+would specify 4 repetitions at 3-monthly intervals on the last Monday
+of the month. For a non-recurring alarm, specify an empty
+string.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurType</parameter></term>
+<listitem>
+<para>Specifies the recurrence type for the alarm. The permissible
+values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
+are defined in class <classname>KAlarmIface</classname> in
+<filename>kalarmiface.h</filename>. Monthly recurrences are of the
+day of the month type, and yearly recurrences are of the date in
+the year type, with the date in both cases taken from the
+<parameter>dateTime</parameter> parameter.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurInterval</parameter></term>
+<listitem>
+<para>Specifies the number of periods
+(minutes/days/weeks/months/years as specified by
+<parameter>recurType</parameter>) between recurrences of the
+alarm.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>recurCount</parameter></term>
+<listitem>
+<para>Specifies the number of times that the alarm should be
+repeated. Specify -1 to repeat the alarm indefinitely.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>endDateTime</parameter></term>
+<listitem>
+<para>Specifies the end date, or date and time, for recurrences of the
+alarm. If <parameter>dateTime</parameter> includes a time, this
+parameter must also include a time; if <parameter>dateTime</parameter>
+contains only a date, this parameter must also contain only a
+date.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatInterval</parameter></term>
+<listitem>
+<para>Specifies the number of minutes between sub-repetitions of
+the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence
+is specified.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>subRepeatCount</parameter></term>
+<listitem>
+<para>Specifies the number of sub-repetitions of the alarm,
+including the initial occurrence.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para><function>scheduleEmail()</function> is a &DCOP; call to
+schedule the specified email for sending at the specified date and
+time. Apart from specifying the email header and contents and omitting
+the message color, font and audio file parameters, its usage is
+identical to
+<link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link>
+- see the description of that function for further details.</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop_edit">
+<refmeta>
+<refentrytitle>edit</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>edit</refname>
+<refpurpose>Display the <link linkend="alarm-edit-dlg">alarm edit
+dialog</link> to edit an alarm.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+bool edit(const QString&amp; <replaceable>eventID</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>eventID</parameter></term>
+<listitem>
+<para>Specifies the unique ID of the event to be edited.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2>
+<title>Return value</title>
+<para><returnvalue>false</returnvalue> if the specified
+alarm could not be found or is read-only,
+<returnvalue>true</returnvalue> otherwise.</para>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+<para><function>edit()</function> is a &DCOP; call to display the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link> to edit the
+specified alarm.</para>
+
+</refsect1>
+</refentry>
+
+<refentry id="dcop_editnew">
+<refmeta>
+<refentrytitle>editNew</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>editNew</refname>
+<refpurpose>Display the <link linkend="alarm-edit-dlg">alarm edit
+dialog</link> to edit a new alarm.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+bool editNew(const QString&amp; <replaceable>templateName</replaceable>)
+</synopsis>
+
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>templateName</parameter></term>
+<listitem>
+<para>Specifies the name of an alarm template to base the new alarm
+on, or empty if no template should be used.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+
+<refsect2>
+<title>Return value</title>
+<para><returnvalue>false</returnvalue> if
+<parameter>templateName</parameter> is non-empty but a template of
+that name cannot be found, <returnvalue>true</returnvalue>
+otherwise.</para>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+<para><function>editNew()</function> is a &DCOP; call to display the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link> to edit a new
+alarm. If an alarm template name is specified as a parameter, the
+dialog is preset with details from the template. If the specified
+template cannot be found, the
+<link linkend="alarm-edit-dlg">alarm edit dialog</link> is still
+displayed but is (obviously) not preset with the template.</para>
+
+</refsect1>
+</refentry>
+
+</sect1>
+
+<sect1 id="cmdline-interface">
+<title>Command line interface</title>
+
+<para>Command line options are provided to enable other programs (such
+as the <application>alarm daemon</application>) to start up &kalarm;
+if it is not already running, in order to trigger or cancel scheduled
+alarms, or schedule new alarms. The reason for using command line
+options for this purpose is that if &kalarm; were started without any
+command line parameters and then sent &DCOP; requests, it would start
+in its default graphical mode, which is clearly undesirable for an
+inter-program request.</para>
+
+<note><para>Programs should first check whether &kalarm; is already
+running; if it is, they should instead use &DCOP; calls to request these
+operations.</para></note>
+
+<para>The command line options for scheduling a new alarm are as
+described in the chapter <link linkend="cmdline-operation">Command line
+operation</link>. The options for triggering and canceling scheduled
+alarms are as follows:</para>
+
+<note><para>Normal users may also if they wish use these command line
+options (assuming that they can supply the necessary parameter
+information).</para></note>
+
+<informaltable>
+<tgroup cols="2">
+<thead>
+<row>
+  <entry>Option</entry>
+  <entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+  <entry><option>--calendarURL <replaceable>url</replaceable></option></entry>
+  <entry>Use the calendar file with the specified &URL;. This option
+  is only used for integrity checking: if the &URL; doesn't specify
+  &kalarm;'s current default calendar file, the request will be
+  ignored.</entry>
+</row>
+<row>
+  <entry><option>--cancelEvent <replaceable>eventID</replaceable></option></entry>
+  <entry>Cancel the alarm with the specified event ID.</entry>
+</row>
+<row>
+  <entry><option>--triggerEvent <replaceable>eventID</replaceable></option></entry>
+  <entry>Trigger the alarm with the specified event ID. The action
+  taken is the same as for the
+  <link linkend="triggerEvent">triggerEvent()</link> &DCOP;
+  call.</entry>
+</row>
+<row>
+  <entry><option>--handleEvent <replaceable>eventID</replaceable></option></entry>
+  <entry>Trigger or cancel the alarm with the specified event
+  ID. &kalarm; determines which action to take in the same way as for
+  the <link linkend="handleEvent">handleEvent()</link> &DCOP; call.</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para><option>--cancelEvent</option>, <option>--triggerEvent</option>
+and <option>--handleEvent</option> are mutually
+exclusive. <option>--calendarURL</option> is optional, but can only be
+used with one of the other three options.</para>
+
+<para>Examples are:</para>
+
+<informalexample><screen>
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>--triggerEvent <replaceable>&kalarm;-387486299.702</replaceable></option> <option>--calendarURL <replaceable>file:/home/zaphod/hydra.ics</replaceable></option></userinput>
+<prompt>%</prompt> <userinput><command>kalarm</command> <option>--cancelEvent <replaceable>&kalarm;-388886299.793</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+</sect1>
+</chapter>
+
+
+<chapter id="faq">
+<title>Questions and Answers</title>
+
+&reporting.bugs;
+&updating.documentation;
+
+<qandaset id="faqlist">
+<qandaentry>
+<question>
+<para>What is the alarm daemon?</para>
+</question>
+<answer>
+<para>The <application>alarm daemon</application> is an application
+which runs in the background, monitoring alarms and telling &kalarm;
+to trigger them when they become due.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>What configuration files does &kalarm; use?</para>
+</question>
+<answer>
+<para>The file <filename>$KDEHOME/share/config/kalarmrc</filename>
+holds your &kalarm; preferences.</para>
+
+<para>The calendar file which stores your pending alarms is
+<filename>$KDEHOME/share/apps/kalarm/calendar.ics</filename>, unless
+a different calendar file is specified in the preferences file by a
+<parameter>Calendar</parameter> entry in the
+<parameter>General</parameter> section.</para>
+
+<para>The calendar file which stores your expired alarms is
+<filename>$KDEHOME/share/apps/kalarm/expired.ics</filename>, unless
+a different calendar file is specified in the preferences file by an
+<parameter>ExpiredCalendar</parameter> entry in the
+<parameter>General</parameter> section.</para>
+
+<para>The calendar file which stores your alarm templates is
+<filename>$KDEHOME/share/apps/kalarm/template.ics</filename>, unless
+a different calendar file is specified in the preferences file by a
+<parameter>TemplateCalendar</parameter> entry in the
+<parameter>General</parameter> section.</para>
+
+<para>Details of alarms currently being displayed are stored in the
+calendar file
+<filename>$KDEHOME/share/apps/kalarm/displaying.ics</filename>.</para>
+
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>What configuration files does the <application>alarm
+daemon</application> use?</para>
+</question>
+<answer>
+<para>The file <filename>$KDEHOME/share/config/kalarmdrc</filename>
+holds your <application>alarm daemon</application> preferences,
+together with details of the &kalarm; client application.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>What format are alarms stored in?</para>
+</question>
+<answer>
+<para>The calendar files in which &kalarm; stores its alarms are text
+files whose format is defined by the document
+<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445 -
+Internet Calendaring and Scheduling Core Object Specification
+(iCalendar)</ulink>. This is the standard format used by all kdepim
+applications. &kalarm; uses certain non-standard properties in the
+Alarm component, in conformance with RFC2445:
+<literal>X-KDE-KALARM-NEXTRECUR</literal>,
+<literal>X-KDE-KALARM-REPEAT</literal>,
+<literal>X-KDE-KALARM-TYPE</literal>,
+<literal>X-KDE-KALARM-NEXTREPEAT</literal>,
+<literal>X-KDE-KALARM-FONTCOLOR</literal>,
+<literal>X-KDE-KALARM-VOLUME</literal>,
+<literal>X-KDE-KALARM-SPEAK</literal>,
+<literal>X-KDE-KALARM-EMAILID</literal>.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>What are the application names of &kalarm; and the
+<application>alarm daemon</application>?</para>
+</question>
+<answer>
+<para>&kalarm;'s application name is <application>kalarm</application>,
+and the <application>alarm daemon</application>'s application name is
+<application>kalarmd</application>.</para>
+</answer>
+</qandaentry>
+
+</qandaset>
+</chapter>
+
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>
+&kalarm;
+</para>
+<para>
+Program copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 David Jarvie <email>&David.Jarvie.mail;</email>
+</para>
+<para>
+Alarm daemon authors:
+<itemizedlist>
+<listitem><para>Preston Brown <email>[email protected]</email></para>
+</listitem>
+<listitem><para>David Jarvie <email>&David.Jarvie.mail;</email></para>
+</listitem>
+<listitem><para>Cornelius Schumacher <email>[email protected]</email></para>
+</listitem>
+</itemizedlist>
+</para>
+
+<para>
+Documentation copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 David Jarvie <email>&David.Jarvie.mail;</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;               <!-- FDL: do not remove -->
+
+&underGPL;        	 <!-- GPL License -->
+
+<para>Thanks go to the author of the &kde; 1 KAlarm application,
+Stefan Nikolaus <email>[email protected]</email>,
+who kindly agreed to allow the name &kalarm; to be used by this
+&kde; 2 / &kde; 3 application.
+</para>
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kalarm">
+<title>How to obtain &kalarm;</title>
+
+&install.intro.documentation;
+
+<para>&kalarm; is available for &kde; 2 and as a standalone package for
+&kde;3 from <ulink url="http://www.astrojar.org.uk/kalarm">http://www.astrojar.org.uk/kalarm</ulink>
+</para>
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>&kalarm; requires the standard &kde; libraries to be installed
+(the <filename>kdelibs</filename> package). To compile from source,
+you also need the &Qt; and <filename>kdelibs</filename> development
+packages. The X11 development package, if present, is used to improve
+&kalarm;'s ability to function under &kde; without a system
+tray.</para>
+
+<para>The following optional packages enhance &kalarm; at runtime if
+they are installed:</para>
+
+<itemizedlist>
+<listitem><para>&kmix; (from kdemultimedia package): if installed, it
+allows &kalarm; to set the absolute sound volume when playing audio
+files.</para>
+</listitem>
+
+<listitem><para><application>KTTSD</application> (from
+kdeaccessibility package): if installed and configured, together with
+a compatible speech synthesizer package, it allows &kalarm; to speak
+alarm messages when they are displayed.</para>
+</listitem>
+</itemizedlist>
+
+<para>&kalarm; uses about 12 Mb and the <application>alarm
+daemon</application> uses about 2.5 Mb of memory to run, but this may
+vary depending on your platform and configuration.</para>
+
+<para>You can find a list of changes in the
+<filename>ChangeLog</filename> file, or at <ulink
+url="http://www.astrojar.org.uk/kalarm">http://www.astrojar.org.uk/kalarm</ulink>.</para>
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and installation</title>
+
+<para>If you cannot obtain a suitable precompiled binary package, you
+need to compile &kalarm; yourself from source files. Get the source
+package file <filename>kdepim-x.x.tar.bz2</filename> or
+<filename>kalarm-x.x.tar.bz2</filename> (or similar), depending on
+whether you want to install &package; or just &kalarm;. Unpack it in a
+new folder using a command similar to
+<userinput><command>tar</command> <option>xvfj
+<replaceable>package.tar.bz2</replaceable></option></userinput>, and
+change to the folder which has been created.</para>
+
+&install.compile.documentation;
+
+<note><para>If you have more than one version of &kde; installed
+(e.g. &kde; 2 and &kde; 3), this may possibly install &kalarm; into
+the wrong &kde; folder. If necessary, you can give the &kde; folder
+as a parameter to
+<userinput><command>./configure</command></userinput> . For example,
+if your &kde; is installed in <filename>/opt/kde2</filename>:</para>
+
+<para><userinput><command>./configure</command> --prefix=<replaceable>/opt/kde2</replaceable></userinput></para>
+</note>
+
+<warning><para>If you install &kalarm; into a folder different from
+where &kde; is installed, it will not run correctly unless you make
+its location known to &kde;. To do this, you must prefix the
+<envar>KDEDIRS</envar> environment variable with &kalarm;'s location,
+each time before you start &kde;.</para>
+
+<para>For example, if &kde; is installed in
+<literal>/opt/kde</literal>, <envar>KDEDIRS</envar> might normally
+be set to <literal>/etc/opt/kde:/opt/kde</literal>. If you install
+&kalarm; into <literal>/usr/local</literal>, you would need to set
+<envar>KDEDIRS</envar> to
+<literal>/usr/local:/etc/opt/kde:/opt/kde</literal> before starting
+&kde;.</para></warning>
+
+<para>The standalone version of &kalarm; has a special configuration
+option which allows you to select which languages documentation is to
+be installed for by specifying a language code, or a list of language
+codes, as a parameter to <command>./configure</command>. By default,
+documentation in all available languages is installed. A list of
+documentation languages included in the package, together with their
+codes, is in the <filename>DOC-LANGUAGES</filename> file. For example,
+to install only French and British English documentation:</para>
+
+<para><userinput><command>./configure</command> --enable-doc-language=<replaceable>"fr en_GB"</replaceable></userinput></para>
+
+<para>Note that this option has no effect on which user interface
+translations are installed.</para>
+
+</sect1>
+
+<sect1 id="configuration">
+<title>Configuration</title>
+
+<para>No special configuration is required to set up &kalarm; to run
+on the &kde; desktop. Once you have run &kalarm; for the first time,
+the <application>alarm daemon</application> will start every time you
+log in, in order to monitor scheduled alarms.</para>
+
+<para>To run &kalarm; on a non-&kde; desktop, the main requirement is
+to ensure that the <application>alarm daemon</application> is run
+automatically whenever you log in. More detailed instructions are
+contained in the <filename>INSTALL</filename> file which is
+distributed with &kalarm;.</para>
+
+</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:
+-->
+
diff --git a/doc/kalarm/mainwindow.png b/doc/kalarm/mainwindow.png
new file mode 100644
index 000000000..a1c58908d
--- /dev/null
+++ b/doc/kalarm/mainwindow.png
diff --git a/doc/kalarm/spinbox.png b/doc/kalarm/spinbox.png
new file mode 100644
index 000000000..ef9db8972
--- /dev/null
+++ b/doc/kalarm/spinbox.png