summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commit460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree67208f7c145782a7e90b123b982ca78d88cc2c87 /doc
downloadtdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz
tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip
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
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am5
-rw-r--r--doc/akregator/Makefile.am2
-rw-r--r--doc/akregator/add-feed.pngbin0 -> 16387 bytes
-rw-r--r--doc/akregator/add-feed2.pngbin0 -> 22099 bytes
-rw-r--r--doc/akregator/add-folder.pngbin0 -> 8307 bytes
-rw-r--r--doc/akregator/add-folder2.pngbin0 -> 12435 bytes
-rw-r--r--doc/akregator/advanced-tab.pngbin0 -> 40114 bytes
-rw-r--r--doc/akregator/appearance-tab.pngbin0 -> 41801 bytes
-rw-r--r--doc/akregator/archive-tab.pngbin0 -> 42731 bytes
-rw-r--r--doc/akregator/browser-tab.pngbin0 -> 44333 bytes
-rw-r--r--doc/akregator/general-tab.pngbin0 -> 45866 bytes
-rw-r--r--doc/akregator/index.docbook1163
-rw-r--r--doc/akregator/konq.pngbin0 -> 22546 bytes
-rw-r--r--doc/akregator/konq2.pngbin0 -> 7387 bytes
-rw-r--r--doc/akregator/main-window.pngbin0 -> 107896 bytes
-rw-r--r--doc/akregator/main-window2.pngbin0 -> 98345 bytes
-rw-r--r--doc/akregator/main-window3.pngbin0 -> 82554 bytes
-rw-r--r--doc/akregator/main-window4.pngbin0 -> 104901 bytes
-rw-r--r--doc/akregator/quick-filter.pngbin0 -> 5699 bytes
-rw-r--r--doc/akregator/rss.pngbin0 -> 1324 bytes
-rw-r--r--doc/akregator/rss3.pngbin0 -> 1158 bytes
-rw-r--r--doc/api/Dox-pimlogo.pngbin0 -> 16598 bytes
-rw-r--r--doc/api/Doxyfile.pim1162
-rw-r--r--doc/api/doxygen.css611
-rw-r--r--doc/api/header.html70
-rw-r--r--doc/api/kdateedit.pngbin0 -> 25949 bytes
-rw-r--r--doc/api/mainheader.html70
-rw-r--r--doc/kaddressbook/Makefile.am2
-rw-r--r--doc/kaddressbook/addhost.pngbin0 -> 17168 bytes
-rw-r--r--doc/kaddressbook/conf.pngbin0 -> 54444 bytes
-rw-r--r--doc/kaddressbook/contactdlg.pngbin0 -> 37331 bytes
-rw-r--r--doc/kaddressbook/edit_instant_messenging.pngbin0 -> 17465 bytes
-rw-r--r--doc/kaddressbook/exportdlg.pngbin0 -> 17618 bytes
-rw-r--r--doc/kaddressbook/extension.pngbin0 -> 77793 bytes
-rw-r--r--doc/kaddressbook/filtereditdlg.pngbin0 -> 14473 bytes
-rw-r--r--doc/kaddressbook/index.docbook1179
-rw-r--r--doc/kaddressbook/mainwin.pngbin0 -> 58199 bytes
-rw-r--r--doc/kaddressbook/resourcedlg.pngbin0 -> 20021 bytes
-rw-r--r--doc/kaddressbook/resourcesdlg.pngbin0 -> 73504 bytes
-rw-r--r--doc/kaddressbook/vieweditdlg.pngbin0 -> 20401 bytes
-rw-r--r--doc/kalarm/Makefile.am2
-rw-r--r--doc/kalarm/alarmmessage.pngbin0 -> 13620 bytes
-rw-r--r--doc/kalarm/editwindow.pngbin0 -> 33209 bytes
-rw-r--r--doc/kalarm/index.docbook4170
-rw-r--r--doc/kalarm/mainwindow.pngbin0 -> 34092 bytes
-rw-r--r--doc/kalarm/spinbox.pngbin0 -> 587 bytes
-rw-r--r--doc/kandy/Makefile.am2
-rw-r--r--doc/kandy/index.docbook348
-rw-r--r--doc/karm/Makefile.am4
-rw-r--r--doc/karm/clipboard-history.pngbin0 -> 11153 bytes
-rw-r--r--doc/karm/copy-this-task.pngbin0 -> 11552 bytes
-rw-r--r--doc/karm/csvexport.pngbin0 -> 13239 bytes
-rw-r--r--doc/karm/daterange.pngbin0 -> 11241 bytes
-rw-r--r--doc/karm/idle-detect.pngbin0 -> 10610 bytes
-rw-r--r--doc/karm/index.docbook1238
-rw-r--r--doc/karm/karm.pngbin0 -> 19634 bytes
-rw-r--r--doc/karm/systray.pngbin0 -> 5876 bytes
-rw-r--r--doc/kleopatra/Makefile.am4
-rw-r--r--doc/kleopatra/index.docbook1458
-rw-r--r--doc/kmail/Makefile.am4
-rw-r--r--doc/kmail/configure.docbook2048
-rw-r--r--doc/kmail/credits-and-licenses.docbook153
-rw-r--r--doc/kmail/faq.docbook590
-rw-r--r--doc/kmail/getting-started.docbook329
-rw-r--r--doc/kmail/importing.docbook270
-rw-r--r--doc/kmail/index.docbook161
-rw-r--r--doc/kmail/intro.docbook56
-rw-r--r--doc/kmail/menus.docbook2222
-rw-r--r--doc/kmail/using-kmail.docbook2303
-rw-r--r--doc/knode/Makefile.am9
-rw-r--r--doc/knode/commands.docbook1890
-rw-r--r--doc/knode/credits.docbook55
-rw-r--r--doc/knode/eyes.pngbin0 -> 140 bytes
-rw-r--r--doc/knode/faq.docbook189
-rw-r--r--doc/knode/gloss.docbook257
-rw-r--r--doc/knode/greyball.pngbin0 -> 181 bytes
-rw-r--r--doc/knode/greyballchk.pngbin0 -> 219 bytes
-rw-r--r--doc/knode/index.docbook130
-rw-r--r--doc/knode/install.docbook54
-rw-r--r--doc/knode/introduction.docbook56
-rw-r--r--doc/knode/journey.docbook530
-rw-r--r--doc/knode/knode-cleanup.pngbin0 -> 19537 bytes
-rw-r--r--doc/knode/knode-colors-fonts.pngbin0 -> 23760 bytes
-rw-r--r--doc/knode/knode-composer-attachments.pngbin0 -> 27665 bytes
-rw-r--r--doc/knode/knode-composer-settings.pngbin0 -> 23566 bytes
-rw-r--r--doc/knode/knode-edit-filter.pngbin0 -> 16449 bytes
-rw-r--r--doc/knode/knode-edit-header1.pngbin0 -> 9364 bytes
-rw-r--r--doc/knode/knode-edit-header2.pngbin0 -> 9490 bytes
-rw-r--r--doc/knode/knode-filters.pngbin0 -> 34596 bytes
-rw-r--r--doc/knode/knode-followup.pngbin0 -> 21113 bytes
-rw-r--r--doc/knode/knode-header-settings.pngbin0 -> 24015 bytes
-rw-r--r--doc/knode/knode-identity.pngbin0 -> 24099 bytes
-rw-r--r--doc/knode/knode-mail-account.pngbin0 -> 17420 bytes
-rw-r--r--doc/knode/knode-new-article.pngbin0 -> 20641 bytes
-rw-r--r--doc/knode/knode-news-account.pngbin0 -> 11104 bytes
-rw-r--r--doc/knode/knode-post-settings.pngbin0 -> 25790 bytes
-rw-r--r--doc/knode/knode-read-news-appearance-dialog.pngbin0 -> 29498 bytes
-rw-r--r--doc/knode/knode-read-news-settings.pngbin0 -> 25953 bytes
-rw-r--r--doc/knode/knode-reply.pngbin0 -> 19592 bytes
-rw-r--r--doc/knode/knode-rule-editor.pngbin0 -> 16638 bytes
-rw-r--r--doc/knode/knode-search.pngbin0 -> 16101 bytes
-rw-r--r--doc/knode/knode-start.pngbin0 -> 24388 bytes
-rw-r--r--doc/knode/knode-subscribe.pngbin0 -> 15885 bytes
-rw-r--r--doc/knode/knode-views.pngbin0 -> 38641 bytes
-rw-r--r--doc/knode/more.docbook134
-rw-r--r--doc/knode/newsubs.pngbin0 -> 193 bytes
-rw-r--r--doc/knode/redball.pngbin0 -> 191 bytes
-rw-r--r--doc/knode/redballchk.pngbin0 -> 211 bytes
-rw-r--r--doc/knode/using-firststart.docbook1859
-rw-r--r--doc/knode/using-morefeatures.docbook855
-rw-r--r--doc/knode/using-subscribing.docbook1367
-rw-r--r--doc/knotes/Makefile.am4
-rw-r--r--doc/knotes/index.docbook383
-rw-r--r--doc/konsolekalendar/Makefile.am4
-rw-r--r--doc/konsolekalendar/index.docbook871
-rw-r--r--doc/kontact/Makefile.am4
-rw-r--r--doc/kontact/calendar-sidebar-icon.pngbin0 -> 4312 bytes
-rw-r--r--doc/kontact/configuration-components.pngbin0 -> 20385 bytes
-rw-r--r--doc/kontact/configuration-main.pngbin0 -> 71470 bytes
-rw-r--r--doc/kontact/configuration-select-components.pngbin0 -> 26329 bytes
-rw-r--r--doc/kontact/configuration-starting-component.pngbin0 -> 71172 bytes
-rw-r--r--doc/kontact/configuration-summary-view-kpilot.pngbin0 -> 95032 bytes
-rw-r--r--doc/kontact/configuration-summary-view.pngbin0 -> 47610 bytes
-rw-r--r--doc/kontact/index.docbook1097
-rw-r--r--doc/kontact/kaddressbook-sidebar-icon.pngbin0 -> 5084 bytes
-rw-r--r--doc/kontact/main-view.pngbin0 -> 57385 bytes
-rw-r--r--doc/kontact/menu-bar-kmail.pngbin0 -> 892 bytes
-rw-r--r--doc/kontact/menu-bar-korganizer.pngbin0 -> 819 bytes
-rw-r--r--doc/kontact/menu-bar-summary.pngbin0 -> 430 bytes
-rw-r--r--doc/kontact/new-menu.pngbin0 -> 93001 bytes
-rw-r--r--doc/kontact/settings-menu-kmail.pngbin0 -> 6444 bytes
-rw-r--r--doc/kontact/side-pane.pngbin0 -> 20231 bytes
-rw-r--r--doc/kontact/summary-view-calendar.pngbin0 -> 7356 bytes
-rw-r--r--doc/kontact/summary-view-contacts.pngbin0 -> 7606 bytes
-rw-r--r--doc/kontact/summary-view-kpilot.pngbin0 -> 14406 bytes
-rw-r--r--doc/kontact/summary-view-mail.pngbin0 -> 4735 bytes
-rw-r--r--doc/kontact/summary-view-newsticker.pngbin0 -> 15615 bytes
-rw-r--r--doc/kontact/summary-view-notes.pngbin0 -> 4735 bytes
-rw-r--r--doc/kontact/summary-view-repositioning.pngbin0 -> 103520 bytes
-rw-r--r--doc/kontact/summary-view-todos.pngbin0 -> 7303 bytes
-rw-r--r--doc/kontact/summary-view-weather.pngbin0 -> 11760 bytes
-rw-r--r--doc/kontact/summary-view.pngbin0 -> 90481 bytes
-rw-r--r--doc/kontact/todo-list-sidebar-icon.pngbin0 -> 5257 bytes
-rw-r--r--doc/korganizer/Makefile.am2
-rw-r--r--doc/korganizer/event-attachments.pngbin0 -> 19806 bytes
-rw-r--r--doc/korganizer/event-attendees.pngbin0 -> 15705 bytes
-rw-r--r--doc/korganizer/event-freebusy.pngbin0 -> 16779 bytes
-rw-r--r--doc/korganizer/event-general.pngbin0 -> 15095 bytes
-rw-r--r--doc/korganizer/event-recurrence.pngbin0 -> 16984 bytes
-rw-r--r--doc/korganizer/groupevent.pngbin0 -> 1059 bytes
-rw-r--r--doc/korganizer/i_actions_newevent.pngbin0 -> 837 bytes
-rw-r--r--doc/korganizer/i_actions_newtodo.pngbin0 -> 1106 bytes
-rw-r--r--doc/korganizer/i_copy.pngbin0 -> 3781 bytes
-rw-r--r--doc/korganizer/i_cut.pngbin0 -> 2169 bytes
-rw-r--r--doc/korganizer/i_edit_delete.pngbin0 -> 951 bytes
-rw-r--r--doc/korganizer/i_edit_find.pngbin0 -> 2396 bytes
-rw-r--r--doc/korganizer/i_edit_redo.pngbin0 -> 1172 bytes
-rw-r--r--doc/korganizer/i_edit_undo.pngbin0 -> 1160 bytes
-rw-r--r--doc/korganizer/i_file_close.pngbin0 -> 1594 bytes
-rw-r--r--doc/korganizer/i_file_new.pngbin0 -> 1369 bytes
-rw-r--r--doc/korganizer/i_file_open.pngbin0 -> 2232 bytes
-rw-r--r--doc/korganizer/i_file_print.pngbin0 -> 1633 bytes
-rw-r--r--doc/korganizer/i_file_quit.pngbin0 -> 1915 bytes
-rw-r--r--doc/korganizer/i_file_revert.pngbin0 -> 1651 bytes
-rw-r--r--doc/korganizer/i_file_save.pngbin0 -> 1348 bytes
-rw-r--r--doc/korganizer/i_file_saveas.pngbin0 -> 2069 bytes
-rw-r--r--doc/korganizer/i_go_backward.pngbin0 -> 1625 bytes
-rw-r--r--doc/korganizer/i_go_forward.pngbin0 -> 1647 bytes
-rw-r--r--doc/korganizer/i_go_to_today.pngbin0 -> 1385 bytes
-rw-r--r--doc/korganizer/i_paste.pngbin0 -> 1458 bytes
-rw-r--r--doc/korganizer/i_settings_prefs.pngbin0 -> 1839 bytes
-rw-r--r--doc/korganizer/i_view_day.pngbin0 -> 1155 bytes
-rw-r--r--doc/korganizer/i_view_journal.pngbin0 -> 622 bytes
-rw-r--r--doc/korganizer/i_view_list.pngbin0 -> 891 bytes
-rw-r--r--doc/korganizer/i_view_month.pngbin0 -> 1304 bytes
-rw-r--r--doc/korganizer/i_view_todo_list.pngbin0 -> 1358 bytes
-rw-r--r--doc/korganizer/i_view_week.pngbin0 -> 1204 bytes
-rw-r--r--doc/korganizer/i_view_whatsnext.pngbin0 -> 876 bytes
-rw-r--r--doc/korganizer/i_view_work_week.pngbin0 -> 1082 bytes
-rw-r--r--doc/korganizer/i_view_xdays.pngbin0 -> 1226 bytes
-rw-r--r--doc/korganizer/index.docbook4982
-rw-r--r--doc/korganizer/korganizer-resource.pngbin0 -> 5456 bytes
-rw-r--r--doc/korganizer/o2v_importing1.pngbin0 -> 34424 bytes
-rw-r--r--doc/korganizer/o2v_importing2.pngbin0 -> 43891 bytes
-rw-r--r--doc/korganizer/o2v_importing3.pngbin0 -> 34798 bytes
-rw-r--r--doc/korganizer/o2v_main.pngbin0 -> 4108 bytes
-rw-r--r--doc/korganizer/o2v_progress.pngbin0 -> 7486 bytes
-rw-r--r--doc/korganizer/o2v_save.pngbin0 -> 13672 bytes
-rw-r--r--doc/korganizer/o2v_warning.pngbin0 -> 4297 bytes
-rw-r--r--doc/korganizer/organizer.pngbin0 -> 698 bytes
-rw-r--r--doc/korganizer/outlook-to-vcalendar.docbook283
-rw-r--r--doc/korganizer/plugins-chapter.docbook48
-rw-r--r--doc/korganizer/remotefile-resource.pngbin0 -> 10422 bytes
-rw-r--r--doc/korganizer/todo-general.pngbin0 -> 15158 bytes
-rw-r--r--doc/korn/Makefile.am4
-rw-r--r--doc/korn/index.docbook238
-rw-r--r--doc/kpilot/Makefile.am2
-rw-r--r--doc/kpilot/address-app.pngbin0 -> 45741 bytes
-rw-r--r--doc/kpilot/conduit-knotes.pngbin0 -> 10540 bytes
-rw-r--r--doc/kpilot/conduit-mal.pngbin0 -> 17072 bytes
-rw-r--r--doc/kpilot/conduit-palmdoc.pngbin0 -> 19899 bytes
-rw-r--r--doc/kpilot/conduit-popmail-kmail.pngbin0 -> 13320 bytes
-rw-r--r--doc/kpilot/conduit-sysinfo.pngbin0 -> 17411 bytes
-rw-r--r--doc/kpilot/conduit-vcal.pngbin0 -> 18217 bytes
-rw-r--r--doc/kpilot/configuration.docbook1783
-rw-r--r--doc/kpilot/daemon-menu.pngbin0 -> 42531 bytes
-rw-r--r--doc/kpilot/db-app.pngbin0 -> 67476 bytes
-rw-r--r--doc/kpilot/faq.docbook386
-rw-r--r--doc/kpilot/file-app.pngbin0 -> 52976 bytes
-rw-r--r--doc/kpilot/index.docbook280
-rw-r--r--doc/kpilot/main-app.pngbin0 -> 98692 bytes
-rw-r--r--doc/kpilot/memo-app.pngbin0 -> 42851 bytes
-rw-r--r--doc/kpilot/setup-address.pngbin0 -> 19165 bytes
-rw-r--r--doc/kpilot/setup-conduit.pngbin0 -> 14841 bytes
-rw-r--r--doc/kpilot/setup-dbspecial.pngbin0 -> 14014 bytes
-rw-r--r--doc/kpilot/setup-general.pngbin0 -> 14136 bytes
-rw-r--r--doc/kpilot/setup-hotsync.pngbin0 -> 16480 bytes
-rw-r--r--doc/kpilot/setup-items.pngbin0 -> 5383 bytes
-rw-r--r--doc/kpilot/setup-startup-exit.pngbin0 -> 15955 bytes
-rw-r--r--doc/kpilot/setup-tabs.pngbin0 -> 69881 bytes
-rw-r--r--doc/kpilot/setup-viewer.pngbin0 -> 17644 bytes
-rw-r--r--doc/kpilot/sidebar.pngbin0 -> 42645 bytes
-rw-r--r--doc/kpilot/sync.docbook450
-rw-r--r--doc/kpilot/todo-app.pngbin0 -> 42459 bytes
-rw-r--r--doc/kpilot/toolbar_backup.pngbin0 -> 1036 bytes
-rw-r--r--doc/kpilot/toolbar_hotsync.pngbin0 -> 984 bytes
-rw-r--r--doc/kpilot/usage.docbook648
-rw-r--r--doc/kpilot/wizard-conduits.pngbin0 -> 33694 bytes
-rw-r--r--doc/kpilot/wizard-connection.pngbin0 -> 30923 bytes
-rw-r--r--doc/kpilot/wizard-general.pngbin0 -> 27281 bytes
-rw-r--r--doc/ktnef/Makefile.am4
-rw-r--r--doc/ktnef/index.docbook75
-rw-r--r--doc/kwatchgnupg/Makefile.am4
-rw-r--r--doc/kwatchgnupg/index.docbook282
234 files changed, 38845 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 00000000..6812bd2d
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,5 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+SUBDIRS = $(AUTODIRS)
+
diff --git a/doc/akregator/Makefile.am b/doc/akregator/Makefile.am
new file mode 100644
index 00000000..171f575c
--- /dev/null
+++ b/doc/akregator/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
diff --git a/doc/akregator/add-feed.png b/doc/akregator/add-feed.png
new file mode 100644
index 00000000..0fdfe0cf
--- /dev/null
+++ b/doc/akregator/add-feed.png
Binary files differ
diff --git a/doc/akregator/add-feed2.png b/doc/akregator/add-feed2.png
new file mode 100644
index 00000000..744da128
--- /dev/null
+++ b/doc/akregator/add-feed2.png
Binary files differ
diff --git a/doc/akregator/add-folder.png b/doc/akregator/add-folder.png
new file mode 100644
index 00000000..e4953481
--- /dev/null
+++ b/doc/akregator/add-folder.png
Binary files differ
diff --git a/doc/akregator/add-folder2.png b/doc/akregator/add-folder2.png
new file mode 100644
index 00000000..53590dd3
--- /dev/null
+++ b/doc/akregator/add-folder2.png
Binary files differ
diff --git a/doc/akregator/advanced-tab.png b/doc/akregator/advanced-tab.png
new file mode 100644
index 00000000..59dcac6c
--- /dev/null
+++ b/doc/akregator/advanced-tab.png
Binary files differ
diff --git a/doc/akregator/appearance-tab.png b/doc/akregator/appearance-tab.png
new file mode 100644
index 00000000..3c3e29fa
--- /dev/null
+++ b/doc/akregator/appearance-tab.png
Binary files differ
diff --git a/doc/akregator/archive-tab.png b/doc/akregator/archive-tab.png
new file mode 100644
index 00000000..41e52dad
--- /dev/null
+++ b/doc/akregator/archive-tab.png
Binary files differ
diff --git a/doc/akregator/browser-tab.png b/doc/akregator/browser-tab.png
new file mode 100644
index 00000000..a02e93cc
--- /dev/null
+++ b/doc/akregator/browser-tab.png
Binary files differ
diff --git a/doc/akregator/general-tab.png b/doc/akregator/general-tab.png
new file mode 100644
index 00000000..3cea71a7
--- /dev/null
+++ b/doc/akregator/general-tab.png
Binary files differ
diff --git a/doc/akregator/index.docbook b/doc/akregator/index.docbook
new file mode 100644
index 00000000..54b653de
--- /dev/null
+++ b/doc/akregator/index.docbook
@@ -0,0 +1,1163 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY akregator "<application>Akregator</application>">
+ <!ENTITY kappname "&akregator;">
+ <!ENTITY package "kdepim">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &akregator; Handbook</title>
+
+<authorgroup>
+
+<author>
+<firstname>Frank</firstname>
+<surname>Osterfeld</surname>
+<affiliation><address><email>frank.osterfeld@kdemail.net</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>Anne-Marie</firstname>
+<surname>Mahfouf</surname>
+<affiliation><address>&Anne-Marie.Mahfouf.mail;
+</address></affiliation>
+</author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+<copyright>
+<year>2006</year>
+<holder>Frank Osterfeld</holder>
+</copyright>
+<copyright>
+<year>2006</year>
+<holder>&Anne-Marie.Mahfouf;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2006-12-08</date>
+<releaseinfo>1.2.5</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+&akregator; is a program to read <acronym>RSS</acronym> and other online news feeds.
+</para>
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Akregator</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<sect1 id="what-is-akregator">
+<title>What is &akregator;?</title>
+
+<para>&akregator; is a &kde; application for reading online news feeds. It has a
+powerful, user-friendly interface for reading feeds and the management of
+them.</para>
+
+<para>&akregator; is a lightweight and fast program for displaying news items
+provided by feeds, supporting all commonly-used versions of
+<acronym>RSS</acronym> and Atom feeds. Its interface is similar to those of
+e-mail programs, thus hopefully being very familiar to the user. Useful features include searching within article titles, management of feeds in folders and setting archiving
+preferences. Feeds can be displayed in a similar manner to e-mails. Websites related to a feed can be shown in &akregator;'s embedded browser or, at the users' choice, opened in an external browser.</para>
+</sect1>
+
+<sect1 id="rss-and-atom-feeds">
+<title><acronym>RSS</acronym> and Atom feeds</title>
+
+<para><acronym>RSS</acronym> (Really Simple Syndication) is an &XML;-based format used for publishing news or articles in a machine-readable form. An <acronym>RSS</acronym>
+or Atom file is also called a feed. A program that can be used to read such feeds is
+called a feed reader or aggregator, hence the title of the application, &akregator;.</para>
+
+<para>&akregator; automatically extracts new items from the feed and displays them in a human-friendly form to the user. The user can therefore save time with regularly-visited websites, as they need no longer manually check whether there are new pieces of information available.</para>
+<para><acronym>RSS</acronym> is available in different versions which
+are not compatible with each other (this situation caused by competing companies):
+<acronym>RSS</acronym> 0.9, <acronym>RSS</acronym> 1.0 and
+<acronym>RSS</acronym> 2.0. Atom is also an &XML;-based feed language which has
+been redesigned to fit the needs of webloggers and news sites. Atom attempts to
+replace <acronym>RSS</acronym> feeds and remove the uncertainty with
+incompatiblities in the different <acronym>RSS</acronym> versions.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="quick-start">
+<title>Quick Start to &akregator;</title>
+
+<para>
+This section describes how to start using &akregator;. It explains the user
+interface and shows you how to add your own feed to the list. This section is
+particularily interesting if you are not yet familiar with the
+general <acronym>RSS</acronym>/Atom and feed aggregator concept.
+</para>
+
+<sect1 id="main-window">
+<title>The Main Window</title>
+<!--part of kontact
+say how to start it -->
+<para>When you first start &akregator;, you see its main window:
+<screenshot>
+<screeninfo>&akregator; main window</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="main-window.png" format="PNG" /></imageobject>
+<textobject><phrase>&akregator; main window</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+The main window consists of the feed list, the article list and the article
+viewer.
+</para>
+<para>
+The feed list is on the left. In the tree, you have news feeds you can
+select. A news feed is a collection of articles: for example, the recent news of
+a news site or the new entries of a blog. The default list contains feeds related to
+the &kde; project, but of course you can add your own feeds and remove the ones
+you are not interested in.
+<screenshot>
+<screeninfo>All articles are fetched</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="main-window2.png" format="PNG" /></imageobject>
+<textobject><phrase>All articles are fetched</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para>
+<para>
+In the upper right is the article list. It contains all the articles of the
+feed selected in the feed list (if it is empty, you must first fetch the feed). The list shows the headlines of the articles and the date when
+they were published. By default, the newest articles are at the top.
+<screenshot>
+<screeninfo>The article list</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="main-window3.png" format="PNG" /></imageobject>
+<textobject><phrase>The article list for one feed</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para>
+<para>
+If you select an article, it will be displayed in the article viewer in the
+lower right of the window. Depending on the feed, it contains either only a headline, a short
+summary, or the complete article content.
+<screenshot>
+<screeninfo>Reading an article from Planet &kde;</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="main-window4.png" format="PNG" /></imageobject>
+<textobject><phrase>Reading an article from Planet &kde;</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para>
+</sect1>
+
+<sect1 id="add-feed">
+<title>Adding a feed</title>
+<para>&akregator; provides you with some default feeds related to &kde; - of course, you
+probably want to add your own feeds. Good candidates are the news sites you visit
+regularly.</para>
+
+<itemizedlist>
+<listitem><para>
+Go to the menu <guimenu>Feed</guimenu> and choose <guimenuitem>Add
+Feed...</guimenuitem> or use the default keyboard shortcut (<keycap>Insert</keycap>).
+The following dialog appears, with an input line labeled <guilabel>Feed
+URL:</guilabel>.
+<screenshot>
+<screeninfo>Add a new feed</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="add-feed.png" format="PNG" /></imageobject>
+<textobject><phrase>Add a new feed</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para></listitem>
+
+<listitem><para>
+Enter
+<userinput>www.slashdot.org</userinput>
+or <userinput>http://www.slashdot.org </userinput> in the line edit next
+to <guilabel>Feed URL</guilabel> and click <guibutton>OK</guibutton>.
+</para></listitem>
+<listitem><para>
+The feed settings dialog appears and you can modify the default options. When
+you are happy with the feed settings, click <guibutton>OK</guibutton> again.
+<screenshot>
+<screeninfo>The feed properties dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="add-feed2.png" format="PNG" /></imageobject>
+<textobject><phrase>The feed properties dialog</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para></listitem>
+<listitem><para>
+Now Slashdot has been added to your feed list.
+</para> </listitem>
+</itemizedlist>
+<para>
+There are multiple other ways to find and add interesting feeds. Within KDE,
+websites browsed with &konqueror; will display the recognizable &quot;RSS
+lozenge&quot;<inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="rss3.png" format="PNG"/>
+ </imageobject>
+ </inlinemediaobject>in the bottom-right if a compatible news feed is
+detected at the website. Just left-click on the icon and choose
+<guimenuitem>Add Feed to &akregator;</guimenuitem>:
+<screenshot>
+<screeninfo>Automatically finding feeds through &konqueror;</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="konq2.png" format="PNG" /></imageobject>
+<textobject><phrase>Automatically finding feeds through &konqueror;</phrase></textobject>
+</mediaobject>
+</screenshot>
+On pages with this RSS icon<inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="rss.png" format="PNG"/>
+ </imageobject>
+ </inlinemediaobject>, right-click on the icon and choose in the context
+ menu <guimenuitem>Add Feed to &akregator;</guimenuitem>:
+ <screenshot>
+ <screeninfo>Automatically finding feeds through &konqueror;</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="konq.png" format="PNG"
+/></imageobject>
+ <textobject><phrase>Automatically finding feeds through
+ &konqueror;</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para>
+</sect1>
+
+<sect1 id="creating-folder">
+<title>Creating a Folder</title>
+<para>After adding your own feeds, you may want to group them in some way,
+rather than just leave them unsorted. So let us create a folder for the
+Slashdot feed we just added:</para>
+<itemizedlist>
+<listitem><para>Select the parent folder of the new folder. In this example, we
+select <guilabel>All Feeds</guilabel>.
+</para></listitem>
+<listitem><para>Open <guimenu>Feed</guimenu>
+<guimenuitem>New Folder...</guimenuitem>.
+Enter <userinput>News</userinput> (or a more appropriate name for the feed category) in the line edit and choose <guibutton>OK</guibutton>.
+<screenshot>
+<screeninfo>The New Folder dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="add-folder.png" format="PNG" /></imageobject>
+<textobject><phrase>The New Folder dialog</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para> </listitem>
+<listitem><para>Now you can drag the Slashdot feed to the new folder.
+<screenshot>
+<screeninfo>The News folder in the feed list</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="add-folder2.png" format="PNG" /></imageobject>
+<textobject><phrase>The News folder in the feed list</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para> </listitem>
+</itemizedlist>
+</sect1>
+
+<sect1 id="browsing-inside">
+<title>Browsing inside of &akregator;</title>
+<para>When reading feed articles, often you may want to read the web page that
+belongs to the article: some articles only contain the headline, and not the actual
+content. In this case, you need to visit the web page to read the complete article. Or perhaps
+an article links to some website, or you are reading a blog and want to comment
+on an entry. For these situations, &akregator; contains a simple web browser.
+Whenever you follow a link in the article viewer, &akregator; opens the link in
+new tab:</para>
+<note><para>Note that the browser in &akregator; is not intended to replace your
+favorite Web Browser. It is meant for reading articles, commenting on them, or
+following up a link quickly. It is not meant for browsing the web in general. It
+lacks many features fully-fledged web browsers offer.</para></note>
+</sect1>
+</chapter>
+
+<chapter id="configuration">
+<title>Configuring &akregator;</title>
+<para>Most of &akregator;'s options are listed in the &akregator; configuration
+dialog. The configuration dialog can be found in the menu under <menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure &akregator;...</guimenuitem>
+</menuchoice></para>
+<sect1 id="general-tab">
+<title>General</title>
+<para>The General tab contains the basic and otherwise-uncategorizable options of &akregator;.</para>
+<screenshot>
+<screeninfo>The General tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="general-tab.png" format="PNG" /></imageobject>
+<textobject><phrase>The General tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Global</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Show tray icon</guilabel></term>
+<listitem><para>Display the &akregator; icon in the systray.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Use notifications for all feeds</guilabel></term>
+<listitem><para>Set global notifications for all feeds. This setting will
+override the individual notification value of each feed. When enabled, &akregator; will notify you of all new articles fetched in any feed. If you only want to enable notifications for some (but not all) feeds, leave this option disabled and enable notifications for the each specific feed using the individual feed properties dialog.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Use interval fetching</guilabel></term>
+<listitem><para>If this is unchecked, interval checking is disabled. However, if this is checked, you can set in <guilabel>Fetch feeds
+every:</guilabel> the interval that &akregator; will automatically check for new feed entries. Note that fetching articles generates traffic and therefore may be costly to the provider hosting the feed you're reading. Some sites may even block connections from your computer if you attempt to fetch the feed too often. In general, 30 minutes is a good choice. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Fetch feeds every:</guilabel></term>
+<listitem><para>This is enabled when <guilabel>Use interval
+fetching</guilabel> is checked. You can specify a time interval, after which
+feeds are checked for new articles. Default is 30 minutes.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Startup</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Mark all feeds as read on startup</guilabel></term>
+<listitem><para>When enabled, &akregator; marks all articles as read when
+started.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Fetch all feeds on startup</guilabel></term>
+<listitem><para>When enabled, &akregator; fetches all feeds right after
+start.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Network</guilabel></term>
+<listitem>
+<variablelist>
+<varlistentry>
+<term><guilabel>Use the browser cache (less network traffic)</guilabel></term>
+<listitem><para>When enabled, the &kde;-wide browser cache settings are used when
+updating feeds. You can configure the &kde;-wide browser cache either in
+&kcontrolcenter; or in &konqueror; configuration dialog.</para>
+<note><para>You should leave this option enabled whenever possible. Disabling
+this option leads to increased network traffic. The traffic caused by
+aggregators not using caching increases the costs for providers and may decrease the number of feeds are offered in future.</para></note>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+<sect1 id="archive-tab">
+<title>Archive</title>
+<para>Archiving articles means storing the links of articles. Here you can limit the
+number of articles stored and the method used for archiving. These settings are
+global settings, used by all feeds within &akregator;. If you want to use a custom
+setting for a feed, you can set it in each feed properties dialog in the archive
+tab.</para>
+<screenshot>
+<screeninfo>The Archive tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="archive-tab.png" format="PNG" /></imageobject>
+<textobject><phrase>The Archive tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Default Archive Settings</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Keep all articles</guilabel></term>
+<listitem><para>All articles are kept forever.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Limit feed archive size to:</guilabel></term>
+<listitem><para>If the number of articles exceeds the chosen limit, the oldest
+articles are deleted. Note that flagged articles are ignored when counting the
+number of articles: if your limit is 500, and you have 510 unflagged and 50
+flagged articles, &akregator; will ignore the 50 flagged ones and only delete
+the 10 oldest unflagged articles. So in this example, 550 articles would be kept.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Delete articles older than:</guilabel></term>
+<listitem><para>Articles older than the specified number of days are deleted from the archive, unless they have the keep flag set. &akregator; checks for expired articles at startup and then once per hour, so expiry may be delayed.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Disable archiving</guilabel></term>
+<listitem><para>No articles are stored - all articles are discarded when
+quitting &akregator;.</para> </listitem>
+</varlistentry>
+</variablelist>
+
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Do not expire important articles</guilabel></term>
+<listitem><para>Right clicking on an article opens a context menu where
+you can mark this article as Important. Articles marked as Important will not
+expire, they will be kept.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+<sect1 id="appearance-tab">
+<title>Appearance</title>
+<para>On this page you can configure the appearance of the article viewer and
+the browser tabs. You can specify the font sizes and families to be used.
+</para>
+<screenshot>
+<screeninfo>The Appearance tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="appearance-tab.png" format="PNG"
+/></imageobject>
+<textobject><phrase>The Appearance tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Font Size</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Minimum font size</guilabel></term>
+<listitem><para>Set the minimum size for the article viewer</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Medium font size</guilabel></term>
+<listitem><para>Set the default font size for the article viewer</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Fonts</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Standard font:</guilabel></term>
+<listitem><para>In the article viewer, the content is rendered using
+the Standard font in Medium font size. If you change the Standard font,
+the change will be applied in the article viewer.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Fixed font:</guilabel></term>
+<listitem><para>If the article uses a fixed-width font in the article viewer, the
+content will be rendered using this font family in MediumĀ font size. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Serif font:</guilabel></term>
+<listitem><para>If the article uses Serif fonts, they will be
+rendered using the family you choose here in Medium font size.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Sans serif font:</guilabel></term>
+<listitem><para>If the article uses Sans-serif fonts, they will be
+rendered using the family you choose here in Medium font size.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Underline links</guilabel></term>
+<listitem><para>Check this if you want links to be underlined by default.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+<sect1 id="browser-tab">
+<title>Browser</title>
+<para>This tab allows you to customize the behavior of the internal browser
+tabs.</para>
+<screenshot>
+<screeninfo>The Browser tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="browser-tab.png" format="PNG" /></imageobject>
+<textobject><phrase>The Browser tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Left mouse click</guilabel></term>
+<listitem><para>You can choose three actions for the Left mouse click
+action: <guilabel>Open in Tab</guilabel> (open the link in a tab and put this
+tab in focus), <guilabel>Open in Background Tab</guilabel> (open the link in a
+tab but keep the current tab in focus) and <guilabel>Open in External
+Browser (open in a new window with your default browser)</guilabel>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Middle mouse click</guilabel></term>
+<listitem><para>As above, you can set one of the three actions for the
+middle mouse click.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>For External Browsing</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Use default &kde; web browser</guilabel></term>
+<listitem><para>If this is checked, &akregator; will use the web browser
+you set in &kcontrolcenter;. It may be the KDE default, &konqueror;, or another browser
+depending on what you set here.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Use this command:</guilabel></term>
+<listitem><para>You can use another web browser for &akregator; other than your
+&kde; default. If you wish to do so, check this option and enter the command for the
+browser, provided it is in your $<envar>PATH</envar>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Show tab close button on hover</guilabel></term>
+<listitem><para>If this option is checked, the close button will appear when
+you move your mouse on the left side of the tab title so you can more easily
+close tabs.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+<sect1 id="advanced-tab">
+<title>Advanced</title>
+<para>The Advanced tab allows you to set more advanced options. If you
+are not sure about their effect, you can just leave the dafault ones.</para>
+<screenshot>
+<screeninfo>The Advanced tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="advanced-tab.png" format="PNG" /></imageobject>
+<textobject><phrase>The Advanced tab</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Archive</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Archive backend:</guilabel></term>
+<listitem><para>&akregator; currently only uses the Metakit database but for &kde; 4, &akregator; will offer other database backends.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Article List</guilabel></term>
+<listitem>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Mark selected article read after</guilabel></term>
+<listitem><para>Default is 0 seconds, which means that as soon as
+you click on an article it is marked as read. You can choose to mark any
+article as read after a specified number of seconds.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Reset search bar when changing feeds</guilabel></term>
+<listitem><para>This will clear the search bar when you change feed.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+</chapter>
+
+<chapter id="commands">
+<title>Command Reference</title>
+
+<sect1 id="akregator-mainwindow">
+<title>Menus and Shortcut Keys</title>
+
+<sect2>
+<title>The <guimenu>File</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Import feeds...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the import feeds dialog</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Export feeds...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the save as dialog</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Print...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the print dialog</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Quit</action> &akregator;</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Edit</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycap>F2</keycap>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Edit Feed...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Edit</action> current feed to change its properties in
+the Properties dialog</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Alt;<keycap>Delete</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Delete feed</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Delete</action> current feed</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Copy</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Copy selected text to the clipboard</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Select All</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Select all text in the article viewer</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Find...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Launch</action> the Find Text dialog to allow you to
+search for text in the article viewer</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycap>F3</keycap>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Find Next</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the nearest match (down the list) of the
+search term (text or regular expression) searched for within the article viewer, starting
+from cursor position</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>View</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>View Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> the View Mode for &akregator;</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>+</keycap></keycombo></shortcut>
+<guimenu>View</guimenu>
+<guimenuitem>Increase Font Sizes</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Increase</action> the font size in the article
+viewer</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>-</keycap></keycombo></shortcut>
+<guimenu>View</guimenu>
+<guimenuitem>Decrease Font Sizes</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Decrease</action> the font size in the article
+viewer</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Go</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>Left</keycap></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Previous Article</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the previous article in the article
+list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>-</keycap></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Previous Unread Article</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the previous unread
+article in the article list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>Right</keycap></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Next Article</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the next article in the article
+list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>+</keycap></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Next Unread Article</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the next unread article in the article
+list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>P</keycap></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Previous Feed</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the previous feed in the feed
+list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Alt;<keycap>-</keycap></keycombo></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Previous Unread Feed</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the previous unread feed in the feed
+list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>N</keycap></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Next Feed</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the next feed in the feed
+list</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Alt;<keycap>+</keycap></keycombo></shortcut>
+<guimenu>Go</guimenu>
+<guimenuitem>Next Unread Feed</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Go</action> to the next unread feed in the feed
+list</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Feed</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>Insert</keycap></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>Add Feed...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the Add Feed dialog</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Shift;<keycap>Insert</keycap></keycombo></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>New Folder...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the Add Folder dialog</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>Mark Feed as Read</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Mark</action> the current feed as read</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl; &Shift;<keycap>R</keycap></keycombo></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>Mark All Feeds as Read</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Mark</action> all feeds as already
+read</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>F5</keycap></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>Fetch Feed</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Fetch</action> the current feed</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>L</keycap></keycombo></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>Fetch All Feeds</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Fetch</action> all feeds</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>Escape</keycap></shortcut>
+<guimenu>Feed</guimenu>
+<guimenuitem>Abort Fetches</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Stop</action> &akregator; fetching
+feeds</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Article</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Shift;<keycap>Return</keycap></keycombo></shortcut>
+<guimenu>Article</guimenu>
+<guimenuitem>Open in Tab</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the current article in a
+tab within &akregator;</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl; &Shift;<keycap>Return</keycap></keycombo></shortcut>
+<guimenu>Article</guimenu>
+<guimenuitem>Open in External Browser.</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the current article iin
+an external browser</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo
+action="simul">&Ctrl;<keycap>I</keycap></keycombo></shortcut>
+<guimenu>Article</guimenu>
+<guimenuitem>Mark as Important</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Mark</action> the current article as
+important</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Article</guimenu>
+<guimenuitem>Mark as</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Mark</action> the current article as
+Read, New or Unread</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>Delete</keycap></shortcut>
+<guimenu>Article</guimenu>
+<guimenuitem>Delete</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Delete</action> the current article</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Article</guimenu>
+<guimenuitem>Send Link Address...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> your mail client and attach the link
+in the mail.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Article</guimenu>
+<guimenuitem>Send File...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> your mail client and attach the file
+in the mail.
+</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Toolbars</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Toggle</action> the toolbars</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggle</action> the statusbar</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Quick Filter</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggle</action> the Quick Filter (Show/Hide it)
+<screenshot>
+<screeninfo>The Quick Filter</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="quick-filter.png" format="PNG" /></imageobject>
+<textobject><phrase>The Quick Filter</phrase></textobject>
+</mediaobject>
+</screenshot>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Notifications...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Display</action> the Notifications Settings dialog
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &akregator;...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Display</action> the &akregator; settings dialog
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> standard &kde; setting dialog that allows
+you to choose different shortcut keys for different actions
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Configure</action> the items you want to put in the
+toolbar
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Help</guimenu> Menu</title>
+&help.menu.documentation;
+</sect2>
+</sect1>
+</chapter>
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>
+&akregator;
+</para>
+<para>
+Program copyright 2004-2006 Frank Osterfeld
+<email>frank.osterfeld@kdemail.net</email>
+</para>
+
+<para>
+Documentation copyright 2006
+Frank Osterfeld <email>frank.osterfeld@kdemail.net</email>
+</para>
+
+<para>
+Documentation copyright 2006
+&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL; <!-- FDL: do not remove -->
+&underGPL; <!-- GPL License -->
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-akregator">
+<title>How to obtain &akregator;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and installation</title>
+
+&install.compile.documentation;
+
+</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:
+--> \ No newline at end of file
diff --git a/doc/akregator/konq.png b/doc/akregator/konq.png
new file mode 100644
index 00000000..0dda199b
--- /dev/null
+++ b/doc/akregator/konq.png
Binary files differ
diff --git a/doc/akregator/konq2.png b/doc/akregator/konq2.png
new file mode 100644
index 00000000..57c92b6d
--- /dev/null
+++ b/doc/akregator/konq2.png
Binary files differ
diff --git a/doc/akregator/main-window.png b/doc/akregator/main-window.png
new file mode 100644
index 00000000..4b0e59d3
--- /dev/null
+++ b/doc/akregator/main-window.png
Binary files differ
diff --git a/doc/akregator/main-window2.png b/doc/akregator/main-window2.png
new file mode 100644
index 00000000..30872191
--- /dev/null
+++ b/doc/akregator/main-window2.png
Binary files differ
diff --git a/doc/akregator/main-window3.png b/doc/akregator/main-window3.png
new file mode 100644
index 00000000..35b50c3f
--- /dev/null
+++ b/doc/akregator/main-window3.png
Binary files differ
diff --git a/doc/akregator/main-window4.png b/doc/akregator/main-window4.png
new file mode 100644
index 00000000..abff29c0
--- /dev/null
+++ b/doc/akregator/main-window4.png
Binary files differ
diff --git a/doc/akregator/quick-filter.png b/doc/akregator/quick-filter.png
new file mode 100644
index 00000000..c30d7678
--- /dev/null
+++ b/doc/akregator/quick-filter.png
Binary files differ
diff --git a/doc/akregator/rss.png b/doc/akregator/rss.png
new file mode 100644
index 00000000..3537e0f2
--- /dev/null
+++ b/doc/akregator/rss.png
Binary files differ
diff --git a/doc/akregator/rss3.png b/doc/akregator/rss3.png
new file mode 100644
index 00000000..3008a51d
--- /dev/null
+++ b/doc/akregator/rss3.png
Binary files differ
diff --git a/doc/api/Dox-pimlogo.png b/doc/api/Dox-pimlogo.png
new file mode 100644
index 00000000..87934def
--- /dev/null
+++ b/doc/api/Dox-pimlogo.png
Binary files differ
diff --git a/doc/api/Doxyfile.pim b/doc/api/Doxyfile.pim
new file mode 100644
index 00000000..319ad141
--- /dev/null
+++ b/doc/api/Doxyfile.pim
@@ -0,0 +1,1162 @@
+# Doxyfile 1.3.6
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+# TAG = value [value, ...]
+# For lists items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME =
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER =
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY = ../apidocs/
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch,
+# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en
+# (Japanese with English messages), Korean, Korean-en, Norwegian, Polish, Portuguese,
+# Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian.
+
+OUTPUT_LANGUAGE = English
+
+# This tag can be used to specify the encoding used in the generated output.
+# The encoding is not always determined by the language that is chosen,
+# but also whether or not the output is meant for Windows or non-Windows users.
+# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES
+# forces the Windows encoding (this is the default for the Windows binary),
+# whereas setting the tag to NO uses a Unix-style encoding (the default for
+# all platforms other than Windows).
+
+USE_WINDOWS_ENCODING = NO
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC = NO
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator
+# that is used to form the text in various listings. Each string
+# in this list, if found as the leading text of the brief description, will be
+# stripped from the text and the result after processing the whole list, is used
+# as the annotated text. Otherwise, the brief description is used as-is. If left
+# blank, the following values are used ("$name" is automatically replaced with the
+# name of the entity): "The $name class" "The $name widget" "The $name file"
+# "is" "provides" "specifies" "contains" "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF =
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC = YES
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
+# members of a class in the documentation of that class as if those members were
+# ordinary class members. Constructors, destructors and assignment operators of
+# the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. It is allowed to use relative paths in the argument list.
+# If left blank the directory from which doxygen is run is used as the
+# path to strip.
+
+STRIP_FROM_PATH =
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like the Qt-style comments (thus requiring an
+# explicit @brief command for a brief description.
+
+JAVADOC_AUTOBRIEF = YES
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# re-implements.
+
+INHERIT_DOCS = YES
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE = 4
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES = obsolete=@deprecated
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
+# only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C = NO
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
+# only. Doxygen will then generate output that is more tailored for Java.
+# For instance, namespaces will be presented as packages, qualified scopes
+# will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC = YES
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES = NO
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these classes will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES = YES
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
+# documentation blocks found inside the body of a function.
+# If set to NO (the default) these blocks will be appended to the
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS = NO
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower-case letters. If set to YES upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# users are advised to set this option to NO.
+
+CASE_SENSE_NAMES = YES
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES = NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put a list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS = NO
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
+# brief documentation of file, namespace and class members alphabetically
+# by member name. If set to NO (the default) the members will appear in
+# declaration order.
+
+SORT_BRIEF_DOCS = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
+# sorted by fully-qualified names, including namespaces. If set to
+# NO (the default), the class list will be sorted only by class name,
+# not including the namespace part.
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the
+# alphabetical list.
+
+SORT_BY_SCOPE_NAME = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST = NO
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST = NO
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or define consists of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and defines in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET = YES
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS = NO
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED = NO
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some
+# parameters in a documented function, or documenting parameters that
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR = YES
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text.
+
+WARN_FORMAT =
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT =
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
+# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc
+
+FILE_PATTERNS = *.h \
+ *.cpp \
+ *.cc \
+ *.hpp \
+ *.dox \
+ *.c++ \
+ *.cxx \
+ *.h++ \
+ *.hh
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE = YES
+
+# The EXCLUDE tag can be used to specify files and/or directories that should
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE =
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories
+# that are symbolic links (a Unix filesystem feature) are excluded from the input.
+
+EXCLUDE_SYMLINKS = NO
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories.
+
+EXCLUDE_PATTERNS = *.moc.* \
+ moc* \
+ *.all_cpp.* \
+ *unload.* \
+ */test/* \
+ */tests/* \
+ *_p.h
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH =
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS =
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output.
+
+INPUT_FILTER =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+# Note: To get rid of all source code in the generated output, make sure also
+# VERBATIM_HEADERS is set to NO.
+
+SOURCE_BROWSER = YES
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES (the default)
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = YES
+
+# If the REFERENCES_RELATION tag is set to YES (the default)
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION = YES
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX = YES
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX = 3
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX = K
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML = NO
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT =
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header.
+
+HTML_HEADER = ../apidocs/common/header.html
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER = ../apidocs/common/footer.html
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet. Note that doxygen will try to copy
+# the style sheet file to the HTML output directory, so don't put your own
+# stylesheet in the HTML output directory as well, or it will be erased!
+
+HTML_STYLESHEET = ../apidocs/common/doxygen.css
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS = YES
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compressed HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output directory.
+
+CHM_FILE =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+# top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it.
+
+DISABLE_INDEX = YES
+
+# This tag can be used to set the number of enum values (range [1..20])
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE = 4
+
+# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
+# generated containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+,
+# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
+# probably better off using the HTML help feature.
+
+GENERATE_TREEVIEW = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX = NO
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT =
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
+# invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, a4wide, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE = a4wide
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS = NO
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX = NO
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE = NO
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not
+# include the index chapters (such as File Index, Compound Index, etc.)
+# in the output.
+
+LATEX_HIDE_INDICES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimized for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF = NO
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT =
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assignments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN = NO
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT =
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION = .kde3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation.
+
+GENERATE_XML = NO
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD =
+
+# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
+# dump the program listings (including syntax highlighting
+# and cross-referencing information) to the XML output. Note that
+# enabling this will significantly increase the size of the XML output.
+
+XML_PROGRAMLISTING = NO
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will
+# generate a Perl module file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_PERLMOD = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
+# nicely formatted so it can be parsed by a human reader. This is useful
+# if you want to understand what is going on. On the other hand, if this
+# tag is set to NO the size of the Perl module output will be much smaller
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY = YES
+
+# The names of the make variables in the generated doxyrules.make file
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
+# This is useful so different doxyrules.make files included by the same
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_PREDEFINED tags.
+
+EXPAND_ONLY_PREDEF = NO
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS =
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed.
+
+PREDEFINED = QT_VERSION=320 \
+ __cplusplus \
+ Q_WS_X11
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all function-like macros that are alone
+# on a line, have an all uppercase name, and do not end with a semicolon. Such
+# function macros are typically used for boiler-plate code, and will confuse the
+# parser if not removed.
+
+SKIP_FUNCTION_MACROS = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles.
+# Optionally an initial location of the external documentation
+# can be added for each tagfile. The format of a tag file without
+# this location is as follows:
+# TAGFILES = file1 file2 ...
+# Adding location for the tag files is done as follows:
+# TAGFILES = file1=loc1 "file2 = loc2" ...
+# where "loc1" and "loc2" can be relative or absolute paths or
+# URLs. If a location is present for each tag, the installdox tool
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE =
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS = NO
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base or
+# super classes. Setting the tag to NO turns the diagrams off. Note that this
+# option is superseded by the HAVE_DOT option below. This is only a fallback. It is
+# recommended to install and use dot, since it yields more powerful graphs.
+
+CLASS_DIAGRAMS = YES
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS = NO
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT = NO
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# collaboration diagrams in a style similar to the OMG's Unified Modeling
+# Language.
+
+UML_LOOK = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH = YES
+
+# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will
+# generate a call dependency graph for every global function or class method.
+# Note that enabling this option will significantly increase the time of a run.
+# So in most cases it will be better to enable call graphs for selected
+# functions only using the \callgraph command.
+
+CALL_GRAPH = NO
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found on the path.
+
+DOT_PATH =
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS =
+
+# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_WIDTH = 800
+
+# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height
+# (in pixels) of the graphs generated by dot. If a graph becomes larger than
+# this value, doxygen will try to truncate the graph, so that it fits within
+# the specified constraint. Beware that most browsers cannot cope with very
+# large images.
+
+MAX_DOT_GRAPH_HEIGHT = 1024
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
+# graphs generated by dot. A depth value of 3 means that only nodes reachable
+# from the root by following a path via at most 3 edges will be shown. Nodes that
+# lay further from the root node will be omitted. Note that setting this option to
+# 1 or 2 may greatly reduce the computation time needed for large code bases. Also
+# note that a graph may be further truncated if the graph's image dimensions are
+# not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH and MAX_DOT_GRAPH_HEIGHT).
+# If 0 is used for the depth value (the default), the graph is not depth-constrained.
+
+MAX_DOT_GRAPH_DEPTH = 0
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermediate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+
+# The SEARCHENGINE tag specifies whether or not a search engine should be
+# used. If set to NO the values of all tags below this one will be ignored.
+
+SEARCHENGINE = NO
+
+
+#-----------------------------------------------------------------------
+# KDE Settings
+#-----------------------------------------------------------------------
+
+ALIASES = \
+ "intern=\par<b>Internal use only.</b>" \
+ "reimp=\par<b>Reimplemented from superclass.</b>" \
+ "obsolete=@deprecated"
+HTML_ALIGN_MEMBERS = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION = NO
+VERBATIM_HEADERS = NO
+GENERATE_LATEX = NO
+GENERATE_RTF = NO
+GENERATE_MAN = NO
+GENERATE_XML = NO
+GENERATE_HTML = YES
+SOURCE_BROWSER = NO
+GENERATE_AUTOGEN_DEF = NO
+ENABLE_PREPROCESSING = NO
+CLASS_DIAGRAMS = NO
+HAVE_DOT = NO
+IGNORE_PREFIX = K
+EXTRACT_ALL = NO
+# RECURSIVE is overridden at toplevel
+# ALPHABETICAL_INDEX is overridden at toplevel
+
diff --git a/doc/api/doxygen.css b/doc/api/doxygen.css
new file mode 100644
index 00000000..e059f34a
--- /dev/null
+++ b/doc/api/doxygen.css
@@ -0,0 +1,611 @@
+/** This CSS is the concatenation of the stylefiles from pim.kde.org,
+* so that includes: KDE standard CSS by Olaf Schmidt, new_pim.css by
+* Adriaan de Groot and new_standard.css by Adriaan de Groot. The combined
+* stylefile is not a normal one, and could use a great deal of editing.
+*/
+
+/**
+ * based on code by Sebastian Faubel
+ * modified by Christoph Cullmann and Olaf Schmidt
+ */
+
+/* common (X)HTML formats */
+
+body {
+font-size: 100%;
+line-height: 1.2em; /* Note: it is inherited as is, not recalculated! */
+background-color: white;
+color: black;
+font-family: sans-serif;
+padding: 0;
+margin: 0;
+}
+
+table, td, th {
+font-family: sans-serif;
+padding: 0;
+margin: 0;
+text-align: left;
+}
+
+input, select {
+font-size: 0.8em;
+line-height: 1em;
+}
+
+form {
+margin: 0;
+padding: 0;
+}
+
+optgroup {
+font-style: normal;
+}
+
+a:link {
+color: #0000C0;
+text-decoration: none;
+}
+
+a:visited {
+color: #800080;
+text-decoration: none;
+}
+
+a:hover {
+text-decoration: underline;
+}
+
+/* navigation header, this is the combined area with logo and section links */
+
+#nav_header_top {
+height: 52px;
+
+text-align: right;
+
+background-color: #418ade;
+border-bottom: 1px solid #000000;
+}
+
+#nav_header_bottom {
+padding: 6px 6px 6px 84px;
+background-color: #dfe7f3;
+border-bottom: 1px solid #000000;
+
+text-align: left;
+}
+
+#nav_header_logo {
+float: left;
+padding: 10px;
+}
+
+#nav_header_logo a img {
+width: 64px;
+height: 64px;
+}
+
+#nav_header_logo_right {
+float: right;
+padding: 10px;
+}
+
+/* title text */
+#nav_header_title {
+position: absolute;
+top: 12px;
+left: 86px;
+border: 0px;
+font-size: 32px;
+font-weight: bold;
+color: white;
+white-space: nowrap;
+
+line-height: 36px;
+}
+
+/* location combo */
+#nav_header_location {
+position: absolute;
+top: 12px;
+right: 8px;
+border: 0px;
+color: #444;
+vertical-align: middle;
+white-space: nowrap;
+
+font-size: 14px;
+}
+
+/* location URL */
+#nav_header_bottom_left {
+vertical-align: middle;
+
+font-size: 0.8em;
+line-height: 1.1em;
+}
+
+/* place for the links to contact, sitemap, ... s*/
+#nav_header_bottom_right {
+float: right;
+vertical-align: middle;
+
+font-size: 0.8em;
+line-height: 1.1em;
+}
+
+/* main color definitions */
+
+.menuheader {
+height: 0;
+line-height: 0;
+margin: 0;
+padding: 0;
+font-size: 0;
+}
+
+#leftmenu, #rightmenu {
+width: 20%;
+}
+
+#leftmenu h2, #rightmenu h2 {
+font-size: 1em;
+padding-left: 1em;
+vertical-align: middle;
+background-color: #418ade;
+border-top: 0.3em solid #418ade;
+border-bottom: 0.3em solid #418ade;
+color: white;
+margin-top: 0;
+}
+
+#rightmenu h3 {
+padding: 0.3em 0.8em;
+font-size: 1em;
+margin-bottom: 0;
+}
+
+#leftmenu ul, #rightmenu ul {
+margin: 0;
+padding-left: 0.5em;
+padding-bottom: 1em;
+}
+
+#leftmenu ul {
+list-style-type: none;
+}
+
+#rightmenu ul {
+list-style-type: none;
+}
+
+#leftmenu li, #rightmenu li {
+font-size: 0.8em;
+}
+
+#leftmenu li {
+margin-left: 1em;
+}
+
+#rightmenu li {
+margin-left: 1.5em;
+}
+
+#leftmenu ul ul, #rightmenu ul ul {
+margin: 0;
+padding-left: 0;
+}
+
+#leftmenu li li, #rightmenu li li {
+font-size: 0.8em;
+margin-left: 2em;
+}
+
+li.here a:link, li.here a:visited, li.here li.here a:link, li.here li.here a:visited {
+text-decoration: underline;
+}
+
+li.here li a:link, li.here li a:visited {
+text-decoration: none;
+}
+
+li.here a:hover, li.here li a:hover, li.here li.here a:hover {
+text-decoration: underline;
+}
+
+/**
+ * page footer
+ */
+
+/* background + border at top */
+#footer {
+border-top: 1px solid #000000;
+background-image: url(../images/footer_bg.png);
+background-repeat: repeat-x;
+width: 100%;
+height: 100px;
+bottom:0px;
+}
+
+/* right footer, contains the wave image */
+#footer_right {
+position: absolute;
+right: 0px;
+text-align: right;
+z-index: 5;
+}
+
+/* left footer, contains the text */
+#footer_left {
+position: absolute;
+left: 0px;
+text-align: left;
+padding: 1em 1.5em 0em 1.5em;
+clear: both;
+z-index: 10;
+}
+
+/* classes */
+
+#main, #content {
+clear: both;
+}
+
+#content {
+background-color: white;
+padding: 0.5em 0.7em 1.5em 0.7em;
+text-align: justify;
+}
+
+#content td, #content th {
+font-family: sans-serif;
+padding: 0.25em;
+margin: 0;
+text-align: left;
+}
+
+#content h4, #content h3, #content h2, #content h1 {
+color: #418ade;
+text-align: left;
+line-height: 1em; /* without this lines stick in each other for headings */
+}
+
+#quicklinks {
+background-color: #E6F0F9;
+font-size: 1em;
+padding: 1em;
+text-align: center;
+margin-top: 1em;
+margin-left: 0.5em;
+margin-bottom: 0.5em;
+margin-right: 0.5em;
+}
+
+#leftmenu, #rightmenu {
+background-color: white;
+color: #036;
+}
+
+.menu_box {
+border-top: 8px solid white;
+
+border-right: 8px solid white;
+border-left: 8px solid white;
+
+background-color: #dfe7f3;
+}
+
+#search {
+text-align: center;
+padding: 0.2em 0.2em 0.2em 0.2em;
+}
+
+#search label {
+display: none;
+}
+
+#search input, #search select {
+width: 95%;
+margin-bottom: 2px;
+}
+
+#hotspot {
+font-size: 0.8em;
+line-height: 1em;
+text-align: center;
+padding: 0 0 0.8em 0;
+}
+
+.newsbox1 {
+background-color: #E6F0F9;
+margin-top: 1em;
+margin-bottom: 0.5em;
+}
+
+.newsbox2 {
+background-color: white;
+margin-top: 1em;
+margin-bottom: 0.5em
+}
+
+/* common style for tables used in the page */
+.table_box {
+background-color: #dfe7f3;
+border: 0;
+padding: 0;
+margin: 0;
+border-spacing: 0;
+}
+
+.table_box th {
+background-color: #418ade;
+color: white;
+}
+
+/* needed for edu.kde.org */
+.contentheader, #content h4.contentheader {
+font-size: 1em;
+font-weight: bold;
+line-height: 1.2em;
+padding: 0.1em 0 0.2em 1em;
+vertical-align: middle;
+background-color: #418ade;
+color: white;
+margin: 0;
+}
+
+/* hidden stuff */
+.doNotDisplay {
+display: none;
+}
+
+@media aural { .doNotDisplay {
+display: inline;
+}}
+/* Stylesheet that handles PIM-specific classes and layout */
+
+#content h1
+{
+display: none;
+}
+
+li.here
+{
+font-weight: bold;
+list-style-type: disc;
+}
+
+.shellcode
+{
+font-family: monospace;
+font-size: small;
+white-space: pre;
+margin-left: 3em;
+margin-right: 3em;
+margin-bottom: 1ex;
+padding-left: 6px;
+}
+
+
+
+
+td.indexkey {
+vertical-align: top;
+background: #dfe7f3;
+}
+
+#content td.memItemLeft {
+text-align: right;
+}
+
+#leftmenu ul ul
+{
+padding: 0px;
+margin-left: 1em;
+}
+
+.newsshort
+{
+float: right;
+margin: 0px 0px 1ex 1em;
+padding: 0px;
+border: 1px solid black;
+width: 40%;
+}
+
+#content .newsshort h2
+{
+margin-top: 0px;
+font-size: 100%;
+}
+
+
+#footer {
+border-top: 1px solid #000000;
+background-image: none;
+background-repeat: x-repeat;
+width: 100%;
+}
+
+#footer_left
+{
+color: black;
+}
+
+#footer_right img
+{
+display: none;
+}
+
+.table_box { background: transparent; }
+
+.newsshort ul { list-style-type: none; margin: 0px; padding: 0px; }
+
+.newsshort li
+{
+margin-bottom: 1ex;
+padding-left: 1em;
+padding-right: 1em;
+}
+
+.newsshort li.text
+{
+padding-left: 0px;
+padding-right: 1em;
+}
+
+.newsshort .date
+{
+display: run-in;
+padding-right: 1em;
+}
+
+.newsbox1, .newsbox2 {
+background-color: transparent;
+vertical-align: top;
+}
+
+.newslong .item
+{
+margin-bottom: 2ex;
+}
+
+.newslong .date
+{
+float: left;
+font-weight: bold;
+margin-right: 2em;
+}
+
+.newslong .title
+{
+width: 100%;
+font-weight: bold;
+}
+
+.newslong .text
+{
+padding-left: 2em;
+}
+
+
+
+.iconlist td
+{
+vertical-align: top;
+}
+
+.iconlist p
+{
+margin: 0px 4px 0px 64px;
+}
+
+.iconlist img
+{
+float: left;
+border: none;
+}
+
+.minipage
+{
+margin: 2ex 2em;
+padding: 1ex 1em;
+}
+
+p.people
+{
+clear: both;
+margin: 1ex 0px;
+}
+
+p.people img
+{
+float: left;
+border: 0px;
+margin: 0ex 1em 1ex 0px;
+}
+
+/**
+ * Color scheme -- Standard KDE PIM scheme
+ */
+
+
+a:link, a:visited, a:hover, a:active {
+color: #000080;
+font-weight: bold;
+}
+
+/* navigation header, this is the combined area with logo and section links */
+
+#nav_header_top {
+background-color: #000080;
+border-bottom: 1px solid #000000;
+}
+
+#nav_header_bottom {
+background-color: #c1cfea;
+border-bottom: 1px solid #000000;
+}
+
+#nav_header_title {
+color: white;
+}
+
+/* location combo */
+#nav_header_location {
+color: #c1cfea;
+}
+
+.menu_box {
+background-color: #c1cfea;
+border: 1px solid white;
+margin: 7px;
+}
+
+#leftmenu h2, #rightmenu h2 {
+background-color: #000080;
+border: none;
+color: white;
+}
+
+#footer {
+background-color: #c1cfea;
+}
+
+
+/* classes */
+
+#content {
+background-color: white;
+}
+
+#content h2 {
+background-color: #000080;
+color: white;
+padding: 0.2ex 1em;
+font-size: 100%;
+font-weight: bold;
+}
+
+#content h3 {
+background-color: #c1cfea;
+color: black;
+padding: 0.2ex 1em;
+font-size: 100%;
+font-weight: bold;
+}
+
+#quicklinks {
+background-color: #c1cfea;
+}
+
+
+#content td.memItemLeft {
+text-align: right;
+}
+
+.groupHeader {
+font-size: large;
+color: #418ADE;
+}
+
diff --git a/doc/api/header.html b/doc/api/header.html
new file mode 100644
index 00000000..cf3300b0
--- /dev/null
+++ b/doc/api/header.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
+
+<head>
+ <title>$title ($projectname)</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <meta http-equiv="Content-Style-Type" content="text/css" />
+
+ <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" comment "ICRAonline DE v2.0" l gen true for "http://www.kde.org" r (nz 1 vz 1 lz 1 oz 1 cb 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://www.kde.org" r (n 0 s 0 v 0 l 0))' />
+
+ <meta name="trademark" content="KDE e.V." />
+ <meta name="description" content="K Desktop Environment Homepage, KDE.org" />
+ <meta name="MSSmartTagsPreventParsing" content="true" />
+ <meta name="robots" content="all" />
+
+ <link rel="shortcut icon" href="@topdir@/favicon.ico" />
+
+<link rel="stylesheet" media="screen" type="text/css" title="APIDOX" href="doxygen.css" />
+
+
+
+<style type="text/css">
+<!--
+hr { display: none; }
+#content h2 { margin-left: 0px; }
+table.mdTable { background-color: #f8f8f8; border: .2em solid #d7d7d7; }
+td.mdRow { padding: 8px 20px; }
+td.md { font-weight: bold; }
+td.mdname1 { font-weight: bold; color: #602020; }
+td.mdname { font-weight: bold; color: #602020; }
+
+-->
+</style>
+
+</head>
+
+<body>
+
+<div id="nav_header_top" align="right">
+ <a href="#content" class="doNotDisplay" accesskey="2">Skip to main content ::</a>
+
+ <a href="@topdir@"><img id="nav_header_logo" alt="Home" align="left" src="@topdir@/kde_gear_64.png" border="0" /></a>
+ <span class="doNotDisplay">::</span>
+ <img id="nav_header_logo_right" alt="" align="right" src="@topdir@/pimlogo.png" border="0" />
+
+ <div id="nav_header_title" align="left">KDE PIM API Reference</div>
+
+
+</div>
+
+<div id="nav_header_bottom" align="right">
+ <span class="doNotDisplay">:: <a href="#navigation" accesskey="5">Skip to Link Menu</a><br/></span>
+ <div id="nav_header_bottom_left" style="text-align: left;">
+/ <a href="@topdir@/">API Reference</a>
+<!-- pmenu $projectname -->
+ </div>
+</div>
+
+
+<table id="main" border="0" cellpadding="0" cellspacing="0" width="100%">
+<tr>
+ <td valign="top" class="menuheader" height="0"></td>
+
+ <td id="contentcolumn" valign="top" rowspan="2" >
+ <div id="content" style="padding-top: 0px;"><div style="width:100%; margin: 0px; padding: 0px;">
+ <h2><a name="content"></a>$projectname</h2>
+
+
diff --git a/doc/api/kdateedit.png b/doc/api/kdateedit.png
new file mode 100644
index 00000000..8fbae210
--- /dev/null
+++ b/doc/api/kdateedit.png
Binary files differ
diff --git a/doc/api/mainheader.html b/doc/api/mainheader.html
new file mode 100644
index 00000000..3acce2c3
--- /dev/null
+++ b/doc/api/mainheader.html
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en_US" xml:lang="en_US">
+
+<head>
+ <title>$title ($projectname)</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <meta http-equiv="Content-Style-Type" content="text/css" />
+
+ <meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" comment "ICRAonline DE v2.0" l gen true for "http://www.kde.org" r (nz 1 vz 1 lz 1 oz 1 cb 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://www.kde.org" r (n 0 s 0 v 0 l 0))' />
+
+ <meta name="trademark" content="KDE e.V." />
+ <meta name="description" content="K Desktop Environment Homepage, KDE.org" />
+ <meta name="MSSmartTagsPreventParsing" content="true" />
+ <meta name="robots" content="all" />
+
+ <link rel="shortcut icon" href="@topdir@/favicon.ico" />
+
+<link rel="stylesheet" media="screen" type="text/css" title="APIDOX" href="doxygen.css" />
+
+
+<style type="text/css">
+<!--
+hr { display: none; }
+#content h2 { margin-left: 0px; }
+table.mdTable { background-color: #f8f8f8; border: .2em solid #d7d7d7; }
+td.mdRow { padding: 8px 20px; }
+td.md { font-weight: bold; }
+td.mdname1 { font-weight: bold; color: #602020; }
+td.mdname { font-weight: bold; color: #602020; }
+.copyrights { width: 80%; margin: 1ex 10%; color:#BCBCBC; }
+.copyrights a { color: #9A9A9A; }
+
+-->
+</style>
+
+</head>
+
+<body>
+
+<div id="nav_header_top" align="right">
+ <a href="#content" class="doNotDisplay" accesskey="2">Skip to main content ::</a>
+
+ <a href="@topdir@"><img id="nav_header_logo" alt="Home" align="left" src="@topdir@/kde_gear_64.png" border="0" /></a>
+ <span class="doNotDisplay">::</span>
+ <img id="nav_header_logo_right" alt="" align="right" src="@topdir@/pimlogo.png" border="0" />
+
+ <div id="nav_header_title" align="left">KDE PIM API Reference</div>
+
+
+</div>
+
+<div id="nav_header_bottom" align="right">
+ <span class="doNotDisplay">:: <a href="#navigation" accesskey="5">Skip to Link Menu</a><br/></span>
+ <div id="nav_header_bottom_left" style="text-align: left;">
+/ <a href="@topdir@/">API Reference</a>
+ </div>
+</div>
+
+
+<table id="main" border="0" cellpadding="0" cellspacing="0" width="100%">
+<tr>
+ <td valign="top" class="menuheader" height="0"></td>
+
+ <td id="contentcolumn" valign="top" rowspan="2" >
+ <div id="content"><div style="width:100%;">
+ <a name="content"></a><h2>$projectname</h2>
+
+
diff --git a/doc/kaddressbook/Makefile.am b/doc/kaddressbook/Makefile.am
new file mode 100644
index 00000000..171f575c
--- /dev/null
+++ b/doc/kaddressbook/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
diff --git a/doc/kaddressbook/addhost.png b/doc/kaddressbook/addhost.png
new file mode 100644
index 00000000..cedbcec7
--- /dev/null
+++ b/doc/kaddressbook/addhost.png
Binary files differ
diff --git a/doc/kaddressbook/conf.png b/doc/kaddressbook/conf.png
new file mode 100644
index 00000000..2c4d7500
--- /dev/null
+++ b/doc/kaddressbook/conf.png
Binary files differ
diff --git a/doc/kaddressbook/contactdlg.png b/doc/kaddressbook/contactdlg.png
new file mode 100644
index 00000000..08d2d65e
--- /dev/null
+++ b/doc/kaddressbook/contactdlg.png
Binary files differ
diff --git a/doc/kaddressbook/edit_instant_messenging.png b/doc/kaddressbook/edit_instant_messenging.png
new file mode 100644
index 00000000..84d1007a
--- /dev/null
+++ b/doc/kaddressbook/edit_instant_messenging.png
Binary files differ
diff --git a/doc/kaddressbook/exportdlg.png b/doc/kaddressbook/exportdlg.png
new file mode 100644
index 00000000..6fc0f1ab
--- /dev/null
+++ b/doc/kaddressbook/exportdlg.png
Binary files differ
diff --git a/doc/kaddressbook/extension.png b/doc/kaddressbook/extension.png
new file mode 100644
index 00000000..5c7bfd2f
--- /dev/null
+++ b/doc/kaddressbook/extension.png
Binary files differ
diff --git a/doc/kaddressbook/filtereditdlg.png b/doc/kaddressbook/filtereditdlg.png
new file mode 100644
index 00000000..02736381
--- /dev/null
+++ b/doc/kaddressbook/filtereditdlg.png
Binary files differ
diff --git a/doc/kaddressbook/index.docbook b/doc/kaddressbook/index.docbook
new file mode 100644
index 00000000..9473fc52
--- /dev/null
+++ b/doc/kaddressbook/index.docbook
@@ -0,0 +1,1179 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
+"dtd/kdex.dtd" [
+ <!ENTITY kappname "&kaddressbook;">
+ <!ENTITY package "kdepim">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kaddressbook; Handbook</title>
+<authorgroup>
+<author>
+<firstname>Tobias</firstname>
+<surname>Koenig</surname>
+<affiliation>
+<address><email>tokoe@kde.org</email></address>
+</affiliation>
+</author>
+<author>
+<firstname>Steffen</firstname>
+<surname>Hansen</surname>
+<affiliation>
+<address><email>hansen@kde.org</email>
+</address>
+</affiliation>
+</author>
+<author>
+<firstname>Don</firstname>
+<surname>Sanders</surname>
+<affiliation>
+<address><email>dsanders@kde.org</email></address>
+</affiliation>
+</author>
+<author>
+<firstname>Michel</firstname>
+<surname>Boyer de la Giroday</surname>
+<affiliation>
+<address><email>michel@klaralvdalens-datakonsult.se</email>
+</address>
+</affiliation>
+</author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<date>2004-09-24</date>
+<releaseinfo>3.3</releaseinfo>
+
+<legalnotice>
+&FDLNotice;
+</legalnotice>
+
+<abstract>
+<para>&kaddressbook; is the &kde; address book.</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kaddressbook</keyword>
+
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&kaddressbook; is the main address book application for &kde;; it
+enables you to manage your contacts efficiently and comfortably.
+Since it is based on the kabc library it supports resources,
+which can be used to load and save your contacts to many different locations &mdash;
+not just the local file system, but also to LDAP servers and SQL databases.
+</para>
+
+<para>
+The user interface is similar to MS Outlook and it supports different views
+for to represent the contact data differently;
+it also provides an incremental search over all fields and a jump button
+bar to quickly access single entries.
+Since the underlying kabc library uses the vCard format (specified in RFC
+2426) as its default storage medium, &kaddressbook; mainly reflects the supported
+entry fields in its graphical user interface.
+</para>
+</chapter>
+
+<chapter id="using-kaddressbook">
+<title>Using &kaddressbook;</title>
+
+<sect1 id="getting-started">
+<title>Getting Started</title>
+
+<para>
+After you have started &kaddressbook; (either using the panel menu or by typing
+<command>kaddressbook</command> at the command prompt) the &kaddressbook; main window
+will be displayed:</para>
+
+<screenshot>
+<screeninfo>Starting &kaddressbook;</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="mainwin.png" format="PNG"/></imageobject>
+<textobject><phrase>The &kaddressbook; main window.</phrase></textobject>
+<caption><para>The &kaddressbook; main window.</para></caption>
+</mediaobject>
+</screenshot>
+</sect1>
+
+<sect1 id="configure-resources">
+<title>Configure Resources</title>
+<para>&kaddressbook; can use multiple resources for loading and storing
+its contacts. After starting &kaddressbook; for the first time you will have
+a default resource installed that saves all contacts in a vCard file
+under $HOME/.kde/share/apps/kabc/std.vcf; you can add more resources
+by using the Resource Configuration dialog, which is available in
+<application>kcontrol</application> under
+<guilabel>KDE Components</guilabel>-><guilabel>KDE Resources Configuration</guilabel>:</para>
+
+<screenshot>
+<screeninfo>The Resource Configuration Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="resourcesdlg.png" format="PNG"/></imageobject>
+<textobject><phrase>The Resource Configuration Dialog.</phrase></textobject>
+<caption><para>The Resource Configuration Dialog.</para></caption>
+</mediaobject>
+</screenshot>
+<para>Load the configuration module you want to add your resource(s) to. By selecting it from the combo box at the top of the <guilabel>Resources</guilabel> section. The module for &kaddressbook; being <guilabel>contact</guilabel>.</para>
+<para>Launch the <guilabel>Resource Configuration</guilabel> dialog by pushing the <guibutton>Add...</guibutton> button. Choose the resource you want to add to your <guilabel>contact</guilabel> module and click <guilabel>OK</guilabel> to confirm your choice.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Directory</guilabel></term>
+<listitem><para>each contact will be stored in its own file;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>File</guilabel></term>
+<listitem><para>all contacts will be stored in one file;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>IMAP</guilabel></term>
+<listitem><para>To be written</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Kolab</guilabel></term>
+<listitem><para>The contacts will be saved in the contact folder of your DIMAP account.</para><para><guilabel>Kolab server specificities:</guilabel> The Kolab resource should never be configured as Read Only. In case you have added several types of resources you need to set your <guilabel>Kolab Server</guilabel> resource as your <guilabel>Standard</guilabel> resource.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>LDAP</guilabel></term>
+<listitem><para>all contacts will be stored on a LDAP server;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Network</guilabel></term>
+<listitem><para>all contacts will be stored in one file, which can be located
+on a remote server (for example, through HTTP, WebDAV, FTP or Fish).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>SLOX</guilabel></term>
+<listitem><para>To be written</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>XML-RPC</guilabel></term>
+<listitem><para>To be written</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>After selecting the type of resource another dialog appears where you can configure the resource-specific settings.</para>
+<para>The <guilabel>File</guilabel> and <guilabel>Directory</guilabel> resource
+supports different formats for storing the contacts:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>vCard</guilabel></term>
+<listitem><para>the contacts will be stored in the vCard format, as
+specified in RFC 2426;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>binary</guilabel></term>
+<listitem><para>the contacts will be stored in a binary format &mdash; this
+increases performance during loading and saving, but it is not portable like
+the vCard format.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>&kaddressbook; needs a standard resource, where all contacts should be
+saved if no other resource is specified; for this reason, after starting
+&kaddressbook; the first time, there is already a resource available.
+If you want to use another resource as the standard resource, use the
+<guibutton>Use as Standard</guibutton> button to select it. You must have
+both read and write access to the new standard resource, otherwise you
+won't be able to select it.
+</para>
+</sect1>
+
+<sect1 id="managing-contacts">
+<title>Managing Contacts</title>
+<para>To create or edit contacts, &kaddressbook; offers a dialog where you
+can input all the data that can be stored in a vCard.
+</para>
+
+<screenshot>
+<screeninfo>The Contact Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="contactdlg.png" format="PNG"/></imageobject>
+<textobject><phrase>The Contact Dialog.</phrase></textobject>
+<caption><para>The Contact Dialog.</para></caption>
+</mediaobject>
+</screenshot>
+
+<sect2 id="managing-contacts-automatic-nameparsing">
+<title>Automatic Name Parsing</title>
+<para>
+&kaddressbook; tries to provide an easy name input by automatic name parsing;
+for this to work properly it is sometimes necessary to add custom name prefixes, suffixes
+or inclusions in the <link linkend="preferences-address-book-contact">configure dialog</link>.
+Nevertheless, no algorithm is perfect, so the name you enter may be parsed
+incorrectly; in this case, you can disable the automatic name parsing in
+the name edit dialog, which is available by clicking the <guibutton>Name...</guibutton> button
+in the contact dialog. If you wish to disable the name parsing for all new contacts you can
+disable automatic name parsing globally in the <link linkend="preferences-address-book-general">configure dialog</link>.
+</para>
+</sect2>
+
+<sect2 id="managing-contacts-formattedname">
+<title>Formatted Name</title>
+<para>
+The formatted name of a contact is used by other programs to represent it.
+&kaddressbook; offers three predefined types of formatted names:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>SimpleName</guilabel></term>
+<listitem><para>&lt;given name&gt; &lt;family name&gt;;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>FullName</guilabel></term>
+<listitem><para>&lt;prefix&gt; &lt;given name&gt; &lt;additional name&gt;
+&lt;family name&gt; &lt;suffix&gt;;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>ReverseName</guilabel></term>
+<listitem><para>&lt;family name&gt;, &lt;given name&gt;.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>
+If none of the above types fit your needs you can select the
+<guilabel>Custom</guilabel> name type, where you can add your own formatted
+name &mdash; this configuration can be done in the name edit dialog.
+To specify a
+default formatted name type for new contacts, use the <link linkend="preferences-address-book-contact">configure dialog</link>.
+</para>
+</sect2>
+<sect2 id="managing-contacts-im-addresses">
+<title>Instant Messaging</title>
+<para>
+ The <guilabel>IM Address</guilabel> text box holds the preferred Instant Messaging Address for this contact. To add, view and edit additional IM Addresses, click the <guilabel>Edit IM Addresses...</guilabel> button. The Edit IM Addresses Dialog appears.
+</para>
+<screenshot>
+<screeninfo>The Edit IM Addresses Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="edit_instant_messenging.png" format="PNG"/></imageobject>
+<textobject><phrase>The Edit IM Addresses Dialog.</phrase></textobject>
+<caption><para>The Edit IM Addresses Dialog.</para></caption>
+</mediaobject>
+</screenshot>
+
+<para>
+ A contact can have multiple instant messaging addresses associated with it. Other applications, such as <application>Kopete</application> and <application>Konversation</application>, store their information here. It is recommended that you add, edit and delete instant messaging addresses in <application>Kopete</application> or <application>Konversation</application> rather than here, since they can assist you better in adding the address, adding the user to a group, and so on. If you are not interested in whether they are picked up in another application, and just want to store the instant messaging address with the contact, then it is fine to add and edit it here.
+</para>
+<para>
+ For more information on adding new Instant Messaging Addresses, see
+ <ulink url="help:/kopete/getting-started.html#creating-accounts"><application>Kopete</application>'s handbook</ulink>
+ and <ulink url="help:/konversation/linkaddressbook.html"><application>Konversation</application>'s handbook</ulink>.
+</para>
+</sect2>
+
+ <sect2 id="managing-contacts-crypto-preferences">
+ <title>Crypto Settings tab</title>
+ <para>
+ In this tab, you can define preferences with regards to
+ cryptography for a contact. At the time of this writing,
+ only <application>KMail</application> will make use of these
+ preferences when composing messages. This mechanism replaces
+ the barely editable per-recipient crypto preferences of
+ earlier <application>KMail</application> releases.
+ </para>
+ <variablelist>
+ <varlistentry id="managing-contacts-crypto-preferences-allowed-protocols">
+ <term>
+ <guilabel>Allowed Protocols</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here, you can restrict the cryptographic message
+ formats that can be used for this contact. See the
+ section on <ulink
+ url="/kmail/the-composer-window.html#cryptographic-message-formats">Cryptographic
+ Message Formats</ulink> in <ulink
+ url="/kmail/"><application>KMail</application>'s
+ handbook</ulink> for a discussion of the different
+ available formats.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="managing-contacts-crypto-preferences-preferred-keys">
+ <term>
+ <guilabel>Preferred OpenPGP encryption key</guilabel>,
+ <guilabel>Preferred S/MIME encryption certificate</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here, you can assign a preferred OpenPGP key and/or
+ S/MIME certificate to be used when encrypting to this
+ contact. Otherwise, the local keyring and local
+ certificate box are searched for matching keys and
+ certificates.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="managing-contacts-crypto-preferences-message-preference">
+ <term>
+ <guilabel>Message Preference</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here, you can select from a set of directives for user
+ interaction both when signing and when encrypting.
+ </para>
+ <variablelist>
+ <varlistentry id="managing-contacts-crypto-preferences-message-preference-none">
+ <term>
+ <guilabel>&lt;none&gt;</guilabel>
+ </term>
+ <listitem>
+ <para>
+ No preference, use whatever mode
+ <application>KMail</application> defaults to.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="managing-contacts-crypto-preferences-message-preference-never">
+ <term>
+ <guilabel>Never Sign</guilabel>, <guilabel>Never Encrypt</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Never sign (encrypt) messages to this
+ contact. Don't ask for confirmation (except in
+ the case of conflicts with preferences of other
+ contacts).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="managing-contacts-crypto-preferences-message-preference-always">
+ <term>
+ <guilabel>Always Sign</guilabel>,
+ <guilabel>Always Encrypt</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Always sign (encrypt) messages to the
+ contact. Don't ask for confirmation (except in
+ the case of conflicts with preferences of other
+ contacts).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="managing-contacts-crypto-preferences-message-preference-if-possible">
+ <term>
+ <guilabel>Always Sign If Possible</guilabel>,
+ <guilabel>Always Encrypt If Possible</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Always sign (encrypt) messages to this contact
+ when it would be possible to do so. Don't ask if
+ it isn't possible. Situations in which signing
+ might not be possible include other recipients
+ having signing preferences of
+ "Never". Situations in which encryption might
+ not be possible include missing
+ keys/certificates for this or other recievers.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="managing-contacts-crypto-preferences-message-preference-ask">
+ <term>
+ <guilabel>Ask</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Always ask whether to sign (encrypt).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+</sect1>
+
+<sect1 id="using-views">
+<title>Using Views</title>
+<para>
+In this version, &kaddressbook; offers different views, which can
+represent the contacts in different ways:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Table View</guilabel></term>
+<listitem><para>All contacts are listed in a table; they can be sorted by
+clicking at the column header of the table.
+The columns of the table depend on the fields which were selected in
+the view configuration dialog.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Icon View</guilabel></term>
+<listitem><para>The contacts are listed as icons in a view. If the
+contact contains a photo or logo, then it is used in the view; otherwise,
+an default icon is used.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Card View</guilabel></term>
+<listitem><para>All contacts are presented in form of cards. The titles of
+these cards are the formatted names; the body of each card depends on
+what fields were selected in the view configuration dialog.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<screenshot>
+<screeninfo>The View Configuration Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="vieweditdlg.png" format="PNG"/></imageobject>
+<textobject><phrase>The View Configuration Dialog.</phrase></textobject>
+<caption><para>The View Configuration Dialog.</para></caption>
+</mediaobject>
+</screenshot>
+
+<para>The <guilabel>Selected Fields</guilabel> page offers you the possibility
+of selecting which of the stored details of a contact should be shown in the view. In the
+<guilabel>Default Filter</guilabel> page you can setup what
+<link linkend="using-filters">filter</link> should be used by the view.</para>
+</sect1>
+
+<sect1 id="using-filters">
+<title>Using Filters</title>
+<para>
+You can setup filters in &kaddressbook; which depend on the categories a
+contact belongs to. For example, you can create a filter that matches all
+contacts which belong to the categories 'Family' and 'Friends';
+you can also create a filter that matches all contacts which do not
+these categories. To manage filters, use the filter configuration dialog:
+</para>
+
+<screenshot>
+<screeninfo>The Filter Configuration Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="filtereditdlg.png" format="PNG"/></imageobject>
+<textobject><phrase>The Filter Configuration Dialog.</phrase></textobject>
+<caption><para>The Filter Configuration Dialog.</para></caption>
+</mediaobject>
+</screenshot>
+
+<para>
+Filters can be used in views to reduce the number of contacts shown.
+In the <link linkend="using-filters">view configuration dialog</link> you can
+specify what filter should be used by a view by default.
+</para>
+</sect1>
+
+<sect1 id="using-extensions">
+<title>Using Extensions</title>
+<para>
+Extensions are implemented as plugins in &kaddressbook;, so 3rd-party
+developers can provide more of them.
+At the moment we already have three extensions:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Contact Editor</guilabel></term>
+<listitem><para>Similar to the the contact editing dialog, but
+designed to allow contacts to be edited quickly.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Location of Contact</guilabel></term>
+<listitem><para>This extension takes the postal address of a contact and
+loads a map service from the internet (like www.map24.de) with these
+data; the result is shown in a <acronym>HTML</acronym> view.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Distribution List Manager</guilabel></term>
+<listitem><para>This extension provides easy management of the distribution
+lists: just create a new list and select a contact in the view; then, after
+clicking <guibutton>Add contact</guibutton>, the selected contact is part
+of the distribution list. A simpler way is to drag a contact from the
+view and drop it over the distribution list manager. See <link linkend="settings-menu"> Settings Menu</link> about how to add an extension.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<screenshot>
+<screeninfo>The main window with distribution list extension.</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="extension.png" format="PNG"/></imageobject>
+<textobject><phrase>The main window with distribution list extension.</phrase></textobject>
+<caption><para>The main window with distribution list extension.</para></caption>
+</mediaobject>
+</screenshot>
+</sect1>
+
+<sect1 id="import-and-export">
+<title>Import and Export</title>
+<para>With the new import/export framework &kaddressbook; offers
+a dialog where you can select which contacts are to be exported.</para>
+
+<screenshot>
+<screeninfo>The export selection dialog.</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="exportdlg.png" format="PNG"/></imageobject>
+<textobject><phrase>The export selection dialog.</phrase></textobject>
+<caption><para>The export selection dialog.</para></caption>
+</mediaobject>
+</screenshot>
+
+<para>The following import and export plugins are available at the
+moment:</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>vCard</guilabel></term>
+<listitem><para>the vCard format is standardized format (RFC 2426)
+that is supported by most addressbook applications &mdash;
+&kaddressbook; can import and export versions 2.1 and 3.0;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Mobile Phone</guilabel></term>
+<listitem><para>this plugin can import contacts from Nokia mobile
+phones via the gnokii library;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Eudora Addressbook</guilabel></term>
+<listitem><para>with this plugin you can import your contacts from
+the Eudora mail client;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>CSV</guilabel></term>
+<listitem><para>CSV (comma separated value) is a format that is used
+by many (addressbook) applications &mdash; you can import and export your
+contacts with this format;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>KDE2</guilabel></term>
+<listitem><para>to import your old addressbook data from KDE 2.X you
+can use this item;</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>LDIF</guilabel></term>
+<listitem><para>LDIF is a plain-text representation of LDAP data, used by
+Netscape and Mozilla to store their addressbook
+data &mdash; &kaddressbook; supports import and export of this format;
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>PAB</guilabel></term>
+<listitem><para>PAB is the MS Exchange Personal Address Book format, used
+by MS Outlook and MS Outlook Express to store their contact
+data &mdash; &kaddressbook; supports the import of this format;
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Opera</guilabel></term>
+<listitem><para>use this plugin to import the contact database of the Opera web browser;
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Bookmarks</guilabel></term>
+<listitem><para>this is a pseudo export plugin that makes the web URLs
+of your contacts available in the bookmark menu of konqueror.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="ldap-queries">
+<title>LDAP queries</title>
+<para>
+Address information from LDAP servers can be imported into &kaddressbook;'s
+local addressbook by using the LDAP search dialog.
+</para>
+<para>
+To configure (a number of) LDAP servers, use the
+<link linkend="preferences-ldap-lookup">configuration dialog.</link>
+</para>
+<para>
+On the main toolbar in &kaddressbook; a button with a picture of
+a magnifying glass over a book is available: use this button to open
+the LDAP search dialog. The dialog itself is pretty straight
+forward; just type in parts of a name, email address or phone number
+and press the <guibutton>Search</guibutton> button.
+</para>
+<para>When the results display in the listbox it is possible to select
+one or more address(es); you can then use the <guibutton>Add Selected</guibutton> to
+import the selected address(es) to the local addressbook, or click the
+<guibutton>Send email to Contact</guibutton> to invoke a mail program
+to write an email to the selected recipients.
+</para>
+<para>
+The <guibutton>Recursive search</guibutton> checkbox is enabled by
+default; this will make the LDAP query consider all objects
+below the base DN of each server. If you only want to consider objects
+one level below the base uncheck this checkbox; if in doubt, leave it
+checked.
+</para>
+</sect1>
+
+<sect1 id="preferences">
+<title>Preferences</title>
+
+<para>You can modify many aspects of &kaddressbook;'s behavior in the
+preferences dialog; the dialog can be opened via
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+KAddressBook</guimenuitem></menuchoice> or using the toolbar icon.</para>
+
+<screenshot>
+<screeninfo>Configuring &kaddressbook;</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="conf.png" format="PNG"/></imageobject>
+<textobject><phrase>The preferences dialog.</phrase></textobject>
+<caption><para>The preferences dialog.</para></caption>
+</mediaobject>
+</screenshot>
+
+<sect2 id="preferences-address-book">
+<title>The <guilabel>Address Book</guilabel> Page</title>
+
+<sect3 id="preferences-address-book-general">
+<title>The <guilabel>General</guilabel> Tab</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Honor KDE single click</guilabel></term>
+<listitem><para>If checked, &kaddressbook; pays attention to the
+KDE single-click option.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Automatic Name Parsing for new addresses</guilabel></term>
+<listitem><para>If checked, the <link linkend="managing-contacts-automatic-nameparsing">automatic name parsing</link>
+feature is used for new addresses.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Script-Hooks</guilabel></term>
+<listitem><para>Here you can specify the commands which are to be executed
+whenever you click at a phone number or fax number link in the details page.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Extensions</guilabel></term>
+<listitem><para>In this list view you can enable and disable extensions individually
+and configure their settings.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect3>
+
+<sect3 id="preferences-address-book-contact">
+<title>The <guilabel>Contact</guilabel> Tab</title>
+<para>&kaddressbook; can automatically parse a name into its parts; to make
+sure this works in many cases you can add, here, additional name parts,
+like prefixes, suffixes and inclusions.
+</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Prefixes</guilabel></term>
+<listitem><para>Here you can manage name prefixes, like 'Prof.' or
+'Dr.'.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Inclusions</guilabel></term>
+<listitem><para>Here you can manage name inclusions, like 'van' or
+'von', which are often part of Dutch or German names.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Suffixes</guilabel></term>
+<listitem><para>Here you can manage name suffixes like 'Sr.' or
+'Jr.'.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Default Formatted Name</guilabel></term>
+<listitem><para>Here you can select the default type of formatted names
+to be used for new contacts.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect3>
+</sect2>
+
+<sect2 id="preferences-ldap-lookup">
+<title>The <guilabel>LDAP Lookup</guilabel> Page</title>
+
+<para>On this page you can configure the LDAP servers that should be used
+for <link linkend="ldap-queries">ldap queries</link> in &kaddressbook;.</para>
+
+<para>Use <guibutton>Add Host...</guibutton> to add and setup a new server.</para>
+<screenshot>
+<screeninfo>Configuring LDAP Lookup for Kolab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="addhost.png" format="PNG"/></imageobject>
+<textobject><phrase>Example of LDAP Lookup configuration (Kolab).</phrase></textobject>
+<caption><para>The Add Host dialog - Example of LDAP Lookup configuration (Kolab).</para></caption>
+</mediaobject>
+</screenshot>
+<para>
+You can include and exclude servers from the search by selecting or deselecting their check boxes. In the server list. Press <guibutton>OK</guibutton> to close the dialog.
+</para>
+<para>You may configure the search order by moving up or down the servers in the list. This can be done using the corresponding arrows on the right side of the dialog.</para>
+</sect2>
+</sect1>
+</chapter>
+
+<chapter id="command-references">
+<title>Command References</title>
+
+<sect1 id="file-menu">
+<title>The <guimenu>File</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>New Contact</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens the contact editor for adding a new contact</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Edit Contact</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens the contact editor for editing the currently-selected
+contact</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Save</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Saves the changed contacts</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Lists all available import modules</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Export</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Lists all available export modules</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Print</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Prints the currently-selected contacts</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Send email to Contact</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens the preferred mail program with the currently-selected
+contacts as recipients</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Send Contact</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens the preferred mail program with the currently-selected
+contact details attached as vCard</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Quits</action> &kaddressbook;.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="edit-menu">
+<title>The <guimenu>Edit</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Undo</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Undos the last change</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Redo</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Redos the last change</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Cut</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Cuts the currently-selected contacts</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Copy</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Copies the currently-selected contacts to the
+clipboard</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Paste</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Paste the clipboard contents into the address book (if
+it is in a valid format)</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul"><keycap>Delete</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Delete Contact</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Deletes the currently-selected contacts</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo>
+</shortcut>
+<guimenu>Edit</guimenu>
+<guimenuitem>Select All</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Selects all contacts</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Edit</guimenu>
+<guimenuitem>Set Categories</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a dialog where you can set the categories
+for the currently-selected contacts; when the selected categories differ
+from the categories of the contacts the dialog will ask you if you
+want to merge these differences or if the categories should be overwritten
+</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Edit</guimenu>
+<guimenuitem>Set Who Am I</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Marks the currently selected contact as the 'Who Am I' contact,
+which represents the user's data. You should have such a contact, because other
+applications, like &kmail; and &kword;, can make use of these data: this way you don't have
+to input it separately in every application
+</action>.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="view-menu">
+<title>The <guimenu>View</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guisubmenu>Select View</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Lists all available views</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Add View</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a <link linkend="using-views">dialog</link> for
+creating a new view</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Modify View...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a <link linkend="using-views">dialog</link> where
+you can modify the settings of the current view</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Delete View</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Deletes the current view</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Refresh View</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Refreshes the current view</action>.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="tools-menu">
+<title>The <guimenu>Tools</guimenu> Menu</title>
+<para>This menu provides tools for acting on the contact database.</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Tools</guimenu>
+<guisubmenu>Lookup Addresses in Directory</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Opens the search dialog for addresses located on
+LDAP servers. You can configure the server settings in the
+<link linkend="preferences-address-book-contact">configure dialog</link></action>.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="settings-menu">
+<title>The <guimenu>Settings</guimenu> Menu</title>
+<para>This menu provides options for configuring &kaddressbook;, changing its
+appearance, shortcuts and standard behavior.</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Toolbars</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Toggles the toolbars on/off</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Show Extension Bar</guisubmenu>
+</menuchoice></term>
+<listitem><para><action>Selects what extension should be shown in the
+extension bar at the bottom of the main window</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Jump Bar</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggles the Jump Bar on/off</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Details</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggles the Details Page on/off</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Edit Filter</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a <link linkend="using-filters">dialog</link> where
+you can edit the filters</action>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a dialog for changing the key bindings.</action>
+Using this option you can change the standard keyboard shortcuts for &kaddressbook;'s commands
+or create new ones.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a dialog for configuring the toolbar.</action> You
+can add and remove toolbuttons for &kaddressbook;'s commands with this option.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure KAddressBook...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Opens the <link linkend="preferences">preferences dialog</link>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="help-menu">
+<title>The <guimenu>Help</guimenu> Menu</title>
+&help.menu.documentation;
+</sect1>
+</chapter>
+
+<chapter id="command-line">
+<title>Command Line Options</title>
+<para>&kaddressbook; supports some command-line arguments, which can be
+used to influence its starting behavior:</para>
+
+<variablelist>
+<varlistentry>
+<term><command>kaddressbook</command> <option>-a, --addr &lt;email&gt;</option></term>
+<listitem><para>Shows the contact editor with the given email address.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>kaddressbook</command> <option>--uid &lt;uid&gt;</option></term>
+<listitem><para>Shows the contact editor with the given uid.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>kaddressbook</command> <option>--editor-only</option></term>
+<listitem><para>Launches in editor only mode.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><command>kaddressbook</command> <option>--new-contact</option></term>
+<listitem><para>Launches an editor for a new contact.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>&kaddressbook; also supports all other command-line options common to
+&kde; and &Qt; programs; you can get a list of these options with
+<userinput><option>--help</option></userinput>,
+<userinput><option>--help-kde</option></userinput>, and
+<userinput><option>--help-qt</option></userinput>.</para>
+</chapter>
+
+<chapter id="configure-non-gui-options">
+<title>Options Without a User Interface Representation</title>
+<para>
+Apart from the options presented in the configuration dialog, some options
+can only be set directly in the configuration file ($KDEHOME/share/config/kaddressbookrc)
+or through KIOSK.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>ContactListAboveExtensions</guilabel></term>
+<listitem>
+<para>
+If enabled, extensions (e.g. the distribution list editor) are shown below the contact list,
+not in an separate column. By default, this option is disabled.
+
+To enable this option, add a line reading (under [MainWindow] section):
+</para>
+<programlisting>ContactListAboveExtensions=true
+</programlisting>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+
+<para>&kaddressbook; - The &kde; Address Book</para>
+
+<para>Copyright (c) 1997-2003, The KDE-PIM Team</para>
+
+<para>&kaddressbook; was originally written in 1997 by Don Sanders
+<email>dsanders@kde.org</email>. Currently it is
+maintained by Tobias Koenig <email>tokoe@kde.org</email>.</para>
+
+&underFDL; <!-- FDL: do not remove -->
+</chapter>
+</book>
+
diff --git a/doc/kaddressbook/mainwin.png b/doc/kaddressbook/mainwin.png
new file mode 100644
index 00000000..147ae19f
--- /dev/null
+++ b/doc/kaddressbook/mainwin.png
Binary files differ
diff --git a/doc/kaddressbook/resourcedlg.png b/doc/kaddressbook/resourcedlg.png
new file mode 100644
index 00000000..800552de
--- /dev/null
+++ b/doc/kaddressbook/resourcedlg.png
Binary files differ
diff --git a/doc/kaddressbook/resourcesdlg.png b/doc/kaddressbook/resourcesdlg.png
new file mode 100644
index 00000000..7870fd1f
--- /dev/null
+++ b/doc/kaddressbook/resourcesdlg.png
Binary files differ
diff --git a/doc/kaddressbook/vieweditdlg.png b/doc/kaddressbook/vieweditdlg.png
new file mode 100644
index 00000000..84ccd1d3
--- /dev/null
+++ b/doc/kaddressbook/vieweditdlg.png
Binary files differ
diff --git a/doc/kalarm/Makefile.am b/doc/kalarm/Makefile.am
new file mode 100644
index 00000000..171f575c
--- /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 00000000..da0fa1ae
--- /dev/null
+++ b/doc/kalarm/alarmmessage.png
Binary files differ
diff --git a/doc/kalarm/editwindow.png b/doc/kalarm/editwindow.png
new file mode 100644
index 00000000..cfb60992
--- /dev/null
+++ b/doc/kalarm/editwindow.png
Binary files differ
diff --git a/doc/kalarm/index.docbook b/doc/kalarm/index.docbook
new file mode 100644
index 00000000..28f44e78
--- /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>pbrown@kde.org</email></para>
+</listitem>
+<listitem><para>David Jarvie <email>&David.Jarvie.mail;</email></para>
+</listitem>
+<listitem><para>Cornelius Schumacher <email>schumacher@kde.org</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>stefan.nikolaus@stuco.uni-oldenburg.de</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 00000000..a1c58908
--- /dev/null
+++ b/doc/kalarm/mainwindow.png
Binary files differ
diff --git a/doc/kalarm/spinbox.png b/doc/kalarm/spinbox.png
new file mode 100644
index 00000000..ef9db897
--- /dev/null
+++ b/doc/kalarm/spinbox.png
Binary files differ
diff --git a/doc/kandy/Makefile.am b/doc/kandy/Makefile.am
new file mode 100644
index 00000000..171f575c
--- /dev/null
+++ b/doc/kandy/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
diff --git a/doc/kandy/index.docbook b/doc/kandy/index.docbook
new file mode 100644
index 00000000..c1a952a3
--- /dev/null
+++ b/doc/kandy/index.docbook
@@ -0,0 +1,348 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY kappname "&kandy;">
+ <!ENTITY package "kdepim">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kandy; Handbook</title>
+<authorgroup>
+<author>
+<firstname>Cornelius</firstname>
+<surname>Schumacher</surname>
+<affiliation>
+<address><email>schumacher@kde.org</email></address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+<date>2002-02-05</date>
+<releaseinfo>0.03.00</releaseinfo>
+<abstract>
+<para>&kandy; is an application for synchronizing the data on a mobile phone
+with the data on the desktop.</para>
+</abstract>
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdepim</keyword>
+<keyword>kandy</keyword>
+<keyword>synchronizing</keyword>
+<keyword>phone</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="using-kandy">
+<title>Using &kandy;</title>
+
+<sect1 id="terminal">
+<title>The Terminal Window</title>
+
+<para>The terminal window provides a low-level interface for controlling
+the mobile phone via <command>AT</command> modem commands. You can type
+in commands in the upper middle field: the lower-middle fields show
+the direct response of the mobile phone; the right side of the main
+window shows the processed output.</para>
+
+<para> On the left side you have the list of available commands; you
+can execute them by double-clicking on them or by pressing the
+<guibutton>Execute</guibutton> button. The modem response output
+fields show what happens. If you have typed in a new command you can
+add it to the list of available commands by pressing the
+<guibutton>Add</guibutton> button; a dialog will pop up to allow you
+select a name and parameters for the command.</para>
+
+<para>The command list is saved to an &XML; file by selecting
+<guimenuitem>Save</guimenuitem> from the menu or by pressing the
+corresponding toolbar button. You can load an existing file by selecting
+<guimenuitem>Open</guimenuitem> from the menu.</para>
+
+</sect1>
+
+<sect1 id="mobilegui">
+<title>Mobile Interface Window</title>
+
+<para>By choosing <guimenuitem>Mobile GUI</guimenuitem> from the
+<guimenu>Show</guimenu> menu of the terminal window you open the
+Interface Window for your mobile phone. This shows a comprehensive view
+of the status and data present on the phone including the
+phonebook. There are twos list of phonebook data: one representing the
+&kde; address book; the other representing the data on the
+phone.</para>
+
+<para>You can read the phone books by pressing the
+<guibutton>Read</guibutton> button right under the corresponding
+list. By pressing the <guibutton>Write</guibutton> button you write back
+the data shown in the list to the corresponding phonebook. By pressing
+<guibutton>Save to File</guibutton> you can store the mobile phonebook
+as list of comma-separated values to disk. After loading the phonebook
+data using the <guibutton>Read</guibutton> buttons you can merge the
+phonebooks by pressing the <guibutton>Merge</guibutton> button: this
+will put data only present in one of the phonebooks into the other and
+vice versa; if conflicts occur during this process, a dialog pops
+up.</para>
+
+<para>The <guibutton>Sync</guibutton> button performs all the actions
+needed for syncing the phonebooks. It reads the data from the &kde;
+addressbook and the mobile phone, does the merge and writes it
+back.</para>
+
+</sect1>
+
+<sect1 id="configuring">
+<title>Configuring &kandy;</title>
+
+<para>By selecting the entry <guimenuitem>Configure Kandy</guimenuitem>
+from the menu you get the preferences dialog of &kandy;. You can set the
+name of the serial device where your mobile is connected in this
+dialog; examples for the name of the serial device under &Linux; are
+<filename class="devicefile">/dev/ttyS0</filename> for the first and
+<filename class="devicefile">/dev/ttyS1</filename> for the second serial
+interface of your computer. You can also set which windows are opened
+by default when starting &kandy;.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="menu-ref">
+<title>Menu Reference</title>
+
+<sect1>
+<title><guimenu>File</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">
+&Ctrl;<keycap>Q</keycap>
+</keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Exit</action> &kandy;.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="show-menu">
+<title><guimenu>Show</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Show</guimenu>
+<guimenuitem>Terminal</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Open the terminal window</action>, where you can interact
+with your phone via <command>AT</command> commands.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="modem-menu">
+<title><guimenu>Modem</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Modem</guimenu>
+<guimenuitem>Connect</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Connect to your phone.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Modem</guimenu>
+<guimenuitem>Disconnect</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Disconnect from your phone.</action></para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="settings-menu">
+<title><guimenu>Settings</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Toolbar</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Toggle whether the toolbar should be displayed.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenu>Show Statusbar</guimenu>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Toggle whether the statusbar should be displayed.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Open a standard dialog to modify shortcut
+keybindings.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Open a standard dialog to modify the icons on the
+toolbar.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Kandy...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Opens a dialog where you can customize the
+application.</action>; this is described further in the <xref
+linkend="configuring"/> section.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="help-menu">
+<title><guimenu>Help</guimenu> menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+</chapter>
+
+<chapter id="credits">
+<title>Credits and Licenses</title>
+
+<para>&kandy; copyright 2001 Cornelius Schumacher
+<email>schumacher@kde.org</email>.</para>
+
+<para>Documentation by Cornelius Schumacher, with additions by Lauri
+Watts <email>lauri@kde.org</email>.</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underGPL;
+&underFDL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kandy">
+<title>How to obtain &kandy;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="kandy-requirements">
+<title>Requirements</title>
+
+<para>You will need to have the kdelibs package installed in order to
+successfully compile the kdepim package that contains &kandy;. The
+kdelibs package may be found at the same location as the kdepim
+package.</para>
+
+<para>The &kaddressbook; is part of the kdebase package. This can also
+be found at the same location as the kdepim package.</para>
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+<para>Compiling and installing the required kdelibs package follows the
+same process. If you encounter any problems compiling or installing
+&kandy;, help may be obtained from the <ulink
+url="http://www.kde.org/mailinglists.html">&kde; mailing lists </ulink>
+or from the Usenet newsgroup: comp.windows.x.kde.</para>
+</sect1>
+</appendix>
+
+<appendix id="developer-info">
+<title>Developer Information</title>
+
+<sect1 id="dcop">
+<title><acronym>DCOP</acronym> Interface</title>
+
+<para>&kandy; provides a <acronym>DCOP</acronym> interface
+<interfacename>KandyIface</interfacename> with the following functions:
+<function>syncPhonebook()</function> syncs the mobile phone book book
+with the &kde; address book. This is equivalent to pressing the
+<guibutton>Sync</guibutton> button in the Mobile Interface
+Window. <function>exit()</function> closes &kandy;.</para>
+
+</sect1>
+
+</appendix>
+
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->
diff --git a/doc/karm/Makefile.am b/doc/karm/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/karm/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/karm/clipboard-history.png b/doc/karm/clipboard-history.png
new file mode 100644
index 00000000..ee0b04d3
--- /dev/null
+++ b/doc/karm/clipboard-history.png
Binary files differ
diff --git a/doc/karm/copy-this-task.png b/doc/karm/copy-this-task.png
new file mode 100644
index 00000000..f5c89bea
--- /dev/null
+++ b/doc/karm/copy-this-task.png
Binary files differ
diff --git a/doc/karm/csvexport.png b/doc/karm/csvexport.png
new file mode 100644
index 00000000..7dc5f8e5
--- /dev/null
+++ b/doc/karm/csvexport.png
Binary files differ
diff --git a/doc/karm/daterange.png b/doc/karm/daterange.png
new file mode 100644
index 00000000..3ad3a70f
--- /dev/null
+++ b/doc/karm/daterange.png
Binary files differ
diff --git a/doc/karm/idle-detect.png b/doc/karm/idle-detect.png
new file mode 100644
index 00000000..43bf7181
--- /dev/null
+++ b/doc/karm/idle-detect.png
Binary files differ
diff --git a/doc/karm/index.docbook b/doc/karm/index.docbook
new file mode 100644
index 00000000..be0faf1e
--- /dev/null
+++ b/doc/karm/index.docbook
@@ -0,0 +1,1238 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY kappname "&karm;">
+ <!ENTITY package "kdepim">
+ <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+ <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &karm; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Jonathan</firstname>
+<surname>Singer</surname>
+<affiliation>
+<address><email>jsinger@leeta.net</email></address>
+</affiliation>
+</author>
+
+<author>
+<firstname>Mark</firstname>
+<surname>Bucciarelli</surname>
+<affiliation>
+<address><email>mark@hubcapconsulting.com</email></address>
+</affiliation>
+</author>
+
+<author>
+<firstname>Sirtaj</firstname>
+<othername>Singh</othername>
+<surname>Kang</surname>
+<affiliation><address><email>taj@kde.org</email></address></affiliation>
+</author>
+
+<othercredit role="reviewer">
+<firstname>Lauri</firstname>
+<surname>Watts</surname>
+<contrib>Reviewer</contrib>
+<affiliation><address><email>lauri@kde.org</email></address></affiliation>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2000-2004</year>
+<holder>Jonathan Singer</holder>
+</copyright>
+
+<copyright>
+<year>2004-2005</year>
+<holder>Mark Bucciarelli</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-02-02</date>
+<releaseinfo>1.5.0</releaseinfo>
+
+<abstract><para>&karm; tracks time spent on various tasks.</para></abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>karm</keyword>
+<keyword>kdeutils</keyword>
+<keyword>time</keyword>
+<keyword>tracker</keyword>
+<keyword>project</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&karm; tracks time spent on various tasks. It is useful for tracking
+ billable hours and can report the hours logged by task and day.</para>
+
+<para>This time history can be exported to a comma-delimited text file for
+ import into other billing and/or project management tools.</para>
+
+<para>&karm; detects when your keyboard and mouse are idle and can associate
+ different tasks with different desktops, two tools that can help keep the
+ timer running on the correct task.</para>
+
+<para>&karm; was originally written by Sirtaj Singh Kang. The word
+<quote>karm</quote> means <quote>work</quote> or <quote>deeds</quote> in the
+author's native Punjabi and is the same word (but a better transliteration)
+as <quote>karma</quote>.</para>
+
+</chapter>
+
+
+<chapter id="using-Karm">
+<title>Using &karm;</title>
+
+<sect1 id="starting">
+<title>Starting &karm;</title>
+
+<para>Type <command>karm</command> at a command prompt or select
+<guimenuitem>Personal Time Tracker</guimenuitem> from the
+<guisubmenu>Utilities</guisubmenu> group in the <guimenu>KDE start
+menu</guimenu>. The standard &Qt; and &kde; command options are
+available, and can be listed by entering
+<userinput><command>karm</command> <option>--help</option></userinput>
+at the command line.</para>
+
+<para>&karm; provides an additional command option that allows you to enter
+the name of the iCalendar file that is used to store your labor history.
+You enter a remote iCalendar file by using http or ftp as part of the file
+name; for example, http://www.mysite.com/mydata/mylabor.ics.</para>
+
+</sect1>
+
+<sect1 id="general-use">
+<title>Tasks</title>
+
+<informalexample>
+<para><emphasis>Problem:</emphasis> You are a free software consultant with
+many clients. Some clients have multiple projects. During the course of a
+day, you switch back and forth between different projects. You need to track
+your time to generate monthly invoices.</para>
+<para><emphasis>Solution:</emphasis> Create one top-level task for each client
+and a subtask for each client project. For projects that require more
+detailed tracking, create a list of project subtasks. Track time by
+double-clicking on task you are currently working on.</para>
+</informalexample>
+
+<para>&karm; provides great flexibility in tracking your time, allowing
+unlimited tasks and task depth. Time may be logged to any task, and more than
+one task can be active at any given time.</para>
+
+<para>
+To create a top-level task, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>New</guimenuitem>
+</menuchoice>
+
+To create a subtask, pick the parent task and select
+
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>New Subtask</guimenuitem>
+</menuchoice>
+</para>
+
+<para>When &karm; exits, the task list is saved to the file specified in
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure KArm</guimenuitem>
+</menuchoice>.
+When it next opens, it reloads the task list from the same file.</para>
+
+<para>&karm; can import and export tasks to minimize your work. See <link linkend="interfaces">Other Systems</link>.</para>
+
+</sect1>
+
+<sect1 id="timers"><title>Timers</title>
+
+<informalexample>
+<para><emphasis>Problem:</emphasis> To remain solvent, you must bill an
+average of five hours a day. To stay on track, you watch your daily and
+weekly totals.</para>
+<para><emphasis>Solution:</emphasis> Reset the session timer at the
+beginning of each work day and reset all timers at the beginning of each
+week.</para> </informalexample>
+
+<para>&karm; makes tracking time simple. To start logging time against a
+task, double-click on the task. To stop logging time, double-click
+the task again. Active tasks display a small clock in the <guilabel>Session
+Time</guilabel> column.</para>
+
+<para>Another visual clue of logging activity is the &karm; system tray icon.
+When a task is active, the second hand in the icon moves. If you rest the
+mouse pointer over this icon, the name of the active task will display in a
+tooltip. If more than one task is active, the task names in the tooltip are
+separated by commas.</para>
+
+<para>&karm; maintains two timers for each task: one for the session time
+and one for the total time. In the default configuration, &karm; displays
+two columns for each timer, resulting in a total of four columns for each task:</para>
+
+<variablelist>
+<varlistentry> <term><guilabel>Session Time</guilabel></term>
+<listitem><para>The time spent on the task since the session
+began.</para></listitem> </varlistentry>
+
+<varlistentry> <term><guilabel>Total Session Time</guilabel></term>
+<listitem><para>The time spent on the task and all it's subtasks since the
+session began.</para></listitem> </varlistentry>
+<varlistentry> <term><guilabel>Time</guilabel></term> <listitem><para>The time
+spent on the task since all times were reset.</para></listitem>
+</varlistentry>
+
+<varlistentry> <term><guilabel>Total Time</guilabel></term>
+<listitem><para>The time spent on the task and all it's subtasks since all
+times were reset.</para></listitem> </varlistentry>
+</variablelist>
+
+<para>To start a new session, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Start New Session</guimenuitem>
+</menuchoice>
+</para>
+
+<para>To reset all times, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Reset All Times</guimenuitem>
+</menuchoice>
+</para>
+
+<sect2><title>Desktop Tracking</title>
+
+<informalexample>
+<para><emphasis>Problem:</emphasis> You have two main projects that you
+switch between each day. To help organize your work, you keep your project
+1 files on Desktop 1 and your project 2 files on Desktop
+2.</para>
+
+<para><emphasis>Solution:</emphasis> Associate project 1 task with Desktop 1
+and the project 2 task with Desktop 2. When you switch from Desktop 2 to
+Desktop 1 active, &karm; automatically stops the project 2 task and starts
+the project 1 task.</para>
+</informalexample>
+
+<para>To associate a task with a one or more desktops, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>Edit</guimenuitem>
+</menuchoice>.
+
+Turn on <guilabel>Auto tracking</guilabel> and select the desktop or desktops
+to associate with this task. When any of the selected desktops becomes active,
+after a short delay &karm; will be automatically start logging time against
+that task.</para>
+
+</sect2>
+
+<sect2><title>Idle Detection</title>
+
+<informalexample> <para><emphasis>Problem:</emphasis> You leave work early on
+Friday to run an errand and forget to stop the timer. When you return on
+Monday, the timer is still running.</para>
+<para><emphasis>Solution:</emphasis> Turn on idle detection.</para>
+</informalexample>
+
+<para>&karm; can be configured to detect when the mouse and keyboard become
+ idle. If the mouse and keyboard are idle for longer than the specified
+ number of minutes, &karm; displays the following dialog:</para>
+
+<screenshot>
+ <screeninfo>&karm; Idle Detection</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="idle-detect.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>&karm; Idle Detection Dialog</phrase>
+ </textobject>
+ </mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry><term><guibutton>Revert &amp; Stop</guibutton></term>
+<listitem><para>Subtract the amount of idle time from all active timers and
+stop them.</para><para>You were not working on the task(s) while you
+computer was idle and you are still are
+not.</para></listitem></varlistentry>
+
+<varlistentry> <term><guibutton>Revert &amp; Continue</guibutton></term>
+<listitem><para>Subtract the amount of idle time from all active timers but
+keep them running.</para><para>You were not working on the task(s) while
+your computer was idle but you are now. </para></listitem></varlistentry>
+
+<varlistentry> <term><guibutton>Continue Timing</guibutton></term>
+<listitem><para>Apply the idle time to all active timers and keep them
+running.</para><para>You were working on the task(s) while your computer
+was idle and still are. </para></listitem></varlistentry> </variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="reporting"><title>Reporting</title>
+
+<para>&karm; provides three ways to report on time you have logged. You can
+send the session and time totals to the printer, copy the time totals to the
+clipboard, or copy the time history to the clipboard.</para>
+
+<sect2><title>Print Totals</title>
+<para>To generate the totals report for the printer, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Print</guimenuitem>
+</menuchoice>.
+This generates a three-column report for the complete list of tasks. The
+first column is the task name, the second column is the <guilabel>Total
+Session Time</guilabel> and the third column is the <guilabel>Total
+Time</guilabel>.</para>
+</sect2>
+
+<sect2><title>Clip Totals</title>
+<para>To generate the totals report to the clipboard, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy Totals to Clipboard</guimenuitem>
+</menuchoice>.
+</para>
+
+<para>This report is generated for the currently selected task and all it's
+subtasks. If the current task is a top-level task, &karm; asks you if you
+want to generate the report for the current task and it's subtasks or for the
+entire task list.</para>
+
+<screenshot>
+<screeninfo>&karm; Copy This Task</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="copy-this-task.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>&karm; Copy This Task Dialog</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>Once the report is generated, open KEdit or some other text editor and
+paste the report data.</para>
+
+<literallayout>
+<computeroutput>
+Task Totals
+2004-07-10 02:26
+
+ Time Task
+----------------------------------------------
+ 9:14 kde
+ 9:14 karm
+ 1:08 bugs
+ 0:00 checkin changes
+ 0:00 promo
+ 0:00 web stuff
+----------------------------------------------
+ 9:14 Total
+</computeroutput>
+</literallayout>
+
+<para>The first column is the <guilabel>Total Time</guilabel> and is indented
+(like the task names) to indicate task/sub-task relationships. The reported times
+include the sub-task times.</para>
+
+</sect2>
+
+<sect2><title>Clip History</title>
+
+<para>To generate the totals report to the clipboard, select
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy History to Clipboard</guimenuitem>
+</menuchoice>.
+</para>
+
+<important><para>You must turn on the <guilabel>Log History</guilabel> option in
+<menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure
+KArm</guimenuitem> </menuchoice>. Otherwise, &karm; only keeps track of
+totals and not the detailed task history.</para></important>
+
+<para>This report is generated for the currently selected task and all it's
+subtasks. You also have the choice to generate it for all tasks.</para>
+
+<para>When you select the history report, &karm; first prompts you to enter the
+date range for the report:</para>
+
+<screenshot>
+<screeninfo>&karm; Enter Date Range</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="daterange.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>&karm; Enter Date Range</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>After entering a date range, open KEdit or some other text editor and
+paste the report data.</para>
+
+<literallayout>
+<computeroutput>
+Task History
+From Thursday 01 July 2004 to Monday 12 July 2004
+Printed on: 2004-07-12 17:18
+
+ Week of Monday 05 July 2004
+ 5 6 7 8 9 10 11
+-------------------------------------------------------------------------
+ 0:00 kde
+ 0:00 dc
+ !:22 1:46 3:14 1:44 8:06 karm
+ 0:00 3.2 feature plan
+ 1:08 1:08 bugs
+ 0:00 checkin changes
+ 0:00 promo
+ 0:00 web stuff
+-------------------------------------------------------------------------
+ 2:30 1:46 3:14 1:44 9:14 Total
+</computeroutput>
+</literallayout>
+
+<para>The task history is totaled for each day and task, grouped by week. The
+first seven columns are Monday through Sunday. The eighth column is the total
+for the week and the ninth column is the task name. The task names are
+indented to indicate the task/sub-task relationships.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="interfaces">
+<title>Other Systems</title>
+<sect2 id="korganizer"><title>KOrganizer</title>
+
+<para>&karm;, like KOrganizer and Apple's iCal, uses the industry standard
+<ulink
+url="http://developer.kde.org/documentation/standards/index.html">iCalendar</ulink>
+format for its data. &karm; can read and write the to do lists created by
+these two applications.</para>
+
+<warning><para>If both &karm; and KOrganizer have the same file open, if you
+edit the file with KOrganizer, you risk losing data. To be safe,
+only edit the file with one application or the other.</para></warning>
+
+</sect2>
+
+<sect2 id="planner"><title>Planner</title>
+
+<para>As a typical usecase, you might want to plan a project with the project
+management tool Imendio Planner
+(from <ulink url="http://planner.imendio.org">planner.imendio.org</ulink>)
+and import its tasks to &karm;, to have them in the industry
+standard <ulink
+url="http://developer.kde.org/documentation/standards/index.html">iCalendar</ulink>
+format. Having done so, you are able to schedule the tasks in KOrganizer, and account your time
+to them in &karm;. That's one way to help ensure your project stays on time
+and under budget.</para>
+
+</sect2>
+
+<sect2 id="dcop"><title>&DCOP;</title>
+
+<para>&DCOP; is the mechanism KDE programs use to communicate with each
+other. A KDE program provides a list of functions that other programs (a Bash
+script, for example) can use.</para>
+
+<example><title>Bash script that echo's &karm;'s version</title>
+<programlisting>
+ DCOPID=`dcop | grep karm`
+ if [ $DCOPID ]
+ then
+ VERS=`dcop $DCOPID KarmDCOPIface version`
+ echo "&karm; version is $VERS"
+ else
+ echo "&karm; not running"
+ fi
+</programlisting>
+</example>
+
+<para>&karm;'s current &DCOP; interface is currently used mainly for automated
+ testing, so it is very limited. For the full interface definition, see
+ <link linkend="dcopappendix">&DCOP; Interface Appendix</link>.</para>
+
+<para>To see the full &DCOP; interface of the &karm; version installed on your
+ system, run the following Bash script:</para>
+
+<example><title>List &karm;'s &DCOP; interface to console</title>
+<programlisting>
+ DCOPID=`dcop | grep karm`
+ if [ $DCOPID ]
+ then
+ dcop $DCOPID KarmDCOPIface
+ else
+ echo "&karm; not running"
+ fi
+</programlisting>
+</example>
+</sect2>
+
+<sect2 id="csv-export"><title>Export Totals to CSV</title>
+
+<para>&karm; can export both totals and history to a comma-delimited file
+format. To export totals, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export to CSV file...</guimenuitem>
+</menuchoice> and &karm; displays the following export dialog:</para>
+
+<screenshot>
+<screeninfo>&karm; CSV Export Dialog</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="csvexport.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>&karm; CSV Export Dialog</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>Enter the file you would like to export the data to, and modify the
+other dialog defaults if necessary. Note that the date range control is
+disabled since you are exporting time totals, not the history data. Click
+<guibutton>Export</guibutton> and &karm; exports the totals for all tasks to
+the file you selected.</para>
+
+<para>Here is an example of the output format:</para>
+
+<literallayout>
+<computeroutput>
+"kde",,,,,0.00,0.00,6.88,9.83
+,"karm",,,,6.88,8.70,6.88,9.83
+,,"3.2 feature plan",,,0.00,0.00,0.00,0.00
+,,"bugs",,,0.00,1.13,0.00,1.13
+,,"checkin changes - translation strings",,,0.00,0.00,0.00,0.00
+,,"time card report",,,0.00,0.00,0.00,0.00
+,"kopete",,,,0.00,0.00,0.00,0.00
+,"promo",,,,0.00,0.00,0.00,0.00
+,"web stuff",,,,0.00,0.00,0.00,0.00
+</computeroutput>
+</literallayout>
+
+<para>Top-level tasks are output in the first column, sub-tasks in the second,
+and so on. The time data is output after the maximum task depth (five in
+this example). The first time column is <guilabel>Session Time</guilabel>,
+the second is <guilabel>Time</guilabel>, the third is <guilabel>Total Session
+Time</guilabel> and the fourth is the <guilabel>Total Time</guilabel>.
+</para>
+
+
+</sect2>
+
+<sect2 id="csv-export-history"><title>Export History to CSV</title>
+
+<para>To export task history, select
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export History to CSV file...</guimenuitem>
+</menuchoice> and &karm; displays the same export dialog as shown above.</para>
+
+<para>Enter the file you would like to export the data to, and select a date
+range that you want the task history. Modify the other dialog defaults if
+necessary. Click <guibutton>Export</guibutton> and &karm; exports the
+task history for all tasks to the file you selected.</para>
+
+<para>Here is an example of the output format:</para>
+
+<literallayout>
+<computeroutput>
+Task History
+From Tuesday 06 July 2004 to Tuesday 13 July 2004
+Printed on: 2004-07-13 18:10
+2004-07-06,2004-07-07,2004-07-08,2004-07-09,2004-07-10,2004-07-11,2004-07-12,2004-07-13,
+,,,,,,,,0.00,"kde"
+,,1.77,3.23,1.73,,1.37,0.82,8.95,,"karm"
+,,,,,,,,0.00,,,"3.2 feature plan"
+,1.13,,,,,,,1.13,,,"bugs"
+,,,,,,,,0.00,,,"checkin changes - translation strings"
+,,,,,,,,0.00,,,"time card report"
+,,,,,,,,0.00,,"kopete"
+,,,,,,,,0.00,,"promo"
+,,,,,,,,0.00,,"web stuff"
+</computeroutput>
+</literallayout>
+
+<para>The three lines identify when the report was generated and for which
+date range. The fourth row is a comma-delimited list of the dates in the
+date range, in ISO 8601 format (YYYY-MM-DD). All subsequent rows list the
+time logged against each task. The last numeric column is the row total
+across all days. The task name prints after the total column, and is indented
+to indicate the task/sub-task relationship. Top level task names appear
+in the first column after the total.</para>
+
+</sect2>
+</sect1>
+
+</chapter>
+
+<chapter id="interface">
+<title>The &karm; interface</title>
+
+<para>The main &karm; window has the following components: menubar, toolbar,
+task/time window and status bar.</para>
+
+<screenshot>
+<screeninfo>&karm; Screen</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="karm.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>&karm; Screen</phrase>
+ </textobject>
+ </mediaobject>
+</screenshot>
+
+<sect1 id="main-window">
+<title>The Task/Time window</title>
+
+<para>The various tasks are displayed in this window, along with the
+time accumulated for each in the current session and in total. Tasks
+being timed have a small clock icon next to the session time.</para>
+
+<para>Subtasks can be created for each task. Clicking the plus sign and
+minus sign in front of the main task toggles the view of its associated
+subtasks. The total time accrued for a task includes the times for its
+subtasks, as well as its own accumulated time.</para>
+
+</sect1>
+
+<sect1 id="menus">
+<title>The &karm; menubar</title>
+<sect2>
+<title>The <guimenu>File</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice><shortcut>
+<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Save</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Saves the current tasks and subtasks with their accumulated
+times</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Print</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+<action>Prints</action> the &karm; window</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Start New Session</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Resets </action>all session times to zero</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Reset All Times</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Resets </action>all times to zero</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Import Legacy Flat File...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Import </action>old style &karm; save files (&karm;
+now uses iCalendar-style save files.)</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Import Tasks from Planner...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Import </action>an imendio planner project (see <ulink
+url="http://planner.imendio.org">planner.imendio.org</ulink>). All tasks, subtasks and their "completed" flag will be imported from a .planner-file. You can import them as a subtask by creating a subtask, leaving it marked, and then importing. </para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export to CSV file...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Export </action>
+<guilabel>Total Session Time</guilabel>,
+<guilabel>Session Time</guilabel>, <guilabel>Time</guilabel>, and
+<guilabel>Total Time</guilabel> to a text file.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guisubmenu>Import/Export</guisubmenu>
+<guimenuitem>Export History to CSV file...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Export </action> task history to a text file.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy Totals to Clipboard</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Copies </action> the current total time for a
+task or all tasks to the &kde; clipboard</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>C</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Copy History to Clipboard</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Copies </action> daily times for a
+given period to the &kde; clipboard</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Closes</action> &karm;</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Clock</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycap>S</keycap></shortcut>
+<guimenu>Clock</guimenu>
+<guimenuitem>Start</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Starts</action> timing the selected task</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Clock</guimenu>
+<guimenuitem>Stop</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Stops</action> timing the selected task</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycap>&Esc;</keycap></shortcut>
+<guimenu>Clock</guimenu>
+<guimenuitem>Stop All Timers</guimenuitem>
+</menuchoice>
+</term>
+<listitem><para><action>Stops</action> timing all tasks</para></listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>The <guimenu>Task</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>New</guimenuitem>
+</menuchoice>
+</term>
+<listitem><para><action>Add</action> a new task</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>New Subtask</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Add</action> a new subtask to the selected task</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut>
+<keycap>Del</keycap>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>Delete</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Delete</action> the selected task or subtask</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>
+</shortcut>
+<guimenu>Task</guimenu>
+<guimenuitem>Edit</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Change the name or accumulated time</action> for the
+current task</para><para>There are two options for changing the time: Edit
+Absolute, in which the session and total times can be changed separately;
+and Edit Relative, in which a certain change is added to or subtracted from
+both the session and total times.</para><para>The Auto tracking option allows
+timing to start and stop automatically when you switch to or from a particular
+&kde; desktop.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>The <guimenu>Settings</guimenu> menu</title>
+<variablelist>
+
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts</guimenuitem>
+</menuchoice>
+</term>
+<listitem><para><action>Opens</action> a dialog to allow the user to customize
+the keyboard shortcuts</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure KArm</guimenuitem>
+</menuchoice>
+</term>
+<listitem><para><action>Opens</action> a dialog to allow the user to
+configure &karm;</para>
+
+<para>The dialog has three tabbed panes: <guilabel>Behavior </guilabel>, which
+allows you to specify an alert for no activity and a warning message when you
+delete a task set, <guilabel>Display </guilabel>, which configures the fields
+shown in the main window and <guilabel>Storage</guilabel>,
+which configures the location of the save file, whether auto saving is
+enabled and the auto save interval.</para> </listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>The <guimenu>Help</guimenu> menu</title>
+
+&help.menu.documentation;
+
+</sect2>
+
+</sect1>
+
+<sect1 id="tool-bar">
+<title>The Toolbar</title>
+<para>The toolbar contains icons for the following commands:</para>
+
+<note><para>(All behave identically to the menu command.)</para></note>
+
+<itemizedlist>
+<listitem><para><guiicon>Start</guiicon></para></listitem>
+<listitem><para><guiicon>Stop</guiicon></para></listitem>
+<listitem><para><guiicon>New</guiicon></para></listitem>
+<listitem><para><guiicon>New Subtask</guiicon></para></listitem>
+<listitem><para><guiicon>Delete</guiicon></para></listitem>
+<listitem><para><guiicon>Edit</guiicon></para></listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="status-bar">
+<title>The Statusbar</title>
+
+<para>Reports the total elapsed time for the session.</para>
+</sect1>
+
+</chapter>
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>
+&karm;
+</para>
+
+<para> Program copyright: </para>
+
+<itemizedlist>
+
+<listitem><para>1997-2000 Sirtaj Singh Kang
+<email>taj@kde.org</email>.</para> </listitem>
+
+<listitem><para>2001-2002 Tomas Pospisek
+<email>tpo_deb@sourcepole.ch</email></para></listitem>
+
+<listitem><para>2003-2004 Mark
+Bucciarelli<email>mark@hubcapconsulting.com</email></para></listitem>
+
+</itemizedlist>
+
+<para>Contributors (in alphabetical order)</para>
+<itemizedlist>
+<listitem><para>Allen Winter <email>winterz@verizon.net</email></para></listitem>
+<listitem><para>David Faure <email>faure@kde.org</email></para></listitem>
+<listitem><para>Espen Sand <email>espen@kde.org</email></para></listitem>
+<listitem><para>Gioele Barabucci <email>gioele@gioelebarabucci.com</email></para></listitem>
+<listitem><para>Jan Schaumann <email>jschauma@netmeister.org</email></para></listitem>
+<listitem><para>Jesper Pedersen <email>blackie@ifad.dk</email></para></listitem>
+<listitem><para>Kalle Dalheimer <email>kalle@kde.org</email></para></listitem>
+<listitem><para>Klar&auml;lvdalens Datakonsult AB</para></listitem>
+<listitem><para>Mark Bucciarelli <email>mark@hubcapconsulting.com</email></para></listitem>
+<listitem><para>Thorsten St&auml;rk <email>dev@staerk.de</email></para></listitem>
+<listitem><para>Tomas Pospisek <email>tpo_deb@sourcepole.ch</email></para></listitem>
+<listitem><para>Willi Richert <email>w.richert@cox.net</email></para></listitem>
+</itemizedlist>
+
+<para>&karm; was inspired by Harald Tveit Alvestrand's very useful
+utility called <application>titrax</application>, the only failing of
+which is that it is based on the Xt toolkit.</para>
+
+<para>Documentation copyright 2000-2004 Jonathan Singer
+<email>jsinger@leeta.net</email> and Sirtaj Singh Kang
+<email>taj@kde.org</email>.</para>
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<glossary id="glossary">
+
+<glossentry id="gloss-active-task">
+<glossterm>active task</glossterm>
+<glossdef><para>A task which has a timer running.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-dcop">
+<glossterm>&DCOP;</glossterm>
+<glossdef><para>The interprocess communication protocol used in KDE. Short
+for Desktop COmmunication Protocol.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-desktop">
+<glossterm>desktop</glossterm>
+<glossdef><para>GNU/Linux, FreeBSD and other systems that run X-Windows have
+multiple desktops. You typically have four different desktops installed by
+default. Each desktop can display it's own set of programs and files. When
+KDE first starts up, the desktop you see is Desktop 1. If you press
+<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>, you will see
+Desktop 2. Pressing <keycombo
+action="simul">&Alt;<keycap>F1</keycap></keycombo> will bring back Desktop
+1. </para></glossdef> </glossentry>
+
+<glossentry id="gloss-history">
+<glossterm>history</glossterm>
+<glossdef><para>If &karm; is configured to log history, it will record ever
+start/stop timer event. This history is never cleared when times are reset
+cleared and remains on file until the task is deleted.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-session"> <glossterm>session</glossterm>
+<glossdef><para>A user-defined starting point for the session timers. A new
+session begins when you select <menuchoice> <guimenu>File</guimenu>
+<guimenuitem>Start New Session</guimenuitem> </menuchoice>.
+Session data is not saved when you create a new session.
+</para></glossdef> </glossentry>
+
+<glossentry id="gloss-system-time"> <glossterm><guilabel>Session
+Time</guilabel></glossterm> <glossdef><para>The time spent on the task
+since the session began.</para></glossdef> </glossentry>
+
+<glossentry id="gloss-system-tray"> <glossterm>system tray</glossterm>
+<glossdef><para>The system tray is in the bar that (by default) appears at
+the bottom of the screen. In this system tray <inlinemediaobject>
+<imageobject> <imagedata fileref="systray.png"
+format="PNG"/></imageobject> </inlinemediaobject> the &karm; icon is on the far
+right.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-top-level-task">
+<glossterm>top level task</glossterm>
+<glossdef><para>A task with no parent tasks.</para></glossdef>
+</glossentry>
+
+<glossentry id="gloss-total-session-time"> <glossterm><guilabel>Total Session
+Time</guilabel></glossterm> <glossdef><para>The time spent on the task and
+all it's subtasks since the session began.</para></glossdef> </glossentry>
+<glossentry> <glossterm><guilabel>Time</guilabel></glossterm>
+<glossdef><para>The time spent on the task since all times were
+reset.</para></glossdef> </glossentry>
+
+<glossentry id="gloss-total-time"> <glossterm><guilabel>Total Time</guilabel></glossterm>
+<glossdef><para>The time spent on the task and all it's subtasks since all
+times were reset.</para></glossdef> </glossentry>
+
+</glossary>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-karm">
+<title>How to obtain &karm;</title>
+
+&install.intro.documentation;
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+<appendix id="dcopappendix"><title>&DCOP; Interface</title>
+
+<refentry id="dcop-version">
+<refmeta>
+<refentrytitle>version</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>version</refname>
+<refpurpose>Return &karm;'s version.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString version()
+</synopsis>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+<para><function>version()</function> is a &DCOP; call that returns &karm;'s
+version number; for example 1.5.0. The version number is returned as a string
+in the typical GNU format of major.minor.bugfix.</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop-quit">
+<refmeta>
+<refentrytitle>quit</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>quit</refname>
+<refpurpose>Return &karm;'s quit.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString quit()
+</synopsis>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+<para><function>quit()</function> is a &DCOP; call that provides a way that an
+external program can gracefully shutdown &karm;.
+</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop-hastodo">
+<refmeta>
+<refentrytitle>hastodo</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>hastodo</refname>
+<refpurpose>Check if top-level todo exists.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString hastodo(QString taskname)
+</synopsis>
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>taskname</parameter></term>
+<listitem>
+ <para>The name of the todo to look for.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+<refsect1>
+<title>Description</title>
+<para><function>hastodo(QString taskname)</function> is a &DCOP; call that
+ looks for a of the given name. If found, it returns the
+ iCalendar UID that identifies that todo. If not found, it returns an empty
+ string.
+</para>
+<para>The iCalendar file that &karm; currently has opened is the file that is
+searched. All todo trees are searched, not just top-level todo's. If more
+than one todo has a matching name, the first one found is returned.</para>
+</refsect1>
+</refentry>
+
+<refentry id="dcop-addtodo">
+<refmeta>
+<refentrytitle>addtodo</refentrytitle>
+</refmeta>
+<refnamediv>
+<refname>addtodo</refname>
+<refpurpose>Add new todo.</refpurpose>
+</refnamediv>
+<refsynopsisdiv>
+<synopsis>
+QString addtodo(QString todoname)
+</synopsis>
+<refsect2>
+<title>Parameters</title>
+<variablelist>
+<varlistentry>
+<term><parameter>todoname</parameter></term>
+<listitem>
+ <para>The name of new todo.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</refsect2>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para><function>addtodo(QString todoname)</function> is a &DCOP; call that
+ adds a new top-level todo to the current storage. The UID of the new todo
+ is returned.
+</para>
+</refsect1>
+</refentry>
+
+</appendix>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->
diff --git a/doc/karm/karm.png b/doc/karm/karm.png
new file mode 100644
index 00000000..0c4a0a3c
--- /dev/null
+++ b/doc/karm/karm.png
Binary files differ
diff --git a/doc/karm/systray.png b/doc/karm/systray.png
new file mode 100644
index 00000000..2b5459d2
--- /dev/null
+++ b/doc/karm/systray.png
Binary files differ
diff --git a/doc/kleopatra/Makefile.am b/doc/kleopatra/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/kleopatra/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kleopatra/index.docbook b/doc/kleopatra/index.docbook
new file mode 100644
index 00000000..ba467215
--- /dev/null
+++ b/doc/kleopatra/index.docbook
@@ -0,0 +1,1458 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY kleopatra "<application>Kleopatra</application>">
+ <!ENTITY kwatchgnupg "<application>KWatchGnuPG</application>">
+ <!ENTITY gpgsm "<application>GpgSM</application>">
+ <!ENTITY gpg "<application>GPG</application>">
+ <!ENTITY gpgconf "<application>GpgConf</application>">
+ <!ENTITY kappname "&kleopatra;">
+ <!ENTITY package "kdepim">
+ <!ENTITY smime "<acronym>S/MIME</acronym>">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE">
+
+ <!ENTITY dn "<acronym>DN</acronym>">
+ <!ENTITY ca "<acronym>CA</acronym>">
+
+ <!-- Expanded all entities to make them translatable - lueck
+ FILE menu
+ <!ENTITY file-new-key-pair "<menuchoice><guimenu>File</guimenu><guimenuitem>New Key Pair...</guimenuitem></menuchoice>">
+ <!ENTITY file-export-certificates "<menuchoice><guimenu>File</guimenu><guimenuitem>Export Certificates...</guimenuitem></menuchoice>">
+ <!ENTITY file-export-secret-key "<menuchoice><guimenu>File</guimenu><guimenuitem>Export Secret key...</guimenuitem></menuchoice>">
+ <!ENTITY file-import-certificates "<menuchoice><guimenu>File</guimenu><guimenuitem>Import Certificates...</guimenuitem></menuchoice>">
+ <!ENTITY file-import-crls "<menuchoice><guimenu>File</guimenu><guimenuitem>Import CRLs...</guimenuitem></menuchoice>">
+ <!ENTITY file-quit "<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>">
+
+ VIEW menu
+ <!ENTITY view-redisplay "<menuchoice><shortcut><keycombo action="simul"><keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Redisplay</guimenuitem></menuchoice>">
+ <!ENTITY view-stop-operation "<menuchoice><shortcut><keycombo action="simul"><keycap>Esc</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Stop Operation</guimenuitem></menuchoice>">
+ <!ENTITY view-certificate-details "<menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details...</guimenuitem></menuchoice>">
+ <!ENTITY view-hierarchical-key-list "<menuchoice><guimenu>View</guimenu><guimenuitem>Hierarchical Key List</guimenuitem></menuchoice>">
+ <!ENTITY view-expand-all "<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>.</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Expand All</guimenuitem></menuchoice>">
+ <!ENTITY view-collapse-all "<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>,</keycap></keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Collapse All</guimenuitem></menuchoice>">
+
+ CERTIFICATES menu
+ <!ENTITY certificates-validate "<menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo></shortcut><guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice>">
+ <!ENTITY certificates-refresh-crls "<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice>">
+ <!ENTITY certificates-delete "<menuchoice><shortcut><keycombo action="simul"><keycap>Delete</keycap></keycombo></shortcut><guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice>">
+ <!ENTITY certificates-download "<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Download</guimenuitem></menuchoice>">
+
+ CRLS menu
+ <!ENTITY crls-clear-crl-cache "<menuchoice><guimenu>CRLs</guimenu><guimenuitem>Clear CRL Cache...</guimenuitem></menuchoice>">
+ <!ENTITY crls-dump-crl-cache "<menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache...</guimenuitem></menuchoice>">
+
+ TOOLS menu
+ <!ENTITY tools-gnupg-log-viewer "<menuchoice><guimenu>Tools</guimenu><guimenuitem>GnuPG Log Viewer...</guimenuitem></menuchoice>">
+
+ SETTINGS menu
+ <!ENTITY settings-show-statusbar "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice>">
+ <!ENTITY settings-configure-shortcuts "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>">
+ <!ENTITY settings-configure-kleopatra "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice>">
+ <!ENTITY settings-configure-gpgme-backend "<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure GpgME Backend...</guimenuitem></menuchoice>">
+ -->
+
+ <!-- Command line options -->
+ <!ENTITY commandline-option-external "<option>--external</option>">
+ <!ENTITY commandline-option-query "<option>--query</option>">
+ <!ENTITY commandline-option-import-certificate "<option>--import-certificate</option>">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kleopatra; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Marc</firstname>
+<surname>Mutz</surname>
+<affiliation>
+<address><email>marc@klaralvdalens-datakonsult.se</email></address>
+</affiliation>
+</author>
+
+<othercredit role="developer">
+<firstname>David</firstname>
+<surname>Faure</surname>
+<contrib>Developer</contrib>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Steffen</firstname>
+<surname>Hansen</surname>
+<affiliation>
+<address>&Steffen.Hansen.mail;</address>
+</affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Matthias Kalle</firstname>
+<surname>Dalheimer</surname>
+<contrib>Developer</contrib>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Jesper</firstname>
+<surname>Pedersen</surname>
+<affiliation>
+<address>&Jesper.Pedersen.mail;</address>
+</affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+<othercredit role="developer">
+<firstname>Daniel</firstname>
+<surname>Molkentin</surname>
+<affiliation>
+<address>&Daniel.Molkentin.mail;</address>
+</affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<legalnotice>&GPLNotice;</legalnotice>
+
+<date>2004-06-11</date>
+<releaseinfo>0.31</releaseinfo>
+
+<abstract>
+<para>
+&kleopatra; is a tool for managing X.509 certificates.
+</para>
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Kapp</keyword>
+<keyword>X509</keyword>
+<keyword>LDAP</keyword>
+<keyword>gpg</keyword>
+<keyword>gpgsm</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction"> <title>Introduction</title>
+
+<para>&kleopatra; is the &kde; tool for managing X.509 certificates in
+the &gpgsm; keybox and for retrieving certificates from
+<acronym>LDAP</acronym> servers.</para>
+
+<para>&kleopatra; can be started from &kmail;'s <guimenu>Tools</guimenu>
+menu, as well as from the command line. The &kleopatra; executable is
+named <userinput><command>kleopatra</command></userinput>.</para>
+
+<note><para>This program is named after Cleopatra, a famous female
+Egyptian pharaoh that lived at the time of Julius Caesar, whom she is
+said to have had an intimate relationship with.</para>
+
+<para>The name was chosen since this program originates from the
+<ulink url="http://www.gnupg.org/aegypten2/">&Auml;gypten
+Projects</ulink> (&Auml;gypten is German for Egypt). Kleopatra is the
+German spelling of Cleopatra.</para></note>
+
+</chapter>
+
+<chapter id="functions"><title>Main Functions</title>
+
+<sect1 id="functions-view"><title>Viewing the Local Keybox</title>
+
+<!-- Viewing and Refreshing, also Validation -->
+
+<para>&kleopatra;'s main function is to display and edit the contents
+of the local keybox, which is similar to &gpg;'s concept of keyrings,
+albeit one should not stretch this analogy too much.</para>
+
+<para>The main window is divided into the large key listing area, the
+menubar and the <link linkend="functions-search">search bar</link> on
+top, and a status bar at the bottom.</para>
+
+<para>Each line in the key list corresponds to one certificate,
+identified by the so-called <guilabel>Subject &dn;</guilabel>. &dn; is
+an acronym for <quote>Distinguished Name</quote>, a hierarchical
+identifier, much like a file system path with an unusual syntax, that is
+supposed to globally uniquely identify a given certificate.</para>
+
+<para>To be valid, and thus usable, (public) keys need to be signed by
+a &ca; (Certification Authority). These signatures are called
+certificates, but usually the terms <quote>certificate</quote> and
+<quote>(public) key</quote> are used interchangeably, and we will not
+distinguish between them in this manual either, except when explicitly
+noted. The name of the &ca; which issued the certificate (its &dn;)
+is shown in the <guilabel>Issuer &dn;</guilabel> column.</para>
+
+<para>&ca;s must in turn be signed by other &ca;s to be valid. Of
+course, this must end somewhere, so the top-level &ca; (root-&ca;)
+signs its key with itself (this is called a self-signature). Root
+certificates thus need to be assigned validity (commonly called trust)
+manually, &eg; after comparing the fingerprint with the one on the
+website of the &ca;. This is typically done by the system administrator or
+the vendor of a product using certificates, but can be done by the
+user via &gpgsm;'s command line interface.</para>
+
+<para>To see which of the certificates are root certificates, you can
+either compare <guilabel>Subject &dn;</guilabel> and <guilabel>Issuer
+&dn;</guilabel>, or you switch to hierarchical keylist mode with <link
+linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
+<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link>.</para>
+
+<para>You can see the details of any certificate by double-clicking it
+or using <link linkend="view-certificate-details"><menuchoice><guimenu>View</guimenu>
+<guimenuitem>Certificate Details...</guimenuitem></menuchoice></link>. This opens a
+dialog that shows the most common properties of the certificate, its
+certificate chain (&ie; the chain of issuers up to the root-&ca;), and
+a dump of all information the backend is able to extract from the
+certificate.</para>
+
+<para>If you change the keybox without using &kleopatra; (&eg; using
+&gpgsm;'s command line interface), you can refresh the view with <link
+linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul">
+<keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu>
+<guimenuitem>Redisplay</guimenuitem></menuchoice></link>.</para>
+
+<para>Since validating a key may take some time (&eg; CRLs might need
+to be fetched), the normal keylisting does not attempt to check the
+validity of keys. For this, <link linkend="certificates-validate">
+<menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo>
+</shortcut><guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice></link>, a
+special variant of <link
+linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul">
+<keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu>
+<guimenuitem>Redisplay</guimenuitem></menuchoice></link>, is provided. It
+either checks the selected certificates, or all keys if none are
+selected.</para>
+
+</sect1>
+
+<sect1 id="functions-search"><title>Searching and Importing Certificates</title>
+
+<para>Most of the time, you will acquire new certificates by verifying
+signatures in emails, since certificates are embedded in the
+signatures made using them most of the time. However, if you need to
+send a mail to someone you have not yet had contact with, you need to
+fetch the certificate from an LDAP directory (although &gpgsm; can do
+this automatically), or from a file. You also need to import your own
+certificate after receiving the &ca; answer to your certification
+request.</para>
+
+<para>To search for a certificate in an LDAP directory, switch the
+dropdown menu of the search bar from <guilabel>in Local
+Certificates</guilabel> to <guilabel>in External
+Certificates</guilabel>, enter some text (&eg; the name of the person
+you want the certificate for) into the line edit, and click on the
+<guilabel>Find</guilabel> icon. The results will be displayed in the
+key list below the search bar, where you can select certificates to
+either look at them with <link linkend="view-certificate-details">
+<menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details...</guimenuitem></menuchoice></link> or
+download them with <link linkend="certificates-download">
+<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Download</guimenuitem></menuchoice></link> into the
+local keybox. Note that you can also download the certificate from the
+details dialog, using the <guilabel>Import to Local</guilabel>
+button.</para>
+
+<para>You can configure the list of LDAP servers to search in the
+<link linkend="configuration-directory-services"><guilabel>Directory
+Services</guilabel></link> page of &kleopatra;'s <link
+linkend="configuration">configure dialog</link>.</para>
+
+<para>If you received the certificate as a file, try <link
+linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu>
+<guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>. &gpgsm; needs to understand the
+format of the certificate file; please refer to &gpgsm;'s manual for a
+list of supported file formats.</para>
+
+<para>If you did not <link linkend="functions-newkey">create your
+keypair with &gpgsm;</link>, you also need to manually import the
+public key (as well as the secret key) from the PKCS#12 file you got from
+the &ca;. You can do this on the command line with <link
+linkend="commandline-option-import-certificate"><userinput><command>kleopatra
+&commandline-option-import-certificate;
+<filename>filename</filename></command></userinput></link> or from
+within &kleopatra; with <link
+linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu>
+<guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>,
+just as you would to for <quote>normal</quote> certificates.</para>
+
+</sect1>
+
+<sect1 id="functions-newkey"><title>Creating New Key Pairs</title>
+
+<para>The menu item <link linkend="file-new-key-pair"><menuchoice>
+<guimenu>File</guimenu><guimenuitem>New Key Pair...</guimenuitem></menuchoice></link> starts the
+certificate-request-creating wizard which will guide you through a
+number of steps to create a certificate request; this request can, on the
+last page of the wizard, either be sent to a certificate authority (&ca;)
+to be signed or saved to a file (for example to a floppy, so it can be
+shipped to the &ca;).</para> <para>Whenever you are done with a step in
+the wizard, press <guibutton>Next</guibutton> to go to the next step
+(or <guibutton>Back</guibutton> to review steps that are already
+completed). The certificate request creation can be canceled at any
+time by pressing the <guibutton>Cancel</guibutton> button.
+</para>
+<para>The first step in the wizard is to type in your personal data
+for the certificate. The fields to fill out are:
+<itemizedlist>
+<listitem>
+<para><guilabel>Name:</guilabel> Your name;</para>
+</listitem>
+<listitem>
+<para><guilabel>Location:</guilabel>The town or city in which you live;</para>
+</listitem>
+<listitem>
+<para><guilabel>Organization:</guilabel>The organization you represent
+(for example, the company you work for);</para>
+</listitem>
+<listitem>
+<para><guilabel>Department:</guilabel>The organizational unit you are
+in (for example, "Logistics");</para>
+</listitem>
+<listitem>
+<para><guilabel>Country code:</guilabel>The two letter code for the
+country in which you are living (for example, "US");</para>
+</listitem>
+<listitem>
+<para><guilabel>Email address:</guilabel>Your email address; be sure
+to type this in correctly&mdash;this will be the address people will be
+sending mail to when they use your certificate.</para>
+</listitem>
+</itemizedlist>
+</para><para>
+The next step in the wizard is to select whether to store the
+certificate in a file or send it directly to a &ca;. You will have to
+specify the filename or email address to send the certificate request to.
+</para></sect1>
+
+
+<sect1 id="functions-keybox-management"><title>Keybox Management</title>
+
+<para>In addition to <link linkend="functions-view">list and
+validate</link>, <link linkend="functions-search">search and
+import</link> certificates and <link
+linkend="functions-newkey">creating new ones</link>, &kleopatra; also
+has some less often used functions that help you manage your local
+keybox.</para>
+
+<para>These functions include deleting certificates from the local
+keybox with <link linkend="certificates-delete"><menuchoice><shortcut>
+<keycombo action="simul"><keycap>Delete</keycap></keycombo></shortcut>
+<guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></link>, as well
+as manual handling of CRLs (<link linkend="certificates-refresh-crls">
+<menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem>
+</menuchoice></link>, <link linkend="crls-clear-crl-cache"><menuchoice><guimenu>CRLs</guimenu>
+<guimenuitem>Clear CRL Cache...</guimenuitem></menuchoice></link>, <link
+linkend="crls-dump-crl-cache"><menuchoice><guimenu>CRLs</guimenu>
+<guimenuitem>Dump CRL Cache...</guimenuitem></menuchoice></link>).</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="menu"><title>Menu Reference</title>
+
+<sect1 id="menufile"><title>File Menu</title>
+
+<variablelist>
+
+<varlistentry id="file-new-key-pair">
+<term><menuchoice><guimenu>File</guimenu><guimenuitem>New Key Pair...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Creates a new key pair (public and private)</action> and
+allows to send the public part to a certification authority
+(&ca;) for signing. The resulting certificate is then
+sent back to you, or stored in an LDAP server for you to download into
+your local keybox, where you can use it to sign and decrypt
+mails.</para>
+
+<para>This mode of operation is called <quote>decentralized key
+generation</quote>, since all keys are created locally. &kleopatra;
+(and &gpgsm;) do not support <quote>centralized key generation</quote>
+directly, but you can import the public/secret key bundle that you
+receive from the &ca; in PKCS#12 format via <menuchoice><guimenu>File</guimenu>
+<guimenuitem>Import Certificates...</guimenuitem></menuchoice>.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="file-export-certificates">
+<term><menuchoice><guimenu>File</guimenu><guimenuitem>Export Certificates...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Exports the selected certificates</action> into a file.</para>
+
+<note><para>This exports only the public keys, even if the
+secret key is available. Use <menuchoice><guimenu>File</guimenu><guimenuitem>Export
+Secret key...</guimenuitem></menuchoice> to export both
+public and secret keys into a file, but note that this is almost
+always a bad idea.</para></note>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="file-export-secret-key">
+<term><menuchoice><guimenu>File</guimenu><guimenuitem>Export Secret key...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Exports both the public and the secret key to a
+(PKCS#12) file.</action></para>
+
+<warning><para>It should rarely be necessary to use this function, and
+if it is, it should be carefully planned. Planning the migration of a
+secret key involves choice of transport media and secure deletion of
+the key data on the old machine, as well as the transport medium,
+among other things.</para></warning>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="file-import-certificates">
+<term><menuchoice><guimenu>File</guimenu><guimenuitem>Import Certificates...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Imports certificates and/or secret keys from files into
+the local keybox.</action></para>
+
+<para>The format of the certificate file must be supported by
+&gpgsm;. Please refer to the &gpgsm; manual for a list of supported
+formats.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="file-import-crls">
+<term><menuchoice><guimenu>File</guimenu><guimenuitem>Import CRLs...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Lets you manually import CRLs from
+files.</action></para>
+
+<para>Normally, Certificate Revocation Lists (CRLs) are handled
+transparently by the backend, but it can sometimes be useful to
+import a CRL manually into the local CRL cache.</para>
+
+<note><para>For CRL import to work, the
+<application>dirmngr</application> tool must be in the search
+<varname>PATH</varname>. If this menu item is disabled, you should
+contact the system administrator and ask them to install
+<application>dirmngr</application>.</para></note>
+
+<para>You can view the contents of the local CRL cache from the menu
+item <menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache...</guimenuitem>
+</menuchoice>. This will display a dialog with
+information about the CRLs in the cache and the fingerprints of the
+certificates in each CRL.
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="file-quit">
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut>
+<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Terminates &kleopatra;.</action></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1> <!-- File Menu -->
+
+
+
+<sect1 id="menuview"><title>View Menu</title>
+
+<variablelist>
+
+<varlistentry id="view-redisplay">
+<term><menuchoice><shortcut><keycombo action="simul"><keycap>F5</keycap></keycombo>
+</shortcut><guimenu>View</guimenu><guimenuitem>Redisplay</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Redisplays the selected certificates or refreshes the
+certificate list.</action></para>
+
+<para>If there are selected certificates, the refresh operation is
+restricted to those selected entries.</para>
+
+<para>If a query result (either remote or local) is currently
+displayed, the query is re-issued and the new results are displayed in
+place of the old ones.</para>
+
+<para>If no query has been performed, the whole keybox contents is
+re-fetched and re-displayed.</para>
+
+<para>You can use this if you have changed the contents of
+the keybox by other means than &kleopatra; (&eg; by using &gpgsm;'s
+command line interface).</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="view-stop-operation">
+<term><menuchoice><shortcut><keycombo action="simul"><keycap>Esc</keycap></keycombo></shortcut>
+<guimenu>View</guimenu><guimenuitem>Stop Operation</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Stops (cancels) all pending operations,</action> &eg; a
+search or a download.</para>
+
+<note><para>Depending on the server used, cancelling a remote search
+can block &kleopatra; for a few seconds while waiting for the backend
+to complete the procedure. This is normal and expected
+behavior.</para></note>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="view-certificate-details">
+<term><menuchoice><guimenu>View</guimenu><guimenuitem>Certificate Details...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Shows the details of the currently selected
+certificate.</action></para>
+
+<para>This function is also available by double-clicking the
+corresponding item in the list view directly.</para>
+
+<!--FIXME: link to the dialog's help, but where do we put _that_?-->
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="view-hierarchical-key-list">
+<term><menuchoice><guimenu>View</guimenu><guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action> Toggles between hierarchical and flat keylist mode.
+</action></para>
+
+<para>In hierarchical mode, certificates are arranged in
+issuer/subject relation, so it is easy to see to which certification
+hierarchy a given certificate belongs, but a given certificate is
+harder to find initially (though you can of course use the
+<link linkend="functions-search">search bar</link>).</para>
+
+<para>In flat mode, all certificates are displayed in a flat list,
+sorted alphabetically. In this mode, a given certificate is easy to
+find, but it is not directly clear which root certificate it belongs
+to.</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry id="view-expand-all">
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>.</keycap>
+</keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Expand All</guimenuitem></menuchoice></term>
+
+<listitem>
+<para>(This function is only available when <link
+linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
+<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> is on.)</para>
+
+<para><action>Expands all list items in the certificate list
+view,</action> &ie; makes all items visible.</para>
+
+<para>This is the default when entering hierarchical keylist
+mode.</para>
+
+<para>You can still expand and collapse each individual item by
+itself, of course.</para>
+</listitem>
+</varlistentry>
+
+
+
+<varlistentry id="view-collapse-all">
+<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>,</keycap>
+</keycombo></shortcut><guimenu>View</guimenu><guimenuitem>Collapse All</guimenuitem></menuchoice></term>
+
+<listitem>
+<para>(This function is only available when <link
+linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
+<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> is on.)</para>
+
+<para><action>Collapses all list items in the certificate list
+view,</action> &ie; hides all but the top-level items.</para>
+
+<para>You can still expand and collapse each individual item by
+itself, of course.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="menucertificates"><title>Certificates Menu</title>
+
+<variablelist>
+
+<varlistentry id="certificates-validate">
+<term><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo>
+</shortcut><guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Validates selected (or all) keys.</action></para>
+
+<para>This is similar to <link
+linkend="view-redisplay"><menuchoice><shortcut><keycombo action="simul">
+<keycap>F5</keycap></keycombo></shortcut><guimenu>View</guimenu>
+<guimenuitem>Redisplay</guimenuitem></menuchoice></link>, but
+performs a validation of the (selected) keys. Validation here means
+that all relevant CRLs are fetched, and the certificate chain is
+checked for correctness. As a result, invalid or expired keys will be
+marked according to your color and font preferences set in the <link
+linkend="configuration-appearance"><guilabel>Appearance</guilabel>
+page</link> of &kleopatra;'s <link linkend="configuration">configure
+dialog</link>.</para>
+
+<warning><para>You can only rely on information from validated keys,
+and, since any of them may be revoked at any time, even validation is
+only ever a snapshot of the current state of the local keyring. This
+is why the backend normally performs such checks whenever the keys
+are used (&eg; for signing, signature verification, encryption or
+decryption).</para></warning>
+</listitem>
+</varlistentry>
+
+
+
+<varlistentry id="certificates-refresh-crls">
+<term><menuchoice><guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Fetches the current CRLs for all selected keys,</action>
+even though they would normally not be fetched when using the
+key.</para>
+
+<para>This function only has an effect on certificates which define a
+CRL distribution point. Depending on the backend used, certificates
+configured to perform checks using OCSP will not be updated.</para>
+
+<para>You may use this &eg; if you have sideband knowledge that a key
+has been revoked, and you want the backend to reflect this
+<emphasis>now</emphasis> instead of relying on this to automatically
+happen at the next scheduled CRL update.</para>
+
+<warning><para>Excessive use of this function might put a high load on
+your provider's or company's network, since CRLs of large
+organizations can be surprisingly big (several megabytes are not
+uncommon).</para>
+
+<para>Use this function scarcely.</para></warning>
+</listitem>
+</varlistentry>
+
+
+
+<varlistentry id="certificates-delete">
+<term><menuchoice><shortcut><keycombo action="simul"><keycap>Delete</keycap></keycombo></shortcut>
+<guimenu>Certificates</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Deletes selected certificate(s)</action> from the local keyring.</para>
+
+<para>Use this function to remove unused keys from your local
+keybox. However, since certificates are typically attached to signed
+emails, verifying an email might result in the key just removed to pop
+back into the local keybox. So it is probably best to avoid using this
+function as much as possible. When you are lost, use the <link
+linkend="functions-search">search bar</link> or the <link
+linkend="view-hierarchical-key-list"><menuchoice><guimenu>View</guimenu>
+<guimenuitem>Hierarchical Key List</guimenuitem></menuchoice></link> function to regain control over
+the lot of certificates.</para>
+</listitem>
+</varlistentry>
+
+
+
+<varlistentry id="certificates-download">
+<term><menuchoice><guimenu>Certificates</guimenu><guimenuitem>Download</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Downloads the selected certificate(s) from the LDAP to the local keybox.</action></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+
+
+<sect1 id="menucrls"><title>CRLs Menu</title>
+
+<variablelist>
+
+<varlistentry id="crls-clear-crl-cache">
+<term><menuchoice><guimenu>CRLs</guimenu><guimenuitem>Clear CRL Cache...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Clears the &gpgsm; CRL cache.</action></para>
+
+<para>You probably never need this. You can force a refresh of the CRL
+cache by selecting all certificates and using <link linkend="certificates-refresh-crls"><menuchoice>
+<guimenu>Certificates</guimenu><guimenuitem>Refresh CRLs</guimenuitem></menuchoice></link> instead.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="crls-dump-crl-cache">
+<term><menuchoice><guimenu>CRLs</guimenu><guimenuitem>Dump CRL Cache...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Shows the detailed contents of the &gpgsm; CRL
+cache.</action></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="menutools"><title>Tools Menu</title>
+
+<variablelist>
+
+<varlistentry id="tools-gnupg-log-viewer">
+<term><menuchoice><guimenu>Tools</guimenu><guimenuitem>GnuPG Log Viewer...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Starts <ulink url="help:/kwatchgnupg/index.html">&kwatchgnupg;</ulink></action></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="menusettings"><title>Settings Menu</title>
+
+<variablelist>
+
+<varlistentry id="settings-show-statusbar">
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Toggles the visibility of the bottom status bar.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="settings-configure-shortcuts">
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Opens the standard &kde; shortcut configuration dialog,
+where you can assign and re-assign keyboard shortcuts for all menu
+items.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="settings-configure-kleopatra">
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Opens &kleopatra;'s configure dialog.</action></para>
+
+<para>See <xref linkend="configuration"/> for more details.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="settings-configure-gpgme-backend">
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure GpgME Backend...</guimenuitem></menuchoice></term>
+
+<listitem>
+<para><action>Opens a dialog that allows you to configure every aspect of
+&gpgsm; and other backend modules.</action></para>
+
+<para>This dialog is dynamically built from the output of the
+&gpgconf; utility and may thus change when backend modules are
+updated.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="menuhelp"><title>Help Menu</title>
+
+
+<para>The <guimenu>Help</guimenu> menu contains the standard &kde;
+help menu.</para>
+
+&help.menu.documentation;
+
+</sect1>
+
+</chapter>
+
+<chapter id="commandline-options"><title>Command Line Options Reference</title>
+
+<para>Only the options specific to &kleopatra; are listed here. As
+with all &kde; applications, you can get a complete list of options
+by issuing the command <userinput><command>kleopatra
+<option>--help</option></command></userinput>.</para>
+
+<variablelist>
+
+<varlistentry id="commandline-option-external">
+<term>&commandline-option-external;</term>
+
+<listitem>
+<para><action>Specifies that &commandline-option-query; shall search
+remotely instead of in the local keybox.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="commandline-option-query">
+<term>&commandline-option-query;</term>
+
+<listitem>
+<para><action>Specifies that &kleopatra; shall start with the given
+query string instead of listing the complete local
+keybox.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="commandline-option-import-certificate">
+<term>&commandline-option-import-certificate;</term>
+
+<listitem>
+<para><action>Specifies a file or URL from which to import
+certificates (or secret keys) from.</action></para>
+
+<para>This is the command line equivalent of <link
+linkend="file-import-certificates"><menuchoice><guimenu>File</guimenu>
+<guimenuitem>Import Certificates...</guimenuitem></menuchoice></link>.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</chapter>
+
+<chapter id="configuration"><title>Configuring &kleopatra;</title>
+
+<para>&kleopatra;'s configure dialog can be accessed via <link
+linkend="settings-configure-kleopatra"><menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kleopatra;...</guimenuitem></menuchoice></link>.</para>
+
+<para>Each of its pages is described in the sections below.</para>
+
+<sect1 id="configuration-directory-services"><title>Configuring Directory Services</title>
+
+<para>On this page, you can configure which LDAP servers to use for
+certificate searches. You can also configure their order, as well as
+some selected LDAP-related settings from the dynamic backend
+configuration dialog, available via <link
+linkend="settings-configure-gpgme-backend"><menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure GpgME Backend...</guimenuitem></menuchoice></link>.</para>
+
+<para>To add a new server, click on the <guilabel>Add
+Service...</guilabel> button. In the dialog that appears, you can set
+the <guilabel>Server name</guilabel>, the <guilabel>Port</guilabel>
+(preset to the default LDAP port), the <guilabel>Base &dn;</guilabel>
+(sometimes referred to as the search root or search base), and the
+usual <guilabel>User name</guilabel> and
+<guilabel>Password</guilabel>, both of which are only needed if the
+server requires authentication. Clicking <guilabel>OK</guilabel> adds
+the server details to the list of servers, while
+<guilabel>Cancel</guilabel> dismisses the input.</para>
+
+<para>To remove a server from the search list, select it in the list,
+then press the <guilabel>Remove Service</guilabel> button.</para>
+
+<para>To change the relative search order of servers, select one of
+them and move it up or down with the arrow buttons right next to the
+list.</para>
+
+<para>To set the LDAP timeout, &ie; the maximum time the backend will
+wait for a server to respond, simply use the corresponding input field
+labelled <guilabel>LDAP timeout</guilabel>.</para>
+
+<para>If one of your servers has a large database, so that even
+reasonable searches like <userinput>Smith</userinput> hit the
+<guilabel>maximum number of items returned by query</guilabel>, you
+might want to increase this limit. You can find out easily if you hit
+the limit during a search, since a dialog box will pop up in that
+case, telling you that the results have been truncated.</para>
+
+<note><para>Some servers may impose their own limits on the number of
+items returned from a query. In this case, increasing the limit here
+will not result in more returned items.</para></note>
+
+</sect1>
+
+<sect1 id="configuration-appearance"><title>Configuring Visual Appearance</title>
+
+<para>&kleopatra; allows you to customize the appearance of
+(validated) keys in the list view. This includes the foreground (text)
+and background colors, as well as the font.</para>
+
+<para>Each <guilabel>Key Category</guilabel> on the left is assigned a
+set of colors and a font in which keys belonging to that category are
+displayed. The category list also acts as a preview of the
+settings. Categories can be freely defined by the administrator or the
+power user, see <xref linkend="admin-key-filters"/> in <xref
+linkend="admin"/>.</para>
+
+<para>To change the text (foreground) color of a category, select it
+in the list, and press the <guilabel>Set Text Color...</guilabel>
+button. The standard &kde; color selection dialog will appear where
+you can select or create a new color.</para>
+
+<para>Changing the background color is done in the same way, just press
+<guilabel>Set Background Color...</guilabel> instead.</para>
+
+<para>To change the font, you basically have two options:</para>
+
+<orderedlist>
+<listitem><para>Modify the standard font, used for all list views in
+&kde;</para></listitem>
+<listitem><para>Use a custom font.</para></listitem>
+</orderedlist>
+
+<para>The first option has the advantage that the font will follow
+whichever style you choose &kde;-wide, whereas the latter gives you
+full control over the font to use. The choice is yours.</para>
+
+<para>To use the modified standard font, select the category in the
+list, and check or uncheck the font modifiers
+<guilabel>Italic</guilabel>, <guilabel>Bold</guilabel>, and/or
+<guilabel>Strikeout</guilabel>. You can immediately see the effect on
+the font in the category list.</para>
+
+<para>To use a custom font, press the <guilabel>Set Font...</guilabel>
+button. The standard &kde; font selection dialog will appear where you
+can select the new font. Note that you can still use the font
+modifiers to change the custom font, just as for modifying the
+standard font.</para>
+
+<para>To switch back to the standard font, you need to press the
+<guilabel>Default Appearance</guilabel> button.</para>
+
+</sect1>
+
+<sect1 id="configuration-dn-order"><title>Configuring the Order &dn; Attributes are Shown</title>
+
+<para>Although &dn;s are hierarchical, the order of the individual
+components (called relative &dn;s (RDNs), or &dn; attributes) is not
+defined. The order in which the attributes are shown is thus a matter
+of personal taste or company policy, which is why it is configurable in
+&kleopatra;.</para>
+
+<note><para>This setting does not only apply to &kleopatra;, but to all
+applications using &kleopatra; Technology. At the time of this
+writing, these include &kmail;, &kaddressbook;, as well as &kleopatra;
+itself, of course.</para></note>
+
+<para>This configuration page basically consists of two lists, one for
+the known attributes (<guilabel>Available attributes</guilabel>), and
+one describing the <guilabel>Current attribute order</guilabel>.</para>
+
+<para>Both lists contain entries described by the short from of the
+attribute (&eg; <guilabel>CN</guilabel>) as well as the spelled-out
+form (<guilabel>Common Name</guilabel>).</para>
+
+<para>The <guilabel>Available attributes</guilabel> list is always
+sorted alphabetically, while the <guilabel>Current attribute
+order</guilabel> list's order reflects the configured &dn; attribute
+order: the first attribute in the list is also the one displayed
+first.</para>
+
+<para>Only attributes explicitly listed in the <guilabel>Current
+attribute order</guilabel> list are displayed at all. The rest is
+hidden by default.</para>
+
+<para>However, if the placeholder entry <guilabel>_X_</guilabel>
+(<guilabel>All others</guilabel>) is in the <quote>current</quote>
+list, all unlisted attributes (whether known or not), are inserted at
+the point of <guilabel>_X_</guilabel>, in their original relative
+order.</para>
+
+<para>A small example will help to make this more clear:</para>
+
+<informalexample>
+<para>Given the &dn;</para>
+<blockquote>
+<para>
+ O=KDE, C=US, CN=Dave Devel, X-BAR=foo, OU=Kleopatra, X-FOO=bar,
+</para>
+</blockquote>
+<para>the default attribute order of <quote>CN, L, _X_, OU, O,
+C</quote> will produce the following formatted &dn;:</para>
+<blockquote>
+<para>
+ CN=Dave Devel, X-BAR=foo, X-FOO=bar, OU=Kleopatra, O=KDE, C=US
+</para>
+</blockquote>
+<para>while <quote>CN, L, OU, O, C</quote> will produce</para>
+<blockquote>
+<para>
+ CN=Dave Devel, OU=Kleopatra, O=KDE, C=US
+</para>
+</blockquote>
+</informalexample>
+
+<para>To add an attribute to the display order list, select it in the
+<guilabel>Available attributes</guilabel> list, and press the
+<guilabel>Add to current attribute order</guilabel> button.</para>
+
+<para>To remove an attribute from the display order list, select it in
+the <guilabel>Current attribute order</guilabel> list, and press the
+<guilabel>Remove from current attribute order</guilabel> button.</para>
+
+<para>To move an attribute to the beginning (end), select it in the
+<guilabel>Current attribute order</guilabel> list, and press the
+<guilabel>Move to top</guilabel> (<guilabel>Move to bottom</guilabel>)
+button.</para>
+
+<para>To move an attribute up (down) one slot only, select it in the
+<guilabel>Current attribute order</guilabel> list, and press the
+<guilabel>Move one up</guilabel> (<guilabel>Move one down</guilabel>)
+button.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="admin"><title>Administrator's Guide</title>
+
+<para>This Administrator's Guide describes ways to customize &kleopatra; that
+are not accessible via the &GUI;, but only via config files.</para>
+
+<para>It is assumed that the reader is familiar with the technology
+used for &kde; application configuration, including layout,
+file system location and cascading of &kde; config files, as well as
+the KIOSK framework.</para>
+
+<sect1 id="admin-certificate-request-wizard"><title>Customization of the Certificate-Creation Wizard</title>
+
+<para>&kleopatra; allows you to customize the fields that the user is
+allowed to enter in order to create their certificate.</para>
+
+<para>Create a group called
+<literal>CertificateCreationWizard</literal> in the system-wide
+<filename>kleopatrarc</filename>. If you want a custom order of
+attributes or if you only want certain items to appear, create a key
+called <varname>DNAttributeOrder</varname>. The argument is one or
+more of <varname>CN,SN,GN,L,T,OU,O,PC,C,SP,DC,BC,EMAIL</varname> If
+you want to initialize fields with a certain value, write something like
+Attribute=value. If you want the attribute to be treated as a required
+one, append an exclamation mark
+(e.g. <varname>CN!,L,OU,O!,C!,EMAIL!</varname>, which happens to be
+the default configuration).</para>
+
+<para> Using the <acronym>KIOSK</acronym> mode modifier
+<varname>$e</varname> allows to retrieve the values from
+environment variables or from an evaluated script or binary. If you
+want to disallow editing of the respective field in addition, use the
+modifier <varname>$i</varname>. If you want to disallow the use
+<guibutton>Insert My Address</guibutton> button, set
+<varname>ShowSetWhoAmI</varname> to false.</para>
+
+<tip><para> Due to the nature of the &kde; <acronym>KIOSK</acronym>
+framework, using the immutable flag (<varname>$i</varname>) makes it
+impossible for the user to override the flag. This is intended
+behavior. <varname>$i</varname> and <varname>$e</varname> can be used
+with all other config keys in &kde; applications as well.</para></tip>
+
+<para>The following example outlines possible customizations:</para>
+
+<para>
+<programlisting>
+[CertificateCreationWizard]
+;Disallow to copy personal data from the addressbook, do not allow local override
+ShowSetWhoAmI[$i]=false
+
+;sets the user name to $USER
+CN[$e]=$USER
+
+;sets the company name to "My Company", disallows editing
+O[$i]=My Company
+
+;sets the department name to a value returned by a script
+OU[$ei]=$(lookup_dept_from_ip)
+
+; sets country to DE, but allows for changes by the user
+C=DE
+</programlisting>
+
+</para>
+</sect1>
+
+ <sect1 id="admin-key-filters">
+
+ <title>
+ Creating and Editing Key Categories
+ </title>
+
+ <para>
+ &kleopatra; allows the user to configure the <link
+ linkend="configuration-appearance">visual appearance</link> of
+ keys based on a concept called <guilabel>Key
+ Categories</guilabel>. This section describes how you can edit
+ the available categories and add new ones.
+ </para>
+
+ <para>
+ When trying to find the category a key belongs to, &kleopatra;
+ tries to match the key to a sequence of key filters,
+ configured in the <filename>libkleopatrarc</filename>. The
+ first one to match defines the category.
+ </para>
+
+ <para>
+ Each key filter is defined in a config group named
+ <literal>Key Filter #<replaceable>n</replaceable></literal>,
+ where <replaceable>n</replaceable> is a number, starting from
+ <literal>0</literal>.
+ </para>
+
+ <para>
+ The only mandatory key in a <literal>Key Filter
+ #<replaceable>n</replaceable></literal> group is
+ <varname>Name</varname>, containing the name of the category
+ as displayed in the <link
+ linkend="configuration-appearance">config dialog</link>.
+ </para>
+
+ <para>
+ <xref linkend="table-key-filters-appearance"/> lists all keys
+ that define the display properties of keys belonging to that
+ category (&ie; those keys that can be adjusted in the <link
+ linkend="configuration-appearance">config dialog</link>),
+ whereas <xref linkend="table-key-filters-criteria"/> lists all
+ keys that define the criteria the filter matches keys against.
+ </para>
+
+ <table id="table-key-filters-appearance">
+ <title>Key-Filter Configuration Keys Defining Display
+ Properties</title>
+ <tgroup cols="3">
+ <colspec colnum="2" align="center"/>
+ <thead>
+ <row>
+ <entry>Config Key</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <!--tfoot/-->
+ <tbody>
+ <row>
+ <entry><varname>background-color</varname></entry>
+ <entry>color</entry>
+ <entry>
+ The background color to use. If missing, defaults to
+ whichever background color is defined globally for list
+ views.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>foreground-color</varname></entry>
+ <entry>color</entry>
+ <entry>
+ The foreground color to use. If missing, defaults to
+ whichever foreground color is defined globally for list
+ views.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>font</varname></entry>
+ <entry>font</entry>
+ <entry>
+ The custom font to use. The font will be scaled to the
+ size configured for list views, and any font
+ attributes (see below) will be applied.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>font-bold</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ If set to <literal>true</literal> and
+ <varname>font</varname> is not set, uses the
+ default list view font with bold font style added (if
+ available). Ignored if <varname>font</varname> is also
+ present.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>font-italic</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ Analogous to <varname>font-bold</varname>, but for
+ italic font style instead of bold.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>font-strikeout</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ If <literal>true</literal>, draws a centered line over
+ the font. Applied even if
+ <varname>font</varname> is set.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>icon</varname></entry>
+ <entry>text</entry>
+ <entry>
+ The name of an icon to show in the first column. Not yet
+ implemented.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table id="table-key-filters-criteria">
+ <title>Key-Filter Configuration Keys Defining Filter Criteria</title>
+ <tgroup cols="3">
+ <colspec colnum="2" align="center"/>
+ <thead>
+ <row>
+ <entry>Config Key</entry>
+ <entry>Type</entry>
+ <entry>If specified, filter matches when...</entry>
+ </row>
+ </thead>
+ <!--tfoot/-->
+ <tbody>
+ <row>
+ <entry><varname>is-revoked</varname></entry>
+ <entry>boolean</entry>
+ <entry>the key has been revoked.</entry>
+ </row>
+ <row>
+ <entry><varname>is-expired</varname></entry>
+ <entry>boolean</entry>
+ <entry>the key is expired.</entry>
+ </row>
+ <row>
+ <entry><varname>is-disabled</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key has been disabled (marked for not using) by
+ the user. Ignored for &smime; keys.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>is-root-certificate</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key is a root certificate. Ignored for OpenPGP
+ keys.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>can-encrypt</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key can be used for encryption.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>can-sign</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key can be used for signing.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>can-certify</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key can be used for signing (certifying) other
+ keys.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>can-authenticate</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key can be used for authentication (&eg; as an
+ <acronym>TLS</acronym> client certificate).
+ </entry>
+ </row>
+ <row>
+ <entry><varname>has-secret-key</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the secret key for this key pair is available.
+ </entry>
+ </row>
+ <row>
+ <entry><varname>is-openpgp-key</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key is an OpenPGP key (<literal>true</literal>),
+ or an &smime; key (<literal>false</literal>).
+ </entry>
+ </row>
+ <row>
+ <entry><varname>was-validated</varname></entry>
+ <entry>boolean</entry>
+ <entry>
+ the key has been validated (see <link
+ linkend="certificates-validate"><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F5</keycap></keycombo></shortcut>
+ <guimenu>Certificates</guimenu><guimenuitem>Validate</guimenuitem></menuchoice></link>).
+ </entry>
+ </row>
+ <row>
+ <entry><varname><replaceable>prefix</replaceable>-ownertrust</varname></entry>
+ <entry>
+ validity<footnote>
+ <para>
+ Validity is an (ordered) enumeration with the
+ following allowed values:
+ <literal>unknown</literal>,
+ <literal>undefined</literal>,
+ <literal>never</literal>,
+ <literal>marginal</literal>,
+ <literal>full</literal>,
+ <literal>ultimate</literal>. See the &gpg; and
+ &gpgsm; manuals for a detailed explanation.
+ </para>
+ </footnote>
+ </entry>
+ <entry>
+ the key has exactly
+ (<replaceable>prefix</replaceable>&nbsp;=&nbsp;<literal>is</literal>),
+ has anything but
+ (<replaceable>prefix</replaceable>&nbsp;=&nbsp;<literal>is-not</literal>),
+ has at least
+ (<replaceable>prefix</replaceable>&nbsp;=&nbsp;<literal>is-at-least</literal>),
+ or has at most
+ (<replaceable>prefix</replaceable>&nbsp;=&nbsp;<literal>is-at-most</literal>)
+ the ownertrust given as the value of the config key. If
+ more than one
+ <varname><replaceable>prefix</replaceable>-ownertrust</varname>
+ keys (with different
+ <replaceable>prefix</replaceable> values) are present in a
+ single group, the behavior is undefined.
+ </entry>
+ </row>
+ <row>
+ <entry><varname><replaceable>prefix</replaceable>-validity</varname></entry>
+ <entry>validity</entry>
+ <entry>
+ Analogous to
+ <varname><replaceable>prefix</replaceable>-ownertrust</varname>,
+ but for key validity instead of ownertrust.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para>
+ Some of the more interesting criteria, such as
+ <varname>is-revoked</varname> or
+ <varname>is-expired</varname> will only work on
+ <emphasis>validated</emphasis> keys, which is why, by
+ default, only validated keys are checked for revocation and
+ expiration, although you are free to remove these extra
+ checks.
+ </para>
+ </note>
+
+ <para>
+ In general, criteria not specified (&ie; the config entry is
+ not set) are not checked for. If a criterion is given, it
+ is checked for and must match for the filter as a whole to
+ match, &ie; the criteria are AND'ed together.
+ </para>
+
+ <example>
+ <title>
+ Examples of key filters
+ </title>
+ <para>
+ To check for all expired, but non-revoked root certificates,
+ you would use a key filter defined as follows:
+ </para>
+<!-- isn't there a better way to not indent this in the output??? -->
+ <screen><!--
+-->[Key Filter #<replaceable>n</replaceable>]
+Name=expired, but not revoked
+was-validated=true
+is-expired=true
+is-revoked=false
+is-root-certificate=true<!--
+ --></screen>
+ <para>
+ To check for all disabled OpenPGP keys (not yet supported by &kleopatra;)
+ with ownertrust of at least
+ <quote>marginal</quote>, you would use:
+ </para>
+ <screen><!--
+-->[Key Filter #<replaceable>n</replaceable>]
+Name=disabled OpenPGP keys with marginal or better ownertrust
+is-openpgp=true
+is-disabled=true
+is-at-least-ownertrust=marginal<!--
+ --></screen>
+ </example>
+
+ </sect1>
+
+ </chapter> <!-- Administrator's Guide -->
+
+<chapter id="credits-and-license">
+<title>Credits and License</title>
+
+<para>&kleopatra; copyright 2002 &Steffen.Hansen;, &Matthias.Kalle.Dalheimer;
+and &Jesper.Pedersen;., copyright 2004 &Daniel.Molkentin;, copyright 2004 Klar&auml;lvdalens Datakonsult AB</para>
+
+<para>Documentation copyright 2002 &Steffen.Hansen;, copyright 2004
+&Daniel.Molkentin;, copyright 2004 Klar&auml;lvdalens Datakonsult AB</para>
+
+<itemizedlist>
+<title>Contributors</title>
+<listitem>
+<para>&Marc.Mutz; &Marc.Mutz.mail;</para>
+</listitem>
+<listitem>
+<para>&David.Faure; &David.Faure.mail;</para>
+</listitem>
+<listitem>
+<para>&Steffen.Hansen; <email>hansen@kde.org</email></para>
+</listitem>
+<listitem>
+<para>&Matthias.Kalle.Dalheimer; &Matthias.Kalle.Dalheimer.mail;</para>
+</listitem>
+<listitem>
+<para>&Jesper.Pedersen; &Jesper.Pedersen.mail;</para>
+</listitem>
+<listitem>
+<para>&Daniel.Molkentin; &Daniel.Molkentin.mail;</para>
+</listitem>
+</itemizedlist>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;
+&underGPL;
+</chapter>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->
diff --git a/doc/kmail/Makefile.am b/doc/kmail/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/kmail/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kmail/configure.docbook b/doc/kmail/configure.docbook
new file mode 100644
index 00000000..a66665ad
--- /dev/null
+++ b/doc/kmail/configure.docbook
@@ -0,0 +1,2048 @@
+<chapter id="configure">
+
+<chapterinfo>
+<authorgroup>
+<author>
+<firstname>Daniel</firstname>
+<surname>Naber</surname>
+<affiliation><address>
+<email>daniel.naber@t-online.de</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>David</firstname>
+<surname>Rugge</surname>
+<affiliation><address>
+<email>davidrugge@mediaone.net</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>Marc</firstname>
+<surname>Mutz</surname>
+<affiliation>
+<orgname>Klar&auml;lvdalens Datakonsult AB</orgname>
+<address>
+<email>mutz@kde.org</email>
+</address>
+</affiliation>
+</author>
+<author>
+<firstname>Michel</firstname>
+<surname>Boyer de la Giroday</surname>
+<affiliation><address>
+<email>michel@kdab.net</email>
+</address></affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+<date>2004-07-13</date>
+<releaseinfo>1.7</releaseinfo>
+</chapterinfo>
+
+<title>Configure &kmail;</title>
+
+<sect1 id="configure-generalinfo">
+<title>General Information</title>
+
+<para>&kmail;'s configuration window enables you to configure &kmail;
+in many ways. You can reach it via
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+&kmail;...</guimenuitem></menuchoice>.</para>
+
+<para>It is divided into six
+pages, each of them represented by one of the
+icons in the list on the left hand side of the dialog. Below the pages
+will be described in detail.</para>
+
+<para>The dialog has several buttons:</para>
+
+<variablelist>
+<varlistentry>
+<term><guibutton>Help</guibutton></term>
+<listitem><para>This will open this manual at the appropriate page.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Defaults</guibutton></term>
+<listitem><para>This will reset the configuration options on the current
+page back to the default values.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Load Profile...</guibutton></term>
+<listitem><para>This will open a dialog which offers several configuration
+profiles. You can use these as starting points for your own configuration.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Reset</guibutton></term>
+<listitem><para>This resets all changes you have made since you last saved
+the settings.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>OK</guibutton></term>
+<listitem><para>This saves the settings and closes the configuration dialog.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Apply</guibutton></term>
+<listitem><para>This saves the settings without closing the configuration
+dialog.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Cancel</guibutton></term>
+<listitem><para>This closes the configuration dialog without saving the
+changes you have made.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="configure-identity">
+<title>Identities Page</title>
+
+<para>You can find a quick introduction to the
+<guilabel>Identities</guilabel> page in the <link
+linkend="getting-started">Getting Started</link> section.</para>
+
+<para>This page allows you to create one or more
+<emphasis>Identities</emphasis>, &ie; combinations of name, email
+address and other settings. For example, you can create one identity
+for business communication and one for
+personal communication. If you have more than one email
+address, you can create one identity per address. You will then be
+able to select an identity on a per-message basis.</para>
+
+<para>The page consists of a list of identities and buttons to manage
+them. The identities list will always show at
+least one identity, which is then the <guilabel>Default</guilabel>
+identity.</para>
+
+<para>To add a new identity to the identity list, click on the
+<guibutton>New...</guibutton> button.
+The <link linkend="configure-identity-newidentitydialog">New identity</link> dialog
+will then appear.</para>
+
+<sect2 id="configure-identity-newidentitydialog">
+<title>The <guilabel>New Identity</guilabel> Dialog</title>
+
+<para>You have to enter the name of the new identity into the
+<guilabel>New Identity</guilabel> edit field. This will be the name
+shown in the identity list.</para>
+
+<para>You can choose how the new identity should be initialized by
+checking one of the three radio buttons in the middle of the
+dialog:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>With empty fields</guilabel></term>
+<listitem>
+<para>All fields of the new identity are cleared or preset with
+standard values.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Use Control Center settings</guilabel></term>
+<listitem>
+<para>Uses the settings of the <application>Control
+Center</application>'s default email profile (you can edit that one
+under <menuchoice><guimenu>Internet &amp; Network</guimenu>
+<guimenuitem>Email</guimenuitem></menuchoice> in the
+<application>Control Center</application>).</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Duplicate existing identity</guilabel></term>
+<listitem>
+<para>Copies all fields from an existing identity. You can
+choose which identity to copy from by selecting the corresponding
+entry in the <guilabel>Existing identities</guilabel> popup.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2 id="configure-identity-general">
+<title>General</title>
+
+<para>The <guilabel>General</guilabel> tab allows you to specify some
+basic settings for the currently selected identity.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Your name</guilabel></term>
+<listitem>
+<para>Enter your full name here (sometimes also called <emphasis>display name</emphasis>).
+Although this field is not strictly mandatory, it is recommended to enter
+the correct value here.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Organization</guilabel></term>
+<listitem>
+<para>Enter your organization here. This field is optional.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Email address</guilabel></term>
+<listitem>
+<para>Enter your email address here, &ie; something like
+<userinput>joe@example.com</userinput>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<example>
+<title>Example</title>
+<para>So if your address is <replaceable>Joe User
+&lt;joe@example.com&gt;</replaceable>, you should enter <userinput>Joe
+User</userinput> into the <guilabel>Your name</guilabel> field and
+<userinput>joe@example.com</userinput> into the <guilabel>Email
+address</guilabel> field.</para></example>
+</sect2>
+
+ <sect2 id="configure-identity-cryptography">
+ <title>
+ Cryptography
+ </title>
+
+ <para>
+ The <guilabel>Cryptography</guilabel> tab allows you to
+ specify &openpgp; and &smime; keys associated with this
+ identity, as well as choosing the preferred (cryptographic)
+ message format to use.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-identity-cryptography-openpgp-sign">
+ <term>
+ <guilabel>OpenPGP signing key</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here you can select the key to be used when
+ &openpgp;-signing messages written with this identity in
+ effect.
+ </para>
+ <para>
+ For brevity, only the short key id of selected keys is
+ shown. Hovering with the mouse over the key list will
+ show more information in a tooltip.
+ </para>
+ <para>
+ To clear the label press the
+ <guibutton>Clear</guibutton> button.
+ </para>
+ <para>
+ To change the selected key, press the
+ <guibutton>Change...</guibutton> button. A dialog
+ listing all secret &openpgp; keys will be shown allowing
+ you to select the one to use.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry id="configure-identity-cryptography-openpgp-encrypt">
+ <term>
+ <guilabel>OpenPGP encryption key</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here you can select the key to &openpgp;-encrypt
+ messages to when this identity and <xref
+ linkend="configure-security-composing-encrypt-to-self"/>
+ are in effect. This key is also used for the <xref
+ linkend="composer-attach-attach-my-public-key"/>
+ function of the <link
+ linkend="the-composer-window">Composer</link>.
+ </para>
+ <para>
+ To change the selected key, press the
+ <guibutton>Change...</guibutton> button. A dialog
+ listing all &openpgp; keys found in your keyring will be
+ shown allowing you to select the one to use.
+ </para>
+ <para>
+ You can clear the list of keys and get more information
+ about them in the same way as described for <xref
+ linkend="configure-identity-cryptography-openpgp-sign"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry id="configure-identity-cryptography-smime-sign">
+ <term>
+ <guilabel>&smime; signing certificate</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here you can select the certificate to be used when
+ &smime;-signing messages written with this identity in
+ effect.
+ </para>
+ <para>
+ To change the selected certificate, press the
+ <guibutton>Change...</guibutton> button. A dialog
+ listing all secret &smime; signing certificates will be
+ shown allowing you to select the one to use.
+ </para>
+ <para>
+ You can clear the list of certificates and get more
+ information about them in the same way as described for
+ <xref linkend="configure-identity-cryptography-openpgp-sign"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry id="configure-identity-cryptography-smime-encrypt">
+ <term>
+ <guilabel>&smime; encryption certificate</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here you can select the certificate to &smime;-encrypt
+ messages to when this identity and <xref
+ linkend="configure-security-composing-encrypt-to-self"/>
+ are in effect.
+ </para>
+ <para>
+ To change the selected certificate, press the
+ <guibutton>Change...</guibutton> button. A dialog
+ listing all &smime; encryption certificates found in
+ your local keybox will be shown allowing you to select
+ the one to use.
+ </para>
+ <para>
+ You can clear the list of certificates and get more
+ information about them in the same way as described for
+ <xref linkend="configure-identity-cryptography-openpgp-sign"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-identity-cryptography-preferred-format">
+ <term>
+ <guilabel>Preferred crypto message format</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Here you can choose which cryptographic message format
+ to use by default with this identity.
+ </para>
+ <para>
+ You can either select any of the four formats supported
+ by &kmail; or leave the option at the recommended
+ default setting of <guilabel>Any</guilabel>, which will
+ choose a suitable format based on the recipients of the
+ message, or might even go so far as to create two copies
+ of the message, one &smime; signed and/or encrypted, the
+ other &openpgp; signed and/or encrypted.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+<sect2 id="configure-identity-advanced">
+<title>Advanced</title>
+
+<para>The <guilabel>Advanced</guilabel> tab allows you to specify some
+rarely used or otherwise specialized settings for the currently
+selected identity.</para>
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Reply-To address</guilabel></term>
+<listitem>
+<para>Enter the address to which replies to your messages should be
+sent. Only fill out this field if it is different from your normal
+address (specified using the <guilabel>Name</guilabel> and
+<guilabel>Email Address</guilabel> on the <link
+linkend="configure-identity-general"><guilabel>General</guilabel>
+tab</link>), since replies default to the sender's address
+anyway.</para>
+<note><para>This field is only useful if you want replies to your mail
+to go somewhere else than your regular email address, &eg; if you are
+using this identity to send messages from an email address that cannot
+receive messages. Note that
+some mailing lists overwrite this header field with their post address to
+make sure that replies go to the list instead of individuals. So the
+usefulness of this field is very limited and it should only be used in
+rare cases.</para></note>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>BCC address</guilabel></term>
+<listitem>
+<para>Optionally enter an address to which blind copies of your messages
+should be sent to. Note that a BCC is only send to this address, when
+<menuchoice><guimenu>View</guimenu><guimenuitem>BCC</guimenuitem></menuchoice>
+is activated while composing a message. If you want to send a BCC regardless
+of this setting, you should look at the <guilabel>Headers</guilabel> tab of the
+<guilabel>Composer</guilabel> page.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Sent-mail folder</guilabel></term>
+<listitem>
+<para>Select the folder into which messages should be filed after sending
+when using this identity. <acronym>IMAP</acronym> users should consider changing this to an
+<acronym>IMAP</acronym> folder, so their sent-mail is stored on a server instead of being
+stored in a local folder. This way they can access these messages at a
+different location.</para>
+
+<tip><para>You can exercise more fine-grained control over where to
+file sent messages by creating a corresponding <link
+linkend="filters">message filter</link> that is applied to outgoing
+messages.</para></tip>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Drafts folder</guilabel></term>
+<listitem>
+<para>Select the folder into which drafts should be filed when using
+this identity. <acronym>IMAP</acronym> users should consider changing this to an
+<acronym>IMAP</acronym> folder, so their drafts are stored on a server instead of being
+stored in a local folder. This way they can easily continue to work
+on their drafts at a different location.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Special transport</guilabel></term>
+<listitem>
+<para>Select or enter an alternative SMTP server to be used when sending
+messages using this identity.</para>
+
+<note><para>You need to configure outgoing mail servers first, before
+you can choose them from the list. You can do this on the <link
+linkend="configure-accounts-sending"><guilabel>Sending</guilabel>
+tab</link> of the <link linkend="configure-accounts">
+<guilabel>Accounts</guilabel> page</link>.</para></note>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2 id="configure-identity-signature">
+<title>Signature</title>
+
+<para>This tab allows you to specify a signature (sometimes called
+<quote>footer</quote> or <quote>disclaimer</quote>)
+to be appended to each message sent using this identity.</para>
+
+<note><para>This type of signature has nothing to do with the
+(digital) signatures for which you can select the keys to use on
+the <link linkend="configure-identity-cryptography">Cryptography</link>
+tab. It is just bad wording to call this a signature, but since
+the term is already used everywhere else, we keep this notation. Just
+keep in mind that these signatures and digital signatures are two
+completely different things.</para></note>
+
+<para>Check the <guilabel>Enable signature</guilabel> option if you
+want to be able to append the signature when using this identity. To
+<emphasis>automatically</emphasis> append it to every new message
+you also have to select <guilabel>Automatically append
+signature</guilabel> in the <guilabel>Composer</guilabel> configuration page.</para>
+
+<para>&kmail; can obtain the signature text from various sources. The
+traditional way on Unix is to read the text from a file called
+<filename>.signature</filename> in your home folder. This file can
+be shared between several programs, so you get the same
+signature in each mail program you use.</para>
+
+<para>To read the text from a text file you select
+<guilabel>Obtain signature text from file</guilabel>. Enter the
+filename in the <guilabel>Specify file</guilabel> edit field or hit
+the button to the right of it to browse your filesystem. If you want
+to edit the file, hit the <guilabel>Edit File</guilabel>
+button.</para>
+
+<para>&kmail; can also read the signature text from the output of a
+command. Thus, you can use programs such as
+<command>fortune</command> to create a new signature text for
+every message. Everything the program prints onto
+<acronym>stdout</acronym> is caught and used as the signature
+text.</para>
+
+<para>To read the text from the output of a command you select
+<guilabel>Obtain signature text from Output of
+Command</guilabel>. Enter the command (preferably with full path) in
+the <guilabel>Specify command</guilabel> edit field.</para>
+
+<para>As a third option, you can enter the signature text directly in
+&kmail;'s configuration dialog. To do this, select <guilabel>Obtain
+signature text from input field below</guilabel> and enter the text
+into the appearing text box.</para>
+
+<note><para>On the Internet, signatures are by convention separated
+from the body of the message by a line containing only the three
+character <quote>-- </quote> (dash, dash, space). &kmail; will
+automatically prepend the signature text with this line if it is not
+already present in the signature text.</para>
+<para>If you do not wish the separator to be prepended
+automatically by &kmail;, simply add it to the signature
+text yourself.</para>
+</note>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="configure-accounts">
+<title>Accounts Page</title>
+
+<para>You can find a quick introduction to the
+<guilabel>Accounts</guilabel> page in the <link
+linkend="setting-up-your-account">Setting up your Account</link>
+section.</para>
+
+<para>This page allows you to create one or more (incoming and
+outgoing) <emphasis>accounts</emphasis>, &ie; combinations of mail
+servers, login information and other settings. Typically, you will
+create one outgoing (used for sending messages) and one incoming (used to
+retrieve messages) account. You can create as many accounts as you want, though,
+and assign each one to different <link
+linkend="configure-identity">identities</link> or decide on a per-message
+basis.</para>
+
+<sect2 id="configure-accounts-sending">
+<title>Sending</title>
+
+<para>The <guilabel>Sending</guilabel> tab allows you to define new
+outgoing mail servers and set some common options.</para>
+
+<para>For basic information, see <link
+linkend="sending-mail">Setting up your Account: Sending</link>.</para>
+
+<para>When you click <guibutton>Add...</guibutton> or
+<guibutton>Modify...</guibutton> the <guilabel>Add
+transport</guilabel> or <guilabel>Modify transport</guilabel> dialogs
+will open respectively. For sending via <application>sendmail</application>
+or similar programs
+you can specify a name and the location of the
+<command>sendmail</command> program. For <acronym>SMTP</acronym> you
+can specify <guilabel>Name</guilabel>, <guilabel>Host</guilabel>, and
+<guilabel>Port</guilabel> of the server. <guilabel>Server requires
+authentication</guilabel> will enable the <guilabel>Login</guilabel>
+and <guilabel>Password</guilabel> fields and the
+<guilabel>Authentication method</guilabel> buttons on the
+<guilabel>Security</guilabel> tab. If you are not sure about the
+security settings you can make &kmail; test for the best settings by
+using <guibutton>Check What the Server Supports</guibutton>.</para>
+
+<para><guilabel>Confirm before send</guilabel> will pop up a
+confirmation box every time you send a message.</para>
+
+<para><guilabel>Send messages in outbox folder</guilabel> lets you specify
+when queued messages, &ie; messages in the outbox folder pending to be sent,
+should be sent. You can choose between:</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>Never Automatically</guilabel></term>
+<listitem><para>Queued messages will only be sent if you select
+<menuchoice><guimenu>File</guimenu><guimenuitem>Send queued messages</guimenuitem></menuchoice>.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>On Manual Mail Checks</guilabel></term>
+<listitem><para>Queued messages will be sent after you have manually checked
+for new mail, &eg; with <menuchoice><guimenu>File</guimenu><guimenuitem>Check Mail</guimenuitem></menuchoice>. Of course, you can also
+manually send the queued messages with
+<menuchoice><guimenu>File</guimenu><guimenuitem>Send queued messages</guimenuitem></menuchoice>.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>On All Mail Checks</guilabel></term>
+<listitem><para>Queued messages will be sent after all checks for new mail,
+&ie; after automatic mail checks as well as after manual mail checks.
+Of course, you can also manually send the queued messages with
+<menuchoice><guimenu>File</guimenu><guimenuitem>Send queued messages</guimenuitem></menuchoice>.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para><guilabel>Default send method</guilabel> lets you define what
+happens when a message is sent. If <guilabel>Send now</guilabel> is
+selected, the message is sent to the mail server immediately, while if
+<guilabel>Send later</guilabel> is selected, the message is queued in
+the outbox to be sent later with the
+<menuchoice><guimenu>File</guimenu><guimenuitem>Send
+Queued Messages</guimenuitem></menuchoice> command or automatically when you
+check your mail, depending on the setting of
+<guilabel>Send messages in outbox folder</guilabel> above.</para>
+
+<para><guilabel>Message property</guilabel> lets you select how your
+message will be encoded when it is sent. <guilabel>Allow
+8-bit</guilabel> means that &kmail; will send your message in 8-bit
+<acronym>ASCII</acronym>, which means that all special characters such
+as accented letters will be sent as-is. If <guilabel>MIME Compliant
+(Quoted Printable)</guilabel> is selected, special characters will be
+encoded using standard &MIME; encodings, which may be more portable to
+mailing systems other than 8-bit <acronym>ASCII</acronym>.
+We recommend to use <guilabel>MIME Compliant</guilabel>.</para>
+
+<note><para>Even with <guilabel>Allow 8-bit</guilabel>
+selected &kmail; will use <guilabel>MIME
+Compliant</guilabel> encoding in some situations, for
+example for sending cryptographically signed messages.</para></note>
+
+<para><guilabel>Default domain</guilabel> lets you specify which domain name
+should be used to complete email addresses that only consist of the recipient's user
+name. For example when you set the default domain to <replaceable>kde.org</replaceable>
+then messages you send to <replaceable>johndoe</replaceable> will be sent to
+<replaceable>johndoe@kde.org</replaceable>.</para>
+
+</sect2>
+
+<sect2 id="configure-accounts-receiving">
+<title>Receiving</title>
+
+<para>For basic information, see <link
+linkend="receiving-mail">Setting up your Account: Receiving</link>.</para>
+
+<para><guilabel>Check mail on startup</guilabel> lets you specify whether
+KMail should check for new mail immediately after it has been started.</para>
+
+<para>With <guilabel>New Mail Notification</guilabel> you can set
+how &kmail; will notify you if new messages have arrived:
+<guilabel>Beep</guilabel> will play a short beep sound;
+if <guilabel>Detailed new mail notification</guilabel> is enabled then
+&kmail; will show the number of new messages for each folder provided
+you have chosen to be notified with a dialog. More advanced
+notification options, like showing a dialog or running a certain command,
+are available via the <guibutton>Other Actions</guibutton> button.</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="configure-appearance">
+<title>Appearance Page</title>
+
+<sect2 id="configure-appearance-fonts">
+<title>Fonts</title>
+
+<para>This section allows you to change the type, size and character set of the
+display fonts. <guilabel>Message Body</guilabel> sets the font for
+the reader pane, <guilabel>Composer</guilabel> sets the font for
+writing messages in the composer window.<!-- fixme in kmail: better wording? -->
+There is a separate entry for <guilabel>Message List - Date Field</guilabel>
+so you can choose a monospaced font for the date field for better readability.</para>
+
+</sect2>
+
+<sect2 id="configure-appearance-colors">
+<title>Colors</title>
+
+<para>This section allows you to change the color of the text.
+<guilabel>Recycle colors on deep quoting</guilabel> means that even text that is
+quoted more than three times will appear in color. Note that the
+<guilabel>Quoted text</guilabel> colors only work in the message reader, not in
+the composer. If you want folders which are close to their quota
+(space alotment, usually used on IMAP servers) to be displayed in a different color,
+you can specify a percentage value as a threshold for this. The color to be used
+can be configured along with the other custom colors.<!-- TODO --></para>
+
+</sect2>
+
+<sect2 id="configure-appearance-layout">
+<title>Layout</title>
+
+<para><guilabel>Show HTML status bar</guilabel> activates a bar at the left side of the reader
+pane that tells you if a message is &html; or not. This is important because
+&html; messages might imitate the look of a signed and encrypted message, so
+you should be aware of the fact that you are reading a &html; message. The &html;
+status bar itself cannot be influenced by the &html; code of the message.</para>
+
+<para>The <guilabel>Window Layout</guilabel> section lets you choose the
+layout of the main window. You can choose where you want the
+<guilabel>Message Preview Pane</guilabel> or choose not to have
+it at all.</para>
+
+<para>The <guilabel>Message Structure Viewer</guilabel> option lets you choose when
+the structure viewer will be shown: the structure viewer is a part of the main window that
+lets you access all parts of a message. <guilabel>Show never</guilabel> will
+disable the structure viewer (note that you can still access attachments as icons),
+<guilabel>Show always</guilabel> will show the structure viewer even if there is only
+one plaintext part. <guilabel>Show only for non-plaintext messages</guilabel> will
+display the structure viewer only if it makes sense, &ie; if the current message
+has attachments or has &html; parts.</para>
+
+</sect2>
+
+<sect2 id="configure-appearance-headers">
+<title>Headers</title>
+
+<para>With <guilabel>Display message sizes</guilabel> selected there will be another
+column in the header pane that shows the messages' size.</para>
+
+<para><guilabel>Show crypto icons</guilabel> will add more status information
+to the <guilabel>Subject</guilabel> columns in the header pane: every message
+that has been signed will have a small <guiicon>Signed</guiicon> icon in front
+of the subject, every message that has been encrypted will have a small
+<guiicon>Encrypted</guiicon> icon in front of the subject. Note that you have
+to select a message once before these icons will appear, until then only
+question marks will be displayed.</para>
+
+<para><guilabel>Thread list of message headers</guilabel> will put all the messages
+in the header pane in a kind of tree list, so that the replies to a message are
+directly below that message.</para>
+
+<para>With <guilabel>Message header threading options</guilabel> you can select
+whether threads should appear expanded (<guilabel>open</guilabel>) by
+default or whether they should be collapsed (<guilabel>closed</guilabel>).
+You can of course still open/close threads using the <guilabel>+</guilabel>/<guilabel>-</guilabel>
+buttons.</para>
+
+<para>With <guilabel>Date Display</guilabel> you can choose between several
+date formats. The <guilabel>Localized Format</guilabel> is the one you can
+specify under <guilabel>Country &amp; Language</guilabel> in &kcontrol;.
+For the <guilabel>Custom</guilabel> format you can get
+a description of the possible values by pressing
+<keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo>
+and then clicking on <guilabel>Custom</guilabel> option.</para>
+
+</sect2>
+
+<sect2 id="configure-appearance-systemtray">
+<title>System Tray</title>
+
+<para>If you enable the system tray icon then a small &kmail; icon with the
+number of unread messages will be shown in the system tray. You can enable
+&kmail;'s system tray icon with <guilabel>Enable system tray icon</guilabel>,
+and with <guilabel>System Tray Mode</guilabel>
+you can specify whether the tray icon should always be shown or only if
+you have unread messages.</para>
+
+<para>If the icon is visible then you can hide &kmail;'s main window by
+clicking on the icon or by clicking on the window close button. By clicking
+on the icon you can make &kmail;'s main window visible again.
+If you click on the icon with the <mousebutton>right</mousebutton>
+mousebutton then you get a menu with a few useful commands. You can check
+for new mail, create a new message or quit &kmail;. Additionally, there is
+the entry <guilabel>New Messages In</guilabel> which lists all folders
+containing unread messages. If you choose one of those folders then this
+folder will be selected in &kmail;'s main window.
+</para>
+
+</sect2>
+
+<!-- fixme?: date + less than/greater than broken in kmail? -->
+<!-- fixme?: "group" wording in program -->
+
+</sect1>
+
+ <sect1 id="configure-composer">
+ <title>
+ Composer Page
+ </title>
+
+ <sect2 id="configure-composer-general">
+ <title>
+ General
+ </title>
+
+ <variablelist>
+ <varlistentry id="configure-composer-general-append-signature">
+ <term>
+ <guilabel>Automatically append signature</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, your signature as defined in the <link
+ linkend="configure-identity-signature">identity
+ page</link> is automatically included at the end of
+ all messages you create (&ie; new messages, replies, &etc;).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="configure-composer-general-smart-quoting">
+ <term>
+ <guilabel>Use smart quoting</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will break long lines but will try
+ to keep the correct quoting (&eg; the <quote>&gt;
+ </quote> will always be at the start of the line).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="configure-composer-general-auto-request-mdns">
+ <term>
+ <guilabel>Automatically request message disposition notifications</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, <xref
+ linkend="composer-options-request-mdn"/> will default to
+ <emphasis>on</emphasis>. Check this option only if you
+ know what you are doing. &mdn;s are considered a
+ nuisance (or are simply ignored) by a lot of people. It
+ is better to decide to request them on a
+ message-by-message basis.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="configure-composer-general-word-wrap">
+ <term>
+ <guilabel>Word wrap at column</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Lets you turn word wrapping on and off in the composer
+ window and lets you set the column at which words will
+ be wrapped (you probably should not need to change the
+ default value, which is <literal>78</literal>).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="configure-composer-general-autosave-interval">
+ <term>
+ <guilabel>Autosave interval</guilabel>
+ </term>
+ <listitem>
+ <para>
+ A backup copy of the text in the composer window can be created
+ regularly. This option lets you specify the interval used to
+ create the backup. You can disable autosaving by setting it to
+ the value <literal>0</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="configure-composer-general-external-editor">
+ <term>
+ <guilabel>External Editor</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If you do not like the Composer you can use a different
+ editor. Note that the composer window will still open
+ and the external editor will open as soon as you type
+ just one character in the body of the message. If you are
+ done, save the text and exit the editor. The text will
+ now appear in the composer window, where you can send
+ it. Note that your editor may not return immediately,
+ you have to use &eg;
+ <userinput>
+ <command>
+ gvim <option>-f</option> <varname>%f</varname>
+ </command>
+ </userinput> for <application>gvim</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
+
+<sect2 id="configure-composer-phrases">
+<title>Phrases</title>
+
+<para>The <guilabel>Phrases</guilabel> tab lets you define the automatically
+generated lines that are added to message replies, forwarded messages, and the
+character that is added in front of quoted text.
+There are special &percnt;-denoted characters that will insert certain
+values, which are also displayed at the top of the <guilabel>Phrases</guilabel> section.
+You can add reply phrases in languages other than
+your default &kde; language using the <guibutton>Add...</guibutton> button.
+You can then choose between different languages with the
+<guilabel>Language</guilabel> drop down box.
+This will only work for languages whose i18n package you have installed.</para>
+
+</sect2>
+
+<sect2 id="configure-composer-subject">
+<title>Subject</title>
+
+<para>This section contains a list of prefixes for <quote>Reply</quote> and
+<quote>Forward</quote>. If you receive messages that use prefixes different
+to the standard ones, you can add them here so &kmail; will recognize
+them. This way &kmail; can ignore them for sorting messages and
+when setting the subject of a reply or a forwarded messages, and optionally
+replace them with <quote>Re:</quote> or <quote>Fwd:</quote>
+respectively.</para>
+
+</sect2>
+
+<sect2 id="configure-composer-charset">
+<title>Charset</title>
+
+<para>Here you can manage the default charsets used for your own messages.
+Every message you send will be checked if it is written in one of the listed
+charsets, starting at the top of the list. If it is, this charset will be used.
+If it is not, a dialog will show up and tell you that you manually have to choose
+a charset using
+<menuchoice><guimenu>Options</guimenu><guisubmenu>Set Encoding</guisubmenu></menuchoice>.
+</para>
+
+<para>If you select <guilabel>Keep original charset when replying
+or forwarding (if possible)</guilabel>, the original message's charset
+will be kept, unless there are now characters that cannot be
+represented using that charset.</para>
+
+</sect2>
+
+<sect2 id="configure-composer-headers">
+<title>Headers</title>
+
+<para>Check the <guilabel>Use custom message-id suffix</guilabel>
+checkbox if you want &kmail; to generate Message-Id's with a custom
+suffix. Enter the desired suffix in the <guilabel>Custom message-id
+suffix</guilabel> field. Please make sure that the suffix that you
+specify is world-wide unique. The best thing is to use the name of a
+domain which you are the owner of. If you do not check <guilabel>Use
+custom Message-Id suffix</guilabel> then &kmail; will automatically
+generate the complete Message-Id. If you do not know what this is all
+about do not check this option.</para>
+
+<para>The <guilabel>Define custom mime header fields</guilabel> list
+sets the headers that &kmail; will use for its outgoing messages. You
+can both invent new fields and overwrite existing ones. This feature
+is only useful for advanced users.</para>
+
+</sect2>
+
+<sect2 id="configure-composer-attachments">
+<title>Attachments</title>
+
+<para>If you have to send attachments with filenames containing non-English
+characters to users of Outlook(TM) or Outlook Express(TM) then you might want
+to check the <guilabel>Outlook-compatible attachment naming</guilabel> option.
+&kmail; will then encode the attachment names in a non-standard way that is
+understood by Outlook(TM).</para>
+<para>Note that &kmail; will create non-standard compliant messages, and
+consequently it is possible that your messages will not be understood by
+standard-compliant mail clients. So, unless you have no other choice, you
+should not enable this option.</para>
+
+<para>Check the <guilabel>Enable detection of missing attachments</guilabel>
+checkbox if you want &kmail; to warn you whenever you are about to send a
+message without attachments although the message text contains certain
+words which indicate that you wanted to include an attachment. The list
+of key words can be modified.</para>
+
+</sect2>
+
+</sect1>
+
+ <sect1 id="configure-security">
+ <title>
+ Security Page
+ </title>
+
+ <sect2 id="configure-security-reading">
+ <title>
+ Reading
+ </title>
+
+ <para>
+ On this tab you can configure security-relevant options for
+ reading messages.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-security-reading-prefer-html">
+ <term>
+ <guilabel>Prefer HTML to plain text</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will show &html; messages with their
+ &html; formatting and layout. We strongly recommend to
+ leave this option off, as security problems with &html;
+ might show up. When this option is off, you can still
+ read &html; messages, but only as plain text.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-reading-external-references">
+ <term>
+ <guilabel>Allow messages to load external references from the Internet</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; can load external images, style
+ sheets &etc; from the Internet when you look at an
+ &html; message. We strongly recommend to leave this
+ option off (although it has no effect if you only view
+ plain text messages). By adding external references to
+ their messages, people sending spam can detect that and
+ when you have looked at their message. Note that this
+ option has no effect on &Java;, JavaScript and Plugins -
+ these are disabled anyway and cannot be enabled at all.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-reading-mdns">
+ <term>
+ <guilabel>Message Disposition Notifications</guilabel>
+ </term>
+ <listitem>
+ <para>
+ &mdn;s are a generalization of what is commonly called a
+ <quote>read receipt</quote>. The message author requests
+ a disposition notification to be sent and the receiver's
+ mail program generates a reply from which the author can
+ learn what happened to his message. Common disposition
+ types include <quote>displayed</quote> (&ie; read),
+ <quote>deleted</quote> and <quote>dispatched</quote>
+ (&eg; forwarded).
+ </para>
+ <para>
+ The following options (listed as <guilabel>Send
+ policy</guilabel>) are available to control
+ <emphasis>when</emphasis> &kmail; sends &mdn;s:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <guilabel>Ignore</guilabel> (recommended)
+ </term>
+ <listitem>
+ <para>
+ Ignores any request for disposition
+ notifications. No &mdn; will ever be sent
+ automatically.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <guilabel>Ask</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Answers requests only after asking the user for
+ permission. This way, you can send &mdn;s for
+ selected messages while denying or ignoring them
+ for others.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <guilabel>Deny</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Always sends a <quote>denied</quote>
+ notification. This is only
+ <emphasis>slightly</emphasis> better than always
+ sending &mdn;s. The author will still know that
+ the messages has been acted upon, he just cannot
+ tell whether it was deleted or read &etc;
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <guilabel>Always send</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Always sends the requested disposition
+ notification. That means that the author of the
+ message gets to know when the message was acted
+ upon and, in addition, what happened to it
+ (displayed, deleted, &etc;). This option is
+ strongly discouraged, but since it makes sense
+ where privacy is not a concern, &eg; in customer
+ relationship management, it has been made
+ available.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ If you are unsure, experiment a while with
+ <guilabel>Ask</guilabel> and if you find &kmail;s
+ questions annoying, switch to <guilabel>Ignore</guilabel>.
+ </para>
+ <para>
+ The following options (listed as <guilabel>Quote
+ original message</guilabel>) are available to control
+ <emphasis>how much</emphasis> of the original message
+ &kmail; sends back in &mdn;s.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <guilabel>Nothing</guilabel>
+ </term>
+ <listitem>
+ <para>
+ No parts of the message other than the mandatory
+ message-id and the original recipient is included
+ in the &mdn; reply. This preserves enough
+ information for the sender to find the message in
+ his sent messages for which this &mdn; was
+ generated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <guilabel>Full message</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Attaches the complete message to the disposition
+ notification. Usually, this is overkill. It does
+ not add any valueable information that cannot be
+ deduced from the message headers alone, but people
+ sometimes insist on this, since it is much easier
+ for humans to correlate the content of the message
+ than just the headers to what they sent earlier.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <guilabel>Only headers</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Attaches only the headers to the disposition
+ notification. This is usually enough to enable
+ both humans (by subject) and computers (by
+ message-id) to easily correlate &mdn; and original
+ message.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ If unsure, leave the option at the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <guilabel>Do not send MDNs in response to encrypted messages</guilabel>
+ </term>
+ <listitem>
+ <para>
+ This option suppresses the sending of &mdn;s if the
+ message is encrypted (partially or in whole). This
+ thwarts attempts to use &kmail;'s &mdn; feature as an
+ <emphasis>oracle</emphasis> to deduce whether you were
+ able to decrypt the message or not.
+ </para>
+ <para>
+ Strictly speaking, this option is not needed, since
+ &kmail; sends &mdn;s regardless of whether the message
+ could be successfully decrypted or not (the disposition
+ notification request resides in the unencrypted part of
+ the message), but it gives the security-conscious user
+ the choice to either send them always if requested
+ (option unchecked), or never (option checked).
+ </para>
+ <para>
+ If unsure, leave the option checked.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <guilabel>Automatically import keys and certificates</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; automatically imports any attachments
+ containing &openpgp; keys into your local keyring, and any
+ attachments containing &smime; keys into your local key
+ box.
+ </para>
+ <note>
+ <para>
+ Verifying &smime; signatures always involves importing
+ the contained certificates. This option thus does not
+ affect this. It is also unrelated to &gpg;'s
+ <option>auto-key-retrieve</option> feature, where &gpg;
+ will try to import unknown keys from a key server.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 id="configure-security-composing">
+ <title>
+ Composing
+ </title>
+
+ <para>
+ On this tab you can configure security-relevant options for
+ composing messages.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-security-composing-automatically-sign">
+ <term>
+ <guilabel>Automatically sign messages</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, the <xref
+ linkend="composer-options-sign-message"/> option in the
+ composer will default to <emphasis>on</emphasis>.
+ </para>
+ <para>
+ However, you can still switch it on and off on a
+ per-message basis.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-composing-encrypt-to-self">
+ <term>
+ <guilabel>Always encrypt to self</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, any message that is encrypted to the
+ recipients will additionally be encrypted to yourself.
+ </para>
+ <warning>
+ <para>
+ If you uncheck this option, you may not be able to
+ decrypt the messages written by yourself and encrypted
+ to other people anymore.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-composing-store-sent-encrypted">
+ <term>
+ <guilabel>Store sent messages encrypted</guilabel><!--
+ --><footnote>
+ <para>
+ This options enables a mode of using mail encryption
+ that is sometimes (misleadingly) called
+ <quote>transport-only</quote> encryption. In this mode
+ of operation, the message encryption is stripped off
+ as soon as the message has reached its
+ destination. The encryption lasts only while the
+ message is on its way.
+ </para>
+ <para>
+ &kmail; supports this mode half-heartedly, since such
+ functionality should better placed at the mail
+ <emphasis>server</emphasis> (<acronym>MTA</acronym>)
+ than at the mail <emphasis>client</emphasis>
+ (<acronym>MUA</acronym>) level. Thus, future versions
+ of &kmail; may drop support for this option.
+ </para>
+ </footnote>
+ </term>
+ <listitem>
+ <para>
+ If checked, messages are stored in your
+ <guilabel>sent-mail</guilabel> folder just as you sent
+ them (&ie; if they were encrypted, they are also stored
+ that way).
+ </para>
+ <para>
+ If unchecked, messages will <emphasis>always</emphasis>
+ be stored unencrypted in your
+ <guilabel>sent-mail</guilabel> folder, even if they are
+ sent encrypted.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-composing-show-encryption-key">
+ <term>
+ <guilabel>Always show the encryption keys for approval</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, everytime you encrypt a message, a dialog
+ will appear that presents you with the encryption keys
+ that will be used for each recipient. You can then
+ review the choice of keys, change them, and approve or
+ cancel the encryption operation. We recommend to keep
+ this option checked, since it makes the encryption
+ process more transparent.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-composing-opportunistic-encryption">
+ <term>
+ <guilabel>Automatically encrypt messages whenever possible</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Also called <quote>opportunistic encryption</quote>. If
+ checked, &kmail; will try to match recipients to
+ (&openpgp; or &smime;) keys even when you did
+ <emphasis>not</emphasis> specifically request
+ encryption. If usable keys are found for all recipients,
+ &kmail; will ask whether or not you want to encrypt the
+ message.
+ </para>
+ <para>
+ It is highly recommended to turn this on, as it makes
+ encrypting messages really easy to use.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-composing-never-sign-encrypt-drafts">
+ <term>
+ <guilabel>Never sign/encrypt when saving as draft</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will not attempt to sign and/or
+ encrypt messages that are merely saved to the
+ <guilabel>drafts</guilabel> folder. This is more
+ convenient, and does not result in a gross loss of
+ security, provided the drafts folder is safe. &imap;
+ users might want this options turned off, if their
+ <guilabel>drafts</guilabel> folder is on the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="configure-security-warnings">
+ <title>
+ Warnings
+ </title>
+
+ <para>
+ On this tab you can switch security-relavant warnings on and
+ off.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-security-warnings-warn-send-unsigned">
+ <term>
+ <guilabel>Warn when trying to send unsigned messages</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will show a warning if for whatever
+ reason a message would be sent without being digitally
+ signed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-warnings-warn-send-unencrypted">
+ <term>
+ <guilabel>Warn when trying to send unencrypted messages</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will show a warning if for whatever
+ reason a message would be sent without being encrypted.
+ </para>
+ <note>
+ <para>
+ While it is common to sign all outgoing messages,
+ encrypting them is not. So unless your company has a
+ policy of never sending any unencrypted messages, it
+ might be a good idea to keep this option switched off
+ and rely on <link
+ linkend="configure-security-composing-opportunistic-encryption">opportunistic
+ encryption</link> to alert you if you
+ <emphasis>could</emphasis> send encrypted messages,
+ but did not request it.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-warnings-warn-receiver-email-not-in-cert">
+ <term>
+ <guilabel>Warn if receiver's email address is not in certificate</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will emit a warning if an &smime;
+ certifciate or &openpgp; key will be used for a recipient
+ whose email address is not listed in the email addresses
+ stored in the certificate.
+ </para>
+ <para>
+ Situations in which this warning will trigger include
+ when configuring your per-identity &openpgp; keys or
+ &smime; certificates, when encrypting, and when verifying
+ signatures, if the signature was made with a certificate
+ that does not include the email address of the sender.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-warnings-warn-near-expire">
+ <term>
+ <guilabel>Warn if certificates/keys expire soon</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &kmail; will warn when an &smime; certificate
+ or &openpgp; key is used which will expire soon.
+ </para>
+ <para>
+ The period in which to warn before key/certificate
+ expiration can then be configured separately for signing
+ and encryption keys, as well as (in the case of &smime;),
+ for end-user certificates, intermediate
+ <acronym>CA</acronym> certificates and root
+ certificates.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-security-warnings-reenable-all-warnings">
+ <term>
+ <guilabel>Re-Enable All &quot;Don&apos;t Ask Again&quot; Warnings</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Apart from the main warnings described above, there are
+ more warning and information messages, which contain an
+ option to not show them again. If you would like to
+ re-enable them after choosing not to show them again,
+ you can achieve this by pressing this button.<!--
+ --><footnote>
+ <para>
+ This will re-enable <emphasis>all</emphasis> such
+ warnings for &kmail;. It does not make much sense to
+ allow more fine-grained selection of which warnings
+ to show since you can just check the option to
+ suppress them again when they next show up.
+ </para>
+ </footnote>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </sect2>
+
+ <sect2 id="configure-security-smime-validation">
+ <title>
+ &smime; Validation
+ </title>
+
+ <para>
+ This tab contains selected entries from &gpgsm;'s <link
+ linkend="configure-security-crypto-backends-configure">dynamic
+ backend configuration dialog</link>. Please refer
+ to the &gpgsm; manual for a description of these options.
+ </para>
+
+ <variablelist>
+
+ <varlistentry id="configure-smime-validation-certificate-crls">
+ <term>
+ <guilabel>Validate certificates using CRLs</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If checked, &smime; certificates are validated using
+ Certificate Revocation Lists (<acronym>CRLs</acronym>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-validation-certificate-ocps">
+ <term>
+ <guilabel>Validate certificates online (OCSP)</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If this option is selected, &smime; certificates are validated
+ using the Online Certificates Status Protocol
+ (<acronym>OCSP</acronym>).
+ </para>
+ <para>
+ Fill in the <acronym>URL</acronym> of the <acronym>OCSP</acronym>
+ responder in the field reserved at this effect.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-online-certificate-responder-url">
+ <term>
+ <guilabel>OCSP responder URL</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Enter the address of the server for online validation
+ of certificates. The <acronym>URL</acronym>
+ is usually starting with <emphasis>http://</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-online-certificate-responder-signature">
+ <term>
+ <guilabel>OCSP responder signature</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Select or change and enter the &smime; key to use.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-online-certificate-responder-ignore">
+ <term>
+ <guilabel>Ignore service URL of certificates</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Check this option to skip online validation using the OCSP.
+ This Option requires <emphasis>dirmngr &gt;= 0.9.0</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-validation-policies">
+ <term>
+ <guilabel>Do not check certificate policies</guilabel>
+ </term>
+ <listitem>
+ <para>
+ By default, <guilabel>GnuPG</guilabel> uses the file
+ <emphasis>~/.gnupg/policies.txt</emphasis> to check if a
+ certificate policy is allowed. If this option is selected,
+ policies are not checked.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-validation-consult-crls">
+ <term>
+ <guilabel>Never consult a CRLs</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If this option is checked, Certificate Revocation Lists are
+ never used to validate <acronym>&smime;</acronym> certificates.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-validation-fetch-issuer">
+ <term>
+ <guilabel>Fetch missing issuer certificates</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Check this option if you want the missing issuer certificates
+ to be fetched when necessary. This applies to both validation
+ methods, <acronym>CRLs</acronym> and <acronym>OCSP</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-http-requests">
+ <term>
+ <guilabel>Do not perform any HTTP requests</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Entirely disables the use of <acronym>HTTP</acronym> for
+ <acronym>&smime;</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-http-ignore-distribution-point">
+ <term>
+ <guilabel>Ignore HTTP CRL Distribution Point of certificates</guilabel>
+ </term>
+ <listitem>
+ <para>
+ When looking for the location of a <acronym>CRL</acronym>,
+ <quote>the "to-be-tested"</quote>certificate usually contains
+ what are known as CRL Distribution Point (<acronym>DP</acronym>) entries,
+ which are <acronym>URLs</acronym> describing the way to access
+ the <acronym>URL</acronym>. The first found <acronym>DP</acronym>
+ entry is used.
+ With this option all entries using the <acronym>HTTP</acronym>
+ scheme are ignored when looking for a suitable
+ <acronym>DP</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-http-proxy">
+ <term>
+ <guilabel>Use system HTTP proxy</guilabel>
+ </term>
+ <listitem>
+ <para>
+ If this option is selected, the value of the
+ <acronym>HTTP</acronym> proxy shown on the right
+ (which comes from the environment variable http_proxy)
+ will be used for any <acronym>HTTP</acronym> request.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-http-requests-proxy">
+ <term>
+ <guilabel>Use this proxy for HTTP requests</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Enter here the location of your <acronym>HTTP</acronym> Proxy,
+ which will be used for all <acronym>HTTP</acronym> requests
+ relating to <acronym>&smime;</acronym>.
+ The syntax is <quote>"host:port"</quote>, for instance
+ <emphasis>myproxy.nowhere.com:3128</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-ldap-requests">
+ <term>
+ <guilabel>Do not perform any LDAP requests</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Entirely disables the use of <acronym>LDAP</acronym> for
+ <acronym>&smime;</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-ldap-distribution-point">
+ <term>
+ <guilabel>Ignore LDAP CRL Distribution Point of certificates</guilabel>
+ </term>
+ <listitem>
+ <para>
+ When looking for the location of a <acronym>CRL</acronym>,
+ the <quote>"to-be-tested"</quote> certificate usually contains
+ what are known as CRL Distribution Point (<acronym>DP</acronym>) entries,
+ which are <acronym>URLs</acronym> describing the way to access
+ the <acronym>URL</acronym>.
+ The first found <acronym>DP</acronym> entry is used.
+ With this option all entries using the <acronym>LDAP</acronym>
+ scheme are ignored when looking for a suitable
+ <acronym>DP</acronym>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="configure-smime-certificate-ldap-proxy-host">
+ <term>
+ <guilabel>Primary host for LDAP requests</guilabel>
+ </term>
+ <listitem>
+ <para>
+ Entering a <acronym>LDAP</acronym> server here will make all
+ <acronym>LDAP</acronym> requests go to that server first.
+ More precisely, this setting overrides any specified host
+ and port part in a <acronym>LDAP URL</acronym> and will also
+ be used if host and port have been omitted from the
+ <acronym>URL</acronym>. Other <acronym>LDAP</acronym> servers
+ will be used only if the connection to the
+ <emphasis>proxy</emphasis> failed.
+ The syntax is <acronym>HOST</acronym> or
+ <acronym>HOST:PORT</acronym>. If <acronym>PORT</acronym> is
+ omitted, <quote>port 389</quote>
+ (standard <acronym>LDAP</acronym> port) is used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2 id="configure-security-crypto-backends">
+ <title>
+ Crypto Backends
+ </title>
+
+ <para>
+ On this tab you can configure which crypto backends are to be
+ used for &openpgp; and &smime; cryptographic operations (such
+ as signing and encrypting).
+ </para>
+
+ <para>
+ On the right-hand side, you see a list of available
+ backends. Below each backend entry, you can see what protocols
+ (&openpgp; and/or &smime;) the backend supports. If a protocol
+ is not listed, the backend does not support it. If it is
+ listed, but greyed out, the backend supports the protocol, but
+ some required programs were not found, or other errors
+ occurred during initialization. If you press
+ <guibutton>Rescan</guibutton>, a dialog box will appear that
+ lists reasons for the initialization failure.
+ </para>
+
+ <para id="configure-security-crypto-backends-configure">
+ To configure a backend, select it in the list of available
+ backends and press <guibutton>Configure...</guibutton>. The
+ per-backend configuration dialog is dynamically created from
+ the information returned by the backend. It may therefore
+ change if you update the backend applications, although
+ &kmail; itself is unchanged. If the
+ <guibutton>Configure...</guibutton> button is disabled, the
+ backend does not support a backend configuration dialog.
+ </para>
+
+ <para>
+ Please refer to the manuals of the applications underlying
+ each backend for a description of the options presented in the
+ backend configuration dialogs.
+ </para>
+
+ <para>
+ In front of each backend's protocol entries, you can see a
+ checkbox, with which you select which backend is to be used
+ for a given protocol. These checkboxes are exclusive per
+ protocol, meaning that if you select a backend to perform
+ &openpgp; operations, any previously selected &openpgp;
+ implementation will be unselected, but the &smime; backend
+ selection will be unchanged. If no backend is selected for a
+ given protocol, that protocol is effectively disabled for use
+ in &kmail;.
+ </para>
+
+ </sect2>
+
+ </sect1> <!-- configure-security -->
+
+<sect1 id="configure-misc">
+<title>Misc Page</title>
+
+<sect2 id="configure-misc-folders">
+<title>Folders</title>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Ask for confirmation before moving all messages to trash</guilabel></term>
+<listitem>
+<para>Enable this option if you want to be asked for confirmation whenever
+you use <menuchoice><guimenu>Folder</guimenu><guimenuitem>Move All Messages to Trash</guimenuitem></menuchoice>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Exclude important messages from expiry</guilabel></term>
+<listitem>
+<para>Enable this option if important messages should never be deleted
+during message expiration, &ie; during automatic deletion of old
+messages.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="configure-misc-folders-go-unread">
+<term><guilabel>When trying to find unread messages</guilabel></term>
+<listitem>
+<para>This option controls what happens if you press one of the shortcuts to
+go to the next or previous unread message (&eg; <keycap>Space</keycap>).
+If you ask &kmail; to go to the next unread message although there is no
+unread message below the currently selected message then the following happens:
+<itemizedlist>
+<listitem>
+<para>If <guilabel>Do not Loop</guilabel> is selected then nothing will happen.
+</para>
+</listitem>
+<listitem>
+<para>If <guilabel>Loop in Current Folder</guilabel> is selected then &kmail;
+will search from the beginning of the current folder for an unread message. If
+none is found then nothing happens.</para>
+</listitem>
+<listitem>
+<para>If <guilabel>Loop in All Folders</guilabel> is selected then &kmail;
+will first search in the current folder for another unread message. If none
+is found then &kmail; will search the next folder containing unread messages.
+</para>
+</listitem>
+</itemizedlist>
+Correspondingly, if you ask &kmail; to go to the previous unread message.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Jump to first unread message when entering a folder</guilabel></term>
+<listitem>
+<para>If this option is enabled &kmail; will go to the first unread message
+when you enter a folder; if it is not enabled, &kmail; will go to first
+new message or, if there is no new message, to the message
+that was selected when you last left the folder.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Mark selected message as read after...</guilabel></term>
+<listitem>
+<para>When you select a <guilabel>new</guilabel> or
+<guilabel>unread</guilabel> message, &kmail; will change the
+message's status to <guilabel>read</guilabel> after the number of seconds
+entered here. If you disable this option, messages will keep their
+<guilabel>new</guilabel> or <guilabel>unread</guilabel> status.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Ask for action after dragging messages to another folder</guilabel></term>
+<listitem>
+<para>When you drag a message to a different folder, a small popup will ask
+you if you want to move or copy the message. If you disable this option,
+the message will be moved immediately, without a popup.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>By default, message folders on disk are...</guilabel></term>
+<listitem>
+<para>Here you can set the default <link linkend="folders-format">folder format</link>
+that is used when you create a new folder.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Open this folder on startup</guilabel></term>
+<listitem>
+<para>Here you can set the folder that should be selected by default if you
+start &kmail;. If you use only &imap; folders then you might want to set
+this to your &imap; inbox folder. If you do that, you can collapse the local
+folders in the folder list, and then they will stay collapsed when &kmail;
+starts.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Empty trash on program exit</guilabel></term>
+<listitem>
+<para>The trash folder is cleared of messages when you quit &kmail; if this
+option is selected.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2 id="configure-misc-groupware">
+<title>Groupware</title>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Enable IMAP resource functionality</guilabel></term>
+<listitem>
+<para>Makes it possible to store the entries from the Kontact applications (KOrganizer, KAddressBook and KNotes). This option has to be set whenever you are configuring Kontact as a <guilabel>KDE Kolab client</guilabel>. This option being enabled you will also need to add the appropriate resources from the <guilabel>KDE Control Center</guilabel> (kcontrol) in the <guilabel>KDE Resources Configuration</guilabel> section. <guilabel>Kolab</guilabel> resources have to be added in case the resource functionality applies to a <guilabel>KDE Kolab client</guilabel> set-up.</para>
+</listitem>
+</varlistentry>
+<varlistentry id="configure-misc-format-groupware-folders">
+<term><guilabel>Format used for the groupware folders</guilabel></term>
+<listitem>
+<para>Choose the storage format for the groupware folders</para>
+<itemizedlist>
+<listitem>
+<para>Default format is <guilabel>Standard (Ical/Vcard)</guilabel> for calendar folders (Ical) and addressbook folders (Vcard). This makes all Kontact features available.</para>
+</listitem>
+<listitem>
+<para><guilabel>Kolab</guilabel> users should choose <guilabel>Kolab XML</guilabel>. This format uses a custom model that matches more closely to the one used in Microsoft Outlook(tm) and gives better compatibility.</para>
+</listitem>
+</itemizedlist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Language of the groupware folders</guilabel></term>
+<listitem>
+<para>Choose between the available languages to set the folder names of the <guilabel>IMAP</guilabel> storage to your local language. Note that this option is only aimed for compatibility with Microsoft Outlook(tm). It is not recommended to change its default unless you have to, since it makes changing languages impossible.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Resource folders are in account</guilabel></term>
+<listitem>
+<para>Select the parent of the <guilabel>IMAP</guilabel> resource folders. You should select the name of your <guilabel>IMAP/DIMAP</guilabel> account. By default the <guilabel>Kolab</guilabel> server sets the <guilabel>IMAP</guilabel> inbox to be the parent.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Hide groupware folders</guilabel></term>
+<listitem>
+<para>You should not need to see the folders that hold the <guilabel>IMAP</guilabel> resources. However if you want to see them, you can set that by enabling this option.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Mangle From:/To: headers in replies to invitations</guilabel></term>
+<listitem>
+<para>Enable this option to make Microsoft Outlook(tm) understand your answers to invitations replies.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Send invitations in the mail body</guilabel></term>
+<listitem>
+<para>Invitations use to be send as attachments to a mail. By enabling this option, you let the invitation mails to be sent in the text of the mail, which is necessary to send invitations and replies to Microsoft Outlook(tm).</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="configure-non-gui-options">
+<title>Options without a user interface representation</title>
+<para>
+Apart from the options presented in the configuration dialog, some options
+can only be set directly in the configuration file ($KDEHOME/share/config/kmailrc)
+or through KIOSK.
+</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guilabel>Send Message Distribution Notifications with an empty sender string (SendMDNsWithEmptySender)</guilabel></term>
+<listitem>
+<para>
+Send Message Disposition Notifications with an empty sender string. Some servers might be configured to reject
+such messages, so if you are experiencing problems sending MDNs, make sure this option is set to false. To
+enable this feature, add a line reading:
+
+SendMDNsWithEmptySender=true
+
+to the [MDN] section of the kmail configuration file. If there is no such section, simply add "[MDN]" on
+a line by itself just above the option.
+
+Note that the default setting of "false" strictly speaking violates internet standards, but is
+set that way for practical reasons, to avoid servers rejecting MDNs that KMail generates because they
+think they are SPAM.
+</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Allow Semicolon As EMail Address Separator (AllowSemicolonAsAddressSeparator)</guilabel></term>
+<listitem>
+<para>
+In RFC2822, the comma (,) is the only allowed separator for email addresses in fields like To, CC and BCC. This option allows to also use the semi-colon (;) as separator. This only affects the user interface, the created messages still use commas only and thus do no violate the standard.
+
+The option is enabled by default. To disable the feature, add a line reading (under [Composer] section):
+</para>
+<programlisting>AllowSemicolonAsAddressSeparator=false
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>ForwardingInlineByDefault</guilabel></term>
+<listitem>
+<para>
+This option allows you to make inline forwarding the default forwarding method instead
+of forwarding as attachement.
+
+To enable the feature, add a line reading (under [Composer] section):
+</para>
+<programlisting>ForwardingInlineByDefault=true
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>MaximumAttachmentSize</guilabel></term>
+<listitem>
+<para>
+This allows the maximum file size allowed for attachments in the mail
+composer to be limited.
+
+To limit attachments to 20 MB ins size, for example, add a line reading (under [Composer] section):
+</para>
+<programlisting>MaximumAttachmentSize=20
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>CloseDespiteSystemTray</guilabel></term>
+<listitem>
+<para>
+This option allows you to configure the application to close fully, even if there
+is a system tray icon configured, which would normally keep the application running.
+
+To enable the feature, add a line reading (under [General] section):
+</para>
+<programlisting>CloseDespiteSystemTray=true
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>CheckOutOfOfficeOnStartup</guilabel></term>
+<listitem>
+<para>
+With this option enabled, KMail will check on every startup if there is an
+active out-of-office configured and show a warning if this is the case.
+
+To disable the feature, add a line reading (under [OutOfOffice] section):
+</para>
+<programlisting>CheckOutOfOfficeOnStartup=false
+</programlisting>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><guilabel>disregardUmask</guilabel></term>
+<listitem>
+<para>
+This option allows you to disregard the users umask setting and use "read-write for the user only".
+
+To enable the feature, add a line reading (under [General] section):
+</para>
+<programlisting>disregardUmask=false
+</programlisting>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>AutoLostFoundMove</guilabel></term>
+<listitem><para>Activate this option to automate the handling of not yet uploaded messages in disconnected IMAP
+folders that can not be uploaded. This can happen if the folder was removed from the server or your access
+rights have been restricted. Such messages will automatically moved to a newly created lost+found folder if
+this option is enabled, you will be ask how to proceed everytime otherwise.
+
+To enable the feature, add a line reading:
+</para>
+<programlisting>AutoLostFoundMove=true</programlisting>
+<para>to the [Behaviour] section of the configuration file </para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+
+</sect1>
+
+</chapter>
diff --git a/doc/kmail/credits-and-licenses.docbook b/doc/kmail/credits-and-licenses.docbook
new file mode 100644
index 00000000..ec986f5c
--- /dev/null
+++ b/doc/kmail/credits-and-licenses.docbook
@@ -0,0 +1,153 @@
+<chapter id="credits-and-licenses">
+
+<chapterinfo>
+<authorgroup>
+<author>
+<firstname>Daniel</firstname>
+<surname>Naber</surname>
+<affiliation><address>
+<email>daniel.naber@t-online.de</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>David</firstname>
+<surname>Rugge</surname>
+<affiliation><address>
+<email>davidrugge@mediaone.net</email>
+</address></affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+<date>2004-07-13</date>
+<releaseinfo>1.7</releaseinfo>
+</chapterinfo>
+
+<title>Credits and Licenses</title>
+
+<para>&kmail;: Copyright the &kmail; developers, 1997-2004</para>
+
+&underGPL;
+&underFDL;
+
+<sect1 id="team">
+<title>Development Team</title>
+<!-- please keep in sync with the authors list on the webpage -->
+
+<!-- don't modify manually, this list is generated: -->
+<itemizedlist>
+<listitem><para>Ingo Kl&ouml;cker (kloecker at kde org): Maintainer</para></listitem>
+<listitem><para>Don Sanders (sanders at kde org): Adopter and co-maintainer</para></listitem>
+<listitem><para>Stefan Taferner (taferner at kde org): Original author</para></listitem>
+<listitem><para>Michael H&auml;ckel (haeckel at kde org): Former maintainer</para></listitem>
+<listitem><para>Till Adam (till at adam-lilienthal de): Core developer</para></listitem>
+<listitem><para>Carsten Burghardt (burghardt at kde org): Core developer</para></listitem>
+<listitem><para>Marc Mutz (mutz at kde org): Core developer</para></listitem>
+<listitem><para>Daniel Naber (daniel naber at t-online de): Documentation</para></listitem>
+<listitem><para>Zack Rusin (zack at kde org): Core developer</para></listitem>
+<listitem><para>Toyohiro Asukai (toyohiro at ksmplus com)</para></listitem>
+<listitem><para>Waldo Bastian (bastian at kde org)</para></listitem>
+<listitem><para>Ryan Breen (ryan at ryanbreen com): system tray notification</para></listitem>
+<listitem><para>Steven Brown (swbrown at ucsd edu)</para></listitem>
+<listitem><para>Matthias Kalle Dalheimer (kalle at kde org)</para></listitem>
+<listitem><para>Cristi Dumitrescu (cristid at chip ro)</para></listitem>
+<listitem><para>David Faure (faure at kde org)</para></listitem>
+<listitem><para>Philippe Fremy (pfremy at chez com)</para></listitem>
+<listitem><para>Kurt Granroth (granroth at kde org)</para></listitem>
+<listitem><para>Andreas Gungl (a gungl at gmx de): PGP 6 support and further enhancements of the encryption support</para></listitem>
+<listitem><para>Steffen Hansen (hansen at kde org)</para></listitem>
+<listitem><para>Igor Janssen (rm at linux ru net)</para></listitem>
+<listitem><para>Matt Johnston (matt at caifex org)</para></listitem>
+<listitem><para>Christer Kaivo-oja (whizkid at telia com)</para></listitem>
+<listitem><para>Lars Knoll (knoll at kde org): Original encryption support, PGP 2 and PGP 5 support</para></listitem>
+<listitem><para>J. Nick Koston (bdraco at darkorb net): GnuPG support</para></listitem>
+<listitem><para>Stephan Kulow (coolo at kde org)</para></listitem>
+<listitem><para>Guillaume Laurent (glaurent at telegraph-road org)</para></listitem>
+<listitem><para>Sam Magnuson (sam at trolltech com)</para></listitem>
+<listitem><para>Laurent Montel (lmontel at mandrakesoft com)</para></listitem>
+<listitem><para>Matt Newell (newellm at proaxis com)</para></listitem>
+<listitem><para>Denis Perchine (dyp at perchine com)</para></listitem>
+<listitem><para>Samuel Penn (sam at bifrost demon co uk)</para></listitem>
+<listitem><para>Carsten Pfeiffer (pfeiffer at kde org)</para></listitem>
+<listitem><para>Sven Radej (radej at kde org)</para></listitem>
+<listitem><para>Mark Roberts (mark at taurine demon co uk)</para></listitem>
+<listitem><para>Wolfgang Rohdewald (wrohdewald at dplanet ch)</para></listitem>
+<listitem><para>Espen Sand (espen at kde org)</para></listitem>
+<listitem><para>Aaron J. Seigo (aseigo at olympusproject org)</para></listitem>
+<listitem><para>George Staikos (staikos at kde org)</para></listitem>
+<listitem><para>Jason Stephenson (panda at mis net)</para></listitem>
+<listitem><para>Jacek Stolarczyk (jacek at mer chemia polsl gliwice pl)</para></listitem>
+<listitem><para>Roberto S. Teixeira (maragato at kde org)</para></listitem>
+<listitem><para>Bo Thorsen (bo at sonofthor dk)</para></listitem>
+<listitem><para>Ronen Tzur (rtzur at shani net)</para></listitem>
+<listitem><para>Mario Weilguni (mweilguni at sime com)</para></listitem>
+<listitem><para>Wynn Wilkes (wynnw at calderasystems com)</para></listitem>
+<listitem><para>Robert D. Williams (rwilliams at kde org)</para></listitem>
+<listitem><para>Markus W&uuml;bben (markus wuebben at kde org)</para></listitem>
+<listitem><para>Karl-Heinz Zimmer (khz at kde org)</para></listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="credits">
+<title>Credits</title>
+
+<itemizedlist>
+<listitem><para>Heiko Hund (heiko at ist eigentlich net): POP filters</para></listitem>
+<listitem><para>Bernhard Reiter (bernhard at intevation de): &Auml;gypten and Kroupware project management</para></listitem>
+<listitem><para>Jan Simonson (jan at simonson pp se): beta testing of PGP 6 support</para></listitem>
+<listitem><para>Patrick S. Vogt (patrick vogt at unibas ch): timestamp for 'Transmission completed' status messages</para></listitem>
+<listitem><para>Jan-Oliver Wagner (jan at intevation de): &Auml;gypten and Kroupware project management</para></listitem>
+<listitem><para>Wolfgang Westphal (wolfgang westphal at gmx de): multiple encryption keys per address</para></listitem>
+<listitem><para>Thorsten Zachmann (t zachmann at zagge de): POP filters</para></listitem>
+</itemizedlist>
+
+</sect1>
+
+<sect1 id="documentation">
+<title>Documentation</title>
+
+<para>Update for &kmail; 1.7 by
+Ingo Kl&ouml;cker <email>kloecker@kde.de</email> and
+Marc Mutz <email>mutz@kde.org</email>,
+Anti-Spam Wizard chapter by Andreas Gungl <email>a.gungl@gmx.de</email>,
+section about filter log by Andreas Gungl <email>a.gungl@gmx.de</email> and
+Brad Hards <email>bradh@frogmouth.net</email>,
+additional changes by Daniel Naber <email>daniel.naber@t-online.de</email>.</para>
+
+<para>Update for &kmail; 1.2 to 1.5 by Daniel Naber
+<email>daniel.naber@t-online.de</email>,
+<application>OpenPGP</application> chapter by Andreas Gungl
+<email>a.gungl@gmx.de</email> and Ingo Kl&ouml;cker <email>kloecker@kde.de</email>,
+message filter chapter by Marc Mutz
+<email>mutz@kde.org</email>, download filter chapter by Thorsten
+Zachmann <email>T.Zachmann@zagge.de</email>. Other parts have been
+contributed by various &kmail; developers.</para>
+
+<para>&kmail; 1.0
+documentation by David Rugge <email>davidrugge@mediaone.net</email>.
+Original documentation by Markus Wuebben
+<email>markus.wuebben@kde.org</email>, Robert Williams
+<email>rwilliams@kde.org</email> (Editor).</para>
+
+<para>Thanks to Michael Elkins <email>me@cs.hmc.edu</email> for his excellent
+description of the different &UNIX; mail formats in the <application>Mutt</application>
+documentation.</para>
+
+<para>Thanks to the following people for providing directions on using other
+email client mailboxes with &kmail;:</para>
+
+<itemizedlist>
+<listitem><para>Nik Gaffney <email>nik@f0.am</email>
+(<application>Mailsmith</application>)</para></listitem>
+<listitem><para>David McMillen <email>mcmillen@math.bu.edu</email> and
+Mendel Mobach <email>mendel@mobach.nl</email> (&Netscape; mail)</para></listitem>
+<listitem><para>Ed Shapard <email>shapard@bigfoot.com</email>
+(<application>Pegasus</application> Mail)</para></listitem>
+<listitem><para>Ray Muir <email>rjmuir@ibm.net</email> (Forte
+<application>Agent</application>)</para></listitem>
+</itemizedlist>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+</sect1>
+</chapter>
diff --git a/doc/kmail/faq.docbook b/doc/kmail/faq.docbook
new file mode 100644
index 00000000..f7ef1e68
--- /dev/null
+++ b/doc/kmail/faq.docbook
@@ -0,0 +1,590 @@
+<chapter id="faq">
+
+<chapterinfo>
+<authorgroup>
+<author>
+<firstname>Daniel</firstname>
+<surname>Naber</surname>
+<affiliation><address>
+<email>daniel.naber@t-online.de</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>David</firstname>
+<surname>Rugge</surname>
+<affiliation><address>
+<email>davidrugge@mediaone.net</email>
+</address></affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+<date>2004-07-14</date>
+<releaseinfo>1.7</releaseinfo>
+</chapterinfo>
+
+<title>Frequently Asked Questions (&FAQ;)</title>
+<!-- TODO: split into categories? unfortunately this will produce several files, eg. with <section> -->
+
+<qandaset id="faq-set">
+
+<!-- fixme: how to use old kmail mail data: copy files from
+~/Mail (incl. hidden ones) to the new ~/Mail folder -->
+
+<qandaentry>
+<question><para>Why are my filters not applied to incoming messages of &imap; accounts?</para></question>
+<answer>
+<para>Normal &imap; mode does not support filtering, but the new
+disconnected &imap; account type does. You could try to use server-side
+filtering (ask your admin for how to install filters on the server and in
+which format), since &imap; is all about managing your email <emphasis>on the server</emphasis>.
+Unfortunately, although there exists a mail filter language (Sieve, defined
+in RFC3028), there is no standardized access protocol for installing or
+editing server-side Sieve scripts. If such a protocol becomes available in
+the future, &kmail; will most probably include support for it.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Using <application>PGP</application> or <application>GnuPG</application>
+is very slow or it blocks &kmail;.</para></question>
+<answer>
+<para>&kmail; accesses <application>PGP</application>/<application>GnuPG</application>
+synchronously, &ie; it blocks while <application>PGP</application>/<application>GnuPG</application>
+works. This means that you might want to disable automatic retrieval
+of unknown keys from a keyserver to make &kmail; look more responsive.
+If you are using <application>GnuPG</application> 1.0.7 (or better) or upgraded from an earlier
+version, then make sure to run <command>gpg <option>--rebuild-keydb-caches</option></command>
+once and <command>gpg <option>--check-trustdb</option></command> after every import or refresh.
+Both will speed up <application>GnuPG</application> immensely.</para>
+</answer>
+</qandaentry>
+
+<qandaentry id="pgp-faq">
+<question><para>What should I know if I want to use
+<application>PGP</application>/<application>GnuPG</application> with
+&kmail;?</para></question>
+
+<answer><para>&kmail; provides a simple and easy-to-use interface for the basic
+ functions of these programs; still you should understand how these programs
+ work and what might make their use insecure. Some important issues:</para>
+
+<itemizedlist>
+<listitem>
+<para>You <emphasis>really</emphasis> should test if encryption works
+before you use it. &kmail; partly relies on
+<application>PGP</application>/<application>GnuPG</application>'s error strings,
+which often change between different versions.</para>
+</listitem>
+<listitem>
+<para>&kmail; will not encrypt messages with an untrusted (unsigned) public key: if you want to encrypt to such a
+key you should check the identity of the key owner and only then sign the key
+with your secret key; if you do not want to or cannot check the identity
+of the key owner but nevertheless want to encrypt the message then
+please sign the key locally with <userinput><command>gpg</command>
+<option>--lsign</option> <replaceable>keyID</replaceable></userinput>.</para>
+</listitem>
+<listitem>
+<para>Trusting a foreign public key without checking it is not a good idea.</para>
+</listitem>
+<listitem>
+<para>&kmail; cannot encrypt and sign attachments if you are using
+the built-in OpenPGP support. For encrypted and signed attachments you need
+to have <link linkend="configure-security-crypto-backends">crypto
+plugins</link> installed and configured.</para>
+</listitem>
+<listitem>
+<para>Starting with GnuPG 1.0.7 you have to set your own key to
+ultimate ownertrust: it is no longer implicitly done for you.</para>
+</listitem>
+</itemizedlist>
+</answer>
+</qandaentry>
+
+<qandaentry> <question><para>Where does &kmail; save my settings and my
+mail?</para></question> <answer> <para>Most &kmail; settings are stored in
+<filename>$<envar>KDEHOME</envar>/share/config/kmailrc</filename>, where
+$<envar>KDEHOME</envar> is typically <filename
+class="directory">~/.kde</filename>; the identities are stored in
+<filename>$<envar>KDEHOME</envar>/share/config/emailidentities</filename>
+and your mail is saved in <filename
+class="directory">$<envar>KDEHOME</envar>/share/apps/kmail</filename> (or
+<filename class="directory">~/Mail</filename> if you upgraded from a
+previous &kmail; version that used this location.) Note that some of the
+files are hidden: remember to also copy those if you want to backup or
+archive your mails.</para> </answer> </qandaentry>
+
+<qandaentry id="faq-index-regeneration">
+<question><para>Why did &kmail; regenerate the index of a folder?</para></question>
+<answer>
+<para>&kmail; regenerates the index of a folder whenever the index appears to be
+out of date, &ie; whenever the contents of a folder are newer than the
+index. &kmail; regenerates the index in this case in order to prevent
+the loss or corruption of messages. Unfortunately, currently-deleted
+messages might reappear and message flags (like important, etc.) might
+be lost when the index is regenerated.</para>
+<para>An outdated index can have several causes; the two most important causes
+are:
+<itemizedlist>
+<listitem><para>Some other program modified the contents of the folder: if you want
+to use &kmail; together with procmail then please read <link
+ linkend="faq-procmail">this &FAQ;</link>. If you want to use &kmail; together with
+another email client then please read <link
+linkend="faq-other-muas">this &FAQ;</link>.</para></listitem>
+<listitem><para>If your mail folder (usually <filename class="directory">$<envar>KDEHOME</envar>/share/apps/kmail/</filename> or <filename class="directory">~/Mail</filename>)
+is on a volume which is mounted via NFS and if the clock of the NFS server is ahead of the
+clock of your computer then the NFS server sometimes reports a wrong
+file date for the index file. In this case &kmail; assumes that the index
+is outdated although in reality it is not. To fix this problem
+you (or your system administrator) have to make sure that the clock of
+the NFS server and the clock of your computer are always in sync. One
+way to achieve this is the use of the ntp daemon.</para></listitem>
+</itemizedlist>
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>I cannot add addresses to my address book after upgrading to KDE 3.x.</para></question>
+<answer>
+<para>You probably copied your old <filename>kmailrc</filename> file manually. That is not
+necessary, there is a script that will do such things when you run KDE 3.x
+for the first time. To fix the problem, remove the complete <quote>[AddressBook]</quote>
+group and the addressbook option in group <quote>[General]</quote> in your
+<filename>kmailrc</filename> file; however, chances are you will also encounter other problems
+that the config update script would have solved.</para>
+</answer>
+</qandaentry>
+
+<qandaentry id="faq-other-muas">
+<question><para>Can I use &kmail; together with a different email client, &eg;
+<application>mutt</application>?</para></question>
+<answer>
+<para>If you're using the mbox format for your folders it is not
+possible to use a different email client while &kmail; is running.
+With <application>mutt</application> there may also be problems
+even if both programs are not running at the same time. We recommend to
+use the maildir format in this case, this should solve all problems.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How can I convert my mailboxes from mbox to maildir?</para></question>
+<answer>
+<para>There is no automatic way to do that. You will have to create a new folder
+in maildir format and copy the messages from the mbox folder into this
+new folder. Remember to adapt any filter rules connected with the old folder before
+you delete it.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How can I use a browser other than &konqueror; to
+open links in messages?</para></question>
+<answer>
+<para>Change the <guilabel>File Associations</guilabel> for HTML files
+using &kcontrol;.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How can I remove attachments from messages without removing
+the message itself?</para></question>
+<answer>
+<para>This is currently not supported. As a workaround, move the
+message to the drafts folder, double click on it in order to open
+it in the composer, remove the attachments, save the message again to the
+drafts folder, move it back to its folder. The disadvantage of
+this workaround is that the date will be changed to the current date.
+Some other headers might also be changed.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How can I make &kmail; check for new messages at startup?</para></question>
+<answer>
+<para>If &kmail; should always check for new messages at startup then
+enable <guilabel>Check mail on startup</guilabel> on the
+<link linkend="configure-accounts-receiving">Accounts configuration page</link>.
+Otherwise start &kmail; with <command>kmail <option>--check</option></command>.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Why does &kmail; get slow / stop working when I try to
+send big attachments?</para></question>
+<answer>
+<!-- fixme: update for 3.2 -->
+<para>&kmail; is known to have problems with large attachments. We are working
+on a solution for this problem for &kde; 3.2 but currently it temporarily consumes
+virtual memory of about 10-15 times the size of the attachment. That
+means that if you attach a 2MB file &kmail; might temporarily need about
+20-30 MB of virtual memory (= RAM + swap space). If you do not have
+enough virtual memory this will lead to problems.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Where can I get a list of changes between the versions of &kmail;?</para></question>
+<answer>
+<para>The welcome screen lists all important changes for your version. It is displayed when you
+select <menuchoice><guimenu>Help</guimenu><guimenuitem>&kmail; Introduction</guimenuitem></menuchoice>.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Can I configure the location of my mail folder?</para></question>
+<answer>
+<para>Exit &kmail;, make a backup of <filename>~/.kde/share/config/kmailrc</filename>,
+then open it with an editor and add &eg; <userinput>folders=/home/username/.mail</userinput>
+to the <quote>[General]</quote> section. Then move all your existing folders (including
+the hidden index files) to the new location. The next time you start &kmail; will use
+<filename class="directory">/home/username/.mail</filename> instead of
+<filename class="directory">/home/username/.kde/share/apps/kmail</filename>. Note that &kmail;
+will lose its filters if you change the mail folder's location but forget
+to move your existing folders.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How can I use mail folders that are not in the normal &kmail; message folder location?</para></question>
+
+<answer><para>To add a whole mbox mail folder use
+<userinput><command>ln</command> <option>-s</option>
+<filename>/somewhere/Mail/.remotedir.directory</filename> <filename
+class="symlink">/home/username/share/apps/kmail/.mymailboxfile.directory</filename></userinput>.
+Note that it is not possible to use links to files, only links that point
+to folders will work.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>I'm one of those people whose mails consist of 100 quoted lines
+and one line written by myself. For some reason this annoys other people. Can
+&kmail; help me and make everyone's life better?</para></question>
+<answer><para>Sure. Just select a short relevant part of the original mail
+with the mouse before you reply. Only this part will then be quoted in your
+reply.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>For some messages the value in the <guilabel>Date</guilabel> field
+is <guilabel>unknown</guilabel> or it is not correct.</para></question>
+<answer><para>Probably the <quote>Date:</quote> header of these messages is
+broken and &kmail; cannot interpret it. That is not a bug in &kmail;
+but in the software that sent the mail.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>My signature has two dashes above it. What's up?</para></question>
+<answer>
+<para>
+Separating the signature from the message body with two dashes and a space
+on a single line is common usage. These symbols permit mail clients who recognize
+them to trim the signatures from a reply. If your signature does not already have
+this separator, &kmail; will automatically add it.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>&kmail; fetches the same messages over and over again.</para></question>
+<answer><para>This happens if you have enabled
+<guilabel>Leave fetched messages on the server</guilabel>
+and your POP3 server does not support the UIDL command. There is currently
+no workaround besides disabling
+<guilabel>Leave fetched messages on the server</guilabel>.
+A more detailed explanation can be found
+<ulink url="http://lists.kde.org/?l=kmail&amp;m=99220697415300&amp;w=2">in this
+mailing list post</ulink>.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Are there any known bugs in &kmail;?</para></question>
+<answer>
+<para>A list of submitted bugs is linked at <ulink
+url="http://kmail.kde.org/">the &kmail; homepage</ulink>. Note that not all
+these bugs are valid. All in all we think that &kmail; is a very robust piece
+of software.</para>
+<para><warning><para>However, you should not run &kmail; while another email client is already
+accessing the files in <filename class="directory">~/Mail</filename>; if you try to do so,
+you might lose messages. Note that you should make backups of your messages anyway.</para></warning></para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>&kmail; does not display <acronym>HTML</acronym> mail properly.</para></question>
+<answer><para>References to external content like images, are disabled by
+default, as they can be used to track whether and when you read a message.
+Loading external references can be activated in the <guilabel>Security</guilabel>
+tab in &kmail;'s configuration dialog; also Plugins (like <trademark
+class="registered">Macromedia</trademark> <application>Flash</application>),
+&Java; and JavaScript will not be displayed in &kmail; for security reasons
+and there is no way to activate them.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Can I use two different versions of &kmail; at the same time? Can I go
+back from a current version of &kmail; to an older one?</para></question>
+<answer><para>You can only run one instance of &kmail; at once. We also recommend
+to stick to a certain version and not switch back and forth between different versions.
+Downgrading to an older version will probably cause problems, &eg; because the index file
+formats might have changed. Upgrading should never be a problem.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Does &kmail; support uuencoded files?</para></question>
+<answer><para>Uuencoded attachments are supported, but inline uuencoded files are not.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>&kmail; crashed while I was writing a mail; is that mail is lost now?</para></question>
+<answer><para>&kmail; tries to save your mail to
+<filename>~/dead.letter</filename> in case of a crash. The next time you start
+&kmail; the mail composer should appear with your mail again; If it does not,
+try to open <filename>~/dead.letter</filename> with an editor. If it does not
+exist then the crash was so bad that &kmail; could not save your mail.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>When I try to set a folder to be mailing list-aware, it does not do
+anything when receiving an email from the list.</para></question>
+<answer><para>Associating a folder with a mailing list has nothing to do with
+filtering the mailing list messages &mdash; you have to add a new filter rule manually; however, once you associated a folder with a mailing list you can use <menuchoice>
+<guimenu>Message</guimenu><guimenuitem>Reply to Mailing-List...</guimenuitem></menuchoice> or
+<menuchoice><guimenu>Message</guimenu><guimenuitem>New Message to Mailing-List...</guimenuitem></menuchoice>
+and the mailing list address will be set in the <guilabel>To:</guilabel> field.
+</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>My SMTP server requires authentication; Does &kmail; support this?</para></question>
+<answer><para>There are two common techniques used for <acronym>SMTP</acronym> authentication:
+<quote>SMTP after POP3</quote> and <quote>SMTP Auth</quote>.
+<quote>SMTP Auth</quote> can be set in the <guilabel>General</guilabel> tab
+of the SMTP configuration dialog.
+To use <quote>SMTP after POP3</quote> you have to collect all your messages in the
+<guilabel>outbox</guilabel> and send them just after you have fetched new mail.
+You can make &kmail; send the queued messages automatically with the
+<guilabel>Send messages in outbox folder</guilabel> option on the
+<link linkend="configure-accounts-sending">Accounts configuration page</link>.
+</para></answer>
+</qandaentry>
+
+<qandaentry id="faq-procmail">
+<question><para>Can I use &kmail; and <application>procmail</application>?</para></question>
+<answer><para>Yes, but it is important to do it the right way or you might lose
+mail. In order to use <application>procmail</application> and &kmail; you need
+to set up &kmail; so that it will fetch new
+mail from the spoolfiles in which <application>procmail</application>
+drops your mail. Do <emphasis>not</emphasis> set up procmail to deliver
+mail in a &kmail; folder, this cannot work.</para>
+
+<para>For each procmail spoolfile you then need to create an account
+from which &kmail; will fetch new mail; you also need to make sure you
+specify the right lockfile name for this account. When setting up an
+account, &kmail; will do some minimal parsing on your
+<filename>.procmail</filename> file, and will try to list every
+spoolfile it has found, and also the lockfiles next to the
+<guilabel>procmail lockfile</guilabel> item. procmail lets the user
+specify lockfiles in three different ways, so there is no way to
+establish a correspondence between the spoolfiles and lockfiles; so it's
+really up to you to make sure you specify the right lockfile for each
+spoolfile.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Spellchecking does not recognize non-English
+characters.</para></question>
+<answer><para>Before you can use spellchecking the first time, you have to
+configure it. You can do so in the composer window's menu
+under <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Spellchecker...</guimenuitem></menuchoice>. You can set
+the dictionary and the encoding there.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How do I use my
+<application>Eudora</application>/&Netscape;/<application>Outlook</application>/...
+mail folders in &kmail;?</para></question>
+<answer><para>See the section <link linkend="importing">Using other Mailbox
+files With &kmail;</link>.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>Can I use encryption with my normal (non-<acronym>SSL</acronym>)
+POP3 account?</para></question>
+<answer><para>If your POP3 server runs an
+<application>ssh</application> daemon, you can use ssh to tunnel your
+POP3 connection using the following command:</para>
+
+<para><userinput><command>ssh</command> <option>-L 11000:127.0.0.1:110
+user@host</option></userinput></para>
+
+<para>Modify your &kmail; configuration to fetch the mail via
+POP3 from <userinput>localhost</userinput> and ssh will tunnel
+the connection for you.
+
+<note><para>If non-encrypted messages have already been sent
+via Internet, the only advantage of using <application>ssh</application> is
+that your <emphasis>password</emphasis> will be sent encrypted to the POP3
+server.</para></note>
+
+<!-- fixme: add link to http://www.linuxdoc.org/HOWTO/mini/Secure-POP+SSH.html -->
+
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry id="faq-file-locking">
+<question><para>Does &kmail; lock the folders it uses?</para></question>
+<answer><para>&kmail; does not lock the files in <filename
+class="directory">~/Mail</filename>.</para>
+<para>To avoid the risk of losing mail <emphasis>if using a local
+account</emphasis> it is necessary to ensure that &kmail; uses the same type of
+locking as your mail delivery agent.</para>
+
+<para>There are five different locking options you can use:</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Procmail lockfile</guilabel></para></listitem>
+<listitem><para><guilabel>Mutt dotlock</guilabel></para></listitem>
+<listitem><para><guilabel>Mutt dotlock privileged</guilabel></para></listitem>
+<listitem><para><guilabel>FCNTL</guilabel> (default)</para></listitem>
+<listitem><para><guilabel>none (use with care)</guilabel></para></listitem>
+</itemizedlist>
+
+<para><guilabel>Procmail lockfile</guilabel> will use a small utility that comes
+with <application>procmail</application> called <command>lockfile</command>. You
+can use this if your mail folder is in a folder where you have write
+permission. This will not work on your <filename
+class="directory">/var/spool/mail/user</filename> file in most cases. It will
+create <filename>.lock</filename> files on your account when &kmail; is checking
+for new mail. Please note that this will only work if
+<application>procmail</application> is installed on your system.</para>
+
+<para><guilabel>Mutt dotlock</guilabel> and <guilabel>Mutt dotlock
+privileged</guilabel> will both use a small utility that comes with
+<application>mutt</application>
+called <command>mutt_dotlock</command>. <guilabel>Mutt dotlock</guilabel>
+can be used in the same way as the <guilabel>Procmail lockfile</guilabel>
+option, with the same limitation with regards to the <filename
+class="directory">/var/spool/mail/</filename> folders. However, the
+<guilabel>Mutt dotlock privileged</guilabel> option can create lock files
+in the <filename class="directory">/var/spool/mail</filename> folder.
+<command>mutt_dotlock</command> is a setgid program and this option will
+run it in setgid mode. Please note that these options will only work if
+<application>mutt</application> is installed on your system.</para>
+
+<para><guilabel>FCNTL</guilabel> will use the
+<function>fcntl()</function> system call.</para>
+
+<warning><para>Usage of FCNTL locking might cause system lockups when the mail
+spool file is on an NFS mounted device.</para></warning>
+
+<para>If you do not want to use any locking, the <guilabel>none</guilabel> option
+is what you want. However, there are risks of losing mail when no locking is
+used.</para>
+
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How do I leave messages on the server?</para></question>
+<answer><para>See the <link linkend="popfilters">Download filters</link> chapter.
+If you want to leave all messages on the server: open up the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kmail;...</guimenuitem>
+</menuchoice> window. Click on the <guilabel>Network</guilabel> page. Select your
+account from the account list and click the <guibutton>Modify...</guibutton>
+button. This dialog contains the <guilabel>Leave fetched messages on the server</guilabel>
+setting which you must enable.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How do I automatically insert a text footer within my
+messages?</para></question>
+<answer><para>The text footer is also called a signature (not to be confused
+with a cryptographic signature). Select
+<menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kmail;...</guimenuitem></menuchoice>
+Look in the <guilabel>Identity</guilabel> page for the <guilabel>Signature</guilabel>
+tab and add your signature there. Then go to the <guilabel>General</guilabel>
+tab on the <guilabel>Composer</guilabel> page and enable
+<xref linkend="configure-composer-general-append-signature"/></para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>How do I set up &Sendmail; to work with
+&kmail; if I have a dial-up connection?</para></question>
+
+<answer><para>First you should check if your distribution
+can do this for you. It probably has already been set up during
+installation.</para>
+
+<para>If that is not the case, you may want to have a look at <ulink
+url="http://en.tldp.org/HOWTO/mini/Mail-Queue.html">the Mail Queue
+HOWTO</ulink>.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>I've seen demonstrations of remote control behavior with &kmail;.
+Is there any documentation on the available interfaces?</para></question>
+<answer><para>You can get a list of functions by using this command in a shell:
+<userinput><command>dcop</command>
+<option>kmail KMailIface</option></userinput>. Some documentation is also
+available in <filename>kdenetwork/kmail/kmailIface.h</filename> and
+<filename>kdenetwork/kmail/mailcomposerIface.h</filename>.</para></answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>When I reply to a message, only a part of the message is quoted. How come?</para></question>
+<answer><para>This can happen when the message contains two dashes and a space on a single line. This is seen as the start of the signature. The remaining part of the message will not be quoted, because when you reply to a message KMail strips the signature.</para></answer>
+</qandaentry>
+
+
+<qandaentry>
+<question><para>I am only using &imap;, can I get rid of those Local Folders in
+the folder list or at least keep them collapsed all the time?</para></question>
+<answer><para>No you can not get rid of them. The local folders function as a
+fallback when the &imap; server is unreachable. Although you only use &imap;,
+&kmail; uses the outbox for sending the messages. If we hide all local folders
+you won't be able to fix messages in the outbox which can not be send for some
+reason. But it is possible to keep the local folders collapsed. What
+you have to do is go to <menuchoice><guimenu>Settings</guimenu><guimenuitem>
+Configure &kmail;...</guimenuitem></menuchoice> and go to the section Misc,
+there you can setup the folder on startup. If you change that to a folder on
+the &imap; account, the Local Folders will stay collapsed when &kmail; starts.
+</para></answer>
+</qandaentry>
+ <qandaentry id="faq-decrypt-on-read">
+ <!-- ideally, this should be in the documentation of the -->
+ <!-- reader window, but oops, there's no documentation of -->
+ <!-- the reader window >:-( (mmutz) -->
+ <question>
+ <para>
+ How do I enable permanent decryption of read messages?
+ </para>
+ </question>
+ <answer>
+ <para>
+ The global reversal of encryption is considered extremely
+ insecure. Shared access to messages for multiple persons
+ should be implemented using semantic solutions (&eg; by
+ defining roles like <quote>department
+ manager</quote>).
+ </para>
+ <para>
+ In case it is imperative to use it in the insecure mode, it
+ has to be manually enabled in the file
+ <filename>$KDEHOME/share/config/kmailrc</filename> by adding
+ the following directive in the <literal>[Reader]</literal>
+ group:
+ <programlisting>
+ store-displayed-messages-unencrypted=true
+ </programlisting>
+ </para>
+ </answer>
+ </qandaentry>
+
+
+</qandaset>
+
+</chapter>
diff --git a/doc/kmail/getting-started.docbook b/doc/kmail/getting-started.docbook
new file mode 100644
index 00000000..c70249e7
--- /dev/null
+++ b/doc/kmail/getting-started.docbook
@@ -0,0 +1,329 @@
+<chapter id="getting-started">
+
+<chapterinfo>
+<authorgroup>
+<author>
+<firstname>Daniel</firstname>
+<surname>Naber</surname>
+<affiliation><address>
+<email>daniel.naber@t-online.de</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>David</firstname>
+<surname>Rugge</surname>
+<affiliation><address>
+<email>davidrugge@mediaone.net</email>
+</address></affiliation>
+</author>
+<author>
+<firstname>Michel</firstname>
+<surname>Boyer de la Giroday</surname>
+<affiliation><address>
+<email>michel@klaralvdalens-datakonsult.se</email>
+</address></affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+<date>2004-07-13</date>
+<releaseinfo>1.7</releaseinfo>
+</chapterinfo>
+
+<title>Getting Started</title>
+
+<para>This is a short introduction to &kmail; and its usage so you can
+start working with it right away. For more in-depth information see the
+<link linkend="using-kmail">Using &kmail;</link> section. Note that
+&kmail;'s installation is described in <link linkend="installation">the
+appendix</link>.</para>
+
+<para>Invoking &kmail; for the first time creates a folder called
+<filename class="directory">Mail</filename> in your home folder.
+This folder contains the initial folders
+(<filename class="directory">inbox</filename>, <filename class="directory">outbox</filename>,
+<filename class="directory">sent-mail</filename>, <filename class="directory">trash</filename> and
+<filename class="directory">drafts</filename>). Use <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure
+&kmail;...</guimenuitem> </menuchoice> to enter some initial information
+so &kmail; will be able to properly retrieve and send your
+messages.</para>
+
+<para>The Configure window consists of six sections:
+<guilabel>Identities</guilabel>, <guilabel>Network</guilabel>,
+<guilabel>Appearance</guilabel>, <guilabel>Composer</guilabel>,
+<guilabel>Security</guilabel>, and
+<guilabel>Misc</guilabel>.</para>
+
+<para>To begin sending and receiving messages you will only have to
+change some settings in the <guilabel>Identities</guilabel> and
+<guilabel>Network</guilabel> pages.</para>
+
+ <sect1 id="setting-your-identity">
+ <title>
+ Setting your Identity
+ </title>
+
+ <para>
+ The settings in the <guilabel>Identities</guilabel> page are
+ fairly straightforward. Select your default identity and click
+ <guibutton>Modify</guibutton>. Fill in the <guilabel>Your
+ name</guilabel> field with your full name (&eg; <userinput>John
+ Doe</userinput>) and the <guilabel>Organization</guilabel> field
+ (optional) with the appropriate information.
+ </para>
+ <para>
+ Next, fill in the <guilabel>Email address</guilabel> field with
+ your email address (&eg; <userinput>john@example.net</userinput>).
+ </para>
+ <para>
+ If you are using <application>PGP</application> or
+ <application>GnuPG</application> you can set your &openpgp; keys
+ and/or &smime; certificates in the <link
+ linkend="configure-identity-cryptography"><guilabel>Cryptography</guilabel></link>
+ tab.
+ </para>
+ <para>
+ Optionally, go to the <guilabel>Signature</guilabel> tab and
+ enter your signature. This is a short text that will be
+ automatically appended to all your messages. It has nothing to
+ do with <emphasis>digital signatures</emphasis>.
+ </para>
+
+ </sect1>
+
+<sect1 id="setting-up-your-account">
+<title>Setting up your Account</title>
+
+<para>The <guilabel>Network</guilabel> page contains the settings that
+tell &kmail; how to send and receive your email messages. Many of these settings
+can vary greatly depending on the setup of your system and on the kind
+of network that your mail server is located in. If you do not know what
+setting to choose or what to put in a field, consult your Internet
+Service Provider (<acronym>ISP</acronym>) or system
+administrator.</para>
+
+<sect2 id="sending-mail">
+<title>Sending Messages</title>
+
+<para>The <guilabel>Sending</guilabel> tab provides a list of
+ways to send messages. The first item in the list is the default
+way to send messages. Using the <guibutton>Add...</guibutton>
+button you can choose between two different ways of sending messages:
+<guilabel>SMTP</guilabel> and
+<guilabel>Sendmail</guilabel>. &Sendmail; here
+means a local software installation -- this has a
+reputation of being difficult to set up, so if you do not already have a
+working &Sendmail; configuration, choose
+<guilabel>SMTP</guilabel> and fill in the <guilabel>Name</guilabel>
+field with a descriptive name
+(&eg; <userinput>My Mail Account</userinput>)
+and the <guilabel>Host</guilabel>
+field with the name and domain of your mail server
+(&eg; <userinput>smtp.provider.com</userinput>). You will probably
+not need to change the <guilabel>Port</guilabel> setting (the default is
+<userinput>25</userinput>).</para>
+
+<!-- TODO: more specific link -->
+<para>If you do want to use &Sendmail; and you are using a dial-up
+connection, follow the instructions for setting up sendmail for a
+dial-up connection in the <link linkend="faq">&FAQ;</link>
+section.</para>
+
+<para>The way of sending messages configured here will be used for
+your default identity and for all other identities that have no own
+way of sending messages. You can use different ways of sending
+messages for different identities by selecting the <guilabel>Special
+transport</guilabel> checkbox in the <guilabel>Advanced</guilabel>
+tab of the <guilabel>Identities</guilabel> section.</para>
+
+<para>A description of the other options can be found
+in the <link linkend="configure-accounts-sending">Configuration</link>
+chapter.</para>
+
+
+<sect3 id="sending-mail-kolab">
+<title>Options relevant to <acronym>Kolab</acronym> server</title>
+
+<para>When configuring a <guilabel>SMTP</guilabel> account with a <guilabel>Kolab</guilabel> server Host, you need to check the <guilabel>Server requires authentification</guilabel> option and to fill in your <guilabel>Kolab</guilabel> user's email address and password in the <guilabel>Login</guilabel> and <guilabel>Password</guilabel> fields. Select then the <guilabel>Security</guilabel> tab and click on the <guibutton>Check What the Server Supports</guibutton> for automated setup of your <guilabel>Security</guilabel> configuration. The default should be <guilabel>TLS/PLAIN</guilabel>. The <guilabel>Kolab</guilabel> server supports <guilabel>SSL/PLAIN</guilabel> as well. Those settings may of course be configured manually.</para>
+</sect3>
+</sect2>
+
+<sect2 id="receiving-mail">
+<title>Receiving Messages</title>
+
+<para>To set up an account so you can receive mail, press the
+<guibutton>Add...</guibutton> button in the <guilabel>Receiving</guilabel>
+tab. You will then be prompted for the type of your email account. Most users should
+select <guilabel>POP3</guilabel> or <guilabel>IMAP</guilabel>. If
+you want to use a local mailbox file, please see the <link linkend="faq-file-locking">FAQ
+about file locking</link>.</para>
+
+<para>You will then be presented with
+the <guilabel>Add account</guilabel> window. First, fill in the
+<guilabel>Name</guilabel> field to name your account. You can choose any name
+you like. <guilabel>Login</guilabel>, <guilabel>Password</guilabel>, and
+<guilabel>Host</guilabel> should be filled in with the appropriate information
+from your <acronym>ISP</acronym> or system administrator. You should not
+need to change the <guilabel>Port</guilabel> setting (the default for POP3 is
+<userinput>110</userinput>, the default for <acronym>IMAP</acronym> is
+<userinput>143</userinput>).</para>
+
+<sect3 id="receiving-mail-kolab">
+<title>Options relevant to <acronym>Kolab</acronym> server</title>
+<para>
+select <guilabel>Disconnected IMAP</guilabel> when choosing your <guilabel>Account Type</guilabel>. Fill in the <guilabel>Login</guilabel> and <guilabel>Password</guilabel> fields with respectively your user email address and password on the <guilabel>Kolab</guilabel> server. In the <guilabel>Security</guilabel> section click on the <guilabel>Check What the Server Support</guilabel> button for automated set-up of your <guilabel>Security</guilabel> configuration. The default should be <guilabel>TLS/PLAIN</guilabel>. The <guilabel>Kolab</guilabel> server supports <guilabel>SSL/PLAIN</guilabel> as well. Those settings may of course be configured manually.</para>
+<para>
+If you want to use the <guilabel>"Out of Office" Replies</guilabel> functionality of the <guilabel>Kolab</guilabel> server, set-up the <guilabel>Filtering</guilabel> section of you <guilabel>DIMAP</guilabel> account by checking the <guilabel>Server supports Sieve</guilabel> option as well as <guilabel>Reuse host and login configuration</guilabel>, <guilabel>Managesieve port</guilabel> should be set to 2000 as default.
+</para>
+</sect3>
+
+<sect3 id="receiving-mail-dimap-misc">
+<title>Options only relevant to DIMAP (<acronym>Kolab</acronym> server)</title>
+<para>
+After having configured your <guilabel>Disconnect IMAP</guilabel> account, you
+need to activate the <guilabel>Groupware</guilabel> functionalities and set-up
+the <guilabel>Misc</guilabel> page for <guilabel>KMail</guilabel>.
+</para>
+<para>
+In the <guilabel>Misc</guilabel> page, of the <guilabel>Configure</guilabel> dialog, choose the <guilabel>Groupware</guilabel> tab. Check the <guilabel>Enable IMAP resource functionality</guilabel> option and select <guilabel>Kolab (XML)</guilabel> as <guilabel>Format used for the groupware folders</guilabel>. The <guilabel>Resource folders are in account</guilabel> combo-box should be set on the <guilabel>Receiving</guilabel> (kolab user) account of your choice (if you happen to have several accounts).You may if you wish hide the groupware folder by checking this option. It is recommended to check both <guilabel>Groupware Compatibility and Legacy Options</guilabel> for compatibility with an eventual <guilabel>Kolab</guilabel> Microsoft Outlook client for sending invitations and replies from a <guilabel>Kolab</guilabel> KDE client.
+</para>
+</sect3>
+
+<sect3 id="receiving-mail-imap">
+<title>Options only relevant to <acronym>IMAP</acronym></title>
+<para>If you are using <acronym>IMAP</acronym>, you can optionally
+specify a path in the <guilabel>Prefix to folders</guilabel> field. This
+tells &kmail; where it can find your folders on the server. If you also
+have a shell account on the server and the messages are stored in your home
+folder it might be useful to store the messages in a subfolder
+<filename class="directory">Mail</filename>. Use this as a value in
+the <guilabel>Prefix to folders</guilabel> field so that &kmail; does
+not mix up mailbox files and other files. If you are not interested in
+this feature, simple leave the field blank.</para>
+
+<para>If you check <guilabel>Automatically compact folders</guilabel>
+&kmail; removes the messages you deleted from the
+server as soon as you leave a folder. Otherwise the messages are
+only marked as deleted and it is up to you to compact the folders
+manually by using the menu item <menuchoice><guimenu>File</guimenu><guimenuitem>Compact All
+Folders</guimenuitem></menuchoice>.</para>
+<para>If you check <guilabel>Show hidden folders</guilabel>,
+folders whose name starts with a dot are also displayed.</para>
+</sect3>
+
+
+<sect3 id="receiving-mail-pop3">
+<title>Options only relevant to POP3</title>
+
+<para>Select <guilabel>Leave fetched messages on the server</guilabel> if you want to
+leave your messages on the server after you downloaded them.</para>
+
+<para>Select <guilabel>Exclude from &quot;Check Mail&quot;</guilabel> if you
+do not want to check this account whenever you use <menuchoice><guimenu>File</guimenu><guimenuitem>Check
+Mail</guimenuitem></menuchoice>. You can still check for new messages on this account
+with <menuchoice><guimenu>File</guimenu><guimenuitem>Check Mail
+In</guimenuitem></menuchoice>.</para>
+
+<para>Select <guilabel>Enable interval mail checking</guilabel> if you want
+&kmail; to check for new messages automatically. The interval can be specified below
+under <guilabel>Check interval</guilabel>.</para>
+
+<para><guilabel>inbox</guilabel> is the default folder for incoming
+messages. If you want to change that for some reason, you can do so with